Grutatxt(3)

NAME
Grutatxt - Text to HTML (and other formats) converter

SYNOPSIS
 use Grutatxt;

 # create a new Grutatxt converter object
 $grutatxt = new Grutatxt();

 # process a Grutatxt format string
 @output = $grutatxt->process($text);

 # idem for a file
 @output2 = $grutatxt->process_file($file);

DESCRIPTION
Grutatxt is a module to process text documents in a special markup format (also called Grutatxt), very similar to plain ASCII text. These documents can be converted to HTML, troff or man.

The markup is designed to be fairly intuitive and straightforward and can include headings, bold and italic text effects, bulleted, numbered and definition lists, URLs, function and variable names, preformatted text, horizontal separators and tables. Special marks can be inserted in the text and a heading-based structural index can be obtained from it.

A comprehensive description of the markup is defined in the README file, included with the Grutatxt package (it is written in Grutatxt format itself, so it can be converted using the grutatxt tool to any of the supported formats). The latest version (and more information) can be retrieved from the Grutatxt home page at:

 http://triptico.com/software/grutatxt.html

FUNCTIONS AND METHODS

  new
 $grutatxt = new Grutatxt([ "mode"  => $mode, ]
            [ "title" => \$title, ]
            [ "marks" => \@marks, ]
            [ "index" => \@index, ]
            [ "abstract" => \$abstract, ]
            [ "strip-parens" => $bool, ]
            [ "strip-dollars" => $bool, ]
            [ %driver_specific_arguments ] );

Creates a new Grutatxt object instance. All parameters are optional.

mode
    Output format. Can be HTML, troff or man. HTML is used if not specified.

title
    If title is specified as a reference to scalar, the first level 1 heading found in the text is stored inside it.

marks
    Marks in the Grutatxt markup are created by inserting the string <-> alone in a line. If marks is specified as a reference to array, it will be filled with the subscripts (relative to the output array) of the lines where the marks are found in the text.

index
    If index is specified as a reference to array, it will be filled with two element arrayrefs with the level as first argument and the heading as second.

    This information can be used to build a table of contents of the processed text.

strip-parens
    Function names in the Grutatxt markup are strings of alphanumeric characters immediately followed by a pair of open and close parentheses. If this boolean value is set, function names found in the processed text will have their parentheses deleted.

strip-dollars
    Variable names in the Grutatxt markup are strings of alphanumeric characters preceded by a dollar sign. If this boolean value is set, variable names found in the processed text will have the dollar sign deleted.

abstract
    The abstract of a Grutatxt document is the fragment of text from the beginning of the document to the end of the first paragraph after the title. If abstract is specified as a reference to scalar, it will contain (after each call to the process() method) the subscript of the element of the output array that marks the end of the subject.

no-pure-verbatim
    Since version 2.0.15, text effects as italics and bold are not processed in verbatim (preformatted) mode. If you want to revert to the old behaviour, use this option.

toc If set, a table of contents will be generated after the abstract. The table of contents will be elaborated using headings from 2 and 3 levels.

  process
 @output = $grutatxt->process($text);

Processes a text in Grutatxt format. The result is returned as an array of lines.

  process_file
 @output = $grutatxt->process_file($filename);

Processes a file in Grutatxt format.

DRIVER SPECIFIC INFORMATION

  HTML Driver
The additional parameters for a new Grutatxt object are:

table-headers
    If this boolean value is set, the first row in tables is assumed to be the heading and rendered using 'th' instead of 'td' tags.

center-tables
    If this boolean value is set, tables are centered.

expand-tables
    If this boolean value is set, tables are expanded (width 100%).

dl-as-dl
    If this boolean value is set, definition lists will be rendered using 'dl', 'dt' and 'dd' instead of tables.

header-offset
    Offset to be summed to the heading level when rendering 'h?' tags (default is 0).

class-oddeven
    If this boolean value is set, tables will be rendered with an "oddeven" CSS class, and rows alternately classed as "even" or "odd". If it's not set, no CSS class info is added to tables.

url-label-max
    If an URL without label is given (that is, the URL itself is used as the label), it's trimmed to have as much characters as this value says. By default it's 80.

  troff Driver
The troff driver uses the -me macros and tbl. A good way to post-process this output (to PostScript in the example) could be by using

 groff -t -me -Tps

The additional parameters for a new Grutatxt object are:

normal-size
    The point size of normal text. By default is 10.

heading-sizes
    This argument must be a reference to an array containing the size in points of the 3 different heading levels. By default, level sizes are [ 20, 18, 15 ].

table-type
    The type of table to be rendered by tbl. Can be allbox (all lines rendered; this is the default value), box (only outlined) or doublebox (only outlined by a double line).

  man Driver
The man driver is used to generate Unix-like man pages. Note that all headings have the same level with this output driver.

The additional parameters for a new Grutatxt object are:

section
    The man page section (see man documentation). By default is 1.

page-name
    The name of the page. This is usually the name of the program or function the man page is documenting and will be shown in the page header. By default is the empty string.

  LaTeX Driver
The additional parameters for a new Grutatxt object are:

docclass
    The LaTeX document class. By default is 'report'. You can also use 'article' or 'book' (consult your LaTeX documentation for details).

papersize
    The paper size to be used in the document. By default is 'a4paper'.

encoding
    The character encoding used in the document. By default is 'latin1'.

Note that you can't nest further than 4 levels in LaTeX; if you do, LaTeX will choke in the generated code with a 'Too deeply nested' error.

  RTF Driver
The additional parameters for a new Grutatxt object are:

normal-size
    The point size of normal text. By default is 20.

heading-sizes
    This argument must be a reference to an array containing the size in points of the 3 different heading levels. By default, level sizes are [ 34, 30, 28 ].

AUTHOR
Angel Ortega angel@triptico.com et al.