convert README to gemtext

dimkr · May 12, 2023 · 5c0f95e · 5c0f95e
1 parent fddd945
commit 5c0f95e
Show file tree

Hide file tree

Showing 4 changed files with 73 additions and 46 deletions.
diff --git a/Makefile b/Makefile
@@ -73,7 +73,7 @@ clean:
 install: all
 	@install -D -m 755 $(BIN) $(DESTDIR)$(PREFIX)/bin/${BIN}
 	@install -D -m 644 gplacesrc $(DESTDIR)$(CONFDIR)/gplacesrc
-	@install -D -m 644 README.md $(DESTDIR)$(PREFIX)/share/doc/gplaces/README.md
+	@install -D -m 644 README.md $(DESTDIR)$(PREFIX)/share/doc/gplaces/README.gmi
 	@install -m 644 LICENSE $(DESTDIR)$(PREFIX)/share/doc/gplaces/LICENSE
 	@install -m 644 AUTHORS $(DESTDIR)$(PREFIX)/share/doc/gplaces/AUTHORS
 	@install -D -m 644 gplaces.1 $(DESTDIR)$(PREFIX)/share/man/man1/gplaces.1

diff --git a/README.md b/README.md
@@ -2,120 +2,139 @@
 
 Because Gemini deserves a light client with a high power to weight ratio!
 
