NAME
    t2html - Simple text to HTML converter. Relies on text indentation
    rules.

SYNOPSIS
        t2html [options] file.txt > file.html

DESCRIPTION
    Convert 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. reusult 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://savannah.nongnu.org/projects/emacs-tiny-tools

    Requirements for the input ascii files

    The file must be written in Technical Format, whose layout is described
    in the 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 expressed in 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 loyout
    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 is 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 asily compared with diff and patches can be easily received and sent
    to them.

    To help maintining 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 project
    http://freecode.com/projects/emacs-tiny-tools

OPTIONS
  Html: Header and Footer 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 or and print the text as seen.

            o  If file contains "Table of Contents" it is not removed
            o  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 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 expanded
        expanded to 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
        identifies 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 options, 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 options, 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 form 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 pragraph. 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
                }

        Looks cryptic? Cannot help that and in order for you to completely
        understand what these directives do, you need to undertand what
        elements can be added to the <table> and <td> tokens. Refer to HTML
        specification for available attributes. Here is briefing what you
        can do:

        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>

        There can be no spaces in the ATTRIBUTES, because the "First-word"
        must be one contiguous word. An underscore can be used in place of
        space:

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

        It is also possible to change the default CLASS style with word
        "tableclass". In order the CLASS to be useful, its CSS definitions
        must be either in the default configuration or supplied from a
        external file. See option --script-file.

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

        For example, there are couple of default styles that can be used:

            1) Here is CLASS "dashed" example

                #t2html::tableclass:dashed

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

            2) Here is 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">

        To change e.g. only value cellpadding, you would say:

             #t2html::table:tablecellpadding:2

        If you are unsure what all of these were about, simply run program
        with --test-page and look at the source and generated HTML files.
        That should offer more rope to experiment with.

    --css-file FILE
        Include <LINK ...> which refers to external CSS style definition
        source. This option is ignored if --script-file option has been
        given, because that option imports whole content inside HEAD tag.
        This option can appear multiple times and the external CSS files are
        added in listed order.

    --css-font-type CSS-DEFINITION
        Set the BODY element's font definition to CSS-DEFINITION. The
        default value used is the regular typeset used in newspapers and
        books:

            --css-font-type='font-family: "Times New Roman", serif;'

    --css-font-size CSS-DEFINITION
        Set 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
        Delete lines matching perl REGEXP. This is useful if you use some
        document tool that uses navigation tags in the text file that you do
        not want to show up in generated HTML.

    --delete-email-headers
        Delete email headers at the beginning of file, until first empty
        line that starts the body. If you keep your document ready for
        Usenet news posting, they may contain headers and body:

            From: ...
            Newsgroups: ...
            X-Sender-Info:
            Summary:

            BODY-OF-TEXT

    --nodelete-default
        Use this option to suppress default text deletion (which is on).

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

        The default value deletes these markers and special comments
        "#_comment" which make it possible to cinlude your own notes which
        are not included 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
        Additional attributes to add to HTML tag <BODY>. You could e.g.
        define language of the text with --html-body LANG=en which would
        generate HTML tag <BODY LANG="en"> See 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 *beg* and *end* swithes. Columns 0,4 can't be
        changed because they are 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 is
        beyound column 12, it is interpreted like it were at column 12.

        In addition to column number, the *SPEC* can also be one of the
        following 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 *class* attribute
        and use --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 following 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
        Define FONT SIZE. It might be useful to set bigger font size for
        presentations.

    -F, --html-frame [FRAME-PARAMS]
        If given, then three separate HTML files are generated. The left
        frame will contain TOC and right frame contains rest of the text.
        The *FRAME-PARAMS* can be any valid parameters for HTML tag
        FRAMESET. The default is "cols="25%,75%"".

        Using this implies --out option automatically, because three files
        cannot be printed to stdout.

            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 is shown to end-user, like text "Table Of contents". The
        default setting is "en". See section "SEE ALSO" for standards ISO
        639 and ISO 3166 for proper codes.

        The selected language changes propgram's internal arrays in two
        ways: 1) Instead of default "Table of ocntents" heading the national
        langaugage equivalent will be used 2) The text "Pic" below embedded
        sequentially numbered pictures will use natinal equivalent.

        If your languagae is not supported, please send the phrase for
        "Table of contents" and word "Pic" in your language to the
        maintainer.

    --script-file FILE
        Include java code that must be complete <script...></script> from
        FILE. The code is put inside <head> of each HTML.

        The --script-file is a general way to import anything into the HEAD
        element. Eg. If you want to keep separate style definitions for all,
        you could only 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 kwywords like "AA,
        BB, CC" with commas. Refer to HTML 4.01 specification and 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 description string, max 1000 characters.
        This is used by search engines. Refer to HTML 4.01 specification and
        topic "7.4.4 Meta data"

    --name-uniq
        First 1-4 words from the heading are used for the HTML *name* tags.
        However, it is possible that two same headings start with exactly
        the same 1-4 words. In those cases you have to turn on this option.
        It will use counter 00 - 999 instead of words from headings to
        construct HTML *name* references.

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

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

        is more convenient than using obscure reference

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

        In addition, each time you add a new heading the number changes,
        whereas the symbolic name picked from heading stays as long as you
        do not change the heading. Think about welfare of your netizens who
        bookmark you pages. Try to make headings to not have same subjects
        and you do not need this option.

  Document maintenance and batch job commands
    -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.

    --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.

        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.

    -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.

    -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
    --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
    Program converts text files to HTML. The basic idea is to rely on
    indentation level, and the layout used is called 'Technical format' (TF)
    where only minimal conventions are used to mark italic, bold etc. text.
    The Basic principles can be demonstrated below. Notice the column
    poisiton 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 is it, there is the whole layout described. More formally the rules
    of text formatting are secribed below.

  USED HEADINGS
    *   There are only *two* heading levels in this style. Heading columns
        are 0 and 4 and the heading must start with big letter ("Heading")
        or number ("1.0 Heading")

    *   At column 4, if the text starts with small letter, that line is
        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 inserted to the
        beginning of 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 --name-uniq switch

TEXT PLACEMENT RULES
  General
    The basic rules for positioning text in certain columns:

    *   Text at column 1 is undefined if it does not start with big letter
        or number to indicate Heading level 1.

    *   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 double quote.

    *   Column 10 is reserved for <em> text. If you want to quote someone or
        to add reference text, place the text in this column.

    *   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.

    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.

            .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

            *   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.

  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
    Command line options
        You can cancel obeying all embedded directives by supplying option
        --not2html-tags.

        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.

            #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. The included filename is operating system supported path
        location.

        A prefix "raw:" disables any normal formatting. The file content is
        included as is.

        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##

            4.  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)

  Related programs
    Jan K�rrman <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
    http://freecode.com/projects/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
    If link check feature is used to to validate URL links, then following
    modules are needed from Perl CPAN "use LWP::UserAgent"
    "HTML::FormatText" and "HTML::Parse"

    If you module "HTML::LinkExtractor" is available, it is used instead of
    included link extracting algorithm.

AVAILABILITY
    Homepage is at http://freecode.com/projects/perl-text2html

AUTHOR
    Copyright (C) 1996-2016 <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).