/doc/English/manpage.html
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 <TAB>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 <foo (a) bar com>. 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): "<B>" "<STRONG>" 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 > 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 <<verde (a) aurelio net>> 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>