Grutatxt - Text to HTML (and other formats) converter
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);
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 or troff.
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://www.triptico.com/software/grutatxt.html
$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 or troff. 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 strings in the format
level,heading
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.
@output=$grutatxt->process($text);
Processes a text in Grutatxt format. The result is returned
as an array of lines.
@output=$grutatxt->process_file($filename);
Processes a file in Grutatxt format.
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.
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).
Angel Ortega angel@triptico.com