forked from lijiext/lammps
238 lines
10 KiB
HTML
238 lines
10 KiB
HTML
<HTML>
|
|
<H3>txt2html - a text to HTML conversion tool
|
|
</H3>
|
|
<P><B>txt2html</B> is a simple tool for converting text files into HTML files.
|
|
Text files can contain simple formatting and mark-up commands that
|
|
<B>txt2html</B> converts into HTML.
|
|
</P>
|
|
<P><B>txt2html</B> was written by <A HREF = "http://www.cs.sandia.gov/~sjplimp">Steve Plimpton</A>. I use it for
|
|
<A HREF = "http://www.cs.sandia.gov/~sjplimp/lammps.html">documentation</A> and <A HREF = "http://www.cs.sandia.gov/~sjplimp">WWW pages</A>. Anna Reese added the table
|
|
formatting options.
|
|
</P>
|
|
<P>See the <A HREF = "example.txt">example.txt</A> and <A HREF = "example.html">example.html</A>
|
|
files in the <B>txt2html</B> directory for examples of what all the
|
|
formatting commands and mark-up syntax end up looking like in HTML.
|
|
</P>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<HR>
|
|
|
|
<P><B>Syntax:</B>
|
|
</P>
|
|
<DL><DT>txt2html file
|
|
<DD> read from text file, write HTML to standard output
|
|
<DT>txt2html file1 file2 file3 ...
|
|
<DD> read each argument as text file, write one HTML file per argument
|
|
</DL>
|
|
<P>Input files are first opened with the specified name. If that fails,
|
|
a ".txt" suffix is added. Output files are created with an ".html"
|
|
suffix, which is either added or replaces the ".txt" suffix.
|
|
</P>
|
|
<HR>
|
|
|
|
<P><B>Compiling:</B>
|
|
</P>
|
|
<P>The source for <B>txt2html</B> is a single C++ file. Compile it by typing:
|
|
</P>
|
|
<PRE>g++ -o txt2html txt2html.cpp
|
|
</PRE>
|
|
<HR>
|
|
|
|
<P><B>How the tool works:</B>
|
|
</P>
|
|
<P><B>txt2html</B> reads a text file, one <I>paragraph</I> at a time. A paragraph
|
|
ends with:
|
|
</P>
|
|
<UL><LI> a blank line
|
|
<LI> a line whose final word starts with ":" (a format string)
|
|
<LI> the end of the file
|
|
</UL>
|
|
<P>Any line in the paragraph which ends with "\" is concatenated to the
|
|
following line by removing the "\" character and following newline.
|
|
This can be useful for some of the formatting commands described below
|
|
that operate on individual lines in the paragraph.
|
|
</P>
|
|
<P>If a paragraph starts with a "<" character and ends with a ">"
|
|
character, it is treated as raw HTML and is written directly into the
|
|
output file.
|
|
</P>
|
|
<P>If a paragraph does not end with a format string, then it is
|
|
surrounded with HTML paragraph markers (<P> and </P>),
|
|
<A HREF = "#markup">mark-up</A> is performed, and the paragraph is written to the
|
|
output file.
|
|
</P>
|
|
<P>If the paragraph ends with a format string, then <A HREF = "#format">formatting</A>
|
|
is performed, <A HREF = "#markup">mark-up</A> is performed, and the paragraph is
|
|
written to the output file.
|
|
</P>
|
|
<HR>
|
|
|
|
<A NAME = "format"></A><B>Formatting:</B>
|
|
|
|
<P>A format string is the last word of a paragraph if it starts with a
|
|
":" character. A format string contains one or more comma-separated
|
|
commands, like ":ulb,l" or ":c,h3". Note that a format string cannot
|
|
contain spaces, else it would not be the last word. An individual
|
|
command can have 0 or more arguments:
|
|
</P>
|
|
<UL><LI> <I>b</I> or <I>line()</I> = 0 arguments
|
|
<LI> <I>image(file)</I> = 1 argument
|
|
<LI> <I>link(alias,value)</I> = 2 or more comma-separated arguments
|
|
</UL>
|
|
<P>Format commands add HTML markers at the beginning or end of the
|
|
paragraph and individual lines. Commands are processed in the order
|
|
they appear in the format string. Thus if two commands add HTML
|
|
markers to the beginning of the paragraph, the 2nd command's marker
|
|
will appear 2nd. The reverse is true at the end of the paragraph; the
|
|
2nd command's marker will appear 1st. Some comands, like <I>line</I> or
|
|
<I>image</I> make most sense if used as stand-alone commands without an
|
|
accompanying paragraph.
|
|
</P>
|
|
<P>Commands that format the entire paragraph:
|
|
</P>
|
|
<UL><LI> p --> surround the paragraph with <P> </P>
|
|
<LI> b --> put <BR> at the end of the paragraph
|
|
<LI> pre --> surround the paragraph with <PRE> </PRE>
|
|
<LI> c --> surround the paragraph with <CENTER> </CENTER>
|
|
<LI> h1,h2,h3,h4,h5,h6 --> surround the paragraph with <H1> </H1>, etc
|
|
</UL>
|
|
<P>Commands that format the lines of the paragraph as a list:
|
|
</P>
|
|
<UL><LI> ul --> surround the paragraph with <UL> </UL>, put <LI> at start of every line
|
|
<LI> ol --> surround the paragraph with <OL> </OL>, put <LI> at start of every line
|
|
<LI> dl --> surround the paragraph with <DL> </DL>, alternate <DT> and <DD> at start of every line
|
|
</UL>
|
|
<P>Commands that treat the paragraph as one entry in a list:
|
|
</P>
|
|
<UL><LI> l --> put <LI> at the beginning of the paragraph
|
|
<LI> dt --> put <DT> at the beginning of the paragraph
|
|
<LI> dd --> put <DD> at the beginning of the paragraph
|
|
<LI> ulb --> put <UL> at the beginning of the paragraph
|
|
<LI> ule --> put </UL> at the end of the paragraph
|
|
<LI> olb --> put <OL> at the beginning of the paragraph
|
|
<LI> ole --> put </OL> at the end of the paragraph
|
|
<LI> dlb --> put <DL> at the beginning of the paragraph
|
|
<LI> dle --> put </DL> at the end of the paragraph
|
|
</UL>
|
|
<P>Commands applied to each line of the paragraph:
|
|
</P>
|
|
<UL><LI> all(p) --> surround each line with <P> </P>
|
|
<LI> all(c) --> surround each line with <CENTER> </CENTER>
|
|
<LI> all(b) --> append a <BR> to each line
|
|
<LI> all(l) --> prepend a <LI> to each line
|
|
</UL>
|
|
<P>Special commands (all HTML is inserted at beginning of paragraph):
|
|
</P>
|
|
<UL><LI> line --> insert a horizontal line = <HR>
|
|
<LI> image(file) --> insert an image = <IMG SRC = "file">
|
|
<LI> image(file,link) --> insert an image that when clicked on goes to link
|
|
<LI> link(name) --> insert a named link that can be referred to elsewhere (see <A HREF = "#markup">mark-up</A>) = <A NAME = "name"></A>
|
|
<LI> link(alias,value) --> define a link alias that can be used elsewhere in this file (see <A HREF = "#markup">mark-up</A>)
|
|
</UL>
|
|
<P>Table command:
|
|
</P>
|
|
<UL><LI> tb(c=3,b=5,w=100%,a=c) --> format the paragraph as a table
|
|
</UL>
|
|
<P>Arguments within tb() can appear in any order and are all optional,
|
|
since they each have default values.
|
|
</P>
|
|
<UL><LI> c=N --> Make an N-column table. Treat the paragraph as one
|
|
long list of entries (separated by the separator character) and put
|
|
them into N columns one after the other. If N = 0, treat each line
|
|
of the paragraph as one row of the table with as many columns as
|
|
there are maximum entries in any line. Default is c=0.
|
|
|
|
<LI> s=: --> Use the character string following the equal sign as
|
|
the separator between entries. Default separator is a comma "," which
|
|
you cannot specify directly since the comma delimits the tb() arguments
|
|
|
|
<LI> b=N --> Create a border N pixels wide. If N is 0, there is no
|
|
border between or outside the cells. If N is 1, there is a minimal
|
|
border between and outside all cells. For N > 1, the border between
|
|
cells does not change but the outside border gets wider. Default is
|
|
b=1.
|
|
|
|
<LI> w=N or w=N% --> The first form makes each cell of the table at
|
|
least N pixels wide. The second form makes the entire table take up
|
|
N% of the width of the browser window. Default is w=0 which means
|
|
each cell will be just as wide as the text it contains.
|
|
|
|
<LI> a=X --> Align the entire table at the left, center, or right of the
|
|
browser window, for X = "l", "c", or "r". Default is a=c.
|
|
|
|
<LI> ea=X --> Align the text in each entry at the left, center, or
|
|
right of its cell, for X = "l", "c", or "r". Default is browser's
|
|
default (typically left).
|
|
|
|
<LI> eva=X --> Vertically align the text in each entry at the
|
|
top, middle, baseline, or bottom of its cell, for X = "t", "m", "ba",
|
|
or "bo". Default is browser's default (typically middle).
|
|
|
|
<LI> cwM=N or cwM=N% --> The first form makes column M be at least
|
|
N pixels wide. The second form makes column M take up N% of the
|
|
width of the browser window. This setting overrides the "w"
|
|
argument for column M. Only one column per table can be tweaked
|
|
with this argument. Default is no settings for any column.
|
|
|
|
<LI> caM=X --> Align the text in each entry of column M at the left,
|
|
center, or right of its cell, for X = "l", "c", or "r". This
|
|
setting overrides the "ea" argument for column M. Only one column
|
|
per table can be tweaked with this argument. Default is no settings
|
|
for any column.
|
|
|
|
<LI> cvaM=X --> Vertically align the text in each entry of column m
|
|
at the top, middle, baseline, or bottom of its cell, for X = "t",
|
|
"m", "ba", or "bo". This setting overrides the "eva" argument for
|
|
column M. Only one column per table can be tweaked with this
|
|
argument. Default is no settings for any column.
|
|
</UL>
|
|
<HR>
|
|
|
|
<A NAME = "markup"></A><B>Mark-up:</B>
|
|
|
|
<P>The text of the paragraph is scanned for special mark-up characters
|
|
which are converted into HTML.
|
|
</P>
|
|
<P>Bold and italic characters:
|
|
</P>
|
|
<UL> <LI> "[" (left brace) --> turn-on bold by inserting a <B>
|
|
<LI> "]" (right brace) --> turn-off bold by inserting a </B>
|
|
<LI> "{" (left bracket) --> turn-on italics by inserting a <I>
|
|
<LI> "}" (right bracket) --> turn-off italics by
|
|
inserting a </I> </UL>
|
|
|
|
<P>If a backspace '\' preceeds any of the bold/italic mark-up characters,
|
|
then mark-up is not performed; the mark-up character is simply left in
|
|
the text.
|
|
</P>
|
|
<P>Links are inserted by enclosing a section of text in double quotes,
|
|
and appending an underscore to the ending quote, followed by the link.
|
|
The link ends when whitespace is found, except that trailing
|
|
punctuation characters (comma, period, semi-colon, colon, question
|
|
mark, exclamation point, parenthesis) are not considered part of the
|
|
link.
|
|
</P>
|
|
<P> A link of the form "text"_link becomes <A HREF =
|
|
"link">text</A> in the HTML output. The only exception is if
|
|
"link" is defined elsewhere in the file as an alias (see the link
|
|
command above). In that case, the value is used instead of the alias
|
|
name. </P>
|
|
|
|
<P>With these rules, links can take several forms.
|
|
</P>
|
|
<UL> <LI> "This links"_#abc to another part of this file which is
|
|
labeled with a :link(abc) command. <BR>
|
|
<LI> "This links"_other.html to another file named other.html. <BR>
|
|
<LI> "This links"_other.html#abc to another file which has an "abc"
|
|
location defined internally. <BR>
|
|
<LI> "This links"_http://www.google.com to a WWW site. <BR>
|
|
<LI> "This"_M12 could be used in place of any of the above forms. It
|
|
requires an alias like :link(M12,http://www.google.com) to be defined
|
|
elsewhere in the file. </UL>
|
|
|
|
</HTML>
|