help.gemini: changes and additions

1 files changed, 42 insertions, 23 deletions

diff --git a/src/about/help.gemini b/src/about/help.gemini
index 6a3eac0..9627e45 100644
--- a/src/about/help.gemini
+++ b/src/about/help.gemini
@@ -14,22 +14,24 @@ The main interface of Kristall consists of three parts:
 ### Navigation bar
 In the navigation bar, you have some buttons and your URL bar.
 
-You can enter any supported URL in the URL bar, press *Return* and Kristall will then load the page in the content view. You usually need to specify the url scheme to navigate to a site, but you can omit the gemini:// prefix for gemini pages. If the URL has no scheme, it will be automatically added by Kristall.
+You can enter any supported URL in the URL bar, press *Return* and Kristall will then load the page in the content view. You usually need to specify the url scheme to navigate to a specific site, but you can omit the gemini:// prefix for gemini pages. If you enter a URL with no scheme, and it looks like a URL (e.g "tilde.pink"), Kristall will assume that it is in fact a gemini URL. If you enter something in the URL bar that *doesn't* look like a URL (e.g "i like dogs"), it will be assumed a search query, and will be forwarded to the search engine that is set in the Settings.
 
-The two buttons on the left give you the ability to navigate back and forth in your browsing history. The button with the round arrow is the refresh button and allows you to reload the currently displayed site. While a site is loading, it is replaced with the stop button (square icon) that allows you to cancel the current request.
+The two buttons on the left of the navigation bar that give you the ability to navigate back and forth in your browsing history. The button with the round arrow is the refresh button and allows you to reload the currently displayed site. While a site is loading, it is replaced with the stop button (square icon) that allows you to cancel the current request. Tip: Some additional buttons can also be enabled in the settings, to quickly navigate to the home page, and even the 'root' and 'parent' of the current URL! (See [Additional Toolbar Items] in Settings)
 
 On the right side of the URL bar you will find two buttons:
-The button with the small heart in it will add or remove this page to your favourites, this can be done as well by pressing CTRL-D. When the heart on the button is filled, the site is contained in your favourites. If not, the heart has only a outline display.
-The button with the shield icon toggles your use of client certificates. Pressing it when no client certificate is enabled, a dialog will pop up asking you to select or create a certificate. When a certificate is enabled, the button will have a filled shield with a small lock in it. Pressing the button now will disable the currently used certificate. Note that if you're using a transient certificate, Kristall will ask you a safety question before destroying the certificate.
+* The button with the small heart icon in it will add or remove this page to your favourites, this can be done as well by pressing *Ctrl-D*. When the heart on the button is filled, the site is contained in your favourites. If not, the heart has only a outline display. Clicking this button will open a small menu to allow you to quickly place the favourite in a folder of your choosing (by default 'Unsorted'). You can press *Return* in this menu to quickly affirm the options displayed in it.
+* The button with the shield icon toggles the use of client certificates. Pressing it when no client certificate is enabled, a dialog will pop up asking you to select or create a certificate. When a certificate is enabled, the button will have a filled shield with a small lock in it. Pressing the button now will disable the currently used certificate. Note that if you're using a transient certificate, Kristall will ask you a safety question before destroying the certificate.
 
 ### Content view
-The content view renders the requested document. For hypertext documents, you get a nicely rendered version of those documents, other text files are displayed in monospace. Audio and video files are played in a small built-in media player that allows you to play/pause the media, scroll around in the time line and mute/unmute audio. Images are rendered in an interactive view where you can drag the image around and zoom in/out with the mouse wheel.
+The content view renders the requested document. For hypertext documents (i.e gemtext, markdown, etc), you get a nicely rendered version of those documents, other text files are displayed in monospace. Audio and video files are played in a small built-in media player that allows you to play/pause the media, scroll around in the time line and mute/unmute audio. Images are rendered in an interactive view where you can drag the image around and zoom in/out with the mouse wheel.
 
 Documents that can't be rendered will be displayed with file size and mime type, so you can save them to disk and open the files with another program.
 
