README

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