diff options
author | Case Duckworth | 2024-06-04 13:05:06 -0500 |
---|---|---|
committer | Case Duckworth | 2024-06-04 13:05:06 -0500 |
commit | ece8ab695c636cdd4fd0cab6eafacde36a9bfec9 (patch) | |
tree | cb266343e9a0a5e033f1aa20fb5a62028039e20f /README.gmi | |
parent | Add repl.scm (diff) | |
download | jimmy-ece8ab695c636cdd4fd0cab6eafacde36a9bfec9.tar.gz jimmy-ece8ab695c636cdd4fd0cab6eafacde36a9bfec9.zip |
Update README, add COPYING
Diffstat (limited to 'README.gmi')
-rw-r--r-- | README.gmi | 63 |
1 files changed, 62 insertions, 1 deletions
diff --git a/README.gmi b/README.gmi index 734ec08..a3e10fd 100644 --- a/README.gmi +++ b/README.gmi | |||
@@ -1,5 +1,66 @@ | |||
1 | # jimmy --- convert .gmi to .html and other formats | 1 | # jimmy --- convert .gmi to .html and other formats |
2 | 2 | ||
3 | [to be documented] | 3 | `jimmy` is a tool that I wrote to allow me to write |
4 | => https://geminiprotocol.net/docs/gemtext-specification.gmi gemtext | ||
5 | and output various other formats. | ||
6 | It differs somewhat (I assume; I haven't checked) from other such tools in that | ||
7 | it allows the author to write *lightly modified* gemtext source that can then be | ||
8 | normalized by the tool as well as converted to other formats like HTML. | ||
4 | 9 | ||
10 | The main goals for this project are as follows: | ||
5 | 11 | ||
12 | * jimmy text should be easy to write and easy to read using the bare minimum of | ||
13 | tools | ||
14 | * jimmy text should be *as close as possible* to canonical gemtext while | ||
15 | providing some QOL and expressivity extensions | ||
16 | |||
17 | Jimmy text should not differ *enough* from gemtext so that special editor | ||
18 | plugins are needed, for example, or so that dumb gemini clients will render the | ||
19 | output differently than plain text. Smart ones, that do autoformatting of lines | ||
20 | on display, might display jimmy text differently---which is why the tool also | ||
21 | offers a normalization function. | ||
22 | |||
23 | ## How jimmy text differs from gemtext | ||
24 | |||
25 | ### Compatible changes | ||
26 | |||
27 | * Paragraphs "auto-wrap", that is, they can be on multiple contiguous lines and | ||
28 | will be automatically merged into one line on normalization. | ||
29 | * Links can be "inline" in paragraphs. If links are surrounded by paragraph | ||
30 | lines, they'll render as regular `<a>` tags in html. If they appear in a list | ||
31 | apart from other paragraphs, they'll render as an unordered list of links. | ||
32 | * Metadata lines for templating: lines of the form `: key value...` are not | ||
33 | rendered but are saved to be referenced in templates and the like. | ||
34 | Recommended: put these lines at the end of documents so that normal gemtext | ||
35 | readers will show them, but they won't be distracting. | ||
36 | * Inline syntax is allowed: *strong*, _em_, and `code` tags are generated for | ||
37 | html in the default configuration, and you can add others if you like. These | ||
38 | tags do not stretch over source line breaks, and there is no check as to | ||
39 | whether they're properly nested. | ||
40 | |||
41 | ### Incompatible changes | ||
42 | |||
43 | This section should be as short as possible, of course. They're incompatible in | ||
44 | that a complying gemtext reader will interpret their meanings as different from | ||
45 | what jimmy text outputs. These changes are behind a flag (TODO!) and can be | ||
46 | disabled at run-time. | ||
47 | |||
48 | * Lines beginning with two or more spaces are automatically joined with the | ||
49 | previous line on output. | ||
50 | |||
51 | ## Installing jimmy | ||
52 | |||
53 | Jimmy requires CHICKEN 5.3+ as well as the following eggs: | ||
54 | |||
55 | * module-declarations | ||
56 | * utf8 | ||
57 | |||
58 | To install, simply run `make install`. You can uninstall with `make uninstall`. | ||
59 | |||
60 | ## Using jimmy | ||
61 | |||
62 | TODO | ||
63 | |||
64 | ## License | ||
65 | |||
66 | Jimmy is free software licensed under the BSD 3-Clause license. See COPYING for details. | ||