1 files changed, 94 insertions, 8 deletions

diff --git a/res/about/help.gmi b/res/about/help.gmi
index 3f21adb8..f71f5164 100644
--- a/res/about/help.gmi
+++ b/res/about/help.gmi
@@ -63,7 +63,7 @@ Lagrange's user interface is modeled after web browsers:
 
 * There is a navigation bar at the top with Back and Forward buttons.
 * There is a tab bar for switching tabs. The tab bar is hidden if there is only one tab open.
-* There is a sidebar for managing bookmarks and TLS identities, and viewing history and the page outline. The sidebar is hidden by default.
+* There is a sidebar for managing bookmarks and TLS identities, and viewing history and the page outline. Sidebars are hidden by default.
 * There is a search bar that appears at the bottom when searching text on the page.
 
 Tip: Try pressing ${CTRL+}5 now to see the page outline.
@@ -126,17 +126,17 @@ Press ${CTRL+}T to open a new tab, and ${CTRL+}W to close the current tab. Right
 
 The set of open tabs is restored when you launch Lagrange.
 
-## Sidebar
+## Sidebars
 
-The sidebar can be toggled via menus or by pressing ${SHIFT+}${CTRL+}L. It has five tabs:
+The sidebars can be toggled via menus or by pressing ${SHIFT+}${CTRL+}L or ${SHIFT+}${CTRL+}P (for the left/right sidebar, respectively). Both sidebars have five tabs:
 
 * Bookmarks: List of bookmarks that you've created. These appear first in search results for quick and easy access.
-* Feeds: Entries found on subscribed feed index pages.
+* Feeds: Entries found on subscribed pages.
 * History: Chronological list of visited URLs. This is not a full history of all the URLs you've accessed over time — only unique URLs are shown at the latest access time.
 * Identities: TLS client certificates.
 * Outline: List of the headings in the currently open tab. Useful when reading longer documents.
 
-${CTRL+}1 through ${CTRL+}5 switch between the sidebar tabs, or hide the sidebar if the current tab's key is pressed. You can also press Escape to dismiss the sidebar.
+${CTRL+}1 through ${CTRL+}5 switch between the left sidebar tabs, or hide the sidebar if the current tab's key is pressed. You can also press Escape to dismiss sidebars.
 
 ## Bookmarks
 
@@ -150,10 +150,11 @@ In addition to a title, bookmarks can have tags. Some tags have a special meanin
 
 * Set a "homepage" tag on a bookmark to make it one of the pages that will be opened when pressing the 🏠 button. If multiple bookmarks are tagged as homepages, a random one is selected.
 * A "subscribed" tag means that Lagrange will periodically fetch the bookmarked page and look for Gemini feed links. All the found links that match the required style ("YYYY-MM-DD Entry title") will appear in the Feeds sidebar tab.
+* "headings" can be used together with "subscribed" to subscribe to new headings instead of Gemini feed links.
 
 ## Feeds
 
-You may be familiar with RSS and Atom XML feeds from the web. Lagrange does _not_ support RSS/Atom, only Gemini feeds. A Gemini feed is simply a regular 'text/gemini' page that contains one or more links whose labels are formatted in a particular way.
+You may be familiar with RSS and Atom XML feeds from the web. Lagrange does _not_ support RSS or Atom, only Gemini feeds. A Gemini feed is simply a regular 'text/gemini' page that contains one or more links whose labels are formatted in a particular way.
 
 => gemini://gemini.circumlunar.space/docs/companion/subscription.gmi  See "Subscribing to Gemini pages" for more information.
 
@@ -213,8 +214,6 @@ You can find a number of settings in Preferences to customize the user interface
 
 ### Browsing behavior
 