+Right-clicking in the content view will produce a menu which allows you to copy text, navigate back/forward in history, and copy or open links which are being hovered over. If you right click a HTTP/S link you will also see an option "Open with external web browser" which allows you to open these pages in your default WWW browser.
+
 ### Status bar
 The status bar displays auxiliary information:
-On the left, you can see the link target when you hover a link. On the right, you can see the document size, time needed to load the document and the mime type of the content. This is especially important when Kristall is not able to render the document nicely.
+On the left, you can see the link target when you hover a link. On the right, you can see the document size, time needed to load the document and the mime type of the content. This is especially important when Kristall is not able to render the document nicely. A "(cached)" indicator will appear to the left of the mime type, indicating that the page has been read from cache.
 
 ## Menus
 This chapter explains what each menu button does. I hope that most stuff isn't surprising 😉
@@ -62,14 +64,14 @@ This menu contains means to navigate the internet.
 
 [Refresh] will reload the current page. This may be necessary for CGI scripts or other interactive content.
 
-[Add to favourites] will add or remove the current page to your list of favourites.
+[Add to favourites] will add or remove the current page to/from your list of favourites.
 
 ### View
 This menu allows you to show/hide dockable dialogs.
 
-[Document Outline] toggles the document outline. Documents with text/gemini get an automatic outline generation that can be used to navigate larger documents quicker. If you're reading this help document in the browser, this is a good place to try this feature out!
+[Document Outline] toggles the document outline. Documents with text/gemini get an automatic outline generation that can be used to navigate larger documents quicker. If you're reading this help document inside of Kristall, this is a good place to try this feature out!
 
-[Bookmarks] opens a dock containing a list of all your favourite sites. Open your bookmarks into a new tab by double-clicking the entries.
+[Favourites] opens a dock containing a list of all your favourite (a.k.a bookmarked) sites. Open your favourites into a new tab by double-clicking the entries. If you right click on an entry you will be presented with a menu in which you can edit the name or location of the entry, or delete it. Right-clicking in the window (not on an entry, not on a group) will allow you to create a new "group" of entries. Right clicking on a group will allow you to rename the group, or recursively delete it (be careful!).
 
 [History] shows the surfing history of the current tab. Double-clicking an entry navigates back and forth in your history without disturbing the list.
 
@@ -85,16 +87,16 @@ This menu contains some stuff that provides help or information about Kristall.
 [About Qt] shows a dialog containing legal information about the Qt version used.
 
 ## Settings
-Kristall offers a vast amount of settings. You can style the documents to your liking, changing fonts and colors. You can also fine-tune the behaviour of Kristall to match your likings and keep track of your trusted pages.
+Kristall offers a vast amount of settings. You can style the documents to your liking, changing fonts and colors. You can also fine-tune the behaviour of Kristall to match your likings and keep track of your trusted pages. Please note that Kristall has been designed mostly for browsing geminispace, thus many of these settings are specific or exclusive to Gemini only.
 
 ### Generic
 This tab contains an unsorted list of settings that allow you to tweak Kristalls behaviour.
 
-[UI Theme] controls whether the Qt interface is displayed in a dark or a light theme. You can adjust that to your system style or to your site rendering. The "OS Default" will use your system theme.
+[UI Theme] controls whether the Qt interface is displayed in a dark or a light theme. Selecting [Light] or [Dark] will use the provided Qt light/dark themes. [OS Default] will use your system theme.
 
-[Icon Theme] controls the specific icon set that the Qt interface will use. Usually, the default "Auto" option should be good enough, however for those using the "OS Default" theme, this option may be useful.
+[Icon Theme] controls the specific icon set that the Qt interface will use. Usually, the default [Auto] option should be good enough, however for those using the [OS Default] UI theme, this option may be useful.
 
-[Start Page] is the URL to the page that will be loaded for new tabs. Default is "about:favourites".
+[Start Page] is the URL to the page that will be loaded for new tabs. Default is [about:favourites].
 
 [Search Engine] is the search engine to use when typing non-URLs in the URL bar. A handful of Gemini search engines are provided as a drop-down. If you would like to specify your own, specify it in a format similar to the following:
 
