1 files changed, 62 insertions, 1 deletions

@@ -1,5 +1,66 @@
 # jimmy --- convert .gmi to .html and other formats
 
-[to be documented]
+`jimmy` is a tool that I wrote to allow me to write
+=> https://geminiprotocol.net/docs/gemtext-specification.gmi gemtext
+and output various other formats.
+It differs somewhat (I assume; I haven't checked) from other such tools in that
+it allows the author to write *lightly modified* gemtext source that can then be
+normalized by the tool as well as converted to other formats like HTML.
 
+The main goals for this project are as follows:
 
+* jimmy text should be easy to write and easy to read using the bare minimum of
+  tools
+* jimmy text should be *as close as possible* to canonical gemtext while
+  providing some QOL and expressivity extensions
+
+Jimmy text should not differ *enough* from gemtext so that special editor
+plugins are needed, for example, or so that dumb gemini clients will render the
+output differently than plain text.  Smart ones, that do autoformatting of lines
+on display, might display jimmy text differently---which is why the tool also
+offers a normalization function.
+
+## How jimmy text differs from gemtext
+
+### Compatible changes
+
+* Paragraphs "auto-wrap", that is, they can be on multiple contiguous lines and
+  will be automatically merged into one line on normalization.
+* Links can be "inline" in paragraphs.  If links are surrounded by paragraph
+  lines, they'll render as regular `<a>` tags in html.  If they appear in a list
+  apart from other paragraphs, they'll render as an unordered list of links.
+* Metadata lines for templating: lines of the form `: key value...` are not
+  rendered but are saved to be referenced in templates and the like.
+  Recommended: put these lines at the end of documents so that normal gemtext
+  readers will show them, but they won't be distracting.
+* Inline syntax is allowed: *strong*, _em_, and `code` tags are generated for
+  html in the default configuration, and you can add others if you like.  These
+  tags do not stretch over source line breaks, and there is no check as to
+  whether they're properly nested.
+
+### Incompatible changes
+
+This section should be as short as possible, of course.  They're incompatible in
+that a complying gemtext reader will interpret their meanings as different from
+what jimmy text outputs.  These changes are behind a flag (TODO!) and can be
+disabled at run-time.
+
+* Lines beginning with two or more spaces are automatically joined with the
+  previous line on output.
+
+## Installing jimmy
+
+Jimmy requires CHICKEN 5.3+ as well as the following eggs:
+
+* module-declarations
+* utf8
+
+To install, simply run `make install`.  You can uninstall with `make uninstall`.
+
+## Using jimmy
+
+TODO
+
+## License
+
+Jimmy is free software licensed under the BSD 3-Clause license.  See COPYING for details.