Kristall Help

This is the user manual for the Kristall small-internet browser. It contains explanations on how to use the program, what each setting means and other information about the browser.

The Mission

Kristall tries to fill the hole of graphical browsers for alternative internet protocols with a high usability and feature richness.

The main interface

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 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 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:

Content view

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. 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 😉

File

[New Tab] will open a new tab to surf.

[New Window] will open a new window to browse in.

[Save as] allows you to save the currently displayed file to your disk.

[Close Tab] will close the current tab. Does the same as clicking the small (×) button on the tab itself.

[Manage Certificates] will bring up a dialog that allows you to create, delete or change client certificates.

[Settings] will open a dialog that helps you configure Kristall to your likings.

[Quit] will close Kristall.

Navigation

This menu contains means to navigate the internet.

[Go to home] will navigate your current tab to your home page.

[Backward] will navigate one page back in your history.

[Foreward] will navigate one page foreward in your history.

[Root] will take you to the root directory of the current site. e.g if you are currently at gemini://example.com/gemlog/some-document.gmi, you will be taken to gemini://example.com/

[Parent] will take you to the ‘parent’ directory of the current site. e.g if you are at gemini://example.com/parent/some-document.gmi, you will be taken to gemini://example.com/parent/

[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/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 inside of Kristall, this is a good place to try this feature out!

[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 or pressing Return on 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.

Help

This menu contains some stuff that provides help or information about Kristall.

[Help] displays the help manual (this document).

[Changelog] will open a document that lists the changes in Kristall in a bulleted list.

[About] shows a dialog with some 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. 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.

[Start Page] is the URL to the page that will be loaded for new tabs and windows. 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:

gemini://example.com/search?%1

Note the “%1” at the end of the URL. This is where search queries will be inserted. This must be provided in order for Kristall to work with the search engine correctly. Be aware that search engine URLs can vary. For example, a different search engine may appear like so:

gemini://example2.com/search/another/%1

[Additional Toolbar Items] contains various additional toolbar items which some may find useful.

[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] UI theme, this option may be useful.

[UI Density] controls the margin of the toolbar buttons.

[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.

[Unknown Scheme] changes the behaviour how Kristall handles unknown/disabled URL schemes. [Use OS default handler] will invoke your OS default, [Display error message] will just pop up a message box and tell you that Kristall cannot handle this URL.

[Max. Number of Redirections] is a setting that allows you to restrict sites to redirect you only a certain number of times before erroring out. Setting this to 0 will disable redirections completely, displaying an error with the target URL.

[Redirection Handling] allows you to fine-tune the way Kristall allows redirections. Each of the options defines if Kristall should ask you to allow the redirect or do it silently. [Ask for cross-scheme redirection] will pop up a message box if a host tries to redirect you from one URL scheme to another, e.g. when a web server redirects you from HTTP to HTTPS. [Ask for cross-host redirection] will pop up the message box for all redirections through host boundaries, e.g. when example.com redirects you to www.example.com. [Ask for cross-scheme or cross-host redirection] will enable both of the previous behaviours, asking when any cross-boundary redirection happens. [Ask for all redirections] will pop up a message box every time a server tries to redirect you, keeping you in full control over all redirections. [Silently redirect everything] is the exact oppositve of that, accepting all redirections without warning or notice.

[Network Timeout] is the time a server is allowed to not respond anything before a error message appears. As long as a server dripples some bytes to Kristall, no timeout will happen, so having a slow or bad connection shouldn’t yield timeouts.

Display

This tabs contains tweaks you can apply to the display behaviour. Change text effects or rendering of documents.

[Render emojis] allows you to toggle whether to render emojis using installed emoji fonts. Disabling this can help prevent text rendering issues due to emojis. Note that emojis are only supported in Kristall builds with Qt 5.13 or later.

[URL bar highlights] sets whether the URL bar should use “fancy” highlights. The highlighting simply makes the domain of the site more prominent/visible, and the text around it slightly dimmed. This is purely a cosmetic feature.

[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.

[Use typographer’s quotes] sets whether to replace regular quotation marks, that is:

"these", and 'these'

with fancy Unicode quotes, which include the following:

“these”, and ‘these’

This is a purely cosmetic feature that may aid in readability.

[ANSI Escape Sequences] determines the method of handling ANSI escape codes. This allows a document to alter some of the format (colour, etc) of text.

[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.

[Hidden files in file:// directories] determines whether hidden files will display in local directory listings (i.e file:// URLs which do not point to a specific document but rather a directory).

[Strip