"
--html-column-beg="quote "
--html-column-end="quote "
B 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 I 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 I attribute and use
B switch to import definitions. Usually /usr/lib/X11/rgb.txt
lists possible color values and the HTML standard at http://www.w3.org/
defines following 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
=item B
See B
=item B
Define FONT SIZE. It is usefull to set big font size if you are
planning to print slides.
=item B
If given, then two separate frame files are generated. The left frame will
contain TOC and right frame contains rest of the text. The I
can be any valid parameters for HTML tag FRAMESET. The default is
Cols="25%,75%".
Using this opption generates 3 files (implies B option)
file.html --> file.html The Frame file, point browser here
file-toc.html Left frame (navigation)
file-body.html Right frame (content)
=item B
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.
=item B
Include java code that must be complete from FILE. The
code is put inside of each html. The default java provided by this
filter is used if you do not supply B. It contains some
Style sheet (CSS) definitions.
The B 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 I<14.3.2 Specifying external style sheets> in HTML 4.0 standard.
=item B
Meta keywords. Used by search engines. Separate kwywords like "AA, BB, CC"
with commas. See http://www.sandia.gov/sci_compute/html_ref.html and
http://www.htmlhelp.com/reference/wilbur/
--meta-keywords "AA,BB,CC"
=item B
Meta Description. Include description string, max 1000 characters. This is
used by search engines.
=item B
(NOT RECOMMENDED TO BE USED)
First 1-4 words from the heading are used for the html I 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 I
references.
Please use this option only in emergencies, because referring to jump block
I via
httpI://foo.com/doc.html#header_name
is more convenient than using obscure reference
httpI://foo.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.
Make sure that the headings do not have same subjects and you do not need
this option.
=back
=head2 Document maintenance or batch job commands
=over 4
=item B
Check all http and ftp links.
I
Option B 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 I.
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 I or that run programs
(links with ? character) are ignored because the GET request used in
checking returns content of the link. You know what that would mean
if I were checked. When you put binary links to your documents,
add them with space:
http://foo.com/dir/dir/ filename.tar.gz
Then the program I check the http addresses. Users may not be able to
get the file at one click, but if you care about maintaining you huge
documents, this is the only way to include the link to the checking phase.
=item B
Print condensed output in I like manner I
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 (Lioke
Emacs M-x compile) that can parse standard grep syntax to jump to locations
in your document to correct the links later.
=item B
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
=item B
Like B, 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
B to ignore this option. The following is a no-op, it will not generate
output to directory "none":
--Out-dir none
=item B
Print filename to stdout after html processing. Normally program prints
no output.
% t2html.pl --Out --print page.txt
--> page.html
=item B
Print filename in URL format. This is usefull if you want to check the
layout immediately with your browser.
% t2html.pl --Out --print-url page.txt | xargs lynx
--> file:/users/foo/txt/page.html
=item B
Split document into smaller pieces when REGEXP matches. I, 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.
=item B
This is shorthand of B command. Define regexp to split on toplevel
heading.
=item B
This is shorthand of B command. Define regexp to split on second
level heading.
=item B
Additional directive for split commands. If you split e.g. by headings using
B, 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
=back
=head2 Miscellaneous options
=over 4
=item B
Turn on debug with positive LEVEL number. Zero means no debug.
=item B
Print help screen.
=item B
Print help in HTML format.
=item B
Print the test page: html and exampl etext file that demonstrates
the capabilities.
=item B
Print to stderr time spent used for handling the file.
=item B
Print verbose messages.
=item B
Print no footer at all. This option has different meaning if
I option is turned on: print only errorneous links.
=item B
Print program version information.
=back
=head1 DESCRIPTION
This is simple text to html converter. Unlike other tools, this
tries to minimize the use of text tags to format the document,
The basic idea is to rely on indentation level, and the layout used is
called 'Technical format' (TF)
--//-- decription start
0123456789 123456789 123456789 123456789 123456789 column numbers
Heading 1 starts from left with big letter
The column positions are currently undeined and may not
format correcly. Do ot place text at columns 1,2,3
This is heading2 at column 4 started with big letter
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
Normal but colored text is between columns 5, 6
Emphatised text at column 7, like heading level 3
"Special text at column 7 starts with double quote"
Another standard text block at 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
strong text at columns 9 and 11
Column 10 is normally reserved for quotations
Column 10 is normally reserved for quotations
Column 10 is normally reserved for quotations
Column 10 is normally reserved for quotations
Column 12 and further is reserved for code examples
Column 12 and further is reserved for code examples
All text here are surrounded by

