T2HTML(1)

📦 version 2020.08.19+git2d9159d, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu resolute, ubuntu stonking

T2HTML(1) — Perl Text to HTML Converter 🦋

NAME 💖

t2html — Simple text to HTML converter. Relies on text indentation rules. No cap. 💅

SYNOPSIS ✨

Run it like this, bestie:

t2html [options] file.txt > file.html

DESCRIPTION 🌸

Okay so this program converts pure text files into nice looking, possibly framed, HTML pages. An example of conversion:

  1. Plain text source code http://pm-doc.git.sourceforge.net/git/gitweb.cgi?p=pm-doc/pm-doc;a=blob_plain;f=doc/index.txt;hb=HEAD
  2. The result of conversion with custom --css-file option: http://pm-doc.sourceforge.net/pm-tips.html http://pm-doc.sourceforge.net/pm-tips.css
  3. An Emacs mode tinytf.el for writing the text files (optional) https://github.com/jaalto/project--emacs-tiny-tools

Requirements for the input ascii files 🎀

The file must be written in Technical Format, whose layout is described in this manual. Basically the idea is simple and there are only two heading levels: one at column 0 and the other at column 4 (halfway between the tab width). Standard text starts at column 8 (the position after pressed tab-key).

The idea of technical format is that each column represents different rendering layout in the generated HTML. There is no special markup needed in the text file, so you can use the text version as a master copy of a FAQ etc. Bullets, numbered lists, word emphasis and quotation etc. can be expressed in a natural way.

HTML description 💻

The generated HTML includes embedded Cascading Style Sheet 2 (CSS2) and a small piece of Java code. The CSS2 is used to colorize the page layout and to define suitable printing font sizes. The generated HTML also takes an approach to support XHTML. See page http://www.w3.org/TR/xhtml1/#guidelines where the backward compatibility recommendations are outlined:

Legal HTML          XHTML requires
<P>                 <p> ..</p>
<BR>                <br></br>
<HR>                <hr></hr>

XHTML does not support fragment identifiers #foo, with the "name" element, but uses "id" instead. For backward compatibility both elements are defined:

< ..name="tag">     Is now <.. name="tag" id="tag">
⚠️ NOTE: This program was never designed to be used for XHTML and the strict XHTML validity is not to be expected. 💀

Motivation 🌈

The easiest format to write large documents, like FAQs, is text. A text file offers WysiWyg editing and it can be turned easily into HTML format. Text files are easily maintained and there are no requirements for special text editors. Any text editor like notepad, vi, Emacs can be used to maintain the documents.

Text files are also the only sensible format if documents are kept under version control like RCS, CVS, SVN, Arch, Perforce, ClearCase. They can be easily compared with diff and patches can be easily received and sent to them.

To help maintaining large documents, there is also available an Emacs minor mode, package called tinytf.el, which offers text fontification with colors, Indentation control, bullet filling, heading renumbering, word markup, syntax highlighting etc. See https://github.com/jaalto/project--emacs-tiny-tools

OPTIONS 💅

  • --as-is — Any extra HTML formatting or text manipulation is suppressed. Text is preserved as it appears in file. Use this option if you plan to deliver and print the text as seen.
    • If file contains "Table of Contents" it is not removed
    • Table of Content block is not created (it usually would)
  • --author, -a STR — Author of document e.g. --author "John Doe"
  • --disclaimer-file FILE — The text that appears at the footer is read from this file. If not given the default copyright text is added. Options --quiet and --simple suppress disclaimers.
  • --document FILE — Name of the document or filename. You could list all alternative URLs to the document with this option.
  • --email, -e EMAIL — The contact address of the author of the document. Must be pure email address with no < and > characters included. Eg. --email foo@example.com
--email "<me@here.com>"     WRONG
--email "me@here.com"       right
  • --simple, -s — Print minimum footer only: contact, email and date. Use --quiet to completely discard footer.
  • --t2html-tags — Allow processing embedded #T2HTML-<tag> directives inside file. See full explanation by reading topic "EMBEDDED DIRECTIVES INSIDE TEXT". By default, you do not need to supply this option — it is "on" by default.

To disregard embedded directives in text file, supply "no" option: --not2html-tags.

  • --title STR, -t STR — The title text that appears in top frame of browser.
  • --url URL — Location of the HTML file. When --document gave the name, this gives the location. This information is printed at the Footer.

