From 1c8e5f1ca9bf0eb6dad8a62bc87428610d96c350 Mon Sep 17 00:00:00 2001 From: Case Duckworth Date: Wed, 3 Aug 2022 23:36:07 -0500 Subject: Begin anew I think this might really be something! --- README.txt | 176 ------------------------------------------------------------- 1 file changed, 176 deletions(-) delete mode 100644 README.txt (limited to 'README.txt') diff --git a/README.txt b/README.txt deleted file mode 100644 index c409335..0000000 --- a/README.txt +++ /dev/null @@ -1,176 +0,0 @@ -# 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