GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages
Grutatxt(3) User Contributed Perl Documentation Grutatxt(3)

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, 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

 $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.

 @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.
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.

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).

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.

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.

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 ].

Angel Ortega angel@triptico.com et al.
2019-11-29 perl v5.32.1

Search for    or go to Top of page |  Section 3 |  Main Index

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with ManDoc.