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