staticgemtexts.lua

   1 local _ = require("gettext")
   2 local T = require("ffi/util").template
   3
   4 local version = "0.2.1"
   5
   6 return {
   7     help = T(_([[
   8 # Gemini client for KOReader
   9 This is a plugin for browsing Gemini in KOReader.
  10
  11 # Quickstart
  12 * Enter the client by selecting "Browse Gemini" from the menu.
  13 * Tap on links to follow them.
  14 * Swipe up to access a navigation menu, or down to go back.
  15
  16 # About Gemini
  17 Gemini is a lightweight text-first alternative to the WWW. It consists of a protocol for fetching gemini:// URLs analogous to https, and the "gemtext" hypertext format analogous to html. Thanks to its simplicity, even the low-end devices which KOReader targets are fully capable of accessing Gemini.
  18 => gemini://geminiprotocol.net Project Gemini home
  19
  20 # Usage
  21 * Navigate a Gemini document using the usual KOReader UI.
  22 * Tap on a link to follow it.
  23 * Swipe up, or select Browse Gemini again, to access the nav menu (see below) at the current URL.
  24 * Long-press or double-tap on a link to access the nav menu at the link URL.
  25 * Swipe down to go back in history.
  26
  27 Further gestures can be configured through the gesture manager; Gemini events are at the end of the Reader section.
  28
  29 ## Nav menu
  30 Buttons perform actions on the displayed URL, which can be edited.
  31 * Identity: Set/change the identity being used at the URL (see below).
  32 * Page Info: Show certificate and other information on the current URL.
  33 * Back: Go back one page in history.
  34 * Unback: Go forwards one page in history; enabled after going back.
  35 * Next: Go to next page in the queue (see below).
  36 * Bookmarks: Show bookmarks page.
  37 * Up: Modify URL by deleting the last component of the path.
  38 * Save: Saves page to filesystem.
  39 * Add: Append URL to the queue (see below).
  40 * Mark: Append URL to bookmarks page.
  41 * Go: Go to URL, reloading if it's the current URL.
  42
  43 ### Advanced actions
  44 The cog icon in the nav title bar toggles to the following advanced button actions, which can also be accessed by long-pressing on the button without using the cog icon.
  45
  46 * Edit Identity URLs: Edit which identities are used at which URLs
  47 * View as text: Show source text of current page.
  48 * History: Show full history and unhistory list.
  49 * Edit Queue: Show queue, with option to remove all items.
  50 * Edit Marks: Bring up text editor to edit the bookmarks gemtext page.
  51 * Root: Remove path from URL.
  52 * Prepend: Put URL at front of queue.
  53 * Quick Mark: Add to bookmarks without asking for a description.
  54 * Input: Prompt for input, as if asked by the server.
  55
  56 ## Troubleshooting
  57 * If loading pages is slow, consider disabling the "Reading statistics" plugin.
  58 * If an inappropriate action happens when you page forward beyond the end of a file, consider changing the action in Settings -> Document -> End of document action.
  59
  60 ## Identities
  61 When connecting to a Gemini URL, you may optionally identify yourself to the server with a cryptographic identity (technically, a TLS client certificate). You can create identities via the Identity button, or import them from another client by placing the .crt and .key files in gemini/identities/ under the koreader data directory.
  62
  63 Once you set an identity to be used at a URL, it will also be used at all subpaths. In particular, if you set an identity to be used at the root of a capsule (gemini://example.net/), it will be used on the whole of the capsule.
  64
  65 Identities are identified within the client by a "petname", which is also the filename they are stored under. This petname is not transmitted to servers you connect to. Some servers expect to see a username when you identify to them (the "Common Name" of the client certificate); this can optionally be set when creating an identity.
  66
  67 ## The queue, and offline use
  68 The queue is a list of URLs, intended to facilitate browsing and offline use. The Next button opens the next URL in the queue and deletes it from the queue. Long-pressing a link and selecting Add will append the link to the queue. You can also hold-drag to add multiple links at once through the text selection menu.
  69
  70 By default, if you have a network connection when you add a link to the queue, it will be fetched immediately. A fetched document is stored as temporary file, and can be accessed offline. Unfetched queue items can be fetched in the queue menu, accessible by long-pressing Next. Recent history and unhistory items are also kept as fetched documents. These features can be used to minimise the need to be online.
  71
  72 ## Certificate trust
  73 Gemini uses the same cryptography as HTTPS to secure connections, but with a simpler Trust-On-First-Use (TOFU) approach to verifying server identities. This is mostly invisible, but occasionally you will be asked to intervene, and you may then wish to read more about it:
  74 => about:tofu Further information on TOFU in Gemini and this client
  75
  76 ## Scheme proxies
  77 By setting proxies, you can use this client to browse gopher, http(s), and other protocols. Once a proxy server for a protocol scheme is set, navigating to a corresponding URL will make a gemini request to that server for that URL.
  78 => https://tildegit.org/solderpunk/agena Agena: proxy server software for gopher
  79 => https://github.com/LukeEmmet/duckling-proxy Duckling-proxy: proxy server software for http(s)
  80
  81 # About this client
  82 gemini.koplugin was written and is maintained by Martin Bays <mbays@sdf.org>, and is distributed under the terms of the GPLv3 or later.
  83 This is version %1.
  84 => gemini://gemini.thegonz.net/gemini.koplugin/ Client home page
  85 ]]), version),
  86     version = version,
  87     tofu = _([[
  88 # TOFU
  89 In place of the complex Certificate Authority based method used on the WWW, Gemini uses a Trust-On-First-Use (TOFU) approach to verifying server identities (which some users may know from SSH).
  90
  91 When you first connect to a server, the cryptographic server identity it presents (technically, the hashed public key of the tail certificate) is stored and considered trusted. As long as the same server identity is presented on subsequent connections to that host, it must indeed be the server you first connected to. If another server identity is ever presented, you will have to choose how to proceed. There are a few things it could mean:
  92 * The server operator changed their server identity. With a well-configured server, this should almost never happen -- essentially only if advances in technology/mathematics have rendered the underlying cryptography no longer secure. In practice however, some server operators use short-lived certificates which have to be changed once they expire, or are about to, and they (unnecessarily) change their server identity along with the certificate. You will be shown the expiry date to help you decide if this is likely to be what's happening.
  93 * Someone is pretending to be that server (a "meddler-in-the-middle attack"). If this is the case and you proceed with the connection, the attacker will be able to see everything the server usually could -- your requests, including any text input, and which identities you use -- and can interfere with the responses.
  94 * Someone *was* pretending to be that server when you first trusted the server identity, but now the attack has ended. To help you gauge the likelihood of this, you are shown the number of times you have seen the trusted server identity on previous connections.
  95
  96 You will also be shown a SHA256 digest of the certificate the server is now presenting, in case you have some out-of-band way of verifying that this is correct.
  97
  98 You will be given the option to permanently trust the new server identity (forgetting the old one), or to temporarily accept the new server identity for this connection (and for further connections to this host within the next hour), or to cancel the connection.
  99 ]]),
 100     welcome = _([[
 101 # Gemini client: First steps
 102 Welcome. To start using this plugin, please follow these two steps:
 103 * Swipe up, or select "Browse Gemini" from the menus, to bring up the navigation dialog.
 104 * Select Bookmarks; further help and starting points for exploration are available from there.
 105 ]]),
 106     xyzzy = "Nothing happens.",
 107     blank = "",
 108     default_bookmarks = _([[
 109 # Starting points
 110 => about:help Help on using this client
 111
 112 => gemini://kennedy.gemi.dev/search? Kennedy: Search engine
 113 => gemini://warmedal.se/~antenna/ Antenna: Gemlog aggregator
 114 => gemini://cdg.thegonz.net/ CDG: Capsule directory
 115 => gemini://bbs.geminispace.org/ BBS: Forum
 116 => gemini://geminiprotocol.net/ Gemini protocol home capsule
 117
 118 # User bookmarks
 119 Add entries here with the "Mark" button. Edit this file by long-pressing the "Bookmarks" button.
 120 ]]),
 121 }