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. Basicly 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://freshmeat.net/projects/emacs-tiny-tools
OPTIONS¶
- --as-is
- Any extra HTML formatting or text manipulation is suppressed. Text is
preserved as it appears in file. Use this option if you plan to deliver 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 occurrance
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 (contructed 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 (defualt 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 defintion 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 langauge 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 langauge 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 errorneous links.
- V, --version
- Print program version information.
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:
--//-- decription 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 ot 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 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 intepreted as code section surrpoundedn
by <pre> HTML codes.
. This is ordered list.
. This is ordered list.
. This is ordered list.
.This line starts wirg dot and is displayed in line by itself.
.This line starts wirg 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 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.
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 or number
- •
- 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 0 is undefined if it does not start with big letter or
number to indicate Heading level 1.
- •
- Text between colums 1-3 is marked with <em>
- •
- Column 4 is reserved for heading level 2
- •
- Text between colums 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 colums 9,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 colum 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> 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
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 intepreted as <strong class='word'>this</strong>
*this* is intepreted as <em class='word'>this</em>
`this' is intepreted 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 intepreted as <span class="word-small">this</span>
+this+ is intepreted as <span class="word-big">this</span>
[this] is intepreted as <span class="word-ref">this</span>
- superscripting
-
word[this] is intepreted 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 intepreted 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:
× < > ≤ ≥ ≠ √ −
α β γ ÷
« » ‹ › - – —
≈ ≡ ∑ ƒ ∞
° ±
™ © ®
€ £ ¥
- 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 isea 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 contructed 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.
- •
- 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 subtituted 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 picturere. 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 refering 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-HTTP-LINK> <embedded inline text>
| |
| whitespace allowed here
Must be kept together
Like if written:
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¶
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 show all the 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 --html-frame --out --print page.txt
To convert page from a text document, including meta tags, buttons, colors and
frames. Pay attention to switch
--html-body which defines document
language.
t2html \
--print \
--out \
--author "Mr. foo" \
--email "foo@example.com" \
--title "This is manual page of page BAR" \
--html-body LANG=en \
--button-prev previous.html \
--button-top index.html \
--buttion-next next.html \
--document http://example.com/dir/this-page.html \
--url manual.html \
--css-code-bg \
--css-code-note '(?:Note|Notice|Warning):' \
--html-frame \
--disclaimer-file $HOME/txt/my-html-footer.txt \
--meta-keywords "language-en,manual,program" \
--meta-description "Bar program to do this that and more of those" \
manual.txt
To check links and print status of all links in par with the http error message
(most verbose):
t2html --link-check file.txt | tee link-error.log
To print only problematic links:
t2html --link-check --quiet file.txt | tee link-error.log
To print terse output in egep -n like manner: line number, link and error code:
t2html --link-check-single --quiet file.txt | tee link-error.log
To check links from multiple pages and cache good links to separate file, use
--link-cache option. The next link check will run much faster because
cached valid links will not be fetched again. At regular intervals delete the
link cache file to force complete check.
t2html --link-check-single \
--link-cache $HOME/tmp/link.cache \
--quiet file.txt
To split large document into pieces, and convert each piece to HTML:
t2html --split1 --split-name file.txt | t2html --simple --out
ENVIRONMENT¶
- EMAIL
- If environment variable EMAIL is defined, it is used in footer for
contact address. Option --email overrides environment setting.
- LANG
- The default language setting for switch "--language" Make sure
the first two characters contains the language definition, like in:
LANG=en.iso88591
SEE ALSO¶
asciidoc(1) html2ps(1) htmlpp(1)
markdown(1)
Jan Kaerrman <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 at
http://www.imatix.com/
Emacs minor mode to write documents based on TF layout is available. See package
tinytf.el in project
http://freshmeat.net/projects/emacs-tiny-tools
Standards¶
RFC
1766 contains list of langauge 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 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 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://freshmeat.net/projects/perl-text2html
AUTHOR¶
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).