Grutatxt - Text to HTML converter Copyright (C) 2000/2005 Angel Ortega <angel@triptico.com> Home Page: http://www.triptico.com/software/grutatxt.html
This software is GPL. NO WARRANTY. See file 'COPYING' for details.
Grutatxt is a plain text to HTML (and now other formats) converter. It succesfully converts subtle text markup to lists, bold, italics, tables and headings to their corresponding HTML, troff, man page or LaTeX markup without having to write unreadable source text files.
To install Grutatxt, do it just like you would do to any Perl module, so
$ perl Makefile.PL $ make $ su -c "make install"
This will install the perl module (Grutatxt.pm) as well as the command line utility (grutatxt).
Grutatxt includes several command-line arguments; see them using
$ grutatxt --help
This README file contains all the marks that Grutatxt is able to understand so that it serves also as a demo. So, to see how this file will look after being converted by Grutatxt, you can just do
$ grutatxt < README > README.html
or
$ grutatxt --mode=troff < README | groff -t -me -Tps > README.ps
or
$ grutatxt --mode=latex < README > README.latex
and see its effects.
A text paragraph is any group of lines containing text delimited by one or more blank lines, provided that none of them beings with a blank space. So, you just write lines as usual (wrapping or not), and separates paragraphs as in a word processor.
A line is understand as a heading if it's immediately followed by another one that contains only a repetition of a special character (see 'Text paragraphs' and 'Headings' for an example). There are three heading levels depending on this special character: if it's a line of = (equal sign), it's a first level heading, used for titles and tagged with h1 HTML tags. If it's - (hyphen), it's a second level heading, and if it's ~ (tilde), a third level one. This document shows the three heading levels. It's suggested that the first level heading is used only once, as it's magically taken as the title for the HTML page, if one is not overriden as a command line argument.
If some text is surrounded by asterisks, as this one, it's marked as bold (you probably wrote text this way in email to emphasize something). As well, text surrounded by the _ symbol (underscore), as this one, is marked as italic. Bold can also be marked up surrounding the text with three apostrophes (this way) and italics with two (this way). If you ever used a WikiWikiWeb system you'll be familiar with these ones.
Other special text is automatically recognized, as URLs (so that the URL http://www.triptico.com should be clickable). Text beginning with ./ is interpreted as relative URLs, so index.html should also be clickable.
Grutatxt can also be useful when documenting source code, as function names
like printf() or variables like $username are also highlighted. There are
command line arguments to make the parenthesis and / or leading dollar to
disappear from the output document. Other than the function names and
variables, inline literal texts can be marked up surrounding the text
with a backtick and apostrophe (like this).
URLs are simply substituted as shown above; if an URL is followed by a phrase surrounded by parentheses (just like you naturally would do to explain the contents of a web), this phrase is used as the link text, as in this example pointing to the Grutatxt Home Page.
Grutatxt is powerful rendering lists. There are three types of lists: unnumbered ones (bulleted), numbered ones and definition lists. They are recognized as lines starting with a blank (space or tab) immediately followed by an special character.
Unnumbered list:
Ordered list:
Definition list:
| first | the first element |
| second | the second element |
| third | the third element |
A text that should be rendered as is should be written with at least a blank in the beginning of all lines. This can be an example:
int main(int argc, char * argv[])
{
/* an example of useless C code */
return(0);
}
If you ever wrote any Perl POD documentation, you'll be familiar with this.
If you write preformatted text and its first line collisions with list definitions (i.e. text with lines beginning with blanks and an asterisk or sharp) just insert a line containing only spaces before it.
If you want to quote a (possibly long) paragraph of text, use a blank followed by a " (double quote) in its first line, as in the following example:
"BRAIN, n. An apparatus with which we think what we think. That which distinguishes the man who is content to be something from the man who wishes to do something. A man of great wealth, or one who has been pitchforked into high station, has commonly such a headful of brain that his neighbors cannot keep their hats on. In our civilization, and under our republican form of government, brain is so highly honored that it is rewarded by exemption from the cares of office." -- Ambrose Bierce
The leading double quote remains as part of the cited paragraph.
If you need to insert HTML as is (for rendering, say, images or complicated layouts), you can also do it. Anything between two < symbols and two > symbols will be passed without any further processing. So, to insert an image, just do this:
Passthrough code can also be inline as in this example.
Any other HTML outside this boundaries is escaped.
But where Grutatxt is really awesome is rendering tables. They are created
using the + (plus) sign for corners, the - (hyphen) for horizontal lines
and the | (pipe) for vertical lines. So this is a table:
| Band Name | Album Name | Number of Songs |
| Dead Can Dance | A Passage in Time | 16 |
| Bel Canto | White-Out Conditions | 10 |
| Depeche Mode | Speak and Spell | 16 |
| Love Spirals Downwards | Temporal | 13 |
As you can see, cells with long text inside can span several lines of
physical text, provided that you delimit table rows with a new line
containing only + and - symbols.
A column can also span several ones, just by marking the intersections
with | (pipe) instead of + (plus). Look in this example how it's done:
| Head 1 | Head 2 | Head 3 | Head 4 |
| Cell 1-1 | Cell spanning two | Cell 1-3 | |
| Cell 2-1 | Cell 2-2 | Cell 2-3 | Cell 2-4 |
| Cell 3-1 | Cell spanning three | ||
It's not possible to span rows by now.
A separator line (horizontal ruler) can be inserted by typing four or more hyphens alone in a line. To avoid being confused with a second level heading, insert a blank line just before. To the end of this document there should be a separator, above my signature.