-gplaces is named after [Going Places](https://en.wikipedia.org/wiki/Going_Places_(Herb_Alpert_and_the_Tijuana_Brass_album)), the 1965 album by Herb Alpert and The Tijuana Brass. The "o" is omitted from the executable name so it doesn't mess up tab completion for Gopher users and Go developers.
+gplaces is named after Going Places, the 1965 album by Herb Alpert and The Tijuana Brass. The "o" is omitted from the executable name so it doesn't mess up tab completion for Gopher users and Go developers.
 
-The gplaces logo is an artist's impression of a Gemini VII capsule with the red accents of a [Humes and Berg](https://humesandberg.com) Stonelined straight trumpet mute. Sort of.
+=> https://en.wikipedia.org/wiki/Going_Places_(Herb_Alpert_and_the_Tijuana_Brass_album) Going Places
 
-gplaces is originally a Gemini port of the [delve](https://github.com/kieselsteini/delve) Gopher client by Sebastian Steinhauer.
+The gplaces logo is an artist's impression of a Gemini VII capsule with the red accents of a Humes and Berg Stonelined straight trumpet mute. Sort of.
+
+=> https://humesandberg.com Humes and Berg
+
+gplaces is originally a Gemini port of the delve Gopher client by Sebastian Steinhauer.
+
+=> https://github.com/kieselsteini/delve delve
 
 ## Features
-- configurable MIME type handlers
-- "powerful" shell with tab completion
-- ~bookmarks~ use aliases
-- subscriptions
-	- only [simple subscriptions](https://gemini.circumlunar.space/docs/companion/subscription.gmi) are supported, to avoid [XML parsing](https://cve.mitre.org/cgi-bin/cvekey.cgi?keyword=xml)
-- variables
-- ~command aliases~ use variables
-- sh-style history with $XDG_DATA_HOME/gplaces_history or ~/.gplaces_history
-- permanent redirects with $XDG_DATA_HOME/gplaces_redirects or ~/.gplaces_redirects
-- VT100 compatible with ANSI escape sequences
-	- with [NO_COLOR](https://no-color.org/) support
-- no exotic external dependencies, no NIH
-	- ~GNU readline is fully optional~ bestline
-	- openssl or libressl
-	- libcurl
-	- libidn2 or libidn (optional)
-	- libmagic (optional)
-- SSH-style TOFU with $XDG_DATA_HOME/gplaces_hosts or ~/.gplaces_hosts
-- client certificates support via $XDG_DATA_HOME/gplaces_$host$path.{crt,key} or ~/.gplaces_$host$path.{crt,key}
-	- auto-generation with user consent
-	- strict implementation, [the certificate for /foo is used for /foo{,/,/bar}](https://gitlab.com/gemini-specification/protocol/-/blob/75fdc58c6f76a8172ccd7dbf90824dd6146ed0b6/specification.gmi#L116)
-- ~internal~ configurable external pager for text & menus
-- support for non-interactive operation
-- UTF-8 word wrapping
-- optional Gopher support
-- optional gophers:// (Gopher+TLS+TOFU) support
-- optional Spartan support
-- optional Finger support
-- hackable, ~about *1k lines* of *C* code~
-- ~100K executable when built with -O3 and -Wl,-s on x86_64
+* SSH-style TOFU with $XDG_DATA_HOME/gplaces_hosts or ~/.gplaces_hosts
+* client certificates support via $XDG_DATA_HOME/gplaces_$host$path.{crt,key} or ~/.gplaces_$host$path.{crt,key}
+* subscriptions
+* permanent redirects with $XDG_DATA_HOME/gplaces_redirects or ~/.gplaces_redirects
+* support for non-interactive operation
+* configurable MIME type handlers
+* "powerful" shell with tab completion, hints and aliases
+* VT100 compatible with ANSI escape sequences and NO_COLOR support
+* sh-style history with $XDG_DATA_HOME/gplaces_history or ~/.gplaces_history
+* UTF-8 word wrapping
+* configurable external pager
+* optional Gopher support
+* optional gophers:// (Gopher+TLS+TOFU) support
+* optional Spartan support
+* optional Finger support
+* small, hackable codebase
+* no exotic external dependencies, no NIH: bestline, openssl or libressl, libcurl, libidn2 or libidn (optional) and libmagic (optional)
+* ~100K executable when built with -O3 and -Wl,-s on x86_64
 
 ## How to install?
-- [using Flatpak](https://flathub.org/apps/details/com.github.dimkr.gplaces): `flatpak install flathub com.github.dimkr.gplaces`
-- compile yourself
+* Using Flatpak: `flatpak install com.github.dimkr.gplaces`
+=> https://flathub.org/apps/details/com.github.dimkr.gplaces gplaces on Flathub
+* compile yourself
 
 ## How to compile?
-- clone this git repo
-- just type `make` or `make WITH_LIBIDN2=0 WITH_LIBIDN=0 WITH_LIBMAGIC=0` on any Unix compatible system
-	- currently tested on
-		- Linux
-- type `make install` to install it on the system (defaults to /usr/local)
+* clone this git repo
+* type `make` or `make WITH_LIBIDN2=0 WITH_LIBIDN=0 WITH_LIBMAGIC=0`
+* type `make install` to install it on the system (defaults to /usr/local)
 
 ## How to use?
 
+```
     > gemini.circumlunar.space
+```
 
 to show a Gemini page, type its URL, press `ENTER` and gplaces will stream the page contents to the terminal.
 
 to abort the download, press `CTRL+c`.
 
 when the download is finished, gplaces will display the downloaded page using less(1), the same tool man(1) uses to display man pages.
 
+```
     `less -r` has exited with exit status 0
     gemini.circumlunar.space/> 
+```
 
 use the arrow keys to scroll, `/` to search and `q` to exit less and return to the gplaces prompt.
 
+```
     (reverse-i-search `g') gemini.circumlunar.space
+```
 
 in addition, gplaces adds the page URL to the history: use the `Up` and `Down` keys to navigate through the history, or `CTRL+r` to search through it. these are only three examples of key bindings from shells like bash(1) which work in gplaces, too.
 
+```
     cached 2023-04-29 19:41:44
     gemini.circumlunar.space/> 
+```
 
 if you visit the same page again, gplaces will return a cached copy and show the time the page was fetched. gplaces remembers up to `histsize` pages, so you can return to previously viewed pages immediately, without downloading them again. type `get` and press `ENTER` to force gplaces to fetch a cached page again.
 
+```
     > gemini://konpeito.media/konpeito-09-a.mp3
+```
 
 gplaces displays only Gemtext, gophermaps or plain text files: it downloads other kinds of files (like images, audio and video) to temporary files and runs external "handler" programs (one for each file type) defined in the gplaces configuration file.
 
+```
     > save gemini.circumlunar.space/docs/specification.gmi
     enter filename: /home/user/Downloads/specification.gmi
+```
 
 to download a file instead of displaying it or saving it to a temporary file, type `save`, followed by its URL, then press `ENTER`.
 
+```
     > save gemini.circumlunar.space/docs/specification.gmi /tmp/spec.gmi
+```
 
 you can also specify the destination path and skip the prompt.
 
+```
     > save gemini://konpeito.media/konpeito-09-a.mp3 -
+```
 
 alternatively, to stream a file into standard input of the handler program without saving to a file on disk and waiting for the download to complete, use `-` as the download destination. this is useful for audio or video streaming, and works only with some programs and some file formats.
 
+```
     gemini.circumlunar.space/> 2 docs/
+```
 
 gplaces associates a number with each link in the last viewed page. type the number of a link to show its URL, then press `ENTER` to follow it.
 
 to edit the URL of a link, type the link number, press `Tab`, edit the URL and press `ENTER`. for example, this is useful if a link leads to a post in another gemlog, but you want to see its homepage.
 
+```
     gemini.circumlunar.space/> #gemini://gemini.circumlunar.space/docs/
     gemini.circumlunar.space/> 
+```
 
 the history can be used as a reading list: prefix a URL with `#` and press `ENTER` to add it to the history without opening it first. for example, to add the URL of link 2 to the history, type `2`, press `Tab` to edit the URL, press `CTRL+a` or `Home` to go to the beginning of the line, type `#` and press `ENTER`. to open this URL later, press the `Up` key, press `CTRL+a` or `Home`, press `Delete` to remove the leading `#`, then press `ENTER`.
 
+```
     gemini.circumlunar.space/docs/> save 2
     enter filename (press ENTER for `/home/user/Downloads/specification.gmi`):
+```
 
 this number can be used to download the link, too.
 
+```
     gemini.circumlunar.space/docs/> search
     Search query> gplaces
+```
 
 the gplaces configuration file allows you to define short aliases for URLs you visit often. for example, the default configuration file defines the `home` alias for the Gemini project homepage and the `search` alias for a Gemini search engine. type `search` and press `ENTER` to search geminispace.
 
+```
     > geminispace.info/search gplaces
     > search gplaces
     > search "gemini client"
+```
 
 if a URL accepts input, you can specify the input in a second argument, to avoid another request to the same URL and skip the prompt. this works with aliases, too.
 
@@ -126,8 +145,8 @@ to exit gplaces, press `CTRL+d`.
 additional documentation and more details are available in `man gplaces`. type `help` and press `ENTER` to see short descriptions of available commands.
 
 ## How to contribute?
-- send me pull-requests and I'll review and merge them :)
-- if you wish to appear on the `help authors` command just add yourself there
+* send me pull-requests and I'll review and merge them :)
+* if you wish to appear on the `help authors` command just add yourself there
 
 ## License
-- [GPLv3](https://www.gnu.org/licenses/gpl-3.0.html)
+=> LICENSE GPLv3
diff --git a/com.github.dimkr.gplaces.appdata.xml b/com.github.dimkr.gplaces.appdata.xml
@@ -21,7 +21,7 @@
        <li>Support for other "small internet" protocols: Spartan, Gopher and Finger</li>
     </ul>
     <p>
-       gplaces should be fairly straightforward to use for anyone used to the command-line and man pages.
+       gplaces should be fairly straightforward to use for anyone used to the command-line and man pages. Type <code>readme</code> for a short introduction.
     </p>
   </description>
 
@@ -39,6 +39,14 @@
   <developer_name>Dima Krasner</developer_name>
 
   <releases>
+    <release date="2023-05-12" version="0.17.5">
+      <description>
+        <ul>
+          <li>README is converted to Gemtext</li>
+        </ul>
+      </description>
+    </release>
+
     <release date="2023-05-06" version="0.17.4">
       <description>
         <ul>

diff --git a/gplacesrc.in b/gplacesrc.in
@@ -9,7 +9,7 @@ set video/							"mpv %f"
 set application/pdf					"xdg-open %f"
 
 # define some aliases
-set readme							file://DOCDIR/README.md
+set readme							file://DOCDIR/README.gmi
 set license							file://DOCDIR/LICENSE
 set authors							file://DOCDIR/AUTHORS
 set search							geminispace.info/search