grutatxt.1

   1 .\" This file was generated by help2man 1.29 (and then hand-edited by Kei).
   2 .TH GRUTATXT "1" "June 2003" "" "User Commands"
   3 .SH NAME
   4 grutatxt \- a plain text to HTML/troff/man/LaTeX converter.
   5 .SH SYNOPSIS
   6 .B grutatxt
   7 [\fIoptions\fR] \fI< input_text_file > output_html_file\fR
   8 .SH DESCRIPTION
   9 .B grutatxt
  10 is a plain text to HTML, troff, man and LaTeX converter.
  11 It succesfully converts subtle text markup to lists, bold, italics, tables
  12 and headings to their corresponding HTML tags, troff, man or LaTeX
  13 commands without having to write unreadable source text files.
  14 .SH
  15 OPTIONS
  16 .PP
  17 Global options:
  18 .TP
  19 \fB\-i\fR|--input=FILE
  20 Input file (STDIN)
  21 .TP
  22 \fB\-o\fR|--output=FILE
  23 Output file (STDOUT)
  24 .TP
  25 \fB\-t\fR|--title=TITLE
  26 Document title (if unset,
  27 level 1 heading is used)
  28 .TP
  29 \fB\-sp\fR|--strip-parens
  30 Strip parentheses in function
  31 names (shown monospaced anyway)
  32 .TP
  33 \fB\-sd\fR|--strip-dollars
  34 Strip leading $ in variable
  35 names (shown monospaced anyway)
  36 .TP
  37 \fB\-m\fR|--mode=[HTML|troff|man|latex]
  38 Selects output mode, HTML, troff, man or LaTeX
  39 (default: HTML)
  40 .PP
  41 HTML options:
  42 .TP
  43 \fB\-c\fR|--css=CSS_URL
  44 Cascade Style Sheet URL
  45 .TP
  46 \fB\-f\fR|--header-offset=NUMBER Offset to add to <h1>,
  47 <h2>... headers (default 0)
  48 .TP
  49 \fB\-b\fR|--table-headers
  50 Use <th> instead of <td> in
  51 the first row of each table
  52 .TP
  53 \fB\-ct\fR|--center-tables
  54 Centers the tables
  55 .TP
  56 \fB\-xt\fR|--expand-tables
  57 Expands the tables (width=100%)
  58 .TP
  59 \fB\-nb\fR|-no-body
  60 Don't generate <html><body>...
  61 </body></html> enclosing.
  62 .TP
  63 \fB\-dl\fR
  64 Use real <dl>, <dd> and <dt>
  65 instead of tables in definition lists.
  66 .TP
  67 \fB\-\-encoding\fR=\fIENCODING\fR
  68 Character encoding (default: iso-8859-1)
  69 .PP
  70 troff options:
  71 .TP
  72 \fB\-\-table\-type\fR=\fITYPE\fR
  73 Table type. Possible values:
  74 box, allbox, doublebox (default allbox)
  75 .PP
  76 man options:
  77 .TP
  78 \fB\-s\fR|--man-section=\fISECTION\fR
  79 Man page section (default: 1)
  80 .PP
  81 LaTeX options:
  82 .TP
  83 \fB\-\-docclass\fR=\fICLASS\fR
  84 Document class (default: report)
  85 .TP
  86 \fB\-\-papersize\fR=\fISIZE\fR
  87 Paper size (default: a4paper)
  88 .TP
  89 \fB\-\-encoding\fR=\fIENCODING\fR
  90 Character encoding (default: latin1)
  91 .TP
  92 \fB\-ts\fR|--tabsize=\fINUMBER\fR
  93 Tab size for mandatory tab to space
  94 conversions in verbatim environment
  95 (default: 8)
  96 .SH "INPUT FILE SYNTAX"
  97 .nf
  98 Text paragraphs
  99 ---------------
 100
 101 A text paragraph is any group of lines containing text delimited by
 102 one or more blank lines, provided that none of them beings with a
 103 blank space. So, you just write lines as usual (wrapping or not), and
 104 separates paragraphs as in a word processor.
 105
 106 Headings
 107 --------
 108
 109 A line is understand as a heading if it's immediately followed by
 110 another one that contains only a repetition of a special character
 111 (see 'Text paragraphs' and 'Headings' for an example). There are three
 112 heading levels depending on this special character: if it's a line of
 113 = (equal sign), it's a first level heading, used for titles and tagged
 114 with h1 HTML tags. If it's - (hyphen), it's a second level heading,
 115 and it it's ~ (tilde), a third level one. This document shows the
 116 three heading levels. It's suggested that the first level heading is
 117 used only once, as it's magically taken as the title for the HTML
 118 page, if one is not overriden as a command line argument.
 119
 120 Text effects
 121 ------------
 122
 123 If some text is surrounded by asterisks, as *this one*, it's marked as
 124 bold (you probably wrote text this way in email to emphasize
 125 something). As well, text surrounded by the _ symbol (underscore), as
 126 _this one_, is marked as italic. Bold can also be marked up
 127 surrounding the text with three apostrophes ('''this way''') and
 128 italics with two (''this way''). If you ever used a WikiWikiWeb system
 129 you'll be familiar with these ones.
 130
 131 Other special text is automatically recognized, as URLs (so the URL
 132 http://www.triptico.com should be clickable). Grutatxt can also be
 133 useful documenting source code, as function names like printf() or
 134 variables like $username are also highlighted. There are command line
 135 arguments to make the parenthesis and / or leading dollar to disappear
 136 from the output document.
 137
 138 URLs are simply substituted as shown above; if an URL is followed by a
 139 phrase surrounded by parentheses (just like you naturally would do to
 140 explain the contents of a web), this phrase is used as the link text,
 141 as in this example pointing to
 142 http://www.triptico.com/software/grutatxt.html (the Grutatxt Home Page).
 143
 144 Lists
 145 -----
 146
 147 Grutatxt is powerful rendering lists. There are three types of lists:
 148 unnumbered ones (bulleted), numbered ones and definition lists. They
 149 are recognized as lines starting with a blank (space or tab)
 150 immediately followed by an special character.
 151
 152  * Unnumbered lists start with some blanks, followed by an asterisk,
 153    followed by another blank. If the following lines are space indented,
 154    they are assumed as part of the same list element. The asterisk can
 155    also be a - (hyphen).
 156  * Lists can have multiple levels. To add another level,
 157    * Just indent a bit deeper,
 158      * and have hours of fun
 159        * nesting
 160          * and nesting.
 161  * Numbered lists are marked up almost the same, just by substuting the
 162    asterisk by a # (sharp) or 1 (number one).
 163  * Definition lists are marked up almost the same, but delimiting the
 164    definition term from the definition itself by a colon. These lists are
 165    rendered using tables, unless you specify a command line argument to
 166    force them being rendered with standard <dl> HTML marks (too ugly
 167    for me).
 168
 169 List examples
 170 ~~~~~~~~~~~~~
 171
 172 Unnumbered list:
 173
 174  * First element. Elements at the same level must be indented
 175    by the same number of spaces.
 176  * The second one.
 177    * The second element has one sub-element.
 178    * And another...
 179       * that, itself, has another one
 180  * The third one...
 181    * Has another extremely long sub-element to show that long
 182      ones are rendered correctly. Please note that the elements
 183      of a list cannot be separated by blank lines or they will
 184      be interpreted as different lists.
 185  * The 4th and final one...
 186    * And its final child.
 187
 188 Ordered list:
 189
 190  # First element.
 191  # The second one.
 192    # The second element has one sub-element.
 193    # And another...
 194       # that, itself, has another one
 195  # The third one...
 196    # Has another extremely long sub-element to show that long
 197      ones are rendered correctly. Please note that the elements
 198      of a list cannot be separated by blank lines or they will
 199      be interpreted as different lists.
 200    # And another sub-element, to show this is not a cut & paste
 201      from the unsorted example.
 202  # The 4th and final one. Note also that ordered and unsorted
 203    lists cannot be combined.
 204
 205 Definition list:
 206
 207  * first: the first element
 208  * second: the second element
 209  * third: the third element
 210
 211 Preformatted text
 212 -----------------
 213
 214 A text that should be rendered as is should be written with at least a
 215 blank in the beginning of all lines. This can be an example:
 216
 217  int main(int argc, char * argv[])
 218  {
 219         /* an example of useless C code */
 220         return(0);
 221  }
 222
 223 If you ever wrote any Perl POD documentation, you'll be familiar with
 224 this.
 225
 226 If you write preformatted text and its first line collisions with list
 227 definitions (i.e. text with lines beginning with blanks and an
 228 asterisk or sharp) just insert a line containing only spaces before
 229 it.
 230
 231 Cites
 232 -----
 233
 234 If you want to quote a (possibly long) paragraph of text, use a blank
 235 followed by a " (double quote) in its first line, as in the following
 236 example:
 237
 238  "BRAIN, n. An apparatus with which we think what we think. That which
 239  distinguishes the man who is content to _be_ something from the man
 240  who wishes to _do_ something. A man of great wealth, or one who has
 241  been pitchforked into high station, has commonly such a headful of
 242  brain that his neighbors cannot keep their hats on. In our
 243  civilization, and under our republican form of government, brain is
 244  so highly honored that it is rewarded by exemption from the cares of
 245  office." -- Ambrose Bierce
 246
 247 The leading double quote remains as part of the cited paragraph.
 248
 249 HTML
 250 ----
 251
 252 If you need to insert HTML as is (for rendering, say, images or
 253 complicated layouts), you can also do it. Anything between a line
 254 containing only two < symbols and a line containing two > symbols will
 255 be passed without any further processing. So, to insert an image, just
 256 do this:
 257
 258 <<
 259 <center>
 260 <img src='http://www.triptico.com/data/themask.jpg' alt="The Mask Cover">
 261 </center>
 262 >>
 263
 264 Any other HTML outside this boundaries is escaped.
 265
 266 Tables
 267 ------
 268
 269 But where Grutatxt is really awesome is rendering tables. They are
 270 created using the + (plus) sign for corners, the - (hyphen) for
 271 horizontal lines and the | (pipe) for vertical lines. So this is a
 272 table:
 273
 274 +----------------+----------------------+-----------+
 275 | Band Name      | Album Name           | Number of |
 276 |                |                      | Songs     |
 277 +----------------+----------------------+-----------+
 278 | Dead Can Dance | A Passage in Time    | 16        |
 279 +----------------+----------------------+-----------+
 280 | Bel Canto      | White-Out Conditions | 10        |
 281 +----------------+----------------------+-----------+
 282 | Depeche Mode   | Speak and Spell      | 16        |
 283 +----------------+----------------------+-----------+
 284 | Love Spirals   | Temporal             | 13        |
 285 | Downwards      |                      |           |
 286 +----------------+----------------------+-----------+
 287
 288 As you can see, cells with long text inside can span several lines of
 289 physical text, provided that you delimit table rows with a new line
 290 containing only + and - symbols.
 291
 292 A column can also span several ones, just by marking the intersections
 293 with | (pipe) instead of + (plus). Look in this example how it's done:
 294
 295 +-----------+-------------+-------------+-----------+
 296 | Head 1    | Head 2      | Head 3      | Head 4    |
 297 +-----------+-------------+-------------+-----------+
 298 | Cell 1-1  | Cell spanning two         | Cell 1-3  |
 299 +-----------+-------------|-------------+-----------+
 300 | Cell 2-1  | Cell 2-2    | Cell 2-3    | Cell 2-4  |
 301 +-----------+-------------+-------------+-----------+
 302 | Cell 3-1  | Cell spanning three                   |
 303 +-----------+-------------|-------------|-----------+
 304
 305 It's not possible to span rows by now.
 306
 307 Separators
 308 ----------
 309
 310 A separator line (horizontal ruler) can be inserted by typing four or
 311 more hyphens alone in a line. To avoid being confused with a second
 312 level heading, insert a blank line just before. To the end of this
 313 document there should be a separator, above my signature.
 314 .fi
 315 .SH AUTHOR
 316 Angel Ortega
 317 .SH MISC
 318 Copyright (C) 2002 Angel Ortega
 319
 320 This software is distributed under the GNU Public License (GPL). NO
 321 WARRANTY.
 322 See the file 'COPYING' in the source distribution for details.
 323
 324 Visit
 325 http://www.triptico.com/software/grutatxt.html
 326 for the latest version.
 327