doc/utils/txt2html/README.html

   1 <HTML>
   2 <H3>txt2html - a text to HTML conversion tool
   3 </H3>
   4 <P><B>txt2html</B> is a simple tool for converting text files into HTML files.
   5 Text files can contain simple formatting and mark-up commands that
   6 <B>txt2html</B> converts into HTML.
   7 </P>
   8 <P><B>txt2html</B> was written by <A HREF = "http://www.cs.sandia.gov/~sjplimp">Steve Plimpton</A>.  I use it for
   9 <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
  10 formatting options.
  11 </P>
  12 <P>See the <A HREF = "example.txt">example.txt</A> and <A HREF = "example.html">example.html</A>
  13 files in the <B>txt2html</B> directory for examples of what all the
  14 formatting commands and mark-up syntax end up looking like in HTML.
  15 </P>
  16
  17
  18
  19
  20
  21
  22 <HR>
  23
  24 <P><B>Syntax:</B>
  25 </P>
  26 <DL><DT>txt2html file
  27 <DD>  read from text file, write HTML to standard output
  28 <DT>txt2html file1 file2 file3 ...
  29 <DD>  read each argument as text file, write one HTML file per argument
  30 </DL>
  31 <P>Input files are first opened with the specified name.  If that fails,
  32 a ".txt" suffix is added.  Output files are created with an ".html"
  33 suffix, which is either added or replaces the ".txt" suffix.
  34 </P>
  35 <HR>
  36
  37 <P><B>Compiling:</B>
  38 </P>
  39 <P>The source for <B>txt2html</B> is a single C++ file.  Compile it by typing:
  40 </P>
  41 <PRE>g++ -o txt2html txt2html.cpp
  42 </PRE>
  43 <HR>
  44
  45 <P><B>How the tool works:</B>
  46 </P>
  47 <P><B>txt2html</B> reads a text file, one <I>paragraph</I> at a time.  A paragraph
  48 ends with:
  49 </P>
  50 <UL><LI>  a blank line
  51 <LI>  a line whose final word starts with ":" (a format string)
  52 <LI>  the end of the file
  53 </UL>
  54 <P>Any line in the paragraph which ends with "\" is concatenated to the
  55 following line by removing the "\" character and following newline.
  56 This can be useful for some of the formatting commands described below
  57 that operate on individual lines in the paragraph.
  58 </P>
  59 <P>If a paragraph starts with a "&lt;" character and ends with a "&gt;"
  60 character, it is treated as raw HTML and is written directly into the
  61 output file.
  62 </P>
  63 <P>If a paragraph does not end with a format string, then it is
  64 surrounded with HTML paragraph markers (&lt;P&gt; and &lt;/P&gt;),
  65 <A HREF = "#markup">mark-up</A> is performed, and the paragraph is written to the
  66 output file.
  67 </P>
  68 <P>If the paragraph ends with a format string, then <A HREF = "#format">formatting</A>
  69 is performed, <A HREF = "#markup">mark-up</A> is performed, and the paragraph is
  70 written to the output file.
  71 </P>
  72 <HR>
  73
  74 <A NAME = "format"></A><B>Formatting:</B>
  75
  76 <P>A format string is the last word of a paragraph if it starts with a
  77 ":" character.  A format string contains one or more comma-separated
  78 commands, like ":ulb,l" or ":c,h3".  Note that a format string cannot
  79 contain spaces, else it would not be the last word.  An individual
  80 command can have 0 or more arguments:
  81 </P>
  82 <UL><LI>  <I>b</I> or <I>line()</I> = 0 arguments
  83 <LI>  <I>image(file)</I> = 1 argument
  84 <LI>  <I>link(alias,value)</I> = 2 or more comma-separated arguments
  85 </UL>
  86 <P>Format commands add HTML markers at the beginning or end of the
  87 paragraph and individual lines.  Commands are processed in the order
  88 they appear in the format string.  Thus if two commands add HTML
  89 markers to the beginning of the paragraph, the 2nd command's marker
  90 will appear 2nd.  The reverse is true at the end of the paragraph; the
  91 2nd command's marker will appear 1st.  Some comands, like <I>line</I> or
  92 <I>image</I> make most sense if used as stand-alone commands without an
  93 accompanying paragraph.
  94 </P>
  95 <P>Commands that format the entire paragraph:
  96 </P>
  97 <UL><LI>  p --&gt; surround the paragraph with &lt;P&gt; &lt;/P&gt;
  98 <LI>  b --&gt; put &lt;BR&gt; at the end of the paragraph
  99 <LI>  pre --&gt; surround the paragraph with &lt;PRE&gt; &lt;/PRE&gt;
 100 <LI>  c --&gt; surround the paragraph with &lt;CENTER&gt; &lt;/CENTER&gt;
 101 <LI>  h1,h2,h3,h4,h5,h6 --&gt; surround the paragraph with                            &lt;H1&gt; &lt;/H1&gt;, etc
 102 </UL>
 103 <P>Commands that format the lines of the paragraph as a list:
 104 </P>
 105 <UL><LI>  ul --&gt; surround the paragraph with &lt;UL&gt; &lt;/UL&gt;,     put &lt;LI&gt; at start of every line
 106 <LI>  ol --&gt; surround the paragraph with &lt;OL&gt; &lt;/OL&gt;,     put &lt;LI&gt; at start of every line
 107 <LI>  dl --&gt; surround the paragraph with &lt;DL&gt; &lt;/DL&gt;,     alternate &lt;DT&gt; and &lt;DD&gt; at start of every line
 108 </UL>
 109 <P>Commands that treat the paragraph as one entry in a list:
 110 </P>
 111 <UL><LI>  l --&gt; put &lt;LI&gt; at the beginning of the paragraph
 112 <LI>  dt --&gt; put &lt;DT&gt; at the beginning of the paragraph
 113 <LI>  dd --&gt; put &lt;DD&gt; at the beginning of the paragraph
 114 <LI>  ulb --&gt; put &lt;UL&gt; at the beginning of the paragraph
 115 <LI>  ule --&gt; put &lt;/UL&gt; at the end of the paragraph
 116 <LI>  olb --&gt; put &lt;OL&gt; at the beginning of the paragraph
 117 <LI>  ole --&gt; put &lt;/OL&gt; at the end of the paragraph
 118 <LI>  dlb --&gt; put &lt;DL&gt; at the beginning of the paragraph
 119 <LI>  dle --&gt; put &lt;/DL&gt; at the end of the paragraph
 120 </UL>
 121 <P>Commands applied to each line of the paragraph:
 122 </P>
 123 <UL><LI>  all(p) --&gt; surround each line with &lt;P&gt; &lt;/P&gt;
 124 <LI>  all(c) --&gt; surround each line with &lt;CENTER&gt; &lt;/CENTER&gt;
 125 <LI>  all(b) --&gt; append a &lt;BR&gt; to each line
 126 <LI>  all(l) --&gt; prepend a &lt;LI&gt; to each line
 127 </UL>
 128 <P>Special commands (all HTML is inserted at beginning of paragraph):
 129 </P>
 130 <UL><LI>  line --&gt; insert a horizontal line = &lt;HR&gt;
 131 <LI>  image(file) --&gt; insert an image = &lt;IMG SRC = "file"&gt;
 132 <LI>  image(file,link) --&gt; insert an image that when clicked on goes to link
 133 <LI>  link(name) --&gt; insert a named link that can be referred to     elsewhere (see <A HREF = "#markup">mark-up</A>) = &lt;A NAME = "name"&gt;&lt;/A&gt;
 134 <LI>  link(alias,value) --&gt; define a link alias that can be used     elsewhere in this file (see <A HREF = "#markup">mark-up</A>)
 135 </UL>
 136 <P>Table command:
 137 </P>
 138 <UL><LI>  tb(c=3,b=5,w=100%,a=c) --&gt; format the paragraph as a table
 139 </UL>
 140 <P>Arguments within tb() can appear in any order and are all optional,
 141 since they each have default values.
 142 </P>
 143 <UL><LI>  c=N --&gt; Make an N-column table.  Treat the paragraph as one
 144   long list of entries (separated by the separator character) and put
 145   them into N columns one after the other.  If N = 0, treat each line
 146   of the paragraph as one row of the table with as many columns as
 147   there are maximum entries in any line.  Default is c=0.
 148
 149 <LI>  s=: --&gt; Use the character string following the equal sign as
 150   the separator between entries.  Default separator is a comma "," which
 151   you cannot specify directly since the comma delimits the tb() arguments
 152
 153 <LI>  b=N --&gt; Create a border N pixels wide.  If N is 0, there is no
 154   border between or outside the cells.  If N is 1, there is a minimal
 155   border between and outside all cells.  For N > 1, the border between
 156   cells does not change but the outside border gets wider.  Default is
 157   b=1.
 158
 159 <LI>  w=N or w=N% --&gt The first form makes each cell of the table at
 160   least N pixels wide.  The second form makes the entire table take up
 161   N% of the width of the browser window.  Default is w=0 which means
 162   each cell will be just as wide as the text it contains.
 163
 164 <LI>  a=X --&gt Align the entire table at the left, center, or right of the
 165   browser window, for X = "l", "c", or "r".  Default is a=c.
 166
 167 <LI>  ea=X --&gt Align the text in each entry at the left, center, or
 168   right of its cell, for X = "l", "c", or "r".  Default is browser's
 169   default (typically left).
 170
 171 <LI>  eva=X --&gt Vertically align the text in each entry at the
 172   top, middle, baseline, or bottom of its cell, for X = "t", "m", "ba",
 173   or "bo".  Default is browser's default (typically middle).
 174
 175 <LI>  cwM=N or cwM=N% --&gt The first form makes column M be at least
 176   N pixels wide.  The second form makes column M take up N% of the
 177   width of the browser window.  This setting overrides the "w"
 178   argument for column M.  Only one column per table can be tweaked
 179   with this argument.  Default is no settings for any column.
 180
 181 <LI>  caM=X --&gt Align the text in each entry of column M at the left,
 182   center, or right of its cell, for X = "l", "c", or "r".  This
 183   setting overrides the "ea" argument for column M.  Only one column
 184   per table can be tweaked with this argument.  Default is no settings
 185   for any column.
 186
 187 <LI>  cvaM=X --&gt Vertically align the text in each entry of column m
 188   at the top, middle, baseline, or bottom of its cell, for X = "t",
 189   "m", "ba", or "bo".  This setting overrides the "eva" argument for
 190   column M.  Only one column per table can be tweaked with this
 191   argument.  Default is no settings for any column.
 192 </UL>
 193 <HR>
 194
 195 <A NAME = "markup"></A><B>Mark-up:</B>
 196
 197 <P>The text of the paragraph is scanned for special mark-up characters
 198 which are converted into HTML.
 199 </P>
 200 <P>Bold and italic characters:
 201 </P>
 202   <UL> <LI> "[" (left brace) --&gt; turn-on bold by inserting a &lt;B&gt;
 203   <LI> "]" (right brace) --&gt; turn-off bold by inserting a &lt;/B&gt;
 204   <LI> "{" (left bracket) --&gt; turn-on italics by inserting a &lt;I&gt;
 205   <LI> "}" (right bracket) --&gt; turn-off italics by
 206     inserting a &lt;/I&gt; </UL>
 207
 208 <P>If a backspace '\' preceeds any of the bold/italic mark-up characters,
 209 then mark-up is not performed; the mark-up character is simply left in
 210 the text.
 211 </P>
 212 <P>Links are inserted by enclosing a section of text in double quotes,
 213 and appending an underscore to the ending quote, followed by the link.
 214 The link ends when whitespace is found, except that trailing
 215 punctuation characters (comma, period, semi-colon, colon, question
 216 mark, exclamation point, parenthesis) are not considered part of the
 217 link.
 218 </P>
 219 <P> A link of the form "text"_link becomes &lt;A HREF =
 220 "link"&gt;text&lt;/A&gt; in the HTML output.  The only exception is if
 221 "link" is defined elsewhere in the file as an alias (see the link
 222 command above).  In that case, the value is used instead of the alias
 223 name. </P>
 224
 225 <P>With these rules, links can take several forms.
 226 </P>
 227 <UL> <LI> "This links"_#abc to another part of this file which is
 228 labeled with a :link(abc) command. <BR>
 229 <LI> "This links"_other.html to another file named other.html. <BR>
 230 <LI> "This links"_other.html#abc to another file which has an "abc"
 231 location defined internally. <BR>
 232 <LI> "This links"_http://www.google.com to a WWW site. <BR>
 233 <LI> "This"_M12 could be used in place of any of the above forms.  It
 234 requires an alias like :link(M12,http://www.google.com) to be defined
 235 elsewhere in the file. </UL>
 236
 237 </HTML>