KIST to HTML Conversion Notes

KIST Markup by Richard Rathe, v0.17, December 2024

Conversion Program

Kist.pl is a Perl script run from the command line as follows…

 kist: keep it simple text conversion

 usage: kist [-cmfbiwsxqvd] file [file2…]
   -c make comments visible
   -m add metadata to footer
   -f supress document footer
   -b supress booklet view
   -i output 'index.html' file
   -w wordpress compatible output (text only) *
   -w=http… wordpress output path to images *
   -s=custom.css use custom stylesheet
   -x xhtml output for ebook
   -q quiet mode (not yet!)
   -v verbose mode (not yet!)
   -d debugging mode (show extra detail) (not yet!)

 *depreciated, will be removed in future versions

 version 0.17 by richard rathe 2024
 cc attribution-share-alike license

Output files (.html) have the same name as source files (.txt) unless the -i flag is set. The parser supports the #! shebang directive on the first line for the above flags.

  #! -b -m

(booklet off, metadata on)

Default Output

Minimal Style

Kist.pl renders documents as plain vanilla HTML by default. Generated pages will degrade gracefully to the degree possible. These pages contain a minimal set of CSS styles in the <head> element. Authors are free to replace these styles with their own custom styles (using the -s flag).

Special Characters

Support for common plain text idioms:

The special HTML characters <, >, & are escaped.

Minimal Footer

By default output files will have a minimal footer containing the version of kist.pl that generated the page and the timestamp when the source file was last updated.

kist: 0.17 - Dec 21, 2024 08:51

Metadata

The -m flag will display the metadata associated with the document.

 author: Richard Rathe †
 category: programming †
 converted: Dec 21, 2024 09:20
 date: December 2024 †
 edited: Dec 21, 2024 09:20
 generator: Keep It Simple Text (KIST) v0.17
 hashtags: css,css_styles,html,perl ‡
 keywords: programming,css,css styles,html,perl §
 kist: 0.17
 permalink: https://mdpaths.com/kist/kist-html.html †
 source: kist-html.txt
 version: 0.17 †
† defined by ^name(value) elements in text
‡ social-media style #hashtags in text
§ 'keywords' combine categories and hashtags

Hierarchical Organization

HTML has several elements that organize information hierarchically. Headings (h1 through h6) help create outlines or chapters. (For practical purposes only # h2 and ## h3 are really useful.) Lists (ul, ol) may contain many sublists (aka Nested Lists).

KIST does not check documents for structural errors. The author must ensure headings are properly used and lists are well formed.

Linkable Sections

Top level headings also divide the document into sections that can be linked to using the # section name format. Sections are labeled s0, s1, etc. Here is a standard HTML link to the second heading/section in a hypothetical document:

  …index.html#s2

Intra-document links are possible using regular markup.

  ^See Above(#s2) (link to second section)

See Above (link to second section)

References are another possible target for links. They are labeled ref1, ref2. etc.

Sticky Headings

<h1> and <h2> headings use the sticky CSS attribute, allowing them to persist at the top as each section scrolls underneath.

List Titles

The HTML standard does not support a title or caption for lists as it does for tables. Various authors have suggested solutions to this problem, none are perfect. For KIST I've opted to treat the first item of the list as the title when needed.

  ^List Title
  one
  two
  three

Which renders as…

Or…

<ul>
<li class="title">List Title</li>
<li>one</li>
<li>two</li>
<li>three</li>
</ul>

Tabs to Tables

The Tab (aka Horizontal Tab) is one of the few ASCII control characters routinely used today. It indicates format rather than content. A TSV file has values (data fields) separated by tabs. This is similar (and superior) to the more well-known CSV (comma separated values) format—because commas are both separators and part of the data! This leads to confusion, special escape codes, and a whole lot of quotation marks!

KIST uses TSV-formatted data directly as its table format.

1	2	3
4	5	6
7	8	9
1 2 3
4 5 6
7 8 9

Alt Text

Missing or erroneous alt text for images is a persistent problem for web developers. KIST pages treat images the same as links with the name=value construct. This ensures the text and visual data always stay together. KIST adds both alt text and title attributes to every image tag.

^Missing Image Example(kist-booklet.png)
Missing Image Example
Missing Image Example

Reference Links

Reference links are a quick way to show notes and references without scrolling away from the main text. (The actual reference text appears elsewhere in the document.)

Some text with a reference link.^[1]
Reference Link Example
Reference Link Example

A reference link will bring up a dialog box with the desired text. Click anywhere outside the box to dismiss the dialog.

Print CSS

A minimal set of media-specific styles are included to optimize printing. If a page contains external links, these appear in the footer. For example…

External Links On This Page
 https://mdpaths.com/kist/mtxformat.txt
 https://forecast.weather.gov/
 https://mdpaths.com/everglades2023c.jpg
 https://mdpaths.com/aj/

'Booklet' Navigation

Longer documents require increasing amounts of scrolling for navigation. (This is mitigated somewhat by the search function in the browser.) In the past I would have used a hypertextual solution, breaking the document into multiple pages with navigation links between.

In this era of responsive content optimized for small vertical screens, KIST takes a simpler approach. The Booklet View is toggled by a '☰' button in the upper right corner of each page.

Booklet View Button
Booklet View Button

Each major section (defined by the top level # headings) collapses to a clickable stub. The reader is then free to navigate with minimal scrolling and focus on a single section at a time. This has the appearance of a card file or folded page. Clicking on the X button will exit the booklet view.

Collapsed Booklet View
Collapsed Booklet View

Clicking on any section will open just that section. The reader is free to scroll, click, and selectively read the entire document in this fashion.

Expanded Section View
Expanded Section View

Booklet Demo (11.2Mb MP4 File)

Example Booklet (Alice in Wonderland)


External Links
 https://mdpaths.com/kist/kist-booklet-demo.mp4
 https://mdpaths.com/kist/alice/

This is a slide!