"Fossies" - the Fresh Open Source Software Archive

Member "Grutatxt-2.20/doc/grutatxt_markup.txt" (5 May 2015, 8969 Bytes) of package /linux/www/Grutatxt-2.20.tar.gz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

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