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