summaryrefslogtreecommitdiff
path: root/res/about
diff options
context:
space:
mode:
authorJaakko Keränen <jaakko.keranen@iki.fi>2021-10-27 12:10:02 +0300
committerJaakko Keränen <jaakko.keranen@iki.fi>2021-10-27 12:10:02 +0300
commitc6a81d733fd6c0340f68ecc220b3dec7005b1039 (patch)
treeae6f8a7f98d7eb223ed483afa73e0e5c11f26725 /res/about
parentc736cc74149a4cdad36389e649c8e0121a197284 (diff)
Updated documentation
Fonts and other changes.
Diffstat (limited to 'res/about')
-rw-r--r--res/about/about.gmi3
-rw-r--r--res/about/help.gmi174
-rw-r--r--res/about/license.gmi8
-rw-r--r--res/about/version.gmi2
4 files changed, 164 insertions, 23 deletions
diff --git a/res/about/about.gmi b/res/about/about.gmi
index a9eedb6d..053e798d 100644
--- a/res/about/about.gmi
+++ b/res/about/about.gmi
@@ -20,6 +20,9 @@ Runtime debug information: contents of currently open tabs, navigation history,
20=> about:feeds 20=> about:feeds
21List of all entries from subscribed feeds. 21List of all entries from subscribed feeds.
22 22
23=> about:fonts
24Installed fonts, and actions for viewing and managing fontpacks.
25
23=> about:help 26=> about:help
24User manual. 27User manual.
25 28
diff --git a/res/about/help.gmi b/res/about/help.gmi
index 3e4aea5d..20c5d6c8 100644
--- a/res/about/help.gmi
+++ b/res/about/help.gmi
@@ -85,7 +85,7 @@ The user interface has been designed for both mouse and keyboard based use. When
85 85
86### 1.1.1 URL entry and quick search 86### 1.1.1 URL entry and quick search
87 87
88The URL input field is in its typical location in the navigation bar. It can be accessed quickly by pressing ${CTRL+}L. You can then type or paste an URL and press Enter to load the page. 88The URL input field can be found in the traditional location in the navigation bar. It can be accessed quickly by pressing ${CTRL+}L. You can then type or paste an URL and press Enter to load the page.
89 89
90As you enter text in the URL input field, Lagrange starts looking for matches in bookmarks, history, identities, and content of cached pages. This provides an easy way to return to a page you've been on recently. Press Tab or ↓ to switch input focus to the results. 90As you enter text in the URL input field, Lagrange starts looking for matches in bookmarks, history, identities, and content of cached pages. This provides an easy way to return to a page you've been on recently. Press Tab or ↓ to switch input focus to the results.
91 91
@@ -388,20 +388,88 @@ Page content color themes are selected on the "Colors" tab of Preferences. The "
388* Sepia: Light sepia background with black text. Does not change depending on domain; use this for readability if you prefer a sepia reading experience. 388* Sepia: Light sepia background with black text. Does not change depending on domain; use this for readability if you prefer a sepia reading experience.
389* High Contrast: White background with black text. Does not change depending on domain; use this for readability if you prefer maximum contrast between text and the background. 389* High Contrast: White background with black text. Does not change depending on domain; use this for readability if you prefer maximum contrast between text and the background.
390 390
391## 2.4 Page style 391## 2.4 Fonts
392 392
393The "Style" tab of the Preferences dialog lets you customize the appearance and layout of page content. 393This version of Lagrange supports TrueType fonts. To use a new font in the app, simply view the .ttf file in the app and a page footer action is available for performing the installation. For example, try drag-and-dropping a .ttf file on the window. Alternatively, you can manually copy the font to the "fonts" subdirectory of the user-specific configuration directory (see section 3.5).
394
395The "Fonts" tab of the Preferences dialog contains options that affect the appearance of text in page content, the user interface, and text rendering in general.
396
397To be precise, on this tab you can select which _typefaces_ to use for certain elements of the page and the UI; picking a particular font (including its size, weight, style, etc.) for specific elements is not possible. Lagrange controls the size and styling of text by choosing fonts according to your theme and typeface preferences. The term "font" is often used to mean "typeface" in this document and in the app UI.
398
399The fonts for document headings, body text, preformatted blocks, and the user interface can be chosen separately. There is also a separate font for monospaced body text, used when the protocol-specific "Monospace body" option is enabled.
400
401There are two built-in fonts available:
402
403* "Source Sans" is the default UI font that is also used for page content.
404* "Iosevka" is the monospaced font.
405
406There is also an "Iosevka (compact)" variant that actually uses the font's original line spacing. It is the default for preformatted blocks to avoid gaps between lines of ASCII art, but not for body text for better legibility.
407
408See sections 2.4.4 and 5 for more details about font management, compatibility, and configuration.
409
410### 2.4.1 Monospace body
411
412The "Monospace body" option causes all pages to be displayed in a monospace font. For example, most Gopher content has been written with the assumption of a monospace font, so it may provide a better reading experience to enable this for Gopher pages. The selected "Monospace font" is applied to the entire document.
413
414Handling of whitespace in page content also changes when this option is enabled: spaces are no longer normalized so if the source uses multiple spaces somewhere, those are shown as-is.
415
416### 2.4.2 ANSI escapes
417
418=> https://en.wikipedia.org/wiki/ANSI_escape_code ANSI escape code (Wikipedia):
419> ANSI escape sequences are a standard for in-band signaling to control cursor location, color, font styling, and other options on video text terminals and terminal emulators.
420
421Sometimes these codes are used for things like colored ASCII art. However, Lagrange is not a terminal emulator so only a very minimal set of codes have any effect; the rest are ignored.
422
423The "ANSI escapes" setting controls which ANSI escape codes are enabled:
394 424
395The fonts for headings and other text are selected separately. This way one can achieve a greater number of style variations. Also, headings that are in a different font are more visually distinct and thus easier for one's eyes to scan. 425* "FG Color" enables changes to text foreground color.
426* "Font Style" enables changing the font style: bold, italic, or monospace. (These correspond to codes 1, 2, and 11.)
427
428A warning banner is displayed if any codes are detected on a page. This helps you be aware of potential visual artifacts, like text color that is being forced to black regardless of the page background color. Click on the warning to dismiss it on a per-site basis.
429
430If you serve content via Gemini, please be aware that ANSI escapes may not be supported by clients, and may in fact disrupt the behavior of a client in unexpected ways. For instance, consider a screen reader or a web proxy that doesn't filter out the codes. Only employ ANSI escapes when the user has somehow indicated that is their preference.
431
432### 2.4.3 Other font options
433
434The "Glyph warnings" option controls whether a warning will be shown when a page is missing one or more characters. This is typically due to the page being in a language that is not covered by any of the installed fonts. Clicking on the glyph warning banner opens the font management page.
435
436"Smoothing" enables or disables glyph antialiasing. In this version, it is recommended that smoothing is always enabled. This is because the text renderer does not support hinting of any kind, which means that without smoothing, glyph shapes will be severely distorted. You may still want to try disabling this option if antialiasing causes eye strain for you.
437
438### 2.4.4 Managing fonts
439
440Open "about:fonts" to see all the installed fonts, and enable, disable or uninstall individual fontpacks. At the top of the page, there is a link to the skyjake.fi Font Library: a curated collection of fontpacks that can be freely distributed. From there you can conveniently install more fonts specifically tuned for Lagrange.
441
442The rest of the page is divided to two sections: enabled and disabled fontpacks. Individual packs can be disabled, so they remain installed but not in use. (Tip: Use the Outline sidebar to see a list of all packs, if there are many.)
443
444Click on the "View file" links to see what each fontpack contains. The fontpack format is described in section 5: it is simply a ZIP archive with some metadata and a bunch of font files. When you install a TrueType font (i.e., copy it to the user's fonts directory), it is treated as a fontpack containing a single file, although no ZIP archive is created for it. Use the "View fontpack.ini template" link to see the generated metadata that can be used as a basis for creating an actual fontpack.
445
446There are multiple locations where Lagrange looks for fontpacks at launch:
447
448* Directory containing the app binary (BIN_DIR)
449* (BIN_DIR)/fonts
450* (BIN_DIR)/../share/lagrange
451* (BIN_DIR)/../../share/lagrange
452* macOS: Lagrange.app/Contents/Resources
453* User configuration directory (CFG_DIR; see section 3.5)
454* (CFG_DIR)/fonts
455
456Individual TrueType fonts are automatically loaded only from the last one, (CFG_DIR)/fonts.
457
458If a "fonts.ini" file is present in the user configuration directory, it will be loaded as fontpack metadata (see section 5). This way you can manually configure fonts without creating a ZIP archive. For example:
459
460```fonts.ini example
461[couriercode]
462name = "Courier Code"
463regular = "/home/jaakko/Fonts/Courier Code/CourierCode-Roman.ttf"
464glyphscale = 0.85
465monospace = true
466```
396 467
397There are six fonts available: 468About compatibility: fonts are complex, and while the TrueType format is not the most advanced one, it still has features that are not supported in Lagrange. The technical reason is that glyphs are rasterized using stb_truetype, a rather simple TrueType font library. (It's nice and small, though.) For example, hinting is not supported. You may find that some fonts simply fail to load correctly, or look wrong in the app.
398 469
399* "Nunito" is a friendly rounded sans-serif font. 470## 2.5 Page style
400* "Fira Sans" is a bolder, narrower, and more angular sans-serif font. 471
401* "Source Sans 3" is the Lagrange UI font (sans-serif). 472The "Style" tab of the Preferences dialog lets you customize the appearance and layout of page content.
402* "Literata" is a heavy and serious serif font.
403* "Tinos" is a lighter serif font.
404* "Iosevka" is the monospace font.
405 473
406Other style options: 474Other style options:
407 475
@@ -409,13 +477,13 @@ Other style options:
409* Quote indicator: Quoted text is shown in an italic font. Additionally, you can select between a quotation mark icon and the traditional vertical line along the left edge of the quote. 477* Quote indicator: Quoted text is shown in an italic font. Additionally, you can select between a quotation mark icon and the traditional vertical line along the left edge of the quote.
410* Big 1st paragraph: When enabled, the leading paragraph on the page is shown in a slightly larger font. 478* Big 1st paragraph: When enabled, the leading paragraph on the page is shown in a slightly larger font.
411 479
412## 2.5 Proxies 480## 2.6 Proxies
413 481
414Gemini allows relaying requests via a proxy server. On the "Network" tab, you can configure proxy servers for Gemini, Gopher, and HTTP/HTTPS requests. 482Gemini allows relaying requests via a proxy server. On the "Network" tab, you can configure proxy servers for Gemini, Gopher, and HTTP/HTTPS requests.
415 483
416When an HTTP proxy server is configured, HTTP/HTTPS links will no longer open in the system's default web browser but will be loaded via the proxy, expecting it to serve a 'text/gemini' version of the link contents. 484When an HTTP proxy server is configured, HTTP/HTTPS links will no longer open in the system's default web browser but will be loaded via the proxy, expecting it to serve a 'text/gemini' version of the link contents.
417 485
418## 2.6 Keybindings 486## 2.7 Keybindings
419 487
420The "Keys" tab lets you change which keys are bound to UI commands. Click on an item with the mouse and then press the new key combination that you want bound to it. Right-click on a binding to erase it or reset it to the default. 488The "Keys" tab lets you change which keys are bound to UI commands. Click on an item with the mouse and then press the new key combination that you want bound to it. Right-click on a binding to erase it or reset it to the default.
421 489
@@ -529,6 +597,9 @@ Each feed entry consists of five consecutive lines:
529* The posted time is a UNIX timestamp that specifies when the entry was posted. This is determined from the "YYYY-MM-DD" date found on the link line. If this is a "new headings" subscription, the posted time and the discovery time are the same. 597* The posted time is a UNIX timestamp that specifies when the entry was posted. This is determined from the "YYYY-MM-DD" date found on the link line. If this is a "new headings" subscription, the posted time and the discovery time are the same.
530* The discovery time is a UNIX timestamp that marks when the entry was added to the cache. 598* The discovery time is a UNIX timestamp that marks when the entry was added to the cache.
531 599
600### fonts.ini
601This file is loaded as fontpack metadata (see section 5). It must be manually created.
602
532### idents.lgr and idents/ 603### idents.lgr and idents/
533idents.lgr is a binary file that contains metadata about the client certificates known to the application, for example on which URLs a particular certificate should be active. 604idents.lgr is a binary file that contains metadata about the client certificates known to the application, for example on which URLs a particular certificate should be active.
534 605
@@ -603,6 +674,9 @@ Persistent configuration variables. The file is rewritten when the application i
603### state.lgr 674### state.lgr
604A binary file that contains the current state of the application: open tabs and their scroll positions, and navigation history with cached page content (up to the configured cache limit). You may delete this file when the application is not running to close all tabs and clear the page content cache. 675A binary file that contains the current state of the application: open tabs and their scroll positions, and navigation history with cached page content (up to the configured cache limit). You may delete this file when the application is not running to close all tabs and clear the page content cache.
605 676
677### sitespec.ini
678Site-specific settings.
679
606### trusted.2.txt 680### trusted.2.txt
607Trusted server certificates. Each line specifies the certificate fingerprint of one server: 681Trusted server certificates. Each line specifies the certificate fingerprint of one server:
608> {domain};{port} {valid-until} {fingerprint} 682> {domain};{port} {valid-until} {fingerprint}
@@ -613,6 +687,9 @@ Trusted server certificates. Each line specifies the certificate fingerprint of
613### uploadbackup.txt 687### uploadbackup.txt
614Backup of the text entered into the Upload with Titan dialog. 688Backup of the text entered into the Upload with Titan dialog.
615 689
690### uploadtoken.txt
691Backup of the server token.
692
616### visited.2.txt 693### visited.2.txt
617The combined navigation history of all tabs. Each line specifies one URL: 694The combined navigation history of all tabs. Each line specifies one URL:
618> {last-visited} {flags} {url} 695> {last-visited} {flags} {url}
@@ -675,7 +752,7 @@ Each hook is specified as three lines:
675* Command to execute, plus additional arguments each separated with semicolons 752* Command to execute, plus additional arguments each separated with semicolons
676 753
677For example: 754For example:
678``` 755```mimehooks.txt
679Convert Atom to Gemini feed 756Convert Atom to Gemini feed
680application/xml 757application/xml
681/usr/bin/python3;/home/jaakko/atomconv.py 758/usr/bin/python3;/home/jaakko/atomconv.py
@@ -686,7 +763,7 @@ The hook program is executed directly without involving the shell. This means sc
686## 4.3 Example: Converting from Atom to Gemini 763## 4.3 Example: Converting from Atom to Gemini
687 764
688The following simple Python script demonstrates how a MIME hook could be used to parse an Atom XML document using Python 3 and output a Gemini feed index page based on the parsed entries. This is just a simple example; a more robust script could include more content from the Atom feed and handle errors, too. 765The following simple Python script demonstrates how a MIME hook could be used to parse an Atom XML document using Python 3 and output a Gemini feed index page based on the parsed entries. This is just a simple example; a more robust script could include more content from the Atom feed and handle errors, too.
689``` 766```python
690import sys 767import sys
691import xml.etree.ElementTree as ET 768import xml.etree.ElementTree as ET
692 769
@@ -720,6 +797,73 @@ for entry in feed_entries:
720 print(f'=> {entry_link} {entry_date} {entry_title}') 797 print(f'=> {entry_link} {entry_date} {entry_title}')
721``` 798```
722 799
800# 5 Fontpacks
801
802Fontpack is a file format defined by Lagrange that is used to combine a set of font files with configuration metadata. The (unregistered) media type for .fontpack files is 'application/lagrange-fontpack+zip'.
803
804A fontpack is a ZIP archive that must have a "fontpack.ini" file at the root level.
805
806```fontpack.ini from firasans.fontpack
807version = 1
808
809[firasans]
810name = "Fira Sans"
811glyphscale = 0.85
812regular = "FiraSans-Regular.ttf"
813italic = "FiraSans-Italic.ttf"
814light = "FiraSans-Light.ttf"
815semibold = "FiraSans-SemiBold.ttf"
816bold = "FiraSans-Bold.ttf"
817```
818
819Fontpacks may use the Deflate compression method, but that can slow down launching the app because each font must then be decompressed before loading.
820
821Each fontpack has an ID that comes from the file name: the ID of "firasans.fontpack" would be "firasans". Space characters are not allowed in the ID.
822
823Fontpacks are versioned, i.e., they have a version number in their metadata. This makes it possible to tell when a fontpack is an updated version of an existing one. The fontpack ID (file name) must remain the same, though, regardless of the version number.
824
825The "fontpack.ini" file uses TOML syntax and can specify any number of typefaces. In the example above, the line `[firasans]` begins the definition of a typeface called "firasans". If the same typeface is found in multiple fontpacks, only the first one that gets loaded is used; the rest are ignored. Typeface IDs can be the same or different than fontpack IDs; they exist in different namespaces. The typeface ID is what is actually used in "prefs.cfg" to save your font preferences.
826
827## 5.1 Fontpack properties
828
829`version` defines the version number of the fontpack. It is a single integer, and if omitted, defaults to zero. It has no specific meaning except that larger values are considered newer versions.
830
831## 5.2 Typeface properties
832
833### 5.2.1 General
834* `name` (string) is the human-readable name of the typeface. This is used in the Preferences dialog and elsewhere in the UI.
835
836### 5.2.2 Prioritization and exclusion
837The same character's glyph(s) may be found in several fonts, so a prioritization is applied to pick the most appropriate font. Font selection may also depend on the context, for example preformatted blocks must be displayed using monospace fonts. These properties control when and if the typeface will be used.
838
839* `priority` (integer) defines a sort order for typefaces. The ones with the highest priority are checked first.
840* `override` (bool): whether this typeface is always checked first before any other one, in any context. Only one typeface can use this flag.
841* `monospace` (bool): is this a monospace typeface and therefore suitable for preformatted blocks and monospace body text.
842* `auxiliary` (bool): if true, this typeface is not included in Preferences as a font choice, but is still checked for glyphs if other fonts do not provide them. Suitable for miscellaneous symbols or additional languages, for examples.
843* `allowspace` (bool): if true, an auxiliary font's metrics for space characters are used. Sometimes symbol fonts have extra wide spaces, so for example a space next to an Emoji would be too wide. This has no effect for non-auxiliary typefaces.
844
845### 5.2.3 Metrics
846These properties can be used to modify the height and spacing of the font.
847
848* `height` (float) is a multiplier to alter the height of the font. It can be at most 2.0, to double the height. This simply scales the font smaller or larger without altering spacing.
849* `glyphscale` (float) scales glyphs smaller without changing the height of the font. The value must be 1.0 or smaller. In effect, this lets you increase the spacing between consecutive lines of text. It can be combined with `height` to keep glyphs the same size but just increase line spacing. For example, `glyphscale` 0.833 would counter the scaling caused by `height` 1.2, increasing line spacing by 1.2x.
850* `voffset` (float) is multiplier applied to the vertical offset that normally centers scaled glyphs on the line. This allows fine-tuning where the baseline of scaled glyphs ends up. Setting this to 1.0 means that glyphs are vertically centered after scaling with `glyphscale`; 0.0 would disable the centering. Reasonable values are likely in the 0.5…1.5 range, depending on the amount of scaling.
851
852Changing only the `glyphscale` property is the recommended way to alter line spacing. This makes it easier to mix and match fonts on a single line without having to deal with changes in text height. Compare your adjusted scaling to see if it looks suitable next to normal body text.
853
854Each of these properties can be set separately for UI text and page content by using the prefixes `ui.` and `doc.`. For example, to only scale the font when used in the UI, set `ui.height` instead of `height`.
855
856### 5.2.4 Font files
857A single typeface can use up to five font files.
858
859* `regular` (string): path of a font file for the regular style. A relative path means that the file is loaded from inside the fontpack archive. Absolute paths can be used to refer to files on the local system.
860* `italic` (string): path of a font file for the italic style.
861* `light` (string): path of a font file for the light weight.
862* `semibold` (string): path of a font file for the semibold weight.
863* `bold` (string): path of a font file for the bold weight.
864
865Only the regular style is required. Undefined styles fall back to the closest available style. The same file path can be used in multiple styles; only one copy of the file will be loaded to memory.
866
723# Open source licenses 867# Open source licenses
724 868
725=> about:license 869=> about:license
diff --git a/res/about/license.gmi b/res/about/license.gmi
index 6721ab9b..09204da2 100644
--- a/res/about/license.gmi
+++ b/res/about/license.gmi
@@ -100,17 +100,11 @@ The libunistring library is covered by the GNU Lesser General Public License (LG
100 100
101This application uses fonts licensed under the Open Font License. 101This application uses fonts licensed under the Open Font License.
102 102
103=> https://github.com/mozilla/Fira/blob/master/LICENSE Fira Sans
104=> https://typeof.net/Iosevka/ Iosevka 103=> https://typeof.net/Iosevka/ Iosevka
105=> https://github.com/googlefonts/literata/blob/master/OFL.txt Literata 104=> https://github.com/googlefonts/noto-fonts Noto Sans Symbols, Noto Sans Symbols 2
106=> https://github.com/google/fonts/blob/master/ofl/nanumgothic/OFL.txt Nanum Gothic
107=> https://www.google.com/get/noto/#sans-arab Noto Sans Arabic
108=> https://www.google.com/get/noto/help/cjk/ Noto Sans CJK (JP, SC)
109=> https://github.com/googlefonts/nunito/blob/master/OFL.txt Nunito
110=> https://github.com/skyjake/lagrange/blob/dev/res/fonts/LICENSE_SmolEmoji.txt Smol Emoji 105=> https://github.com/skyjake/lagrange/blob/dev/res/fonts/LICENSE_SmolEmoji.txt Smol Emoji
111=> https://github.com/adobe-fonts/source-sans/blob/release/LICENSE.md Source Sans 3 106=> https://github.com/adobe-fonts/source-sans/blob/release/LICENSE.md Source Sans 3
112 107
113Additional fonts: 108Additional fonts:
114 109
115=> https://github.com/googlefonts/noto-emoji/blob/master/LICENSE Noto Emoji (Apache License 2.0) 110=> https://github.com/googlefonts/noto-emoji/blob/master/LICENSE Noto Emoji (Apache License 2.0)
116=> https://fonts.google.com/specimen/Tinos#license Tinos (Apache License 2.0)
diff --git a/res/about/version.gmi b/res/about/version.gmi
index 34d44214..a0ab6682 100644
--- a/res/about/version.gmi
+++ b/res/about/version.gmi
@@ -13,7 +13,7 @@
13New features: 13New features:
14* Added a customizable font library. Open "about:fonts" to view and manage the installed fonts. 14* Added a customizable font library. Open "about:fonts" to view and manage the installed fonts.
15* Added TrueType fonts as a recognized content type. When one is viewed in the app (e.g., via a drag-and-drop), there is an option to install it as a user font. 15* Added TrueType fonts as a recognized content type. When one is viewed in the app (e.g., via a drag-and-drop), there is an option to install it as a user font.
16* Added fontpacks. They are ZIP archives containing one or more TrueType fonts and parameters about how they should be used. 16* Added fontpacks: ZIP archives containing one or more TrueType fonts and parameters about how they should be used.
17* Added new font options: separate preformatted and monospace body fonts, UI font, smoothing. 17* Added new font options: separate preformatted and monospace body fonts, UI font, smoothing.
18* Added style option to show all links as bold regardless of visited status. 18* Added style option to show all links as bold regardless of visited status.
19* Added warning message about missing font glyphs. 19* Added warning message about missing font glyphs.