@@ -108,11 +110,11 @@ Note the "%1" at the end of the URL. This is where search queries will be insert
 gemini://example2.com/search/another/%1
 ```
 
-[Enabled Protocols] allows you to fine-tune which protocols are fetched by Kristall. By default, only Gemini is enabled, all other protocols are disabled. Disabled protocols are either not served with an error message or forwarded to your OS handler for that URL scheme.
+[Enabled Protocols] allows you to fine-tune which protocols are fetched by Kristall. By default, only Gemini is enabled, all other protocols are disabled. Disabled protocols are either not served, and produce an error message, or are forwarded to your OS handler for that URL scheme.
 
 [Text Rendering] allows one to control whether Kristall parses text input files or not. This is usually set to [Fancy] which renders text/html, text/gemini, text/markdown and text/gophermap to a nice, hyperlinked display. When set to [Always plain text], Kristall will display all text/* files as plaintext files instead. This may be inconvenient, but necessary for misparsed sites.
 
-[Enable text highlights] allows you to enable an experimental feature that allows *highlighting* and _underlining_ text in text/gemini documents. It will probably misrender, but you can try it out anyways.
+[Enable text highlights] allows you to enable *bolding* and _underlining_ in text/gemini documents. Bolding **like this** also works.
 
 [Gopher Map] allows you to chose a modern iconized style for gopher maps or, if you are an old schooler, just use a textual description of the item types in the map.
 
@@ -147,19 +149,19 @@ This is a purely cosmetic feature that may aid in readability.
 * [Root] button takes you to the root directory of the current site. (See Menus>Navigation section for explanation of what this does).
 * [Parent] button takes you to the parent directory of the current site. (See Menus>Navigation section for explanation of what this does).
 
-[Total cache size limit] sets the total amount of memory that can be used to cache pages. By default this is set to 500 KiB, but can be set to 0 to completely disable the caching system. The larger this number is, the more memory you are allowing Kristall to use.
+[Total cache size limit] sets the total amount of memory that can be used by Kristall to cache pages. By default this is set to 500 KiB, but can be set to 0 to completely disable the caching system. The larger this number is, the more memory you are allowing Kristall to use.
 
 [Cached item size threshold] is the maximum size of a single cached item. By default this is set to 400 KiB. This prevents Kristall from caching any pages that are large from clogging up the in-memory cache.
 
-[Cached item life] is the amount of time in minutes before a single cached item is considered "expired." When a cached item is "expired", it is not read from cache, but instead re-retreived from the server. Cache life can be disabled by enabling the [Unlimited item life] option.
+[Cached item life] is the amount of time in minutes before a single cached item is considered "expired." When a cached item is "expired", it is not read from cache, but instead re-retreived from the server. Cache life can be disabled by enabling the [Unlimited item life] option. Note: [Cached item life] is only recommended if you desperately want to keep your memory usage to a minimum, otherwise, having [Unlimited item life] is usually a great convenience, and due to the usually very small size of pages in geminispace, gopherspace, etc - it doesn't require much memory.
 
 ### Style
-On this tab, you can tweak the document rendering in Kristall. On the left half you can see all possible colors and fonts you can tweak, on the right half of the window is a preview rendering with your currently selected style.
-Most items in the *Style* category have either a [Font], [Color] or both buttons. Click these to change the respective value.
+In this tab, you can customise the document rendering in Kristall. The left pane contains a vast array of options to tweak, and the right pane displays a preview of your currently-selected style.
+Many items in the *Style* category have either a [Font], [Color], or both buttons. Click these to change the respective value.
 
 [Background Color] is the color that fills the empty space in a document.
 
-[Standard Font] allows you to change the font that is used for all non-preformatted and non-heading text. Chose the color and font family/size/style.
+[Standard Font] allows you to change the font that is used for all non-preformatted and non-heading text. Choose the color and font family/size/style.
 
 [Preformatted Font] is the font and text color that is used for all <pre> tags in HTML or preformatted blocks in text/gemini. This should be a monospace font, otherwise ASCII art will break horribly. Note to MacOS X users: "Andale Mono" is a good font choice here.
 
@@ -258,7 +260,7 @@ Using passphrases for importing/exporting certificates is currently not supporte
 Please note that changes in this dialog are immediaty applied and there is no way back when doing an action. This may change in the future, but will stay like this for now.
 
 ## Certificate Selection Dialog
-This dialog allows you to enable client certificates. It is opend by clicking the shield button in the navigation bar or it will automatically pop up when a site requests the use of a client certificate.
+This dialog allows you to enable client certificates. It is opened by clicking the shield button in the navigation bar or it will automatically pop up when a site requests the use of a client certificate.
 
 In the upper part, this dialog provides you with a list of all your persistent certificates. If you want to use one of those, select the certificate and click [Use]. Or simply double-click a certificate to chose it.
 You can also ad-hoc create a new certificate with the click on [Create new identity]. This will open up the certificate creation dialog which allows you to create new identities.
@@ -282,7 +284,7 @@ This dialog enables you to import or export certificate-key-pairs into or from K
 [Certificate File] needs to be a full path to either a .der or .pem file where Kristall will load/store the certificate from/to.
 
 ## Shortcuts
-This list contains all built-in shortcuts:
+The following list contains all of Kristall's built-in shortcuts:
 
 * Ctrl+T ⇒ New tab
 * Ctrl+W ⇒ Close tab
@@ -311,7 +313,7 @@ These protocols are currently supported via their respective URL schemes:
 => https://en.wikipedia.org/wiki/Finger_protocol Finger
 
 ### Gemini
-Kristall tries to implement the current feature set of the gemini specification. All response types of a gemini server are relayed to the user and the user choses when to do certain actions or not. Redirections are followed automatically.
+Kristall tries to implement the current feature set of the gemini specification. All response types of a gemini server are relayed to the user and the user choses when to do certain actions or not. Redirections are followed automatically, and you will be prompted depending on your configured Settings.
 
 ### Gopher
 Kristall provides access to gopherspace and supports most modern/common file types:
@@ -324,6 +326,13 @@ Kristall provides access to gopherspace and supports most modern/common file typ
 
 There is currently no support for automatic redirection on URL: resources or special/oldschool file types like DOS/HexBin/UUencoded data.
 
+### Local file browsing
+The file:// scheme can be used to browse local files and directories on your system. (This feature has not been well-tested on Windows systems)
+
+Browsing to a local directory, such as file:///home/user will create a "directory listing", with links allowing you to navigate the file structure.
+
+Browsing to an actual file, such as file:///home/user/file.txt will cause Kristall to attempt to display that file.
+
 ### Built-in sites
 There is also the scheme about: which can be used to access internal sites for configuration, usability or help (this is one of them!):
 => about:blank
@@ -331,6 +340,7 @@ There is also the scheme about: which can be used to access internal sites for c
 => about:help
 => about:updates
 => about:style-preview
+=> about:cache
 
 ## Security Concept
 Kristall has some built-in security measures to make your browsing experience safe and sane.
@@ -352,6 +362,15 @@ It will also make some artificial hurdles when you can *really* make something t
 * Fine-grained customizations
 * Trusting TLS connections based on manually built lists, TOFU method or using the certificate authority system
 
+## Caching
+Kristall has an in-memory page caching system enabled by default. This allows for quick loading of pages that have already been visited. Currently, this cache is cleared when Kristall is exited.
+
+The caching system is fairly basic; when a page is loaded, it is pushed to the cache (if it is smaller than [Cached item size threshold]). If the cache exceeds the [Total cache size limit], the oldest item in the cache is removed. The [Cached item life] determines how long this cached pages will be valid for.
+
+When a page is read from cache, it is indicated in the Status Bar, to the left of the mime type.
+
+If you would like to disable page caching, set the [Total cache size limit] to 0. See *Settings* for more information
+
 ## Supported Media Types
 * text/plain
 * text/gemini