staticgemtexts.lua

   1 local _ = require("gettext")
   2 local T = require("ffi/util").template
   3
   4 local version = "0.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. The cog icon in the nav title bar toggles advanced button actions, which can also be accessed by long-pressing on the button.
  31 * Identity: Set/change the identity being used at the URL (see below). Advanced: Edit these associations.
  32 * Page Info: Show certificate and other information on the current URL. Advanced: Show page source.
  33 * Back: Go back one page in history. Advanced: History menu.
  34 * Unback: Go forwards one page in history; enabled after going back. Advanced: History menu.
  35 * Next: Go to next page in the queue (see below). Advanced: Queue menu.
  36 * Add: Append URL to the queue (see below). Advanced: Add URL to start of queue.
  37 * Bookmarks: Show bookmarks page. Advanced: Edit bookmarks.
  38 * Mark: Append URL to bookmarks page. Advanced: Quick-add without asking for a description.
  39 * Up: Modify URL by deleting the last component of the path. Advanced: Go all the way up to the root.
  40 * Save: Saves page to filesystem.
  41 * Go: Go to URL, reloading if it's the current URL. Advanced: First set a query.
  42
  43 ## Troubleshooting
  44 If loading pages is slow, consider disabling the "Reading statistics" plugin.
  45
  46 ## Identities
  47 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.
  48
  49 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.
  50
  51 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.
  52
  53 ## The queue, and offline use
  54 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.
  55
  56 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.
  57
  58 ## Certificate trust
  59 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:
  60 => about:tofu Further information on TOFU in Gemini and this client
  61
  62 ## Scheme proxies
  63 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.
  64 => https://tildegit.org/solderpunk/agena Agena: proxy server software for gopher
  65 => https://github.com/LukeEmmet/duckling-proxy Duckling-proxy: proxy server software for http(s)
  66
  67 # About this client
  68 gemini.koplugin was written and is maintained by Martin Bays <mbays@sdf.org>, and is distributed under the terms of the GPLv3 or later.
  69 This is version %1.
  70 => gemini://gemini.thegonz.net/gemini.koplugin/ Client home page
  71 ]]), version),
  72     version = version,
  73     tofu = _([[
  74 # TOFU
  75 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).
  76
  77 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:
  78 * 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.
  79 * 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.
  80 * 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.
  81
  82 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.
  83
  84 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.
  85 ]]),
  86     welcome = _([[
  87 # Gemini client: First steps
  88 Welcome. To start using this plugin, please follow these two steps:
  89 * Swipe up, or select "Browse Gemini" from the menus, to bring up the navigation dialog.
  90 * Select Bookmarks; further help and starting points for exploration are available from there.
  91 ]]),
  92     xyzzy = "Nothing happens.",
  93     default_bookmarks = _([[
  94 # Starting points
  95 => about:help Help on using this client
  96
  97 => gemini://kennedy.gemi.dev/search? Kennedy: Search engine
  98 => gemini://warmedal.se/~antenna/ Antenna: Gemlog aggregator
  99 => gemini://cdg.thegonz.net/ CDG: Capsule directory
 100 => gemini://bbs.geminispace.org/ BBS: Forum
 101 => gemini://geminiprotocol.net/ Gemini protocol home capsule
 102
 103 # User bookmarks
 104 Add entries here with the "Mark" button. Edit this file by long-pressing the "Bookmarks" button.
 105 ]]),
 106 }