From 2848440591884514103712ca34f23b3f5a61684e Mon Sep 17 00:00:00 2001 From: Case Duckworth Date: Wed, 15 Jun 2022 10:11:44 -0500 Subject: Add README --- README.txt | 176 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 176 insertions(+) create mode 100644 README.txt (limited to 'README.txt') diff --git a/README.txt b/README.txt new file mode 100644 index 0000000..c409335 --- /dev/null +++ b/README.txt @@ -0,0 +1,176 @@ +# HAT TRICK + +HAT TRICK is both a lightweight markup language inspired by gemtext and html, +and this awk program to convert the markup language to gemtext, html, and +gophermap markup. It uses a mixture of "block"-level and line-level sigils to +extend the pure line-based markup of gemtext, while removing some of the more +annoying points (to my mind) of writing pure html---i.e., repetitive tags and +other boilerplate. + +## Syntax + +### Blocks + +In HAT TRICK, block of text separated by a blank line is a type of "block." The +default block is a paragraph, or

tag in html. (In gemini and gophermaps, no +extra tags are added.) Other blocks defined by the syntax are as follows: + +>>> +# HEADING 1 +## HEADING 2 +### HEADING 3 +<<< + +Correspond to in html; passed through unmodified to gemtext and gophermaps. + +>>> +> BLOCK QUOTE +<<< + +Corresponds to

; passed through unmodified to gemtext and +gophermaps. + +>>> +- UNORDERED LIST ITEM +1. ORDERED LIST ITEM +<<< + +The first list item in a block automatically opens the necessary list tag in +html. In gemtext, the "-" is converted to "*" (which signifies a list item); +the hyphen is passed through in gophermaps, because I think it's better syntax +personally. + +>>> +--- SECTION BREAK +<<< + +A visual indication to break sections. Corresponds to
in html +(TODO: consider html5
tags --- this would take more logic.) + +HAT TRICK reflows blocks, which means that only the first line of a block +needs to start with the sigils outlined above. However, each line of the block +can begin with the sigil character for easier reading. + +### Lines + +Within blocks, there are certain other sigils that apply only to the line they +prepend. They include the following: + +>>> +=> LINK +<<< + +Links are probably the most important element in any hypertext language---since +without them, it's hardly hypertext. HAT TRICK borrows its link syntax from +gemtext: the line starts with a "=>", the next field is the link's URL, and the +rest of the line is the link's display text. + +>>> + HTML TAG +<<< + +Lines beginning with an html tag are passed on to html verbatim. The closing +tag is automatically appended to the end of the line, before any ending +punctuation. I've found that 99 times out of 100, I don't want formatting to +include the ending punctuation. + +A backslash (\) at the end of the tag line will prevent the tag from being +ended, which is useful for tag-included punctuation as well as nesting tags. +However, the tag is never closed, so you'll have to close it yourself on the +next line. In addition, text that isn't in a tag is html-escaped, so for the +markup to properly apply, you'll need to write something like this: + +>>> +She sells \ +sea shells \ + +on the sea shore.\ + +<<< + +So while this markup is possible, it's discouraged through the awkwardness of +the syntax. + +To translate these tags to meaningful markup in gemtext and gophermaps, a lookup +table is used to correspond the tags to opening and closing characters around +the line's text. This correspondance can be defined with the environment +variable HT_TAGCHARS or HAT TRICK's second positional argument (See INVOCATION, +below). + +>>> +; COMMENT +<<< + +Comments in HAT TRICK aren't passed on to the output text---even in html, which +has a comment syntax. Instead, comments are passed, including the prepending +semicolon, to standard error for further processing. + +### Verbatim blocks + +Finally, there is a special type of block for passing raw text through to the +next phase of processing: the verbatim block. + +>>> + >>> [OUTPUTS] + VERBATIM TEXT + <<< +<<< + +In html, the verbatim text is wrapped in 
 tags; in gemtext, it's
+wrapped in gemtext's own verbatim text markers ```; and the text is unwrapped in
+gophermaps for a cleaner look.
+
+The OUTPUTS can be any output specifier HAT TRICK accepts; see INVOCATION below
+for details.  If OUTPUTS is present, the verbatim text will only be passed
+through in the output formats listed; with no OUTPUTS listed it will output to
+all formats.
+
+## "Escaping" line- and block-types
+
+Each of the types listed above are anchored at the beginning of the line.
+Therefore, a simple "escaping" mechanism is available for free: simply prepend a
+space to any line you don't want processed as a line or block and you'll be
+gravy.  Astute readers will notice I did just that above, to describe the syntax
+for verbatim fencing.
+
+## Invocation
+
+An invocation of HAT TRICK will look something like this:
+
+>>>
+./ht.awk [HT_FORMATS] [HT_TAGCHARS] < INPUT
+<<<
+
+It processes text from standard input and uses two positional parameters to
+customize its usage, in addition to environment variables.  In each instance,
+the parameter will override the variable, and if neither are provided, HAT TRICK
+will choose a default.
+
+### HT_FORMATS (default: "html")
+
+The format(s) to export to.  Can be one or more of "html", "gemini", and
+"gopher".  As a convenience, a format can be prepended with a "-" (i.e.,
+"-html"), in which case every other format will be exported to.  Multiple
+formats can also be specified by separating them with a comma.  The special
+keyword "all" will export to all formats (this is the default).
+
+If HAT TRICK exports to one format, it will simply print out each line
+translated into that format.  However, if more than one format is given, 
+HAT TRICK prints each line multiple times, prepending the name of the format to
+the output.  This allows for further processing to filter outputs according to
+output type with just one pass through the input.
+
+### HT_TAGCHARS (default: 'b:**,i://,code:``')
+
+The correspondance between html tag lines and other output formats.  If
+HT_FORMAT is only html, this option has no real meaning.
+
+Each correspondance is of the (exploded) form
+
+>>>
+TAG : LEFT_CHAR RIGHT_CHAR
+<<<
+
+where TAG is the html tag, LEFT_CHAR is the character on the left of the
+enclosed text, and RIGHT_CHAR is the character on the right.  Rules can be
+separated by commas to pass multiple ones to HAT TRICK.
-- 
cgit 1.4.1-21-gabe81