README

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