-The "Outline on scrollbar" option shows the page outline when the mouse cursor is moved over the scrollbar, allowing one to better navigate long documents. The outline will disappear after the mouse cursor is moved away. If you need a persistent outline, one is always available in the sidebar.
-
 One important characteristic of Gemini is that you remain in control of what gets loaded and when. The browser will not suddenly fetch a ton of images, autoplay videos, or make surreptitious connections to any tracking servers — each network request is purposeful and manually triggered. With this in mind, the "Load image on scroll" option is provided to assist keyboard-only browsing and to facilitate a focused reading experience. When enabled, if there is an image link visible on the page and you press Space or ↓, it will be loaded and shown inline _instead_ of the view scrolling down. This allows you to read and see all the content of the page while only tapping on a single key on the keyboard.
 
 ### Window and UI options
@@ -315,12 +314,99 @@ Other Unix : ~/.config/lagrange/
 
 * bindings.txt
 * bookmarks.txt
+* feeds.txt
 * idents.binary and idents/
+* mimehooks.txt
 * prefs.cfg
 * state.binary
 * trusted.txt
 * visited.txt
 
+# MIME hooks
+
+MIME hooks enable piping Gemini responses through external programs for arbitrary processing. This allows leveraging scripting languages and binary executables to perform format conversions, content transformation, and data analysis.
+
+Hooks are configured using the file "mimehooks.txt" in Lagrange's config directory. Each hook has a regexp that is matched against the response MIME type and parameters, and each matching hook is offered the response body via stdin. The called external programs are free to rewrite the entire response, including the MIME type. If one of the hooks returns a valid response, it is used as the final response of the Gemini request.
+
+Example use cases:
+* Parsing an Atom XML feed and generating a Gemini feed index page
+* Rendering a MIDI file using Timidity as PCM WAV
+* Generate a graph PNG based on values in a CSV
+* Converting HTML or Markdown to 'text/gemini'
+* Language translations
+
+## Interface
+
+When a hook is called, it is given the MIME type and parameters via command line arguments. The response body is provided via stdin. The request's URL is available in the REQUEST_URL environment variable.
+
+The MIME type and parameters are split at semicolons, so "text/gemini; lang=ja" would be called as:
+```
+hookprogram text/gemini lang=ja 
+```
+
+Output from the program (via stdout) must be a valid "20" Gemini response that includes the new MIME type:
+```
+20 text/gemini; lang=en\r\n
+{...body...}
+```
+
+Any output that does not follow this format is considered to mean that the hook refused to process the contents. The next hook will be offered the response instead.
+
+## mimehooks.txt syntax
+
+Like other Lagrange configuration lines, mimehooks.txt has a simple line-oriented syntax. Lagrange must be restarted for changes to the configuration file to take effect.
+
+Each hook is specified as three lines:
+* A human-readable label (for reporting to the user)
+* MIME type/parameter regular expression
+* Command to execute, plus additional arguments each separated with semicolons
+
+For example:
+```
+Convert Atom to Gemini feed
+application/xml
+/usr/bin/python3;/home/jaakko/atomconv.py
+```
+
+The hook program is executed directly without involving the shell. This means scripts must be invoked via the interpreter executable.
+
+## Example: Converting from Atom to Gemini
+
+The 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.
+```
+import sys
+import xml.etree.ElementTree as ET
+
+def atomtag(n):
+    return '{http://www.w3.org/2005/Atom}' + n
+
+root = ET.fromstring(sys.stdin.read())
+if root.tag != atomtag('feed'): 
+    sys.exit(0)
+feed_title = ''
+feed_author = ''
+feed_entries = []
+for child in root:
+    if child.tag == atomtag('title'):
+        feed_title = child.text
+    elif child.tag == atomtag('entry'):
+        feed_entries.append(child)        
+print("20 text/gemini\r")
+print(f'# {feed_title}')
+for entry in feed_entries:   
+    entry_date = ''
+    entry_title = ''
+    entry_link = ''
+    for child in entry:        
+        if child.tag == atomtag('updated'): 
+            entry_date = child.text[:10]
+        elif child.tag == atomtag('title'):
+            entry_title = child.text
+        elif child.tag == atomtag('link'): 
+            entry_link = child.attrib['href']
+    print(f'=> {entry_link} {entry_date} {entry_title}')
+```
+
 # Open source licenses
 
 => about:license