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