PageRenderTime 104ms CodeModel.GetById 64ms app.highlight 31ms RepoModel.GetById 1ms app.codeStats 0ms

/doc/English/manpage.html

http://txt2tags.googlecode.com/
HTML | 456 lines | 400 code | 54 blank | 2 comment | 0 complexity | 113e4709f1869182e248d7171a821957 MD5 | raw file
  1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
  2<HTML>
  3<HEAD>
  4<STYLE>body{margin:3em;} pre{background:#ffc;}</STYLE>
  5<META NAME="generator" CONTENT="http://txt2tags.org">
  6<TITLE>TXT2TAGS</TITLE>
  7</HEAD><BODY BGCOLOR="white" TEXT="black">
  8<CENTER>
  9<H1>TXT2TAGS</H1>
 10<FONT SIZE="4">Aug, 2010</FONT>
 11</CENTER>
 12
 13<P></P>
 14<HR NOSHADE SIZE=1>
 15<P></P>
 16
 17  <UL>
 18  <LI><A HREF="#name">NAME</A>
 19  <LI><A HREF="#synopsis">SYNOPSIS</A>
 20  <LI><A HREF="#description">DESCRIPTION</A>
 21  <LI><A HREF="#markup">MARKUP</A>
 22  <LI><A HREF="#options">OPTIONS</A>
 23  <LI><A HREF="#source">SOURCE FILES</A>
 24  <LI><A HREF="#settings">SETTINGS</A>
 25  <LI><A HREF="#commands">COMMANDS</A>
 26  <LI><A HREF="#macros">MACROS</A>
 27  <LI><A HREF="#examples">EXAMPLES</A>
 28  <LI><A HREF="#files">FILES</A>
 29  <LI><A HREF="#environment">ENVIRONMENT</A>
 30  <LI><A HREF="#author">AUTHOR</A>
 31  <LI><A HREF="#bugs">BUGS</A>
 32  <LI><A HREF="#copyright">COPYRIGHT</A>
 33  </UL>
 34
 35<P></P>
 36<HR NOSHADE SIZE=1>
 37<P></P>
 38
 39<H1 ID="name">NAME</H1>
 40
 41<P>
 42txt2tags - text formatting and conversion tool
 43</P>
 44
 45<H1 ID="synopsis">SYNOPSIS</H1>
 46
 47<P>
 48<B>txt2tags</B> [<I>options</I>] [<I>FILE</I>...]
 49</P>
 50
 51<H1 ID="description">DESCRIPTION</H1>
 52
 53<P>
 54<B>txt2tags</B> reads a text file with minimal markup and convert it to:
 55<I>ASCII Art</I>,
 56<I>AsciiDoc</I>,
 57<I>Creole</I>,
 58<I>DocBook</I>,
 59<I>DokuWiki</I>,
 60<I>Google Code Wiki</I>,
 61<I>HTML</I>,
 62<I>LaTeX</I>,
 63<I>Lout</I>,
 64<I>MagicPoint</I>,
 65<I>Man page</I>,
 66<I>MoinMoin</I>,
 67<I>PageMaker</I>,
 68<I>Plain Text</I>,
 69<I>PmWiki</I>,
 70<I>SGML</I>,
 71<I>Wikipedia</I> and
 72<I>XHTML</I>.
 73</P>
 74<P>
 75This man page was created by <B>txt2tags</B> from a simple text file. The same text file is also converted to HTML for the online version of this manual.
 76</P>
 77<P>
 78ONE source, MULTI targets - <A HREF="http://txt2tags.org">http://txt2tags.org</A>
 79</P>
 80
 81<H1 ID="markup">MARKUP</H1>
 82
 83<PRE>
 84  Headers           First 3 lines of the source file
 85  Title             = words =
 86  Numbered title    + words +
 87  Comment           % comments
 88  Separator line    -----------------------...
 89  Strong line       =======================...
 90  Image             [filename.jpg]
 91  Link              [label url]
 92  
 93  Bold              **words**
 94  Italic            //words//
 95  Underline         __words__
 96  Strike            --words--
 97  Monospaced        ``words``
 98  Raw               ""words""
 99  Tagged            ''words''
100  
101  Paragraph         words
102  Quote             &lt;TAB&gt;words
103  List              - words
104  Numbered list     + words
105  Definition list   : words
106  Table             | cell1 | cell2 | cell3...
107  
108  Verbatim line     ``` words
109  Raw line          """ words
110  Tagged line       ''' words
111  
112  Verbatim block    ```
113                    lines
114                    ```
115  Raw block         """
116                    lines
117                    """
118  Tagged block      '''
119                    lines
120                    '''
121</PRE>
122
123<H1 ID="options">OPTIONS</H1>
124
125<DL>
126<DT>    <B>--art-chars</B>=<I>PATTERN</I></DT><DD>
127Define <I>PATTERN</I> as the pattern of characters used to compose the ASCII Art decorations, in the following order: corner, border, side, bar1, bar2, level2, level3, level4, level5. The default pattern value is +-|-==-^". This option is only used by the ASCII Art target.
128<P></P>
129<DT><B>-C</B>, <B>--config-file</B>=<I>FILE</I></DT><DD>
130Read configuration from the external file <I>FILE</I>. The configuration must be on the <I>%!keyword:value</I> format. See <A HREF="#settings">SETTINGS</A> section for details.
131<P></P>
132<DT>    <B>--css-sugar</B></DT><DD>
133Improves the generated HTML/XHTML code to be used with CSS files. Tag attributes are removed, presentation tags are avoided, header is composed by H1, H2 and H3 tags, new DIVs are created: <I>#header</I>, <I>#body</I>, <I>.toc</I>.
134<P></P>
135<DT>    <B>--css-inside</B></DT><DD>
136Insert CSS file contents inside HTML/XHTML headers. Use <CODE>--style</CODE> to specify a CSS file to be read.
137<P></P>
138<DT>    <B>--dump-config</B></DT><DD>
139Print all the configuration found and exit.
140<P></P>
141<DT>    <B>--dump-source</B></DT><DD>
142Print the document source, with includes (<CODE>%!include</CODE>) expanded.
143<P></P>
144<DT>    <B>--encoding</B>=<I>CODE</I></DT><DD>
145Inform the character set (file encoding) used by the source document. Examples are UTF-8 and iso-8859-1. The encoding is not changed during conversion, so the output document will have the same encoding as the sources.
146<P></P>
147<DT>    <B>--gui</B></DT><DD>
148Invoke Graphical Tk Interface.
149<P></P>
150<DT><B>-h</B>, <B>--help</B></DT><DD>
151Print help information and exit.
152<P></P>
153<DT><B>-H</B>, <B>--no-headers</B></DT><DD>
154Suppress header and footer from the output. Only the contents (body) will be shown.
155<P></P>
156<DT>    <B>--headers</B></DT><DD>
157Show header and footer in the output. Default is ON.
158<P></P>
159<DT>    <B>--height</B>=<I>NUM</I></DT><DD>
160Set the output's height to <I>NUM</I> rows. This option is only used by the ASCII Art target, when also using <CODE>--slides</CODE>.
161<P></P>
162<DT><B>-i</B>, <B>--infile</B>=<I>FILE</I></DT><DD>
163Set <I>FILE</I> as the input file name, the source document. Use '-' to read the sources from the STDIN.
164<P></P>
165<DT>    <B>--mask-email</B></DT><DD>
166Hide emails from spam robots. Removes @ and dots. The address foo@bar.com turns to &lt;foo (a) bar com&gt;.
167<P></P>
168<DT><B>-n</B>, <B>--enum-title</B></DT><DD>
169Turn on automatic numbering for titles. They will be prefixed by 1, 1.1, 1.1.1, ...
170<P></P>
171<DT>    <B>--no-dump-config</B></DT><DD>
172Cancel the <CODE>--dump-config</CODE> action.
173<P></P>
174<DT>    <B>--no-dump-source</B></DT><DD>
175Cancel the <CODE>--dump-source</CODE> action.
176<P></P>
177<DT>    <B>--no-encoding</B></DT><DD>
178Clear the encoding setting.
179<P></P>
180<DT>    <B>--no-enum-title</B></DT><DD>
181Turn off the automatic numbering for titles.
182<P></P>
183<DT>    <B>--no-infile</B></DT><DD>
184Clear all the previous infile declarations.
185<P></P>
186<DT>    <B>--no-targets</B></DT><DD>
187Cancel the <CODE>--targets</CODE> action.
188<P></P>
189<DT>    <B>--no-mask-email</B></DT><DD>
190Turn off the email masking feature.
191<P></P>
192<DT>    <B>--no-outfile</B></DT><DD>
193Clear the previous outfile declaration.
194<P></P>
195<DT>    <B>--no-quiet</B></DT><DD>
196Show messages, turning off the <CODE>--quiet</CODE> option.
197<P></P>
198<DT>    <B>--no-rc</B></DT><DD>
199Do not read the user configuration file ~/.txt2tagsrc.
200<P></P>
201<DT>    <B>--no-slides</B></DT><DD>
202Turn off the slides feature.
203<P></P>
204<DT>    <B>--no-style</B></DT><DD>
205Clear all the style settings.
206<P></P>
207<DT>    <B>--no-toc</B></DT><DD>
208Remove the Table of Contents from the output.
209<P></P>
210<DT>    <B>--no-toc-only</B></DT><DD>
211Turn off the <CODE>--toc-only</CODE> action.
212<P></P>
213<DT><B>-o</B>, <B>--outfile</B>=<I>FILE</I></DT><DD>
214Set <I>FILE</I> as the output file name. Use '-' to send the results to STDOUT.
215<P></P>
216<DT><B>-q</B>, <B>--quiet</B></DT><DD>
217Quiet mode. Suppress all output, except errors.
218<P></P>
219<DT>    <B>--rc</B></DT><DD>
220Read the user configuration file ~/.txt2tagsrc. Default is ON.
221<P></P>
222<DT>    <B>--slides</B></DT><DD>
223Format output as presentation slides. This option is only used by the ASCII Art target.
224<P></P>
225<DT>    <B>--style</B>=<I>FILE</I></DT><DD>
226Use <I>FILE</I> as the document's style file. Used to define CSS files for HTML/XHTML documents and packages for LaTeX. This option can be used multiple times to include multiple files.
227<P></P>
228<DT><B>-t</B>, <B>--target</B>=<I>TYPE</I></DT><DD>
229Set the output document format to <I>TYPE</I>. Some popular types are: <I>html</I>, <I>xhtml</I>, <I>tex</I>, <I>man</I>, <I>txt</I>. Use the <CODE>--targets</CODE> option to see all the available formats.
230<P></P>
231<DT>    <B>--targets</B></DT><DD>
232Print a list of all the available targets and exit.
233<P></P>
234<DT>    <B>--toc</B></DT><DD>
235Include an automatic Table of Contents (TOC) to the output, between the Header and the Body. You can also specify the TOC position using the <CODE>%%TOC</CODE> macro.
236<P></P>
237<DT>    <B>--toc-level</B>=<I>NUM</I></DT><DD>
238Set the maximum TOC level to <I>NUM</I>. All titles deeper than <I>NUM</I> will not be included in the Table of Contents.
239<P></P>
240<DT>    <B>--toc-only</B></DT><DD>
241Print the Table of Contents and exit.
242<P></P>
243<DT><B>-v</B>, <B>--verbose</B></DT><DD>
244Print informative messages during conversion. This option can be used multiple times to increase the number of messages shown.
245<P></P>
246<DT><B>-V</B>, <B>--version</B></DT><DD>
247Print program version and exit.
248<P></P>
249<DT>    <B>--width</B>=<I>NUM</I></DT><DD>
250Set the output's width to <I>NUM</I> columns. This option is only used by the ASCII Art target.
251</DL>
252
253<H1 ID="source">SOURCE FILES</H1>
254
255<P>
256The source files are usually identified by the <I>.t2t</I> extension (such as <CODE>myfile.t2t</CODE>). You may have three areas inside your sources:
257</P>
258
259<DL>
260<DT><B>Header</B> (optional)</DT><DD>
261The first three lines of the file. Leave the first line blank if you don't need headers. Used for document title, author, version and date information.
262<P></P>
263<DT><B>Settings</B> (optional)</DT><DD>
264Begins right after the Header (4th or 2nd line) and ends when the Body area starts.
265Used for settings (configurations) in the <CODE>%!keyword:value</CODE> format.
266<P></P>
267<DT><B>Body</B></DT><DD>
268Begins at the first valid text line (not comment or setting) after the Header area and goes until the end of the document. Used for the document contents.
269</DL>
270
271<H1 ID="settings">SETTINGS</H1>
272
273<P>
274Settings let you customize <B>txt2tags</B>, they're similar to options. They can be used at: source document's Settings area, <CODE>~/.txt2tagsrc</CODE> file, external file called with <CODE>--config-file</CODE>.
275</P>
276
277<DL>
278<DT><B>%!target</B></DT><DD>
279Set the output format, just like <CODE>--target</CODE>. Example:
280
281<PRE>
282  %!target: html
283</PRE>
284
285<P></P>
286<DT><B>%!options(target)</B></DT><DD>
287Set the default options to each target. You must use the command line options. Example:
288
289<PRE>
290  %!options(html): --toc --toc-level 3 --css-sugar
291</PRE>
292
293<P></P>
294<DT><B>%!includeconf</B></DT><DD>
295Include configurations from an external file into the current, just like <CODE>--config-file</CODE>. Example:
296
297<PRE>
298  %!includeconf: myconfig.t2t
299</PRE>
300
301<P></P>
302<DT><B>%!style</B></DT><DD>
303Set a style file for the document, just like <CODE>--style</CODE>. Can be used multiple times. Example:
304
305<PRE>
306  %!style: colors.css
307</PRE>
308
309<P></P>
310<DT><B>%!encoding</B></DT><DD>
311Set the character set used by the document, just like <CODE>--encoding</CODE>. Example:
312
313<PRE>
314  %!encoding: UTF-8
315</PRE>
316
317<P></P>
318<DT><B>%!preproc</B></DT><DD>
319Input search/replace filter used to change the Body of the source document BEFORE any parsing by txt2tags. Search uses Python regular expressions. Example:
320
321<PRE>
322  %!preproc:  "JJS"  "John J. Smith"
323</PRE>
324
325<P></P>
326<DT><B>%!postproc</B></DT><DD>
327Output search/replace filter used to change the generated document AFTER all the txt2tags processing. Search uses Python regular expressions. Example:
328
329<PRE>
330  %!postproc(html):  "&lt;B&gt;"  "&lt;STRONG&gt;"
331</PRE>
332
333</DL>
334
335<P>
336If the same keyword appears more than once, the last found will be the one used (except: options, preproc and postproc, which are cumulative). Invalid keywords are ignored. The parsing order is: <CODE>~/.txt2tagsrc</CODE>, source document's Config area, <CODE>--config-file</CODE> option.
337</P>
338
339<H1 ID="commands">COMMANDS</H1>
340
341<P>
342Commands perform tasks during conversion time. They must be placed at the source document's Body.
343</P>
344
345<DL>
346<DT><B>%!csv: file.csv</B></DT><DD>
347Includes an external CSV file as a table.
348<P></P>
349<DT><B>%!include: file.t2t</B></DT><DD>
350Includes a txt2tags file in the document.
351<P></P>
352<DT><B>%!include: ``file.txt``</B></DT><DD>
353Includes a text file (verbatim) in the document.
354<P></P>
355<DT><B>%!include: ''file.html''</B></DT><DD>
356Includes an already tagged file in the document.
357</DL>
358
359<H1 ID="macros">MACROS</H1>
360
361<P>
362Macros are handy shortcuts to insert dynamic contents in your document. They must be placed at the source document's Body. Except <CODE>%%toc</CODE>, all macros can be customized with special directives, like <CODE>%Y</CODE> and <CODE>%f</CODE>. See the txt2tags User Guide for details.
363</P>
364
365<DL>
366<DT><B>%%date</B></DT><DD>
367Insert the current date. The default format is <CODE>%%date(%Y%m%d)</CODE>, which gives YYYYMMDD.
368<P></P>
369<DT><B>%%infile</B></DT><DD>
370Insert the source file path. The default format is <CODE>%%infile(%f)</CODE>. Useful for footer links like <CODE>[See source %%infile]</CODE>.
371<P></P>
372<DT><B>%%mtime</B></DT><DD>
373Insert the source file modification time. The default format is <CODE>%%date(%Y%m%d)</CODE>, which gives YYYYMMDD.
374<P></P>
375<DT><B>%%outfile</B></DT><DD>
376Insert the output file path. The default format is <CODE>%%outfile(%f)</CODE>. Useful for self mentioning like "This is the manpage.html file".
377<P></P>
378<DT><B>%%toc</B></DT><DD>
379Specifies where the Table of Contents will be placed. You can even use it multiple times. Note that you must also use the <CODE>--toc</CODE> option.
380</DL>
381
382<H1 ID="examples">EXAMPLES</H1>
383
384<DL>
385<DT><CODE>txt2tags -t html file.t2t</CODE></DT><DD>
386<P></P>
387Convert to HTML, saving to file.html.
388<P></P>
389<DT><CODE>txt2tags -t html -o - file.t2t</CODE></DT><DD>
390<P></P>
391Convert to HTML, sending results to STDOUT.
392<P></P>
393<DT><CODE>txt2tags -t html --toc file.t2t</CODE></DT><DD>
394<P></P>
395Convert to HTML, including automatic Table Of Contents.
396<P></P>
397<DT><CODE>txt2tags -t html --toc --toc-level 2 -n file.t2t</CODE></DT><DD>
398<P></P>
399Convert to HTML, with a two level Table of Contents and numbered titles.
400<P></P>
401<DT><CODE>txt2tags --toc-only file.t2t</CODE></DT><DD>
402<P></P>
403Just show the Table of Contents, no conversion is done.
404<P></P>
405<DT><CODE>txt2tags -t html --css-sugar --style base.css --style ui.css file.t2t</CODE></DT><DD>
406<P></P>
407Convert to HTML, preparing the resulting code to be used with CSS, and also include calls to two external CSS files.
408<P></P>
409<DT><CODE>txt2tags -t art --slides --width 80 --height 25 -o - file.t2t | more</CODE></DT><DD>
410<P></P>
411Create ASCII Art presentation slides, ready to be shown in a 80x25 terminal screen/window.
412<P></P>
413<DT><CODE>(echo ; echo "**bold**") | txt2tags -t html -H -</CODE></DT><DD>
414<P></P>
415Handy one-liner for quick tests using STDIN.
416<P></P>
417<DT><CODE>txt2tags -t html -o - file.t2t | tidy &gt; file.html</CODE></DT><DD>
418<P></P>
419Send results to STDOUT, then fine tune the code with an external program before saving the output file.
420</DL>
421
422<H1 ID="files">FILES</H1>
423
424<DL>
425<DT>~/.txt2tagsrc</DT><DD>
426Default user configuration file.
427</DL>
428
429<H1 ID="environment">ENVIRONMENT</H1>
430
431<DL>
432<DT>T2TCONFIG</DT><DD>
433If non-null, sets the full pathname for the default user configuration file.
434</DL>
435
436<H1 ID="author">AUTHOR</H1>
437
438<P>
439Aurelio Jargas &lt;&lt;verde (a) aurelio net&gt;&gt;
440</P>
441
442<H1 ID="bugs">BUGS</H1>
443
444<P>
445<A HREF="http://bugs.txt2tags.org">http://bugs.txt2tags.org</A>
446</P>
447
448<H1 ID="copyright">COPYRIGHT</H1>
449
450<P>
451Copyright (C) 2001-2010 Aurelio Jargas, GNU GPL v2
452</P>
453
454<!-- html code generated by txt2tags 2.6.492 (http://txt2tags.org) -->
455<!-- cmdline: txt2tags -t html doc/English/manpage.t2t -->
456</BODY></HTML>