PageRenderTime 8ms CodeModel.GetById 1ms app.highlight 3ms RepoModel.GetById 1ms app.codeStats 0ms

/doc/English/manpage.t2t

http://txt2tags.googlecode.com/
Unknown | 409 lines | 276 code | 133 blank | 0 comment | 0 complexity | fd3f61cecc18fe517d67d54581b7b927 MD5 | raw file
  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