| blob | 42e40e26e331cf6ce4e3ca6bdbccbf36da253e1d |
1 .\" This file was generated by help2man 1.29 (and then hand-edited by Kei).
2 .TH GRUTATXT "1" "June 2003" "" "User Commands"
3 .SH NAME
4 grutatxt \- a plain text to HTML/troff/man/LaTeX converter.
5 .SH SYNOPSIS
6 .B grutatxt
7 [\fIoptions\fR] \fI< input_text_file > output_html_file\fR
8 .SH DESCRIPTION
9 .B grutatxt
10 is a plain text to HTML, troff, man and LaTeX converter.
11 It succesfully converts subtle text markup to lists, bold, italics, tables
12 and headings to their corresponding HTML tags, troff, man or LaTeX
13 commands without having to write unreadable source text files.
14 .SH
15 OPTIONS
16 .PP
17 Global options:
18 .TP
19 \fB\-i\fR|--input=FILE
20 Input file (STDIN)
21 .TP
22 \fB\-o\fR|--output=FILE
23 Output file (STDOUT)
24 .TP
25 \fB\-t\fR|--title=TITLE
26 Document title (if unset,
27 level 1 heading is used)
28 .TP
29 \fB\-sp\fR|--strip-parens
30 Strip parentheses in function
31 names (shown monospaced anyway)
32 .TP
33 \fB\-sd\fR|--strip-dollars
34 Strip leading $ in variable
35 names (shown monospaced anyway)
36 .TP
37 \fB\-m\fR|--mode=[HTML|troff|man|latex]
38 Selects output mode, HTML, troff, man or LaTeX
39 (default: HTML)
40 .PP
41 HTML options:
42 .TP
43 \fB\-c\fR|--css=CSS_URL
44 Cascade Style Sheet URL
45 .TP
46 \fB\-f\fR|--header-offset=NUMBER Offset to add to <h1>,
47 <h2>... headers (default 0)
48 .TP
49 \fB\-b\fR|--table-headers
50 Use <th> instead of <td> in
51 the first row of each table
52 .TP
53 \fB\-ct\fR|--center-tables
54 Centers the tables
55 .TP
56 \fB\-xt\fR|--expand-tables
57 Expands the tables (width=100%)
58 .TP
59 \fB\-nb\fR|-no-body
60 Don't generate <html><body>...
61 </body></html> enclosing.
62 .TP
63 \fB\-dl\fR
64 Use real <dl>, <dd> and <dt>
65 instead of tables in definition lists.
66 .TP
67 \fB\-\-encoding\fR=\fIENCODING\fR
68 Character encoding (default: iso-8859-1)
69 .PP
70 troff options:
71 .TP
72 \fB\-\-table\-type\fR=\fITYPE\fR
73 Table type. Possible values:
74 box, allbox, doublebox (default allbox)
75 .PP
76 man options:
77 .TP
78 \fB\-s\fR|--man-section=\fISECTION\fR
79 Man page section (default: 1)
80 .PP
81 LaTeX options:
82 .TP
83 \fB\-\-docclass\fR=\fICLASS\fR
84 Document class (default: report)
85 .TP
86 \fB\-\-papersize\fR=\fISIZE\fR
87 Paper size (default: a4paper)
88 .TP
89 \fB\-\-encoding\fR=\fIENCODING\fR
90 Character encoding (default: latin1)
91 .TP
92 \fB\-ts\fR|--tabsize=\fINUMBER\fR
93 Tab size for mandatory tab to space
94 conversions in verbatim environment
95 (default: 8)
96 .SH "INPUT FILE SYNTAX"
97 .nf
98 Text paragraphs
99 ---------------
101 A text paragraph is any group of lines containing text delimited by
102 one or more blank lines, provided that none of them beings with a
103 blank space. So, you just write lines as usual (wrapping or not), and
104 separates paragraphs as in a word processor.
106 Headings
107 --------
109 A line is understand as a heading if it's immediately followed by
110 another one that contains only a repetition of a special character
111 (see 'Text paragraphs' and 'Headings' for an example). There are three
112 heading levels depending on this special character: if it's a line of
113 = (equal sign), it's a first level heading, used for titles and tagged
114 with h1 HTML tags. If it's - (hyphen), it's a second level heading,
115 and it it's ~ (tilde), a third level one. This document shows the
116 three heading levels. It's suggested that the first level heading is
117 used only once, as it's magically taken as the title for the HTML
118 page, if one is not overriden as a command line argument.
120 Text effects
121 ------------
123 If some text is surrounded by asterisks, as *this one*, it's marked as
124 bold (you probably wrote text this way in email to emphasize
125 something). As well, text surrounded by the _ symbol (underscore), as
126 _this one_, is marked as italic. Bold can also be marked up
127 surrounding the text with three apostrophes ('''this way''') and
128 italics with two (''this way''). If you ever used a WikiWikiWeb system
129 you'll be familiar with these ones.
131 Other special text is automatically recognized, as URLs (so the URL
132 http://www.triptico.com should be clickable). Grutatxt can also be
133 useful documenting source code, as function names like printf() or
134 variables like $username are also highlighted. There are command line
135 arguments to make the parenthesis and / or leading dollar to disappear
136 from the output document.
138 URLs are simply substituted as shown above; if an URL is followed by a
139 phrase surrounded by parentheses (just like you naturally would do to
140 explain the contents of a web), this phrase is used as the link text,
141 as in this example pointing to
142 http://www.triptico.com/software/grutatxt.html (the Grutatxt Home Page).
144 Lists
145 -----
147 Grutatxt is powerful rendering lists. There are three types of lists:
148 unnumbered ones (bulleted), numbered ones and definition lists. They
149 are recognized as lines starting with a blank (space or tab)
150 immediately followed by an special character.
152 * Unnumbered lists start with some blanks, followed by an asterisk,
153 followed by another blank. If the following lines are space indented,
154 they are assumed as part of the same list element. The asterisk can
155 also be a - (hyphen).
156 * Lists can have multiple levels. To add another level,
157 * Just indent a bit deeper,
158 * and have hours of fun
159 * nesting
160 * and nesting.
161 * Numbered lists are marked up almost the same, just by substuting the
162 asterisk by a # (sharp) or 1 (number one).
163 * Definition lists are marked up almost the same, but delimiting the
164 definition term from the definition itself by a colon. These lists are
165 rendered using tables, unless you specify a command line argument to
166 force them being rendered with standard <dl> HTML marks (too ugly
167 for me).
169 List examples
170 ~~~~~~~~~~~~~
172 Unnumbered list:
174 * First element. Elements at the same level must be indented
175 by the same number of spaces.
176 * The second one.
177 * The second element has one sub-element.
178 * And another...
179 * that, itself, has another one
180 * The third one...
181 * Has another extremely long sub-element to show that long
182 ones are rendered correctly. Please note that the elements
183 of a list cannot be separated by blank lines or they will
184 be interpreted as different lists.
185 * The 4th and final one...
186 * And its final child.
188 Ordered list:
190 # First element.
191 # The second one.
192 # The second element has one sub-element.
193 # And another...
194 # that, itself, has another one
195 # The third one...
196 # Has another extremely long sub-element to show that long
197 ones are rendered correctly. Please note that the elements
198 of a list cannot be separated by blank lines or they will
199 be interpreted as different lists.
200 # And another sub-element, to show this is not a cut & paste
201 from the unsorted example.
202 # The 4th and final one. Note also that ordered and unsorted
203 lists cannot be combined.
205 Definition list:
207 * first: the first element
208 * second: the second element
209 * third: the third element
211 Preformatted text
212 -----------------
214 A text that should be rendered as is should be written with at least a
215 blank in the beginning of all lines. This can be an example:
217 int main(int argc, char * argv[])
218 {
219 /* an example of useless C code */
220 return(0);
221 }
223 If you ever wrote any Perl POD documentation, you'll be familiar with
224 this.
226 If you write preformatted text and its first line collisions with list
227 definitions (i.e. text with lines beginning with blanks and an
228 asterisk or sharp) just insert a line containing only spaces before
229 it.
231 Cites
232 -----
234 If you want to quote a (possibly long) paragraph of text, use a blank
235 followed by a " (double quote) in its first line, as in the following
236 example:
238 "BRAIN, n. An apparatus with which we think what we think. That which
239 distinguishes the man who is content to _be_ something from the man
240 who wishes to _do_ something. A man of great wealth, or one who has
241 been pitchforked into high station, has commonly such a headful of
242 brain that his neighbors cannot keep their hats on. In our
243 civilization, and under our republican form of government, brain is
244 so highly honored that it is rewarded by exemption from the cares of
245 office." -- Ambrose Bierce
247 The leading double quote remains as part of the cited paragraph.
249 HTML
250 ----
252 If you need to insert HTML as is (for rendering, say, images or
253 complicated layouts), you can also do it. Anything between a line
254 containing only two < symbols and a line containing two > symbols will
255 be passed without any further processing. So, to insert an image, just
256 do this:
258 <<
259 <center>
260 <img src='http://www.triptico.com/data/themask.jpg' alt="The Mask Cover">
261 </center>
262 >>
264 Any other HTML outside this boundaries is escaped.
266 Tables
267 ------
269 But where Grutatxt is really awesome is rendering tables. They are
270 created using the + (plus) sign for corners, the - (hyphen) for
271 horizontal lines and the | (pipe) for vertical lines. So this is a
272 table:
274 +----------------+----------------------+-----------+
275 | Band Name | Album Name | Number of |
276 | | | Songs |
277 +----------------+----------------------+-----------+
278 | Dead Can Dance | A Passage in Time | 16 |
279 +----------------+----------------------+-----------+
280 | Bel Canto | White-Out Conditions | 10 |
281 +----------------+----------------------+-----------+
282 | Depeche Mode | Speak and Spell | 16 |
283 +----------------+----------------------+-----------+
284 | Love Spirals | Temporal | 13 |
285 | Downwards | | |
286 +----------------+----------------------+-----------+
288 As you can see, cells with long text inside can span several lines of
289 physical text, provided that you delimit table rows with a new line
290 containing only + and - symbols.
292 A column can also span several ones, just by marking the intersections
293 with | (pipe) instead of + (plus). Look in this example how it's done:
295 +-----------+-------------+-------------+-----------+
296 | Head 1 | Head 2 | Head 3 | Head 4 |
297 +-----------+-------------+-------------+-----------+
298 | Cell 1-1 | Cell spanning two | Cell 1-3 |
299 +-----------+-------------|-------------+-----------+
300 | Cell 2-1 | Cell 2-2 | Cell 2-3 | Cell 2-4 |
301 +-----------+-------------+-------------+-----------+
302 | Cell 3-1 | Cell spanning three |
303 +-----------+-------------|-------------|-----------+
305 It's not possible to span rows by now.
307 Separators
308 ----------
310 A separator line (horizontal ruler) can be inserted by typing four or
311 more hyphens alone in a line. To avoid being confused with a second
312 level heading, insert a blank line just before. To the end of this
313 document there should be a separator, above my signature.
314 .fi
315 .SH AUTHOR
316 Angel Ortega
317 .SH MISC
318 Copyright (C) 2002 Angel Ortega
320 This software is distributed under the GNU Public License (GPL). NO
321 WARRANTY.
322 See the file 'COPYING' in the source distribution for details.
324 Visit
325 http://www.triptico.com/software/grutatxt.html
326 for the latest version.