HTML codes.
* Bullet 2, text starts at column 12
* Bullet 3. Bullets are adviced to keep together
* Bullet 4. Bullets are adviced to keep together
. This is ordered list nbr 1, text starts at column 12
. This is ordered list nbr 2
. This is ordered list nbr 3
.This line has BR, notice the DOT-code at beginning of
line. It is efective only at columns 1..11, because column 12
is reserved for code examples.
.This line has BR code and is displayed in line by itself.
.This line has BR code and is displayed in line by itself.
!! This adds an HTML code, text in line is marked with
!!
"This is emphasised text starting at column 7"
.And this text is put after the previous line with BR code
"This starts as separate line just below previous one"
.And continues again as usual with BR code
See the document #URL-BASE/document.txt, where #URL-BASE
tag is substituted with contents of --base switch.
Make this email address clickable
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 are also ignored automatically.
Also do not make < this@example.com> because there is extra
white spaces. This may be more convenient way to disable
email addresses temporarily.
Heading1 again at colum 0
Subheading at colum 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
--//-- decription end
That is it, there is the whole layout described. More formally the rules
of text formatting are secribed below.
=head2 USED HEADINGS
=over 4
=item *
There are only I heading levels in this style. Heading columns are 0
and 4 and the heading must start with big letter or number
=item *
at column 4, if the text starts with small letter, that line is interpreted
as
=item *
A HTML mark is added just before printing heading at level 1.
=item *
The headings are gathered, the TOC is built and inserted to the beginning
of html page. The HTML 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 B
switch
=back
=head1 TEXT PLACEMENT RULES
=head2 General
The basic rules for positioning text in certain columns:
=over 4
=item *
Text at column 0 is undefined if it does not start with big letter or number
to indicate Heading level 1.
=item *
Text between colums 1-3 is marked with
=item *
Column 4 is reserved for heading level 2
=item *
Text between colums 5-7 is marked with
=item *
Text at column 7 is if the first character is double quote.
=item *
Column 10 is reserved for text. If you want to quote someone
or to add reference text, place the text in this column.
=item *
Text at colums 9,11 are marked with
=back
Column 8 for text and special codes
=over 4
=item *
Column 8 is reserved for normal text
=item *
At the start of text, at colum 8, there can be DOT-code or COMMA-code.
=back
Column 12 is special
=over 4
=item *
Column 12 is treated specially: block is started with

and lines are
marked as . When the last text at I 12 is found, the
block is closed with

Note follwing 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
=back
=head2 Additional tokens for use at column 8
=over 4
=item *
If there is C(dot) at the beginning of a line and immediately
non-whitespace, then code is added to the end of line.
.This line has BR code at the end.
While these two line are joined together
by your browser, depending on the frame width.
=item *
If there is C(comma) then the

code is not inserted if the previous line is empty. If you use both C(dot) and C(comma), they must be in
order dot-comma. The C(comma) works differently if it is used in bullet
A

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 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 COMMa-code below.
* This is new bullet
// and this is code sample after bullet
if ( $flag ) { ..do something.. }
=item *
Special text markings:
_this_ is intepreted as this
*this* is intepreted as this
`this' is intepreted as this `
Exra modifiers that can be mixed with the above. Usually if you want
bigger font, CAPITALIZE THE WORDS.
=this= is intepreted as this
+this+ is intepreted as this
[this] is intepreted as this
=back
=head2 Directives
=over 4
=item *
#REF command is used for refering to HTML tag inside current document.
The whole command must be placed on one single line, you cannot
break the line. Example:
#REF #how_to_profile;(Note: profiling);
(1) (2)
1. The NAME reference in current document, a single word.
This can also be full http url link.
You can get NAME list by enabling
--Toc-url-print option.
2. The clickable text is delimited by ; characters.
=item *
#URL-BASE is substituted with the contents of command line option B. The #URL-BASE token allows you to refer to documents local to the
current site.
--base http://www.example.com/dir1/dir2/text.html
Then in text the reference is expanded like this
#URL-BASE/next.html
-->
http://www.example.com/dir1/dir2/next.html
=item *
A !! (two exclamation marks) at text column (position 8) causes adding
immediate code. Any text after !! in the same line is written with
and inserted just after code, therefore the word
formatting commands have no effect in this line.
=back
=head2 Http and email marking control
=over 4
=item *
All http and ftp references as well as email
addresses are marked clickable. Email must have surrounding <>
characters to be recognized.
=item *
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.
clickable
http://this.com clickable
me@here.com not clickable
< me@here.com> not clickable; contains space
<5dko56$1@news02.deltanet.com> Message-Id, not clickable
http://foo.com "foo" found, not clickable
-http://this.com hyphen, not clickable
http://$EXAMPLE variable. not clickable
=back
=head2 Lists and bullets
=over 4
=item *
The bulletin table is contructed if there is "o" or "*" at column 8 and 3
spaces after it, so that text starts at column 12. Bulleted lines are
adviced to be kept together; no spaces between bullet blocks.
=item *
The ordered list is started with ".", a dot, and written like bullet where
text starts at column 12.
=back
=head2 Line breaks
=over 4
=item *
All line breaks are visible in your document, do not use more than one line
break to separate paragraphs.
=item *
Very important is that there is only I line break after headings.
=back
=head1 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 I can
be used.
=head1 TROUBLESHOOTING
=head2 Generated html document did not look what I intended
The most common mistake is that you have extra newlines all over your
document. Keeep I empty line between headings and text, keep I
empty line between paragraphs, keep I empty line between body
text and bullet. Make it your mantra: I I I ...
Next, you may have put text at wrong column position. Remember that text
column position is 8.
If generated html suddendly starts using only one font, eg