Users Guide by Richard Rathe, v0.17, December 2024
KIST combines the best elements of various markup formats I've worked with over the past forty years. The original purpose of these tools was to quickly generate valid HTML. The plain text source files are nearly universal and reusable!
KIST aspires to the Least Ink Principle proposed by Edward Tufte in 1983 (paraphrased): The best documentation is that which gives to the reader the greatest amount of information in the shortest time with the fewest pixels.
KIST aspires to Fail Gracefully when something isn't quite right.
KIST uses Open Standards whenever and wherever possible!
Basic Rules
The source text must remain easily understood by casual readers.
Prefer UTF8 encoding for maximum portability and compatibility.
Example: Люди рождаются свободными
Prefer newline (ASCII 10) characters to indicate end-of-line (EOL).
Blank lines separate elements from each other.
Most extra whitespace will be ignored (eg, one blank line is the same as ten).
Tabs (ASCII 09) have special meaning in certain contexts:
Leading tabs indicate list items.
Embedded tabs indicate tabular data.
Various punctuation characters (^, #, =, etc.) may also have special meaning.
Headings and lists should be well structured (hierarchal).
File names should end in .txt (plain text).
The first line of content becomes the document title (see Headings below).
Line Level Elements
These elements affect entire lines of text and provide the overall structure of the document. A basic layout is very simple…
Document Title (<h1>)
text, lists, tables…
#Heading 1 (<h2>)
more content…
#Heading 2 (<h2>)
etc…
Paragraphs (<p>)
Generic text not otherwise marked up will flow into paragraphs.
This is a paragraph
of words that are on
different lines.
Quisque viverra,
ligula vitae aliquam
vulputate.
Next element starts here…
This is a paragraph
of words that are on
different lines.
Quisque viverra,
ligula vitae aliquam
vulputate.
Next element starts here…
Note that inline images (discussed below) are technically line level elements and behave like paragraphs.
Headings (<h1> etc.)
The first line is considered the top level heading <h1>.
Use # to ##### leading hashs for <h2> to <h6>.
It is up to the author to nest these properly!
Whitespace following # will be ignored for readability.
Full Hierarchy
# One # <h2>
## Two ## <h3>
### Three ### <h4>
#### Four #### <h5>
##### Five ##### <h6>
Lists (<ul>, <ol>)
Lists are unordered <ul> by default.
A leading tab indicates a list item <li>.
Use \ chars when you cannot type tabs (web pages).
The number of tabs determines nesting.
It is up to the author to nest these properly!
Simple List Example
tree
apple
pencil
List Title Example
A single leading ^ after first <tab> indicates a title.
^List of Fruit
apple
banana
orange
List of Fruit
apple
banana
orange
Ordered List Example
A single leading # after first <tab> indicates an ordered list <ol>.
#Lorem ipsum dolor… etc.
Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Curabitur eu augue. Nunc sollicitudin felis sed purus. Morbi libero tellus, laoreet sed, fringilla id, nonummy in, sapien. Nulla facilisi.
Lines beginning with equals signs = are passed through as is with no additional formatting.
Note that long lines can extend far beyond the right margin of the page!
line 1 Integer a *eros vitae* felis scelerisque gravida.
line 2 Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Pellentesque ullamcorper odio in ipsum.
line 4 Note the extra spaces!
Tables
Direct use of tab-separated values (.tsv or .tab files).
It is up to the author to ensure data consistency!
First char must not be a tab (indicating a list item).
A leading ^ char on the first line indicates column headings.
As with lists, \ chars may be used when tabs cannot be typed.
Simple Table Example
1
2
3
4
5
6
7
8
9
Table with Column Headings and Empty Cells
Col1
Col2
Col3
Col4
felis scelerisque
accumsan
eu nonummy quis justo pellentesque euismod quis pretium ut leo
quis justo
eleifend
consectetuer
pellentesque
viverra
augue in elit
mauris
Block Quoting (Email Style)
Compatible with email systems that use leading > chars for quotation. This is especially useful for formating poetry or verse. Note that nested quotations (>>, etc.) are not supported.
>Twinkle, twinkle, little bat!
> How I wonder what you're at!
>
>>Up above the world you fly,
>> Like a tea-tray in the sky.
Twinkle, twinkle, little bat!
How I wonder what you're at!
Up above the world you fly,
Like a tea-tray in the sky.
Comments
Comment lines begin with a single quote ' and may be ignored in most output formats. Comments can also be used to hide metadata elements as described below.
'List
'of
'Comments
Horizontal Rule (<hr>)
Line begins with at least three dashes.
--- text is ignored, can be used as a comment
Text Level Markup
These elements occur within paragraphs, lists, etc. and cannot span lines.
Hypertext Links
Images
Metadata
Word Level Styles
Name/Value Elements
^name(value)
Also referred to as a key/value pair.
Used for links, images, and metadata.
This construct cannot span lines.
Hypertext Links
Link to the ^Weather Forecast(https://forecast.weather.gov/).
Placeholders are a way to quickly add an image without specific alt text.
^placeholder(kist_images/picture2.jpg)
picture2.jpg
It is often useful to have smaller inline images that are linked to full-sized versions. This is indicted by the suffix -sm at the end of the filename. KIST assumes there is a corresponding image by the same name (without -sm) and will link to it.
You cannot have reference and image links in the same element.
^Small Image with Link(kist_images/picture4-sm.jpg)
It is also possible to have inline images within block quotes.
>Block Quote with an Inline Image
>
>^Smaller Flower Photo(kist_images/picture2.jpg)
>
>End Block
Block Quote with an Inline Image
Smaller Flower Photo
End Block
Floating Images
These images are limited to 25-33% of the document width and will float to the right of the paragraph text that follows. Note that there is currently no way to clear these floats, so images may overflow if there is not enough text.
^Carl Sagan(carl_sagan.png) Floating Paragraph…
Carl Sagan
Floating Paragraph… Are creatures of the cosmos Orion's sword dream of the mind's eye network of wormholes invent the universe hundreds of thousands. The only home we've ever known stirred by starlight encyclopaedia galactica preserve and cherish that pale blue dot courage of our questions rich in heavy atoms?
Note that this is a normal paragraph following the floating image paragraph above. The image may or may not overlap depending on the size of the display… Astonishment stirred by starlight hundreds of thousands a mote of dust suspended in a sunbeam extraordinary claims require extraordinary evidence with pretty stories for which there's little good evidence.
Embedded Images (Depreciated)
Eliminated in favor of the simpler formats outlined above.
Image Galleries
This is a quick & dirty approach to formatting images into useful contact sheet style galleries. The individual file names become the captions for each image. It is up to the user to provide meaningful file names.
Galleries use the same general rules for images, formats, etc.
Each gallery has a title and a relative URL to a directory.
Each gallery image has a hypertext link to its full-sized original.
There can be multiple galleries on a single page.
It is assumed the gallery directory contains only image files.
Caption text is cleaned up for clarity (capitalized, punctuation removed).
Click anywhere on the image to go to the next slide.
Click anywhere outside of the image to end the show.
Embedded Video & Audio
Use the kind=video_id format to embed a media clip (as opposed to linking to it).
This is a provisional feature.
Other media types and sources may be possible in the future.
Youtube
^Vermilion Cliffs Video(youtube=69KjOHNljaE)
Note that Youtube videos embedded in this way will attempt to contact youtube even when not being viewed. Make sure your browser prevents this or avoid this feature entirely if you have concerns!
Metadata provide information about the document, tagging the author's name for example.
The actual text is left in place, but the name=value pairs can be used elsewhere as needed.
^author(Joe Blow), ^date(March 1, 2021), etc.
Use a comment (see above) to completely hide metadata.
The permalink name has special meaning, it specifies the permanent address (URL) for the document.
References & Footnotes
A Reference (footnote/endnote) is a special type of list item that starts with square brackets []. There are two possible styles: Numeric and Textual. These IDs must be unique within the document and cannot contain other links.
[1] This is the first reference. Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Curabitur eu augue. Nunc sollicitudin felis sed purus.
[2] This is a second much longer reference… Something incredible is waiting to be known corpus callosum hydrogen atoms of brilliant syntheses Cambrian explosion network of wormholes? Rings of Uranus rogue white dwarf the ash of stellar alchemy invent the universe a still more glorious dawn awaits? Invent the universe the sky calls to us courage of our questions two ghostly white figures in coveralls and helmets are softly dancing extraordinary claims require extraordinary evidence from which we spring.
This is a non-reference item just to show you can mix and match.
[3] This is the third reference. It is linked to from an image.
[Author2008] Author/Year is a popular style used mostly in academic papers.
Lists of references may occur anywhere in the document (typically at the ends of sections or the end of the document). They can be used alone or with reference links.[2]
Reference Links
Reference links allow the reader to quickly find notes and reference material. In plain text, simply search on the [ref] id (which should be unique). In HTML, these links will bring up references in a pop-up dialog box to prevent scrolling away from the text. Links to references may appear more than once in the same document.
Numeric reference links take this form and can be used `multiple` times.
A Numeric Footnote^[1]
A Numeric Footnote[1]
Textual reference links must begin with a letter and cannot contain spaces or punctuation.
Author/Year Style Footnote^[Author2008]
Author/Year Style Footnote[Author2008]
There is also a sample endnote at the bottom[4] of this document.
Stylistic Markup
None of these elements can span lines!
Emphasis (<em>)
Surround text with stars * for emphasis.
You should *not* do that.
You should not do that.
Inline Quotes (<q>)
Surround text with double quotes.
Everyone should read "Walden" by Thoreau.
Everyone should read Walden by Thoreau.
Highlighting/Redlining (<ins>, <del>)
Surround text with curly brackets {} to indicate inline editorial comments, recent changes, or highlighting. Surround text with hyphens '-' to indicate deleted or erroneous text. Note that the trailing '-' must have a space after it to distinguish deleted text from normal hyphenation.
This is -old text- {new text} about a topic.
This is old text new text about a topic.
The following sentence has hyphenation, stray hyphens, and nested curly brackets to demonstrate how these elements interact. Note that they do not nest.
Made in the anti-matter of collapsing stars—the -cosmic ocean Apollonius of Perga two ghostly white figures in coveralls and {helmets are softly dancing hydrogen atoms from which} we spring?
Hashtags/Keywords
Under Development, Subject to Change
Hashtags are commonly found in Social Media posts.
They are an informal way to indicate keywords, topics, or threads.
They often consist of phrases made up of multiple words.
There are several equivalent formats:
Use a hash # before words to indicate a #hashtag.
Underscores tie_words_together into #multi_word_phrases.
Mid-phrase capitalization indicates a #WordBoundary.
These hashtags are equivalent #WordBoundary, #wordBoundary, & #Word_Boundary.
Note that outside this context underscores '_' have no special meaning.
Use a hash # before words to indicate a hashtag.
Underscores tie_words_together into multi word phrases.
Mid-phrase capitalization indicates a Word Boundary.
The hashtags Word Boundary, word Boundary, & Word Boundary are equivalent.
Note that outside this context underscores '_' have no special meaning.
White space after first char is ignored for readability.
!! AJ Item Examples
. open task (.)
! open priority task (!)
? open query/decision task (?)
~ completed task (~)
| deferred/reassigned task (|)
AJ Item Examples
☐
open task (.)
☐!
open priority task (!)
☐?
open query/decision task (?)
☒
completed task (~)
◊
deferred/reassigned task (|)
*Note that the title element (!!) is new and the deferred flag (|) has changed from (\).
The choice of markup characters is not arbitrary.
AJ task lists will sort correctly based on ASCII order.
My History of Textual Tinkering
1988 HYTEXT Hypertext Publishing System for MS-DOS
1989 Conversion of Medical Textbooks with AWK (NLM Fellowship)
1996 MTX Marked TeXt for Web Publishing (U of Fla)