# jimmy --- convert .gmi to .html and other formats

`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 (UNIMPLEMENTED)

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 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:

* args
* module-declarations
* utf8

To install, simply run `make install`.  You can uninstall with `make uninstall`.

## Using jimmy

You can run jimmy on the command line as a filter or on a file.  Run it like
this:

```
jimmy [OPTIONS...] [FILE]
```

FILE, if present, is the file to read; otherwise read standard input.

The available options comprise

* *-t, --to=FORMAT* --- Translate the input to FORMAT, one of `gemini`, `html`,
  or a filename with format specifications in it (see OUTPUT FORMATS, below).
* *-n, --no-extensions* --- Don't enable any of the breaking extensions to
  gemtext outlined above (NOT IMPLEMENTED)
* *-T, --template=TEMPLATE* --- Wrap the generated text in TEMPLATE using
  metadata from the document (see TEMPLATES, below).
* -h, --help --- Show the help text and exit

### Output Formats



### Templates

## License

Jimmy is free software licensed under the BSD 3-Clause license.  See COPYING for details.