3 files changed, 89 insertions, 1 deletions

@@ -0,0 +1,26 @@
+Copyright Case Duckworth <acdw@acdw.net>
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors
+   may be used to endorse or promote products derived from this software without
+   specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
\ No newline at end of file
@@ -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.
@@ -1,5 +1,6 @@
 ((author "Case Duckworth")
  (synopsis "The ssg king")
+ (license "BSD-3-clause")
  (dependencies (chicken "5.3.0")
                module-declarations
                utf8)