.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.32)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "T2HTML 1"
.TH T2HTML 1 "2016-10-20" "perl v5.22.2" "Perl Text to HTML Converter"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
t2html \- Simple text to HTML converter. Relies on text indentation rules.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    t2html [options] file.txt > file.html
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Convert pure text files into nice looking, possibly framed, \s-1HTML\s0
pages. An example of conversion:
.PP
.Vb 2
\&  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
.Ve
.PP
\&\fBRequirements for the input ascii files\fR
.PP
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).
.PP
The idea of technical format is that each column represents different
rendering layout in the generated \s-1HTML.\s0 There is no special markup needed
in the text file, so you can use the text version as a master copy of a \s-1FAQ\s0
etc. Bullets, numbered lists, word emphasis and quotation etc. can
expressed in natural way.
.PP
\&\fB\s-1HTML\s0 description\fR
.PP
The generated \s-1HTML\s0 includes embedded Cascading Style Sheet 2 (\s-1CSS2\s0) and a
small piece of Java code. The \s-1CSS2\s0 is used to colorize the page loyout and
to define suitable printing font sizes. The generated \s-1HTML\s0 also takes an
approach to support \s-1XHTML.\s0 See page http://www.w3.org/TR/xhtml1/#guidelines
where the backward compatibility recommendations are outlined:
.PP
.Vb 4
\&    Legal HTML          XHTML requires
\&    <P>                 <p> ..</p>
\&    <BR>                <br></br>
\&    <HR>                <hr></hr>
.Ve
.PP
\&\s-1XHTML\s0 does not support fragment identifiers #foo, with the \f(CW\*(C`name\*(C'\fR element,
but uses \f(CW\*(C`id\*(C'\fR instead. For backward compatibility both elements are
defined:
.PP
.Vb 1
\&    < ..name="tag">     Is now <.. name="tag" id="tag">
.Ve
.PP
\&\s-1NOTE:\s0 This program was never designed to be used for \s-1XHTML\s0 and the
strict \s-1XHTML\s0 validity is not to be expected.
.PP
\&\fBMotivation\fR
.PP
The easiest format to write large documents, like FAQs, is text. A text
file offers WysiWyg editing and it can be turned easily into \s-1HTML\s0 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.
.PP
Text files are also the only sensible format if documents are kept under
version control like \s-1RCS, CVS, SVN,\s0 Arch, Perforce, ClearCase. They can be
asily compared with diff and patches can be easily received and sent to
them.
.PP
To help maintining large documents, there is also available an
\&\fIEmacs\fR minor mode, package called \fItinytf.el\fR, 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
.SH "OPTIONS"
.IX Header "OPTIONS"
.SS "Html: Header and Footer options"
.IX Subsection "Html: Header and Footer options"
.IP "\fB\-\-as\-is\fR" 4
.IX Item "--as-is"
Any extra \s-1HTML\s0 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.
.Sp
.Vb 2
\&    o  If file contains "Table of Contents" it is not removed
\&    o  Table of Content block is not created (it usually would)
.Ve
.IP "\fB\-\-author \-a \s-1STR\s0\fR" 4
.IX Item "--author -a STR"
Author of document e.g. \fB\-\-author \*(L"John Doe\*(R"\fR
.IP "\fB\-\-disclaimer\-file\fR \s-1FILE\s0" 4
.IX Item "--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 \f(CW\*(C`\-\-quiet\*(C'\fR and
\&\f(CW\*(C`\-\-simple\*(C'\fR suppress disclaimers.
.IP "\fB\-\-document \s-1FILE\s0\fR" 4
.IX Item "--document FILE"
\&\fBName\fR of the document or filename. You could list all
alternative URLs to the document with this option.
.IP "\fB\-\-email \-e \s-1EMAIL\s0\fR" 4
.IX Item "--email -e EMAIL"
The contact address of the author of the document. Must be pure email
address with no \*(L"<\*(R" and \*(L">\*(R" characters included. Eg.
\&\fB\-\-email foo@example.com\fR
.Sp
.Vb 2
\&    \-\-email "<me@here.com>"     WRONG
\&    \-\-email "me@here.com"       right
.Ve
.IP "\fB\-\-simple\fR \fB\-s\fR" 4
.IX Item "--simple -s"
Print minimum footer only: contact, email and date. Use \f(CW\*(C`\-\-quiet\*(C'\fR to
completely discard footer.
.IP "\fB\-\-t2html\-tags\fR" 4
.IX Item "--t2html-tags"
Allow processing embedded #T2HTML\-<tag> directives inside file. See full
explanation by reading topic \f(CW\*(C`EMBEDDED DIRECTIVES INSIDE TEXT\*(C'\fR. By
default, you do not need to to supply this option \- it is \*(L"on\*(R" by default.
.Sp
To disregard embedded directives in text file, supply \*(L"no\*(R" option:
\&\fB\-\-not2html\-tags\fR.
.IP "\fB\-\-title \s-1STR\s0\fR \fB\-t \s-1STR\s0\fR" 4
.IX Item "--title STR -t STR"
The title text that appears in top frame of browser.
.IP "\fB\-\-url \s-1URL\s0\fR" 4
.IX Item "--url URL"
.PP
Location of the \s-1HTML\s0 file. When \fB\-\-document\fR gave the name, this gives the
location. This information is printed at the Footer.
.SS "Html: Navigation urls"
.IX Subsection "Html: Navigation urls"
.IP "\fB\-\-base \s-1URL\s0\fR" 4
.IX Item "--base URL"
\&\s-1URL\s0 location of the \s-1HTML\s0 file in the \fBdestination site\fR where it will be
put available. This option is needed only if the document is hosted on a
\&\s-1FTP\s0 server (rare, but possible). A \s-1FTP\s0 server based document cannot use
Table Of Contents links (fragment \fI#tag\fR identifiers) unless \s-1HTML\s0 tag \s-1BASE\s0
is also defined.
.Sp
The argument can be full \s-1URL\s0 to the document:
.Sp
.Vb 2
\&    \-\-base ftp://ftp.example.com/file.html
\&    \-\-base ftp://ftp.example.com/
.Ve
.IP "\fB\-\-button\-heading\-top\fR" 4
.IX Item "--button-heading-top"
Add additional \fB[toc]\fR navigation button to the end of each heading. This
may be useful in long non-framed \s-1HTML\s0 files.
.IP "\fB\-\-button\-top \s-1URL\s0\fR" 4
.IX Item "--button-top URL"
Buttons are placed at the top of document in order: [previous][top][next]
and \fI\-\-button\-*\fR options define the URLs.
.Sp
If \s-1URL\s0 is string \fInone\fR then no button is inserted. This may be handy if
the buttons are defined by a separate program. And example using Perl:
.Sp
.Vb 1
\&    #!/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
.Ve
.IP "\fB\-\-button\-prev \s-1URL\s0\fR" 4
.IX Item "--button-prev URL"
\&\s-1URL\s0 to go to previous document or string \fInone\fR.
.IP "\fB\-\-button\-next \s-1URL\s0\fR" 4
.IX Item "--button-next URL"
\&\s-1URL\s0 to go to next document or string \fInone\fR.
.IP "\fB\-\-reference tag=value\fR" 4
.IX Item "--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 \s-1TAG\s0 is replaced with \s-1VALUE. E\s0.g. when given following options:
.Sp
.Vb 2
\&    \-\-reference "#HOME\-URL=http://www.example.com/dir"
\&    \-\-reference "#ARCHIVE\-URL=http://www.example.com/dir/dir2"
.Ve
.Sp
When referenced in text, the generated \s-1HTML\s0 includes expanded expanded to
values. An example text:
.Sp
.Vb 2
\&        The homepage is #HOME\-URL/page.html and the mirrot page it at
\&        #ARCHIVE\-URL/page.html where you can find the latest version.
.Ve
.IP "\fB\-R, \-\-reference\-separator \s-1STRING\s0\fR" 4
.IX Item "-R, --reference-separator STRING"
See above. String that is used to split the \s-1TAG\s0 and \s-1VALUE.\s0 Default is equal
sign \*(L"=\*(R".
.IP "\fB\-T, \-\-toc\-url\-print\fR" 4
.IX Item "-T, --toc-url-print"
Display URLs (constructed from headings) that build up the Table of Contents
(\s-1NAME AHREF\s0 tags) in a document. The list is outputted to stderr, so that
it can be separated:
.Sp
.Vb 1
\&    % t2html \-\-toc\-url\-print tmp.txt > file.html 2> toc\-list.txt
.Ve
.Sp
Where would you need this? If you want to know the fragment identifies
for your file, you need the list of names.
.Sp
.Vb 1
\&  http://www.example.com/myfile.html#fragment\-identifier
.Ve
.SS "Html: Controlling \s-1CSS\s0 generation (\s-1HTML\s0 tables)"
.IX Subsection "Html: Controlling CSS generation (HTML tables)"
.IP "\fB\-\-css\-code\-bg\fR" 4
.IX Item "--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.
.ie n .IP "\fB\-\-css\-code\-note ""\s-1REGEXP"" \s0\fR" 4
.el .IP "\fB\-\-css\-code\-note ``\s-1REGEXP'' \s0\fR" 4
.IX Item "--css-code-note REGEXP "
Option \fB\-\-css\-code\-bg\fR is required to activate this option. A special word
defined using regexp (default is 'Note:') will mark code sections specially.
The \f(CW\*(C`first word\*(C'\fR is matched against the supplied Perl regexp.
.Sp
The supplied regexp must not, repeat, must not, include any matching group
operators. This simply means, that grouping parenthesis like
\&\f(CW\*(C`(one|two|three)\*(C'\fR are not allowed. You must use the Perl non-grouping ones
like \f(CW\*(C`(?:one|two|three)\*(C'\fR. Please refer to perl manual page [perlre] if
this short introduction did not give enough rope.
.Sp
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.
.Sp
An example will clarify. Suppose that you passed options \fB\-\-css\-code\-bg\fR
and \fB\-\-css\-code\-note='(?:Notice|Note):'\fR, which instructed to treat the
first paragraphs at column 12 differently. Like this:
.Sp
.Vb 2
\&    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 \*(AqNotice:\*(Aq.
\&        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
\&        }
.Ve
.Sp
One note, text written with initial special word, like \f(CW\*(C`Notice:\*(C'\fR,
must all fit in one full pragraph. Any other paragraphs that follow,
are rendered as code sections. Like here:
.Sp
.Vb 2
\&    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 \*(AqNotice:\*(Aq
\&        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
\&        }
.Ve
.Sp
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:
.Sp
.Vb 1
\&    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
\&        }
.Ve
.Sp
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 \s-1HTML\s0 specification
for available attributes. Here is briefing what you can do:
.Sp
The start command is:
.Sp
.Vb 4
\&    #t2html::
\&            |
\&            After this comes attribute pairs in form key:value
\&            and multiple ones as key1:value1:key2:value2 ...
.Ve
.Sp
The \f(CW\*(C`key:value\*(C'\fR pairs can be:
.Sp
.Vb 3
\&    td:ATTRIBUTES
\&       |
\&       This is converted into <td attributes>
\&
\&    table:ATTRIBUTES
\&          |
\&          This is converted into <table attributes>
.Ve
.Sp
There can be no spaces in the \s-1ATTRIBUTES,\s0 because the \f(CW\*(C`First\-word\*(C'\fR must
be one contiguous word. An underscore can be used in place of space:
.Sp
.Vb 3
\&    table:border=1_width=94%
\&          |
\&          Interpreted as <table border="1" width="94%">
.Ve
.Sp
It is also possible to change the default \s-1CLASS\s0 style with word
\&\f(CW\*(C`tableclass\*(C'\fR. In order the \s-1CLASS\s0 to be useful, its \s-1CSS\s0 definitions must be
either in the default configuration or supplied from a external file.
See option \fB\-\-script\-file\fR.
.Sp
.Vb 3
\&    tableclass:name
\&               |
\&               Interpreted as <table class="name">
.Ve
.Sp
For example, there are couple of default styles that can be used:
.Sp
.Vb 1
\&    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
\&            }
.Ve
.Sp
You can change any individual value of the default table
definition which is:
.Sp
.Vb 1
\&    <table  class="shade\-note">
.Ve
.Sp
To change e.g. only value cellpadding, you would say:
.Sp
.Vb 1
\&     #t2html::table:tablecellpadding:2
.Ve
.Sp
If you are unsure what all of these were about, simply run program with
\&\fB\-\-test\-page\fR and look at the source and generated \s-1HTML\s0 files. That
should offer more rope to experiment with.
.IP "\fB\-\-css\-file \s-1FILE\s0\fR" 4
.IX Item "--css-file FILE"
Include <\s-1LINK ...\s0> which refers to external \s-1CSS\s0 style definition source.
This option is ignored if \fB\-\-script\-file\fR option has been given,
because that option imports whole content inside \s-1HEAD\s0 tag. This option
can appear multiple times and the external \s-1CSS\s0 files are added in
listed order.
.IP "\fB\-\-css\-font\-type CSS-DEFINITION\fR" 4
.IX Item "--css-font-type CSS-DEFINITION"
Set the \s-1BODY\s0 element's font definition to CSS-DEFINITION. The
default value used is the regular typeset used in newspapers and books:
.Sp
.Vb 1
\&    \-\-css\-font\-type=\*(Aqfont\-family: "Times New Roman", serif;\*(Aq
.Ve
.IP "\fB\-\-css\-font\-size CSS-DEFINITION\fR" 4
.IX Item "--css-font-size CSS-DEFINITION"
Set the body element's font size to CSS-DEFINITION. The default font
size is expressed in points:
.Sp
.Vb 1
\&    \-\-css\-font\-size="font\-size: 12pt;"
.Ve
.SS "Html: Controlling the body of document"
.IX Subsection "Html: Controlling the body of document"
.IP "\fB\-\-delete \s-1REGEXP\s0\fR" 4
.IX Item "--delete REGEXP"
Delete lines matching perl \s-1REGEXP.\s0 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 \s-1HTML.\s0
.IP "\fB\-\-delete\-email\-headers\fR" 4
.IX Item "--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:
.Sp
.Vb 4
\&    From: ...
\&    Newsgroups: ...
\&    X\-Sender\-Info:
\&    Summary:
\&
\&    BODY\-OF\-TEXT
.Ve
.IP "\fB\-\-nodelete\-default\fR" 4
.IX Item "--nodelete-default"
Use this option to suppress default text deletion (which is on).
.Sp
Emacs \f(CW\*(C`folding.el\*(C'\fR package and vi can be used with any text or
programming language to place sections of text between tags \fB{{{\fR and
\&\fB}}}\fR. 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/
.Sp
The default value deletes these markers and special comments
\&\f(CW\*(C`#_comment\*(C'\fR which make it possible to cinlude your own notes which
are not included in the generated output.
.Sp
.Vb 1
\&  {{{ 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 ...
\&
\&  }}}
.Ve
.IP "\fB\-\-html\-body \s-1STR\s0\fR" 4
.IX Item "--html-body STR"
Additional attributes to add to \s-1HTML\s0 tag <\s-1BODY\s0>. You could e.g. define
language of the text with \fB\-\-html\-body LANG=en\fR which would generate
\&\s-1HTML\s0 tag <\s-1BODY\s0 LANG=\*(L"en\*(R"> See section \*(L"\s-1SEE ALSO\*(R"\s0 for \s-1ISO 639.\s0
.ie n .IP "\fB\-\-html\-column\-beg=""\s-1SPEC\s0 HTML-SPEC""\fR" 4
.el .IP "\fB\-\-html\-column\-beg=``\s-1SPEC\s0 HTML-SPEC''\fR" 4
.IX Item "--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 \fIbeg\fR and \fIend\fR swithes. Columns 0,4 can't be changed because
they are reserved for headings. Here are some samples:
.Sp
.Vb 2
\&    \-\-html\-column\-beg="7quote <em class=\*(Aqquote7\*(Aq>"
\&    \-\-html\-column\-end="7quote </em>"
\&
\&    \-\-html\-column\-beg="10    <pre> class=\*(Aqcolumn10\*(Aq"
\&    \-\-html\-column\-end="10    </pre>"
\&
\&    \-\-html\-column\-beg="quote <span class=\*(Aqword\*(Aq>"
\&    \-\-html\-column\-end="quote </span>"
.Ve
.Sp
\&\fBNote:\fR You can only give specifications up till column 12. If text
is beyound column 12, it is interpreted like it were at column 12.
.Sp
In addition to column number, the \fI\s-1SPEC\s0\fR can also be one of the
following strings
.Sp
.Vb 8
\&    Spec    equivalent word markup
\&    \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
\&    quote   \`\*(Aq
\&    bold    _
\&    emp     *
\&    small   +
\&    big     =
\&    ref     []   like: [Michael] referred to [rfc822]
\&
\&    Other available Specs
\&    \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
\&    7quote      When column 7 starts with double quote.
.Ve
.Sp
For style sheet values for each color, refer to \fIclass\fR attribute and use
\&\fB\-\-script\-file\fR option to import definitions. Usually /usr/lib/X11/rgb.txt
lists possible color values and the \s-1HTML\s0 standard at http://www.w3.org/
defines following standard named colors:
.Sp
.Vb 8
\&    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
.Ve
.ie n .IP "\fB\-\-html\-column\-end=""\s-1COL\s0 HTML-SPEC""\fR" 4
.el .IP "\fB\-\-html\-column\-end=``\s-1COL\s0 HTML-SPEC''\fR" 4
.IX Item "--html-column-end=COL HTML-SPEC"
See \fB\-\-html\-column\-beg\fR
.IP "\fB\-\-html\-font \s-1SIZE\s0\fR" 4
.IX Item "--html-font SIZE"
Define \s-1FONT SIZE.\s0 It might be useful to set bigger font size for presentations.
.IP "\fB\-F, \-\-html\-frame [\s-1FRAME\-PARAMS\s0]\fR" 4
.IX Item "-F, --html-frame [FRAME-PARAMS]"
If given, then three separate \s-1HTML\s0 files are generated. The left frame will
contain \s-1TOC\s0 and right frame contains rest of the text. The \fIFRAME-PARAMS\fR
can be any valid parameters for \s-1HTML\s0 tag \s-1FRAMESET.\s0 The default is
\&\f(CW\*(C`cols="25%,75%"\*(C'\fR.
.Sp
Using this implies \fB\-\-out\fR option automatically, because three files
cannot be printed to stdout.
.Sp
.Vb 1
\&    file.html
\&
\&    \-\-> file.html       The Frame file, point browser here
\&        file\-toc.html   Left frame (navigation)
\&        file\-body.html  Right frame (content)
.Ve
.IP "\fB\-\-language \s-1ID\s0\fR" 4
.IX Item "--language ID"
Use language \s-1ID,\s0 a two character \s-1ISO\s0 identifier like \*(L"en\*(R" for English
during the generation of \s-1HTML.\s0 This only affects the text that is shown to
end-user, like text \*(L"Table Of contents\*(R". The default setting is \*(L"en\*(R". See
section \*(L"\s-1SEE ALSO\*(R"\s0 for standards \s-1ISO 639\s0 and \s-1ISO 3166\s0 for proper codes.
.Sp
The selected language changes propgram's internal arrays in two ways: 1)
Instead of default \*(L"Table of ocntents\*(R" heading the national langaugage
equivalent will be used 2) The text \*(L"Pic\*(R" below embedded sequentially
numbered pictures will use natinal equivalent.
.Sp
If your languagae is not supported, please send the phrase for \*(L"Table of
contents\*(R" and word \*(L"Pic\*(R" in your language to the maintainer.
.IP "\fB\-\-script\-file \s-1FILE\s0\fR" 4
.IX Item "--script-file FILE"
Include java code that must be complete <script...></script> from \s-1FILE.\s0 The
code is put inside <head> of each \s-1HTML.\s0
.Sp
The \fB\-\-script\-file\fR is a general way to import anything into the \s-1HEAD\s0
element. Eg. If you want to keep separate style definitions for
all, you could only import a pointer to a style sheet.
See \fI14.3.2 Specifying external style sheets\fR in \s-1HTML 4.0\s0 standard.
.IP "\fB\-\-meta\-keywords \s-1STR\s0\fR" 4
.IX Item "--meta-keywords STR"
Meta keywords. Used by search engines. Separate kwywords like \*(L"\s-1AA, BB, CC\*(R"\s0
with commas. Refer to \s-1HTML 4.01\s0 specification and topic \*(L"7.4.4 Meta data\*(R"
and see http://www.htmlhelp.com/reference/wilbur/ and
.Sp
.Vb 1
\&    \-\-meta\-keywords "AA,BB,CC"
.Ve
.IP "\fB\-\-meta\-description \s-1STR\s0\fR" 4
.IX Item "--meta-description STR"
Meta description. Include description string, max 1000 characters. This is
used by search engines. Refer to \s-1HTML 4.01\s0 specification and topic
\&\*(L"7.4.4 Meta data\*(R"
.IP "\fB\-\-name\-uniq\fR" 4
.IX Item "--name-uniq"
First 1\-4 words from the heading are used for the \s-1HTML \s0\fIname\fR 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 \s-1HTML \s0\fIname\fR
references.
.Sp
Please use this option only in emergencies, because referring to jump block
\&\fIname\fR via
.Sp
.Vb 1
\&    httpI://example.com/doc.html#header_name
.Ve
.Sp
is more convenient than using obscure reference
.Sp
.Vb 1
\&    httpI://example.com/doc.html#11
.Ve
.Sp
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.
.SS "Document maintenance and batch job commands"
.IX Subsection "Document maintenance and batch job commands"
.IP "\fB\-A, \-\-auto\-detect\fR" 4
.IX Item "-A, --auto-detect"
Convert file only if tag \f(CW\*(C`#T2HTML\-\*(C'\fR is found from file. This option
is handy if you run a batch command to convert all files to \s-1HTML,\s0 but
only if they look like \s-1HTML\s0 base files:
.Sp
.Vb 2
\&    find . \-name "*.txt" \-type f \e
\&         \-exec t2html \-\-auto\-detect \-\-verbose \-\-out {} \e;
.Ve
.Sp
The command searches all *.txt files under current directory and feeds
them to conversion program. The \fB\-\-auto\-detect\fR only converts files
which include \f(CW\*(C`#T2HTML\-\*(C'\fR directives. Other text files are not
converted.
.IP "\fB\-\-link\-check \-l\fR" 4
.IX Item "--link-check -l"
Check all http and ftp links.
\&\fIThis option is supposed to be run standalone\fR
Option \fB\-\-quiet\fR has special meaning when used with link check.
.Sp
With this option you can regularly validate your document and remove dead
links or update moved links. Problematic links are outputted to \fIstderr\fR.
This link check feature is available only if you have the \s-1LWP\s0 web
library installed. Program will check if you have it at runtime.
.Sp
Links that are big, e.g. which match \fItar.gz .zip ...\fR or that run
programs (links with ? character) are ignored because the \s-1GET\s0 request
used in checking would return whole content of the link and it would.
be too expensive.
.Sp
A suggestion: When you put binary links to your documents, add them with
space:
.Sp
.Vb 1
\&    http://example.com/dir/dir/ filename.tar.gz
.Ve
.Sp
Then the program \fIdoes\fR 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.
.IP "\fB\-L, \-\-link\-check\-single\fR" 4
.IX Item "-L, --link-check-single"
Print condensed output in \fIgrep \-n\fR like manner \fI\s-1FILE:LINE:MESSAGE\s0\fR
.Sp
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.
.IP "\fB\-o, \-\-out\fR" 4
.IX Item "-o, --out"
write generated \s-1HTML\s0 to file that is derived from the input filename.
.Sp
.Vb 3
\&    \-\-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
.Ve
.IP "\fB\-\-link\-cache \s-1CACHE_FILE\s0\fR" 4
.IX Item "--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 \*(L"ok\*(R" 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.
.Sp
.Vb 3
\&    $ t2html \-\-link\-check\-single \e
\&      \-\-quiet \-\-link\-cache ~tmp/link.cache \e
\&      \`find . \-name "*.txt" \-type f\`
.Ve
.IP "\fB\-O, \-\-out\-dir \s-1DIR\s0\fR" 4
.IX Item "-O, --out-dir DIR"
Like \fB\-\-out\fR, but chop the directory part and write output files to
\&\s-1DIR.\s0 The following would generate the \s-1HTML\s0 file to current directory:
.Sp
.Vb 1
\&    \-\-out\-dir .
.Ve
.Sp
If you have automated tool that fills in the directory, you can use word
\&\fBnone\fR to ignore this option. The following is a no-op, it will not generate
output to directory \*(L"none\*(R":
.Sp
.Vb 1
\&    \-\-out\-dir none
.Ve
.IP "\fB\-p, \-\-print\fR" 4
.IX Item "-p, --print"
Print filename to stdout after \s-1HTML\s0 processing. Normally program prints
no file names, only the generated \s-1HTML.\s0
.Sp
.Vb 1
\&    % t2html \-\-out \-\-print page.txt
\&
\&    \-\-> page.html
.Ve
.IP "\fB\-P, \-\-print\-url\fR" 4
.IX Item "-P, --print-url"
Print filename in \s-1URL\s0 format. This is useful if you want to check the
layout immediately with your browser.
.Sp
.Vb 1
\&    % t2html \-\-out \-\-print\-url page.txt | xargs lynx
\&
\&    \-\-> file: /users/foo/txt/page.html
.Ve
.IP "\fB\-\-split \s-1REGEXP\s0\fR" 4
.IX Item "--split REGEXP"
Split document into smaller pieces when \s-1REGEXP\s0 matches. \fISplit commands
are standalone\fR, meaning, that it starts and quits. No \s-1HTML\s0 conversion for
the file is engaged.
.Sp
If \s-1REGEXP\s0 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:
.Sp
.Vb 1
\&    \-\-split \*(Aq^[A\-Z]\*(Aq
.Ve
.Sp
A sequential numbers, 3 digits, are added to the generated partials:
.Sp
.Vb 1
\&    filename.txt\-NNN
.Ve
.Sp
The split feature is handy if you want to generate slides from each heading:
First split the document, then convert each part to \s-1HTML\s0 and finally print
each part (page) separately to printer.
.IP "\fB\-S1, \-\-split1\fR" 4
.IX Item "-S1, --split1"
This is shorthand of \fB\-\-split\fR command. Define regexp to split on toplevel
heading.
.IP "\fB\-S2, \-\-split2\fR" 4
.IX Item "-S2, --split2"
This is shorthand of \fB\-\-split\fR command. Define regexp to split on second
level heading.
.IP "\fB\-SN, \-\-split\-named\-files\fR" 4
.IX Item "-SN, --split-named-files"
Additional directive for split commands. If you split e.g. by headings using
\&\fB\-\-split1\fR, 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:
.Sp
.Vb 2
\&    Program guidelines
\&    Conclusion
.Ve
.Sp
Then the generated partial filenames would be as follows.
.Sp
.Vb 2
\&    FILENAME\-program_guidelines
\&    FILENAME\-conclusion
.Ve
.IP "\fB\-X, \-\-xhtml\fR" 4
.IX Item "-X, --xhtml"
Render using strict \s-1XHTML.\s0 This means using <hr/>, <br/> and paragraphs
use <p>..</p>.
.Sp
\&\f(CW\*(C`Note: this option is experimental. See BUGS\*(C'\fR
.SS "Miscellaneous options"
.IX Subsection "Miscellaneous options"
.IP "\fB\-\-debug \s-1LEVEL\s0\fR" 4
.IX Item "--debug LEVEL"
Turn on debug with positive \s-1LEVEL\s0 number. Zero means no debug.
.IP "\fB\-\-help \-h\fR" 4
.IX Item "--help -h"
Print help screen. Terminates program.
.IP "\fB\-\-help\-css\fR" 4
.IX Item "--help-css"
Print default \s-1CSS\s0 used. Terminates program. You can copy and modify
this output and instruct to use your own with \fB\-\-css\-file=FILE\fR.
You can also embed the option to files with \f(CW\*(C`#T2HTML\-OPTION\*(C'\fR
directive.
.IP "\fB\-\-help\-html\fR" 4
.IX Item "--help-html"
Print help in \s-1HTML\s0 format. Terminates program.
.IP "\fB\-\-help\-man\fR" 4
.IX Item "--help-man"
Print help page in Unix manual page format. You want to feed this output to
\&\fBnroff \-man\fR in order to read it. Terminates program.
.IP "\fB\-\-test\-page\fR" 4
.IX Item "--test-page"
Print the test page: \s-1HTML\s0 and example text file that demonstrates
the capabilities.
.IP "\fB\-\-time\fR" 4
.IX Item "--time"
Print to stderr time spent used for handling the file.
.IP "\fB\-v, \-\-verbose [\s-1LEVEL\s0]\fR" 4
.IX Item "-v, --verbose [LEVEL]"
Print verbose messages.
.IP "\fB\-q, \-\-quiet\fR" 4
.IX Item "-q, --quiet"
Print no footer at all. This option has different meaning if
\&\fI\-\-link\-check\fR option is turned on: print only erroneous links.
.IP "\fBV, \-\-version\fR" 4
.IX Item "V, --version"
Print program version information.
.SH "FORMAT DESCRIPTION"
.IX Header "FORMAT DESCRIPTION"
Program converts text files to \s-1HTML.\s0 The basic idea is to rely on
indentation level, and the layout used is called 'Technical format'
(\s-1TF\s0) 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:
.PP
.Vb 1
\& \-\-//\-\- 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\*(Aq. You can \`_*nest*_\*(Aq \`the\*(Aq
\&         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 \*(Aqexample\*(Aq 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
.Ve
.PP
That is it, there is the whole layout described. More formally the rules
of text formatting are secribed below.
.SS "\s-1USED HEADINGS\s0"
.IX Subsection "USED HEADINGS"
.IP "\(bu" 4
There are only \fItwo\fR heading levels in this style. Heading columns
are 0 and 4 and the heading must start with big letter (\*(L"Heading\*(R") or
number (\*(L"1.0 Heading\*(R")
.IP "\(bu" 4
At column 4, if the text starts with small letter, that line is interpreted
as <strong>
.IP "\(bu" 4
A \s-1HTML\s0 <hr> mark is added just before printing heading at level 1.
.IP "\(bu" 4
The headings are gathered, the \s-1TOC\s0 is built and inserted to the beginning
of \s-1HTML\s0 page. The \s-1HTML\s0 <name> references used in \s-1TOC\s0 are the first 4
sequential words from the headings. Make sure your headings are uniquely
named, otherwise there will be same \s-1NAME\s0 references in the generated \s-1HTML.\s0
Spaces are converted into underscore when joining the words. If you can not
write unique headings by four words, then you must use \fB\-\-name\-uniq\fR
switch
.SH "TEXT PLACEMENT RULES"
.IX Header "TEXT PLACEMENT RULES"
.SS "General"
.IX Subsection "General"
The basic rules for positioning text in certain columns:
.IP "\(bu" 4
Text at column 1 is undefined if it does not start with big letter or
number to indicate Heading level 1.
.IP "\(bu" 4
Text between columns 2 and 3 is marked with <em>
.IP "\(bu" 4
Column 4 is reserved for heading level 2
.IP "\(bu" 4
Text between columns 5\-7 is marked with <strong>
.IP "\(bu" 4
Text at column 7 is <em> if the first character is double quote.
.IP "\(bu" 4
Column 10 is reserved for <em> text. If you want to quote someone
or to add reference text, place the text in this column.
.IP "\(bu" 4
Text at columns 9 and 11 are marked with <strong>
.PP
Column 8 for text and special codes
.IP "\(bu" 4
Column 8 is reserved for normal text
.IP "\(bu" 4
At the start of text, at column 8, there can be DOT-code or COMMA-code.
.PP
Column 12 is special
.IP "\(bu" 4
Column 12 is treated specially: block is started with <pre> and lines are
marked as <samp></samp>. When the last text at \fIcolumn\fR 12 is found, the
block is closed with </pre>. An example:
.Sp
.Vb 2
\&    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
.Ve
.SS "Additional tokens for use at column 8"
.IX Subsection "Additional tokens for use at column 8"
.IP "\(bu" 4
If there is \f(CW\*(C`.\*(C'\fR(dot) at the beginning of a line and immediately
non-whitespace, then <br> code is added to the end of line.
.Sp
.Vb 3
\&    .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.
.Ve
.IP "\(bu" 4
If there is \f(CW\*(C`,\*(C'\fR(comma) then the <p> code is not inserted if the previous
line is empty. If you use both \f(CW\*(C`.\*(C'\fR(dot) and \f(CW\*(C`,\*(C'\fR(comma), they must be in
order dot-comma. The \f(CW\*(C`,\*(C'\fR(comma) works differently if it is used in bullet
.Sp
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
.Sp
.Vb 2
\&    *   This is a bullet and it has all text ketp together
\&        even if there is another line in the bullet.
.Ve
.Sp
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
.Sp
.Vb 2
\&    *   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.. }
.Ve
.SS "Special text markings"
.IX Subsection "Special text markings"
.IP "italic, bold, code, small, big tokens" 4
.IX Item "italic, bold, code, small, big tokens"
.Vb 3
\&    _this_      is interpreted as <strong class=\*(Aqword\*(Aq>this</strong>
\&    *this*      is interpreted as <em class=\*(Aqword\*(Aq>this</em>
\&    \`this\*(Aq      is interpreted as <sample class=\*(Aqword\*(Aq>this</sample> \`
.Ve
.Sp
Exra modifiers that can be mixed with the above. Usually if you want
bigger font, \s-1CAPITALIZE THE WORDS.\s0
.Sp
.Vb 3
\&    =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>
.Ve
.IP "superscripting" 4
.IX Item "superscripting"
.Vb 4
\&    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.
.Ve
.IP "subscripting" 4
.IX Item "subscripting"
.Vb 5
\&    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.
.Ve
.IP "embedding standard \s-1HTML\s0 tokens" 4
.IX Item "embedding standard HTML tokens"
Stanadard special \s-1HTML\s0 entities can be added inside text in a normal way,
either using sybolic names or the hash code. Here are exmples:
.Sp
.Vb 7
\&    &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;
.Ve
.IP "embedding \s-1PURE HTML\s0 into text" 4
.IX Item "embedding PURE HTML into text"
\&\fBThis feature is highly experimental\fR. It is possible to embed pure
\&\s-1HTML\s0 inside text in occasions, where e.g. some special formatting is
needed. The idea is simple: you write \s-1HTML\s0 as usual but double every '<'
and '>' characters, like:
.Sp
.Vb 1
\&    <<p>>
.Ve
.Sp
The other rule is that all \s-1PURE HTML\s0 must be kept together. There must
be no line breaks between pure \s-1HTML\s0 lines. This is incorrect:
.Sp
.Vb 1
\&    <<table>>
\&
\&        <<tr>>one
\&        <<tr>>two
\&
\&    <</table>>
.Ve
.Sp
The pure \s-1HTML\s0 must be written without extra newlines:
.Sp
.Vb 4
\&    <<table>>
\&        <<tr>>one
\&        <<tr>>two
\&    <</table>>
.Ve
.Sp
This \*(L"doubling\*(R" affects normal text writing rules as well. If you write
documents, where you describe Unix styled HERE-documents, you \s-1MUST NOT\s0 put
the tokens next to each other:
.Sp
.Vb 3
\&        bash$ cat<<EOF              # DON\*(AqT, this will confuse parser.
\&        one
\&        EOF
.Ve
.Sp
You must write the above code example using spaces to prevent \*(L"<<\*(R" from
interpreting as \s-1PURE HTML:\s0
.Sp
.Vb 3
\&        bash$ cat << EOF            # RIGHT, add spaces
\&        one
\&        EOF
.Ve
.IP "drawing a short separator" 4
.IX Item "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.
.SS "Http and email marking control"
.IX Subsection "Http and email marking control"
.IP "\(bu" 4
All http and ftp references as well as <foo@example.com> email
addresses are marked clickable. Email must have surrounding <>
characters to be recognized.
.IP "\(bu" 4
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.
.Sp
.Vb 2
\&    <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
.Ve
.SS "Lists and bullets"
.IX Subsection "Lists and bullets"
.IP "\(bu" 4
The bulletin table is constructed if there is \*(L"o\*(R" or \*(L"*\*(R" 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.
.Sp
.Vb 2
\&    *   This is a bullet
\&    *   This is a bullte
.Ve
.Sp
Another example:
.Sp
.Vb 2
\&    o   This is a bullet
\&    o   This is a bullet
.Ve
.Sp
List example:
.Sp
.Vb 2
\&    .   This is an ordered list
\&    .   This is an ordered list
.Ve
.IP "\(bu" 4
The ordered list is started with \*(L".\*(R", a dot, and written like bullet where
text starts at column 12.
.SS "Line breaks"
.IX Subsection "Line breaks"
.IP "\(bu" 4
All line breaks are visible in your document, do not use more than one line
break to separate paragraphs.
.IP "\(bu" 4
Very important is that there is only \fIone\fR line break after headings.
.SH "EMBEDDED DIRECTIVES INSIDE TEXT"
.IX Header "EMBEDDED DIRECTIVES INSIDE TEXT"
.IP "Command line options" 4
.IX Item "Command line options"
You can cancel obeying all embedded directives by supplying option
\&\fB\-\-not2html\-tags\fR.
.Sp
You can include these lines anywhere in the document and their content
is included in \s-1HTML\s0 output. Each directive line must fit in one line and
it cannot be broken to separate lines.
.Sp
.Vb 6
\&    #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>
.Ve
.Sp
You can pass command line options embedded in the file. Like if you
wanted the \s-1CODE\s0 section (column 12) to be coloured with shade of gray,
you could add:
.Sp
.Vb 1
\&    #T2HTML\-OPTION  \-\-css\-code\-bg
.Ve
.Sp
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.
.Sp
.Vb 9
\&    #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):
.Ve
.Sp
You can also embed your own comments to the text. These are stripped away:
.Sp
.Vb 2
\&    #T2HTML\-COMMENT  You comment here
\&    #T2HTML\-COMMENT  You another comment here
.Ve
.IP "Embedding files" 4
.IX Item "Embedding files"
#INCLUDE\- command
.Sp
This is used to include the content into current current position. The \s-1URL\s0
can be a filename reference, where every \f(CW$VAR\fR is substituted from the
environment variables. The tilde(~) expansion is not supported. The
included filename is operating system supported path location.
.Sp
A prefix \f(CW\*(C`raw:\*(C'\fR disables any normal formatting. The file content is
included as is.
.Sp
The \s-1URL\s0 can also be a \s-1HTTP\s0 reference to a remote location, whose content is
included at the point. In case of remote content or when filename ends to
extension \f(CW\*(C`.html\*(C'\fR or \f(CW\*(C`.html\*(C'\fR, the content is stripped in order to make
the inclusion of the content possible. In picture below, only the lines
within the \s-1BODY,\s0 marked with !!, are included:
.Sp
.Vb 9
\&    <html>
\&      <head>
\&        ...
\&      </head>
\&      <body>
\&        this text                 !!
\&        and more of this          !!
\&      </body>
\&    </html>
.Ve
.Sp
Examples:
.Sp
.Vb 3
\&    #INCLUDE\-$HOME/lib/html/picture1.html
\&    #INCLUDE\-http://www.example.com/code.html
\&    #INCLUDE\-raw:example/code.html
.Ve
.IP "Embedding pictures" 4
.IX Item "Embedding pictures"
#PIC command is used to include pictures into the text
.Sp
.Vb 2
\&    #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"
.Ve
.Sp
Note: The \f(CW\*(C`Caption Text\*(C'\fR will also become the \s-1ALT\s0 text of the image
which is used in case the browser is not capable of showing pictures.
You can suppress the \s-1ALT\s0 text with option \fB\-\-no\-picture\-alt\fR.
.IP "Fragment identifiers for named tags" 4
.IX Item "Fragment identifiers for named tags"
#REF command is used for referring to \s-1HTML\s0 <name> tag inside current
document. The whole command must be placed on one single line and
cannot be broken to multiple lines. An example:
.Sp
.Vb 2
\&    #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.
.Ve
.IP "Referring to external documents." 4
.IX Item "Referring to external documents."
\&\f(CW\*(C`#URL\*(C'\fR 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 \s-1URL.\s0
This directive cannot be broken to separate lines,
.Sp
.Vb 4
\&     #URL<FULL\-URL><embedded inline text>
\&         |          |
\&         |          Displayed, clickable, text
\&         Must be kept together
.Ve
.Sp
An example:
.Sp
.Vb 1
\&     See search engine #URL<http://www.google.com><Google>
.Ve
.SH "TABLE OF CONTENT HEADING"
.IX Header "TABLE OF CONTENT HEADING"
If there is heading 1, which is named exactly \*(L"Table of Contents\*(R", then all
text up to next heading are discarded from the generated \s-1HTML\s0 file. This is
done because program generates its own \s-1TOC.\s0 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 \fItinytf.el\fR can
be used.
.SH "TROUBLESHOOTING"
.IX Header "TROUBLESHOOTING"
.SS "Generated \s-1HTML\s0 document did not look what I intended"
.IX Subsection "Generated HTML document did not look what I intended"
Did you use editor that inseted TABs which inserts single ascii code
(\et) and 8 spaces? check our editor's settings and prefer writing
in-all-space format.
.PP
The most common mistake is that there are extra newlines in the
document. Keeep \fIone\fR empty line between headings and text, keep \fIone\fR
empty line between paragraphs, keep \fIone\fR empty line between body
text and bullet. Make it your mantra: \fIone\fR \fIone\fR \fIone\fR ...
.PP
Next, you may have put text at wrong column position. Remember that the
regular text is at column 8.
.PP
If generated \s-1HTML\s0 suddendly starts using only one font, eg <pre>, then
you have forgot to close the block. Make it read even, like this:
.PP
.Vb 4
\&    Code block
\&        Code block
\&        Code block
\&    ;;  Add empty comment here to "close" the code example at column 12
.Ve
.PP
Headings start with a big letter or number, likein \*(L"Heading\*(R", not
\&\*(L"heading\*(R". Double check the spelling.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
To print the test page and demonstrate possibilities:
.PP
.Vb 1
\&    t2html \-\-test\-page
.Ve
.PP
To make simple \s-1HTML\s0 page without any meta information:
.PP
.Vb 2
\&    t2html \-\-title "Html Page Title" \-\-author "Mr. Foo" \e
\&           \-\-simple \-\-out \-\-print file.txt
.Ve
.PP
If you have periodic post in email format, use \fB\-\-delete\-email\-headers\fR to
ignore the header text:
.PP
.Vb 1
\&    t2html \-\-out \-\-print \-\-delete\-email\-headers page.txt
.Ve
.PP
To make page fast
.PP
.Vb 1
\&    t2html \-\-out \-\-print page.txt
.Ve
.PP
To convert page from a text document, including meta tags, buttons, colors
and frames. Pay attention to switch \fI\-\-html\-body\fR which defines document
language.
.PP
.Vb 10
\&    t2html                                              \e
\&    \-\-print                                             \e
\&    \-\-out                                               \e
\&    \-\-author    "Mr. foo"                               \e
\&    \-\-email     "foo@example.com"                       \e
\&    \-\-title     "This is manual page of page BAR"       \e
\&    \-\-html\-body LANG=en                                 \e
\&    \-\-button\-prev  previous.html                        \e
\&    \-\-button\-top   index.html                           \e
\&    \-\-buttion\-next next.html                            \e
\&    \-\-document  http://example.com/dir/this\-page.html   \e
\&    \-\-url       manual.html                             \e
\&    \-\-css\-code\-bg                                       \e
\&    \-\-css\-code\-note \*(Aq(?:Note|Notice|Warning):\*(Aq          \e
\&    \-\-html\-frame                                        \e
\&    \-\-disclaimer\-file   $HOME/txt/my\-html\-footer.txt    \e
\&    \-\-meta\-keywords    "language\-en,manual,program"     \e
\&    \-\-meta\-description "Bar program to do this that and more of those" \e
\&    manual.txt
.Ve
.PP
To check links and print status of all links in par with the http error
message (most verbose):
.PP
.Vb 1
\&    t2html \-\-link\-check file.txt | tee link\-error.log
.Ve
.PP
To print only problematic links:
.PP
.Vb 1
\&    t2html \-\-link\-check \-\-quiet file.txt | tee link\-error.log
.Ve
.PP
To print terse output in egep \-n like manner: line number, link and
error code:
.PP
.Vb 1
\&    t2html \-\-link\-check\-single \-\-quiet file.txt | tee link\-error.log
.Ve
.PP
To check links from multiple pages and cache good links to separate file,
use \fB\-\-link\-cache\fR 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.
.PP
.Vb 3
\&    t2html \-\-link\-check\-single \e
\&           \-\-link\-cache $HOME/tmp/link.cache \e
\&           \-\-quiet file.txt
.Ve
.PP
To split large document into pieces, and convert each piece to \s-1HTML:\s0
.PP
.Vb 1
\&    t2html \-\-split1 \-\-split\-name file.txt | t2html \-\-simple \-\-out
.Ve
.SH "ENVIRONMENT"
.IX Header "ENVIRONMENT"
.IP "\fB\s-1EMAIL\s0\fR" 4
.IX Item "EMAIL"
If environment variable \fI\s-1EMAIL\s0\fR is defined, it is used in footer for
contact address. Option \fB\-\-email\fR overrides environment setting.
.IP "\fB\s-1LANG\s0\fR" 4
.IX Item "LANG"
The default language setting for switch \f(CW\*(C`\-\-language\*(C'\fR Make sure the
first two characters contains the language definition, like in:
LANG=en.iso88591
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIasciidoc\fR\|(1)
\&\fIhtml2ps\fR\|(1)
\&\fIhtmlpp\fR\|(1)
\&\fImarkdown\fR\|(1)
.SS "Related programs"
.IX Subsection "Related programs"
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
.PP
\&\s-1HTML\s0 validator is at http://validator.w3.org/
.PP
iMATIX created htmlpp which is available from http://www.imatix.com and seen
2014\-03\-05 at http://legacy.imatix.com/html/htmlpp
.PP
Emacs minor mode to help writing documents based on \s-1TF\s0 layout is
available. See package tinytf.el in project
http://freecode.com/projects/emacs\-tiny\-tools
.SS "Standards"
.IX Subsection "Standards"
\&\s-1RFC \s0\fB1766\fR contains list of language codes at
http://www.rfc.net/
.PP
Latest \s-1HTML/XHTML\s0 and \s-1CSS\s0 specifications are at http://www.w3c.org/
.SS "\s-1ISO\s0 standards"
.IX Subsection "ISO standards"
\&\fB639\fR Code for the representation of the names of languages
http://www.oasis\-open.org/cover/iso639a.html
.PP
\&\fB3166\fR Standard Country Codes
http://www.niso.org/3166.html and
http://www.netstrider.com/tutorials/HTMLRef/standards/
.SH "BUGS"
.IX Header "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.
.PP
As the options \fB\-\-xhtml\fR was much later added, it may not produce
completely syntactically valid markup.
.SH "SCRIPT CATEGORIES"
.IX Header "SCRIPT CATEGORIES"
CPAN/Administrative
html
.SH "PREREQUISITES"
.IX Header "PREREQUISITES"
No additional Perl \s-1CPAN\s0 modules needed for text to \s-1HTML\s0 conversion.
.SH "COREQUISITES"
.IX Header "COREQUISITES"
If link check feature is used to to validate \s-1URL\s0 links, then following
modules are needed from Perl \s-1CPAN \s0\f(CW\*(C`use LWP::UserAgent\*(C'\fR \f(CW\*(C`HTML::FormatText\*(C'\fR
and \f(CW\*(C`HTML::Parse\*(C'\fR
.PP
If you module \f(CW\*(C`HTML::LinkExtractor\*(C'\fR is available, it is used
instead of included link extracting algorithm.
.SH "AVAILABILITY"
.IX Header "AVAILABILITY"
Homepage is at http://freecode.com/projects/perl\-text2html
.SH "AUTHOR"
.IX Header "AUTHOR"
Copyright (C) 1996\-2016 <jari.aalto@cante.net>
.PP
This program is free software; you can redistribute and/or modify
program under the terms of \s-1GNU\s0 General Public license either version 2
of the License, or (at your option) any later version.
.PP
This documentation may be distributed subject to the terms and
conditions set forth in \s-1GNU\s0 General Public License v2 or later; or, at
your option, distributed under the terms of \s-1GNU\s0 Free Documentation
License version 1.2 or later (\s-1GNU FDL\s0).