Html: Navigation urls 🧚

  • --base URL — URL location of the HTML file in the destination site where it will be put available. This option is needed only if the document is hosted on a FTP server (rare, but possible). A FTP server based document cannot use Table Of Contents links (fragment #tag identifiers) unless HTML tag BASE is also defined.

The argument can be full URL to the document:

--base ftp://ftp.example.com/file.html
--base ftp://ftp.example.com/
  • --button-heading-top — Add additional [toc] navigation button to the end of each heading. This may be useful in long non-framed HTML files.
  • --button-top URL — Buttons are placed at the top of document in order: [previous][top][next] and --button-* options define the URLs.

If URL is string none then no button is inserted. This may be handy if the buttons are defined by a separate program. And example using Perl:

#!/usr/bin/perl

my $top   = "index.html";             # set defaults
my $prev  = "none";
my $next  = "none";

# ... somewhere $prev or $next may get set, or then not

qx(t2html --button-top "$top" --button-prev "$prev" --button-next "$next" ...);

# End of sample program
  • --button-prev URL — URL to go to previous document or string none.
  • --button-next URL — URL to go to next document or string none.
  • --reference tag=value — You can add any custom references (tags) inside text and get them expand to any value. This option can be given multiple times and every occurrence of TAG is replaced with VALUE. E.g. when given following options:
--reference "#HOME-URL=http://www.example.com/dir"
--reference "#ARCHIVE-URL=http://www.example.com/dir/dir2"

When referenced in text, the generated HTML includes the expanded values. An example text:

        The homepage is #HOME-URL/page.html and the mirrot page it at
        #ARCHIVE-URL/page.html where you can find the latest version.
  • -R, --reference-separator STRING — See above. String that is used to split the TAG and VALUE. Default is equal sign "=".
  • -T, --toc-url-print — Display URLs (constructed from headings) that build up the Table of Contents (NAME AHREF tags) in a document. The list is outputted to stderr, so that it can be separated:
% t2html --toc-url-print tmp.txt > file.html 2> toc-list.txt

Where would you need this? If you want to know the fragment identifiers for your file, you need the list of names.

http://www.example.com/myfile.html#fragment-identifier

Html: Controlling CSS generation (HTML tables) 💅

  • --css-code-bg — This option affects how the code section (column 12) is rendered. Normally the section is surrounded with a <pre>..</pre> codes, but with this option, something more fancier is used. The code is wrapped inside a <table>...</table> and the background color is set to a shade of gray.
  • --css-code-note "REGEXP" — Option --css-code-bg is required to activate this option. A special word defined using regexp (default is 'Note:') will mark code sections specially. The "first word" is matched against the supplied Perl regexp.

The supplied regexp must not, repeat, must not, include any matching group operators. This simply means, that grouping parenthesis like "(one|two|three)" are not allowed. You must use the Perl non-grouping ones like "(?:one|two|three)". Please refer to perl manual page [perlre] if this short introduction did not give enough rope.

With this option, instead of rendering column 12 text with <pre>..</pre>, the text appears just like regular text, but with a twist. The background color of the text has been changed to darker grey to visually stand out from the text.

An example will clarify. Suppose that you passed options --css-code-bg and --css-code-note='(?:Notice|Note):', which instructed to treat the first paragraphs at column 12 differently. Like this:

        This is the regular text that appears somewhere at column 8.
        It may contain several lines of text in this paragraph.

            Notice: Here is the special section, at column 12,
            and the first word in this paragraph is 'Notice:'.
            Only that makes this paragraph at column 12 special.

        Now, we have some code to show to the user:

            for ( i = 0; i++; i < 10 )
            {
                //  Doing something in this loop
            }

One note, text written with initial special word, like "Notice:", must all fit in one full paragraph. Any other paragraphs that follow, are rendered as code sections. Like here:

        This is the regular text that appears somewhere
        It may contain several lines of text in this paragraph

            Notice: Here is the special section, at column 12,
            and the first word in this paragraph is 'Notice:'
            which makes it special

            Hoewver, this paragraph IS NOT rendered specially
            any more. Only the first paragraph above.

            for ( i = 0; i++; i < 10 )
            {
                //  Doing something in this loop
            }

As if this were not enough, there are some special table control directives that let you control the <table>..</table> which is put around the code section at column 12. Here are few examples:

        Here is example 1

            #t2html::td:bgcolor=#F7F7DE

            for ( i = 0; i++; i < 10 )
            {
                //  Doing something in this loop
            }

        Here is example 2

            #t2html::td:bgcolor=#F7F7DE:tableborder:1
    for ( i = 0; i++; i < 10 )
    {
        //  Doing something in this loop
    }

Here is example 3

#t2html::td:bgcolor="#FFFFFF":tableclass:dashed

for ( i = 0; i++; i < 10 )
{
    //  Doing something in this loop
}

Here is example 4

#t2html::td:bgcolor="#FFFFFF":table:border=1_width=94%_border=0_cellpadding="10"_cellspacing="0"

for ( i = 0; i++; i < 10 )
{
    //  Doing something in this loop
}

okay bestie I know — this looks cryptic, and honestly there's nothing anyone can do about that 💀. But if you actually want to get what these directives are doing, you need to know which elements you can slap onto the <table> and <td> tokens. Go check the HTML spec for the full attribute list. Here's the quick briefing though 🫶:

The start command is:

#t2html::
        |
        After this comes attribute pairs in form key:value
        and multiple ones as key1:value1:key2:value2 ...

The key:value pairs can be:

td:ATTRIBUTES
   |
   This is converted into <td attributes>

table:ATTRIBUTES
      |
      This is converted into <table attributes>

no spaces allowed in the ATTRIBUTES, because that "First-word" has to be one single contiguous word. If you need a space, use an underscore instead:

table:border=1_width=94%
      |
      Interpreted as <table border="1" width="94%">

You can also swap out the default CLASS style with the word tableclass. But heads up — for CLASS to actually do anything, its CSS definitions have to either live in the default configuration or come in from an external file. See the --script-file option for that.

tableclass:name
           |
           Interpreted as <table class="name">

Like, there are a couple of default styles already sitting there ready to go:

  1. Here's the CLASS "dashed" example
#t2html::tableclass:dashed

    for ( i = 0; i++; i < 10 )
    {
        //  Doing something in this loop
    }
  1. And here's the CLASS "solid" example:
#t2html::tableclass:solid

    for ( i = 0; i++; i < 10 )
    {
        //  Doing something in this loop
    }

You can change any individual value of the default table definition, which is:

<table  class="shade-note">

So if you wanted to change, say, only the cellpadding value, you'd say:

 #t2html::table:tablecellpadding:2

And if none of this is landing and you're just sitting there like ??? — literally just run the program with --test-page and go stare at the source file and the generated HTML file side by side. That gives you way more rope to experiment with. vibe check passed, go break stuff 💅

  • --css-file FILE — drops in a <LINK ...> that points at an external CSS style definition source. Important though: this option gets ignored if the --script-file option has been given, because that option imports the whole content inside the HEAD tag. You can use this option multiple times, and the external CSS files get added in the order you listed them.
  • --css-font-type CSS-DEFINITION — sets the BODY element's font definition to CSS-DEFINITION. The default value is the regular typeset you'd see in newspapers and books:
--css-font-type='font-family: "Times New Roman", serif;'
  • --css-font-size CSS-DEFINITION — sets the BODY element's font size to CSS-DEFINITION. The default font size is expressed in points:
--css-font-size="font-size: 12pt;"

🦋 Html: Controlling the body of document 🦋

  • --delete REGEXP — deletes lines matching the perl REGEXP. Super useful if you use some document tool that sprinkles navigation tags into your text file and you do not want those showing up in the generated HTML. bye felicia ✨
  • --delete-email-headers — nukes the email headers at the beginning of the file, all the way until the first empty line that starts the body. Like, if you keep your document ready for Usenet news posting, it might contain headers plus body:
From: ...
Newsgroups: ...
X-Sender-Info:
Summary:

BODY-OF-TEXT
  • --nodelete-default — use this to suppress the default text deletion (which is on by default, just so you know).

The Emacs "folding.el" package and vi can be used with any text or programming language to place sections of text between the tags {{{ and }}}. You can open or close those folds. This makes keeping big documents in order and manageable honestly pretty easy. For Emacs support, see. ftp://ftp.csd.uu.se/pub/users/andersl/beta/

The default value deletes these markers and the special comments "#_comment", which make it possible to include your own notes that don't end up in the generated output.

 {{{ Security section

 #_comment Make sure you revise this section to
 #_comment the next release

 The seecurity is an important issue in everyday administration...
 More text ...

 }}}
  • --html-body STR — extra attributes to add to the HTML tag <BODY>. You could, for example, define the language of the text with --html-body LANG=en, which would generate the HTML tag <BODY LANG="en">. See the section "SEE ALSO" for ISO 639.
  • --html-column-beg="SPEC HTML-SPEC" — the default interpretation of columns 1,2,3, 5,6,7,8,9,10,11,12 can be changed with the beg and end switches. Columns 0 and 4 can't be changed, because they're reserved for headings. Here are some samples:
--html-column-beg="7quote <em class='quote7'>"
--html-column-end="7quote </em>"

--html-column-beg="10    <pre> class='column10'"
--html-column-end="10    </pre>"

--html-column-beg="quote <span class='word'>"
--html-column-end="quote </span>"

Note: you can only give specifications up till column 12. If text goes beyond column 12, it gets interpreted like it were at column 12.

In addition to a column number, the SPEC can also be one of these strings:

Spec    equivalent word markup
------------------------------
quote   `'
bold    _
emp     *
small   +
big     =
ref     []   like: [Michael] referred to [rfc822]

Other available Specs
------------------------------
7quote      When column 7 starts with double quote.

For style sheet values for each color, refer to the class attribute and use the --script-file option to import definitions. Usually /usr/lib/X11/rgb.txt lists possible color values, and the HTML standard at http://www.w3.org/ defines these standard named colors:

  • Black — #000000
  • Maroon — #800000
  • Green — #008000
  • Navy — #000080
  • Silver — #C0C0C0
  • Red — #FF0000
  • Lime — #00FF00
  • Blue — #0000FF
  • Gray — #808080
  • Purple — #800080
  • Olive — #808000
  • Teal — #008080
  • White — #FFFFFF
  • Fuchsia — #FF00FF
  • Yellow — #FFFF00
  • Aqua — #00FFFF
  • --html-column-end="COL HTML-SPEC" — see --html-column-beg.
  • --html-font SIZE — defines FONT SIZE. Might be useful to set a bigger font size for presentations. 👑
  • -F, --html-frame [FRAME-PARAMS] — if given, then three separate HTML files get generated. The left frame holds the TOC and the right frame holds the rest of the text. The FRAME-PARAMS can be any valid parameters for the HTML tag FRAMESET. The default is "cols="25%,75%"".

Using this implies the --out option automatically, because three files can't be printed to stdout. obviously 💅

file.html

--> file.html       The Frame file, point browser here
    file-toc.html   Left frame (navigation)
    file-body.html  Right frame (content)
  • --language ID — use language ID, a two character ISO identifier like "en" for English, during the generation of HTML. This only affects the text that's shown to the end-user, like the text "Table Of contents". The default setting is "en". See the section "SEE ALSO" for the standards ISO 639 and ISO 3166 for the proper codes.

The selected language changes the program's internal arrays in two ways: 1) instead of the default "Table of contents" heading, the national language equivalent gets used, and 2) the text "Pic" below embedded sequentially numbered pictures uses the national equivalent.

If your language isn't supported, please send the phrase for "Table of contents" and the word "Pic" in your language to the maintainer. they'd literally love that 🫶

  • --script-file FILE — includes java code that must be a complete <script...></script> from FILE. The code gets put inside <head> of each HTML.

The --script-file is the general way to import anything into the HEAD element. E.g. if you want to keep separate style definitions for all of them, you could just import a pointer to a style sheet. See 14.3.2 Specifying external style sheets in HTML 4.0 standard.

  • --meta-keywords STR — meta keywords. Used by search engines. Separate keywords like "AA, BB, CC" with commas. Refer to the HTML 4.01 specification and the topic "7.4.4 Meta data" and see http://www.htmlhelp.com/reference/wilbur/ and
--meta-keywords "AA,BB,CC"
  • --meta-description STR — meta description. Include a description string, max 1000 characters. This is used by search engines. Refer to the HTML 4.01 specification and the topic "7.4.4 Meta data".
  • --name-uniq — the first 1-4 words from the heading get used for the HTML name tags. But plot twist: it's totally possible that two identical headings start with exactly the same 1-4 words 😭. In those cases you have to turn this option on. It'll use a counter 00 - 999 instead of words from the headings to construct the HTML name references.

Please only use this option in emergencies, because referring to a jump block name via

httpI://example.com/doc.html#header_name

is way more convenient than using an obscure reference like

httpI://example.com/doc.html#11

On top of that, every single time you add a new heading the number changes, whereas the symbolic name picked from the heading stays put as long as you don't change the heading. Think about the welfare of your netizens who bookmark your pages, bestie 😭. Try to make headings that don't share the same subjects and you won't need this option at all.

🛠️ Document maintenance and batch job commands 🛠️

okay bestie, this next batch of flags is all about keeping your docs cute and your links alive 💖. It's giving maintenance era, and honestly? Iconic.

  • -A, --auto-detect — Convert file only if tag "#T2HTML-" is found from file. This option is handy if you run a batch command to convert all files to HTML, but only if they look like HTML base files:
find . -name "*.txt" -type f \
     -exec t2html --auto-detect --verbose --out {} \;

The command searches all *.txt files under current directory and feeds them to conversion program. The --auto-detect only converts files which include "#T2HTML-" directives. Other text files are not converted. No cap.

  • --link-check, -l — Check all http and ftp links. This option is supposed to be run standalone. Option --quiet has special meaning when used with link check.

With this option you can regularly validate your document and remove dead links or update moved links. Problematic links are outputted to stderr. This link check feature is available only if you have the LWP web library installed. Program will check if you have it at runtime.

Links that are big, e.g. which match tar.gz, .zip, ... or that run programs (links with ? character) are ignored because the GET request used in checking would return whole content of the link and it would. be too expensive. (Like, imagine downloading a whole tarball just to check a link. Not the vibe.)

A suggestion: When you put binary links to your documents, add them with space:

http://example.com/dir/dir/ filename.tar.gz

Then the program does check the http addresses. Users may not be able to get the file at one click, checker can validate at least the directory. If you are not the owner of the link, it is also possible that the file has moved of new version name has appeared.

  • -L, --link-check-single — Print condensed output in grep -n like manner FILE:LINE:MESSAGE

This option concatenates the url response text to single line, so that you can view the messages in one line. You can use programming tools (like Emacs M-x compile) that can parse standard grep syntax to jump to locations in your document to correct the links later. Obsessed.

  • -o, --out — write generated HTML to file that is derived from the input filename.
--out --print /dir/file            --> /dir/file.html
--out --print /dir/file.txt        --> /dir/file.html
--out --print /dir/file.this.txt   --> /dir/file.this.html
  • --link-cache CACHE_FILE — When links are checked periodically, it would be quite a rigorous to check every link every time that has already succeeded. In order to save link checking time, the "ok" links can be cached into separate file. Next time you check the links, the cache is opened and only links found that were not in the cache are checked. This should dramatically improve long searches. Consider this example, where every text file is checked recursively.
$ t2html --link-check-single \
  --quiet --link-cache ~tmp/link.cache \
  `find . -name "*.txt" -type f`
  • -O, --out-dir DIR — Like --out, but chop the directory part and write output files to DIR. The following would generate the HTML file to current directory:
--out-dir .

If you have automated tool that fills in the directory, you can use word none to ignore this option. The following is a no-op, it will not generate output to directory "none":

--out-dir none
  • -p, --print — Print filename to stdout after HTML processing. Normally program prints no file names, only the generated HTML.
% t2html --out --print page.txt

--> page.html
  • -P, --print-url — Print filename in URL format. This is useful if you want to check the layout immediately with your browser.
% t2html --out --print-url page.txt | xargs lynx

--> file: /users/foo/txt/page.html
  • --split REGEXP — Split document into smaller pieces when REGEXP matches. Split commands are standalone, meaning, that it starts and quits. No HTML conversion for the file is engaged.

If REGEXP is found from the line, it is a start point of a split. E.g. to split according to toplevel headings, which have no numbering, you would use:

--split '^[A-Z]'

A sequential numbers, 3 digits, are added to the generated partials:

filename.txt-NNN

The split feature is handy if you want to generate slides from each heading: First split the document, then convert each part to HTML and finally print each part (page) separately to printer. Slay.

  • -S1, --split1 — This is shorthand of --split command. Define regexp to split on toplevel heading.
  • -S2, --split2 — This is shorthand of --split command. Define regexp to split on second level heading.
  • -SN, --split-named-files — Additional directive for split commands. If you split e.g. by headings using --split1, it would be more informative to generate filenames according to first few words from the heading name. Suppose the heading names where split occur were:
Program guidelines
Conclusion

Then the generated partial filenames would be as follows.

FILENAME-program_guidelines
FILENAME-conclusion
  • -X, --xhtml — Render using strict XHTML. This means using <hr/>, <br/> and paragraphs use <p>..</p>.
"Note: this option is experimental. See BUGS"

🎀 Miscellaneous options 🎀

And now for the lil extras, the sprinkles on top, the garnish, the vibe check. 💅

  • --debug LEVEL — Turn on debug with positive LEVEL number. Zero means no debug.
  • --help, -h — Print help screen. Terminates program.
  • --help-css — Print default CSS used. Terminates program. You can copy and modify this output and instruct to use your own with --css-file=FILE. You can also embed the option to files with "#T2HTML-OPTION" directive.
  • --help-html — Print help in HTML format. Terminates program.
  • --help-man — Print help page in Unix manual page format. You want to feed this output to nroff -man in order to read it. Terminates program.
  • --test-page — Print the test page: HTML and example text file that demonstrates the capabilities.
  • --time — Print to stderr time spent used for handling the file.
  • -v, --verbose [LEVEL] — Print verbose messages.
  • -q, --quiet — Print no footer at all. This option has different meaning if --link-check option is turned on: print only erroneous links.
  • V, --version — Print program version information.

✨ FORMAT DESCRIPTION ✨

okay so here's the tea, bestie: this program converts text files to HTML, and the entire vibe of how it does that is indentation level. The layout it uses is called 'Technical format' (TF), and the whole point is that you only use minimal conventions to mark italic, bold etc. text. Like, barely any markup, just vibes and column positions. 🫶

The basic principles can be demonstrated below. Notice the column position ruler at the top:

--//-- description start

123456789 123456789 123456789 123456789 123456789 column numbers

Heading 1 starts with a big letter at leftmost column 1

 The column positions 1,2,3 are currently undefined and may not
 format correctly. Do not place text at columns 1,2 or 3.

    Heading level 2 starts at half-tab column 4 with a big letter

     Normal but colored text at columns 5

      Normal but colored text at columns 6

       Heading 3 can be considered at position TAB minus 1, column 7.

       "Special <em> text at column 7 starts with double quote"

        Standard text starts at column 8, you can *emphatize* text or
        make it _strong_ and write =SmallText= or +BigText+ show
        variable name `ThisIsAlsoVariable'. You can `_*nest*_' `the'
        markup. more txt in this paragraph txt txt txt txt txt txt
        txt txt txt txt txt txt txt txt txt txt txt txt txt txt txt
        txt txt txt txt txt txt txt txt txt txt txt txt txt txt txt
        txt txt

         Strong text at column 9

          Column 10 is reserved for quotations
          Column 10 is reserved for quotations
          Column 10 is reserved for quotations
          Column 10 is reserved for quotations

         Strong text at column 11

          Column 12 and further is reserved for code examples
          Column 12 and further is reserved for code examples
          All text here are surrounded by <pre> HTML codes
          This CODE column in affected by the --css-code* options.

    Heading 2 at column 4 again

       If you want something like Heading level 3, use column 7 (bold)

        Column 8. Standard tab position. txt txt txt txt txt txt txt
        txt txt txt txt txt txt txt txt txt txt txt txt txt txt txt
        txt txt txt txt txt txt txt txt txt txt txt txt txt txt
        [1998-09-10 Mr. Foo said]:

          cited text at column 10. cited text cited text cited text
          cited text cited text cited text cited text cited text
          cited text cited text cited text cited text cited text
          cited text

        *   Bullet at column 8. Notice 3 spaces after (*), so
            text starts at half-tab forward at column 12.
        *   Bullet. txt txt txt txt txt txt txt txt txt txt txt txt
        *   Bullet. txt txt txt txt txt txt txt txt txt txt txt txt
            ,txt txt txt txt

            Notice that previous paragraph ends to P-comma
            code, it tells this paragraph to continue in
            bullet mode, otherwise this text at column 12
            would be interpreted as code section surrounded
            by <pre> HTML codes.

        .   This is ordered list.
        .   This is ordered list.
        .   This is ordered list.

        .This line starts with dot and is displayed in line by itself.
        .This line starts with dot and is displayed in line by itself.

        !! This adds an <hr> HTML code, text in line is marked with
        !! <strong> <em>

        Make this email address clickable <account@tt.com> Do not
        make this email address clickable bar@example.com, because it
        is only an example and not a real address. Notice that the
        last one was not surrounded by <>. Common login names like
        foo, bar, quux, or internet site 'example' are ignored
        automatically.

        Also do not make < this@example.com> because there is extra
        white space. This may be more convenient way to disable email
        addresses temporarily.

Heading1 again at column 0

    Subheading at column 4

        And regular text, column 8 txt txt txt txt txt txt txt txt txt
        txt txt txt txt txt txt txt txt txt txt txt txt txt txt txt txt
        txt txt txt txt txt txt txt txt txt txt txt

--//-- description end

That's literally it. There's the whole layout described. 👑

🚨 friendly lil heads up: columns 1, 2 and 3 are currently undefined and may not format correctly. Do not place text at columns 1, 2 or 3. fr fr.

More formally, the rules of text formatting are described below.

🎀 USED HEADINGS 🎀

  • There are only two heading levels in this style, no more, that's the whole menu. Heading columns are 0 and 4, and the heading must start with a big letter ("Heading") or a number ("1.0 Heading").
  • At column 4, if the text starts with a small letter, that line gets interpreted as <strong>.
  • A HTML <hr> mark is added just before printing heading at level 1.
  • The headings are gathered, the TOC is built, and it's inserted to the beginning of the HTML page. The HTML <name> references used in TOC are the first 4 sequential words from the headings. Make sure your headings are uniquely named, otherwise there will be same NAME references in the generated HTML. Spaces are converted into underscore when joining the words. If you can not write unique headings by four words, then you must use the --name-uniq switch.
iykyk: duplicate headings = duplicate NAME refs in your HTML and that is not the slay you want. name your headings like a main character or hit up --name-uniq. 💅

✨ TEXT PLACEMENT RULES ✨

Okay bestie, this is the part where the magic of column placement happens 💅. Like, where you put your text on the line literally changes what HTML you get. No cap.

General 🎀

The basic rules for positioning text in certain columns:

  • Text at column 1 is undefined if it does not start with a big letter or number to indicate Heading level 1. So like, don't just put random stuff there, okay? 💀
  • Text between columns 2 and 3 is marked with <em>.
  • Column 4 is reserved for heading level 2.
  • Text between columns 5-7 is marked with <strong>.
  • Text at column 7 is <em> if the first character is a double quote.
  • Column 10 is reserved for <em> text. If you want to quote someone or add reference text, place the text in this column. It's giving citation energy ✨.
  • Text at columns 9 and 11 are marked with <strong>.

Column 8 for text and special codes 🦋

  • Column 8 is reserved for normal text.
  • At the start of text, at column 8, there can be DOT-code or COMMA-code. (Yes, we'll get to those 👀)

Column 12 is special 💖

  • Column 12 is treated specially: block is started with <pre> and lines are marked as <samp></samp>. When the last text at column 12 is found, the block is closed with </pre>. An example:
               txt txt txt         ;evenly placed block, fine, do it like this
               txt txt

               txt txt txt txt     ;Can not terminate the /pre, because last
               txt txt txt txt     ;column is not at 12
                   txt txt txt txt

               txt txt txt txt
               txt txt txt txt
                   txt txt txt txt
               ;; Finalizing comment, now the text is evenly placed

Additional tokens for use at column 8 🌸

  • If there is "." (dot) at the beginning of a line and immediately non-whitespace, then <br> code is added to the end of line. Like:
               .This line will have a <BR> HTML tag at the end.
               While these two line are joined together
               by the browser, depending on the frame width.
  • If there is "," (comma) then the <p> code is not inserted if the previous line is empty. If you use both "." (dot) and "," (comma), they must be in order dot-comma. The "," (comma) works differently if it is used in bullet.

A <p> is always added if there is separation of paragraphs, but when you are writing a bullet, there is a problem, because a bullet exist only as long as text is kept together. Like:

               *   This is a bullet and it has all text ketp together
                   even if there is another line in the bullet.

But to write bullets tat spread multiple paragraphs, you must instruct that those are to kept together and the text in next paragraph is not <sample> while it is placed at column 12:

               *   This is a bullet and it has all text ketp together
                   ,even if there is another line in the bullet.

                   This is new paragrah to the previous bullet and this is
                   not a text sample. See continued COMMA-code above.

               *   This is new bullet

                   // and this is code sample after bullet
                   if ( $flag ) { ..do something.. }

Special text markings 💫

italic, bold, code, small, big tokens

               _this_      is interpreted as <strong class='word'>this</strong>
               *this*      is interpreted as <em class='word'>this</em>
               `this'      is interpreted as <sample class='word'>this</sample> `

Exra modifiers that can be mixed with the above. Usually if you want bigger font, CAPITALIZE THE WORDS.

               =this=      is interpreted as <span class="word-small">this</span>
               +this+      is interpreted as <span class="word-big">this</span>
               [this]      is interpreted as <span class="word-ref">this</span>

superscripting

               word[this]  is interpreted as superscript. You can use like
                           this[1], multiple[(2)] and almost any[(ab)] and
                           imaginable[IV superscritps] as long as the left
                           bracket is attached to the word.

subscripting

               12[[10]]    is representation of value 12 un base 10.
                           This is interpreted as subscript. You can use like
                           this[[1]], multiple[[(2)]] and almost any[[(ab)]] and
                           imaginable[[IV superscritps]] as long as *two* left
                           brackets are attached to the word.

embedding standard HTML tokens

Stanadard special HTML entities can be added inside text in a normal way, either using sybolic names or the hash code. Here are exmples:

               &times; &lt; &gt; &le; &ge; &ne; &radic; &minus;
               &alpha; &beta; &gamma; &divide;
               &laquo; &raquo; &lsaquo; &rsaquo; - &ndash; &mdash;
               &asymp; &equiv; &sum; &fnof; &infin;
               &deg; &plusmn;
               &trade; &copy; &reg;
               &euro; &pound; &yen;

embedding PURE HTML into text

This feature is highly experimental 🧪. It is possible to embed pure HTML inside text in occasions, where e.g. some special formatting is needed. The idea is simple: you write HTML as usual but double every '<' and '>' characters, like:

               <<p>>

The other rule is that all PURE HTML must be kept together. There must be no line breaks between pure HTML lines. This is incorrect:

               <<table>>

                   <<tr>>one
                   <<tr>>two

               <</table>>

The pure HTML must be written without extra newlines:

               <<table>>
                   <<tr>>one
                   <<tr>>two
               <</table>>

This "doubling" affects normal text writing rules as well. If you write documents, where you describe Unix styled HERE-documents, you MUST NOT put the tokens next to each other:

                   bash$ cat<<EOF              # DON'T, this will confuse parser.
                   one
                   EOF

You must write the above code example using spaces to prevent "<<" from interpreting as PURE HTML:

                   bash$ cat << EOF            # RIGHT, add spaces
                   one
                   EOF

drawing a short separator

A !! (two exclamation marks) at text column (position 8) causes adding immediate <hr> code. any text after !! in the same line is written with <strong> <em> and inserted just after <hr> code, therefore the word formatting commands have no effect in this line. So like, it's a separator, periodt 💅.

Http and email marking control 🔗

  • All http and ftp references as well as <foo@example.com> email addresses are marked clickable. Email must have surrounding <> characters to be recognized.
  • If url is preceded with hyphen, it will not be clickable. If a string foo, bar, quux, test, site is found from url, then it is not counted as clickable.
               <me@here.com>                   clickable
               http://example.com              clickable

               < me@here.com>                  not clickable; contains space
               <5dko56$1@news02.deltanet.com>  Message-Id, not clickable

               -http://example.com             hyphen, not clickable
               http://$EXAMPLE                 variable. not clickable

Lists and bullets 📝

  • The bulletin table is constructed if there is "o" or "*" at column 8 and 3 spaces after it, so that text starts at column 12. Bulleted lines are advised to be kept together; no spaces between bullet blocks.
               *   This is a bullet
               *   This is a bullte

Another example:

               o   This is a bullet
               o   This is a bullet

List example:

               .   This is an ordered list
               .   This is an ordered list
  • The ordered list is started with ".", a dot, and written like bullet where text starts at column 12.

Line breaks 🚦

  • All line breaks are visible in your document, do not use more than one line break to separate paragraphs.
  • Very important is that there is only one line break after headings.

💖 EMBEDDED DIRECTIVES INSIDE TEXT 💖

Bestie. Okay. So you can literally just... talk to t2html from inside your own document. Sneaky. Iconic. Let's go.

Command line options

You can cancel obeying all embedded directives by supplying option --not2html-tags. (Yep, one flag and the whole directive party is over. 🙈)

You can include these lines anywhere in the document and their content is included in HTML output. Each directive line must fit in one line and it cannot be broken to separate lines. One line. That's the rule. Don't fight it.

#T2HTML-TITLE            <as passed option --title>
#T2HTML-EMAIL            <as passed option --email>
#T2HTML-AUTHOR           <as passed option --author>
#T2HTML-DOC              <as passed option --doc>
#T2HTML-METAKEYWORDS     <as passed option --meta-keywords>
#T2HTML-METADESCRIPTION  <as passed option --meta-description>

You can pass command line options embedded in the file. Like if you wanted the CODE section (column 12) to be coloured with shade of gray, you could add:

#T2HTML-OPTION  --css-code-bg

Or you could request turning on particular options. Notice that each line is exactly as you have passed the argument in command line. Imagine surrounding double quoted around lines that are arguments to the associated options.

#T2HTML-OPTION  --as-is
#T2HTML-OPTION  --quiet
#T2HTML-OPTION  --language
#T2HTML-OPTION  en
#T2HTML-OPTION  --css-font-type
#T2HTML-OPTION  Trebuchet MS
#T2HTML-OPTION --css-code-bg
#T2HTML-OPTION --css-code-note
#T2HTML-OPTION (?:Note|Notice|Warning):

You can also embed your own comments to the text. These are stripped away:

#T2HTML-COMMENT  You comment here
#T2HTML-COMMENT  You another comment here

Embedding files

#INCLUDE- command

This is used to include the content into current current position. The URL can be a filename reference, where every $VAR is substituted from the environment variables. The tilde(~) expansion is not supported (sorry, ~ girlies 😭). The included filename is operating system supported path location.

A prefix "raw:" disables any normal formatting. The file content is included as is. No glow-up, no edits, just vibes. ✨

The URL can also be a HTTP reference to a remote location, whose content is included at the point. In case of remote content or when filename ends to extension ".html" or ".html", the content is stripped in order to make the inclusion of the content possible. In picture below, only the lines within the BODY, marked with !!, are included:

<html>
  <head>
    ...
  </head>
  <body>
    this text                 !!
    and more of this          !!
  </body>
</html>

Examples:

#INCLUDE-$HOME/lib/html/picture1.html
#INCLUDE-http://www.example.com/code.html
#INCLUDE-raw:example/code.html

Embedding pictures

#PIC command is used to include pictures into the text 🎀

#PIC picture.png#Caption Text#Picture HTML attributes#align#
      (1)        (2)          (3)                     (4)
  1. The NAME or URL address of the picture. Like image/this.png
  2. The Text that appears below picture
  3. Additional attributes that are attached inside <img> tag. For <img width="200" height="200">, the line would read:
#PIC some.png#Caption Text#width=200 length=200##
  1. The position of image: "left" (default), "center", "right"
Note: The "Caption Text" will also become the ALT text of the image which is used in case the browser is not capable of showing pictures. You can suppress the ALT text with option --no-picture-alt.

Fragment identifiers for named tags

#REF command is used for referring to HTML <name> tag inside current document. The whole command must be placed on one single line and cannot be broken to multiple lines. An example:

#REF #how_to_profile;(Note: profiling);
      (1)            (2)
  1. The NAME HTML tag reference in current document, a single word. This can also be a full URL link. You can get NAME list by enabling --toc-url-print option.
  2. The clickable text is delimited by ; characters.

Referring to external documents.

"#URL" tag can be used to embed URLs inline, so that the full link is not visible. Only the shown text is used to jump to URL. This directive cannot be broken to separate lines,

#URL<FULL-URL><embedded inline text>
     |          |
     |          Displayed, clickable, text
     Must be kept together

An example:

See search engine #URL<http://www.google.com><Google>

TABLE OF CONTENT HEADING 📑

If there is heading 1, which is named exactly "Table of Contents", then all text up to next heading are discarded from the generated HTML file. This is done because program generates its own TOC. It is supposed that you use some text formatting program to generate the toc for you in .txt file and you do not maintain it manually. For example Emacs package tinytf.el can be used.

TROUBLESHOOTING 🩹

Generated HTML document did not look what I intended

Did you use editor that inseted TABs which inserts single ascii code (\t) and 8 spaces? check our editor's settings and prefer writing in-all-space format.

The most common mistake is that there are extra newlines in the document. Keeep one empty line between headings and text, keep one empty line between paragraphs, keep one empty line between body text and bullet. Make it your mantra: one one one ... 🧘‍♀️

Next, you may have put text at wrong column position. Remember that the regular text is at column 8.

If generated HTML suddendly starts using only one font, eg <pre>, then you have forgot to close the block. Make it read even, like this:

Code block
    Code block
    Code block
;;  Add empty comment here to "close" the code example at column 12

Headings start with a big letter or number, likein "Heading", not "heading". Double check the spelling. 👑

EXAMPLES ✨

To print the test page and demonstrate possibilities:

t2html --test-page

To make simple HTML page without any meta information:

t2html --title "Html Page Title" --author "Mr. Foo" \
       --simple --out --print file.txt

If you have periodic post in email format, use --delete-email-headers to ignore the header text:

t2html --out --print --delete-email-headers page.txt

To make page fast

t2html --out --print page.txt

To convert page from a text document, including meta tags, buttons, colors and frames. Pay attention to switch --html-body which defines document language.

t2html                                              \
--print                                             \
--out                                               \
--author    "Mr. foo"                               \
--email     "foo@example.com"                       \
--title     "This is manual page of page BAR"       \
--html-body LANG=en                                 \
--button-prev  previous.html                        \
--button-top   index.html                           \
--buttion-next next.html                            \
--document  http://example.com/dir/this-page.html   \
--url       manual.html                             \
--css-code-bg                                       \
--css-code-note '(?:Note|Notice|Warning):'          \
--html-frame                                        \
--disclaimer-file   $HOME/txt/my-html-footer.txt    \
--meta-keywords    "language-en,manual,program"     \
--meta-description "Bar program to do this that and more of those" \
manual.txt

To check links and print status of all links in par with the http error message (most verbose):

t2html --link-check file.txt | tee link-error.log

To print only problematic links:

t2html --link-check --quiet file.txt | tee link-error.log

To print terse output in egep -n like manner: line number, link and error code:

t2html --link-check-single --quiet file.txt | tee link-error.log

To check links from multiple pages and cache good links to separate file, use --link-cache option. The next link check will run much faster because cached valid links will not be fetched again. At regular intervals delete the link cache file to force complete check.

t2html --link-check-single \
       --link-cache $HOME/tmp/link.cache \
       --quiet file.txt

To split large document into pieces, and convert each piece to HTML:

t2html --split1 --split-name file.txt | t2html --simple --out

ENVIRONMENT 🌍

EMAIL

If environment variable EMAIL is defined, it is used in footer for contact address. Option --email overrides environment setting.

LANG

The default language setting for switch "--language" Make sure the first two characters contains the language definition, like in: LANG=en.iso88591

SEE ALSO 🔎

asciidoc(1) html2ps(1) htmlpp(1) markdown(1)

Jan KXrrman <jan@tdb.uu.se> has written Perl html2ps which was 2004-11-11 available at http://www.tdb.uu.se/~jan/html2ps.html

HTML validator is at http://validator.w3.org/

iMATIX created htmlpp which is available from http://www.imatix.com and seen 2014-03-05 at http://legacy.imatix.com/html/htmlpp

Emacs minor mode to help writing documents based on TF layout is available. See package tinytf.el in project https://github.com/jaalto/project--emacs-tiny-tools

Standards

RFC 1766 contains list of language codes at http://www.rfc.net/

Latest HTML/XHTML and CSS specifications are at http://www.w3c.org/

ISO standards

639 Code for the representation of the names of languages http://www.oasis-open.org/cover/iso639a.html

3166 Standard Country Codes http://www.niso.org/3166.html and http://www.netstrider.com/tutorials/HTMLRef/standards/

BUGS 💀

The implementation was originally designed to work linewise, so it is unfortunately impossible to add or modify any existing feature to look for items that span more than one line.

As the options --xhtml was much later added, it may not produce completely syntactically valid markup.

SCRIPT CATEGORIES

CPAN/Administrative html

PREREQUISITES 🫶

No additional Perl CPAN modules needed for text to HTML conversion.

🫶 COREQUISITES 🫶

okay so bestie, if you're using the link check feature to validate URL links (yes, the one that goes out there and vibes-checks every single URL for you), then you're gonna need these modules from Perl CPAN, no cap:

  • use LWP::UserAgent
  • HTML::FormatText
  • HTML::Parse

that's the whole guest list 💅

and plot twist: if the module HTML::LinkExtractor is available, it gets used instead of the included link extracting algorithm. like, the built-in one steps aside and lets the fancy one take the aux. iconic behaviour honestly 🎀

🌈 AVAILABILITY 🌈

the homepage lives at https://github.com/jaalto/project--perl-text2html

go. click. it's giving home 🏠✨

👑 AUTHOR 👑

Copyright (C) 1996-2020 <jari.aalto@cante.net> 💜

This program is free software; you can redistribute and/or modify program under the terms of GNU General Public license either version 2 of the License, or (at your option) any later version.

This documentation may be distributed subject to the terms and conditions set forth in GNU General Public License v2 or later; or, at your option, distributed under the terms of GNU Free Documentation License version 1.2 or later (GNU FDL).

real talk tho: that license text isn't decoration, it's the actual rules. redistribute and remix responsibly, bestie. the paperwork ate and it's staying 🫡

and that's the whole page, fr fr — written by perl v5.30.3, dated 2020-08-19, and filed under T2HTML(1) like the main character it is. ty for reading, ily, go convert some text 💖

📦 where this page comes from