1# a gemtext converter
2
3*NOTE: this readme only sort of describes the use of clarence. i'm working on it.*
4
5gemtext is *almost* perfect---it's only missing a few things, roughly in order of disruption to the existing spec:
6
7* lightweight inline markup: *strong*, _emphasis_, =code=, etc.
8* "smart" punctuation, like “...”, —, etc.
9* extra verbatim properties and filters
10* a handful of extra line types
11* line continuation (?)
12
13clarence attempts to address these issues and provide a compatible way to export gemtext documents to richer formats, like html. in this project my explicit goals are as follows:
14
15* provide a way for gemtext to "scale up" to more expressive formats like HTML or LaTeX while staying readable as plain gemtext
16* provide a gemtext normalization function to remove breaking changes in a build step to gemtext
17* allow for all extra functionality to be turned off
18* be reasonably extensible (maybe)
19
20## using clarence
21
22```
23clarence [-f FORMAT] [-o FILE] FILE
24clarence [OPTIONS] < FILE [> FILE]
25```
26
27* FORMAT is one of =gemtext= =html=.
28* -o FILE specifies the output file. You can also pipe clarence's output wherver.
29* if a FILE is given on the command line, it's read as input; otherwise clarence reads standard input.
30
31
32## installing clarence
33
34you'll need
35* sbcl (i have version 2.1.11) -- or possibly any CL impl (not tested)
36* common lisp libraries CL-PPCRE, CLINGON
37* I think that's it..?
38
39```
40make
41make install
42```
43
44or do the sbcl commands yourself, i don't care.
45
46we're not on quicklisp yet, womp
47
48## rationale
49
50### inline markup
51
52i think one of the main things markdown got right was how it made writing inline markup like *bold* and _italic_ text much easier than plain HTML. adding this functionality to gemtext is pretty straight forward and i think degrades gracefully the same way as it does in markdown. to keep the line-based nature of gemtext the inline tags can't span lines, making the implementation even simpler: basically a search and replace for =\*[^*]\*= and the like.
53
54what works:
55* * bold * , _ italic _ , = code = (without spaces) => *bold*, _italic_, =code=
56what doesn't:
57* no escaping logic at the moment, which e.g. just now came up
58
59### extra verbatim properties and filters
60
61another thing that I *personally* think is a good idea for gemtext as an authoring format is extension through filtering, that is, using properties on ```-delimited text to call other programs on preformatted blocks for nicer output in output formats. the example that immediately comes to mind is tables:
62
63```
64 ```|table
65 | State | Capital |
66 | New York | Albany |
67 | Tennessee | Nashville |
68 | Maine | Augusta |
69 ```
70```
71
72In this example, =table= is the name of some Unix filter that will convert the table shown above into, say, an HTML table or a LaTeX table or what-have-you. A benefit is that the table is still fairly readable in a plain gemtext context as well -- though the =table= utility could also align columns for plaintext output.
73
74### verbatim filter syntax
75
76the trickiest part is figuring out the syntax of verbatim filters. features i want:
77
78* =|filter= means pipe the contents of the verbatim block to the filter, allowing other verbatim alt-text lines to still have meaning
79* some way to pass the current output to the program -- i'm thinking env vars
80
81* i've thought that having directives to *only* filter a block if it's a given output format, or hide it altogether, would be good --- but i'm starting to think that's against the spirit of gemini
82
83### smart punctuation [NOT IMPLEMENTED]
84
85i think smart punctuation can be somewhat overblown, but it can also be useful. i especially find -- as en-dash and --- as em-dash useful, and really, the smart quotes thing is only marred by the fact that the regular rules aren't intuitive (to me). double quotes are easy: they enclose the text, so if whitespace is on the left it's a left quote, and otherwise it's a right quote.
86
87single quotes are more complex though: they're also used as apostrophes, share the same appearance as right quotes even when beginning a word. thus, "'twas" does not look the same as "he said, 'are you sure?'" because the first use is rarer, i'm going to do this:
88
89- ' is for "default" smart quotes -- that is, whitespace on left means it's a left quote, otherwise it's a right quote.
90- ` is for "reverse" quotes -- it reverses the meaning of '
91
92so 'twas becomes `twas. not the most beautiful, but functional.
93
94### extra line types [NOT IMPLEMENTED]
95
96### horizontal rules
97
98sometimes it's nice to have a thematic break. in clarence gemtext, =---= makes a <hr> in html while staying as-is in gemtext, which gets the meaning across just fine.
99
100### metadata lines
101
102in an earlier iteration i had =:= introduce a metadata line, structured like a link but containing metadata. the other day i had a thought that maybe having page metadata all in its own index file would be a better idea.... also metadata doesn't add anything really to the document's view, which would be needed for gemtext compat. the same goes for comments as well...
103
104### escaping
105
106the conventional wisdom with escaping text lines that start with one of the special characters is to prepend it with a space. is this what i want? do i want to use a backslash? should i remove one prepended space, all prepended spaces, ... ?
107
108### line continuation [NOT IMPLEMENTED]
109
110gemtext is a line-based format, with but one state variable: verbatim-ness. i don't want to break that, but at the same time i want the ability to split a paragraph across lines or continue list items for readability ...
111
112or now that i'm thinking about it, *do i?* i'm writing this document in emacs with everything as one big line, and it's fine! i have visual-line-mode, visual-fill-column-mode, and adaptive-wrap-prefix-mode all on, and it's doing exactly what i want it to do, to be honest.
113
114## contact
115
116uh, questions? comments? email me at
117=> mailto:acdw@acdw.net acdw@acdw.net