PageRenderTime 70ms CodeModel.GetById 22ms RepoModel.GetById 0ms app.codeStats 0ms

/doc/English/userguide/userguide.html

http://txt2tags.googlecode.com/
HTML | 3589 lines | 3457 code | 131 blank | 1 comment | 0 complexity | c0fe9b895ad72f0cb4c9dc464dd836c9 MD5 | raw file
Possible License(s): GPL-2.0, GPL-3.0, WTFPL
  1. <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
  2. <!-- This document was generated from userguide.t2t -->
  3. <HTML>
  4. <HEAD>
  5. <META NAME="generator" CONTENT="http://txt2tags.org">
  6. <LINK REL="stylesheet" TYPE="text/css" HREF="userguide.css">
  7. <TITLE>Txt2tags User Guide</TITLE>
  8. </HEAD>
  9. <BODY>
  10. <DIV CLASS="header" ID="header">
  11. </DIV>
  12. <DIV CLASS="body" ID="body">
  13. <H1>About</H1>
  14. <P>
  15. This is the <A HREF="http://txt2tags.org">txt2tags</A> User Guide, the
  16. complete manual about the program.
  17. </P>
  18. <UL>
  19. <LI>User Guide official address:
  20. <A HREF="http://txt2tags.org/userguide">http://txt2tags.org/userguide</A>
  21. <P></P>
  22. <LI>User Guide PDF download:
  23. <A HREF="http://txt2tags.org/userguide/userguide.pdf">http://txt2tags.org/userguide/userguide.pdf</A>
  24. </UL>
  25. <A NAME="intro"></A>
  26. <H1>Part I - Introducing Txt2tags</H1>
  27. <A NAME="1st-questions"></A>
  28. <H2>The First Questions You May Have</H2>
  29. <P>
  30. This chapter is a txt2tags overview, that will introduce the program
  31. purpose and features.
  32. </P>
  33. <H3>What is it?</H3>
  34. <P>
  35. Txt2tags is a text formatting and conversion tool.
  36. </P>
  37. <DL>
  38. <DT><B>A text formatting tool</B>: The txt2tags wiki-like syntax is easy to use and to remember. You can use it for every purpose, like storing your notes and formatting your documents.</DT><DD>
  39. <P></P>
  40. <DT><B>A conversion tool</B>: You can use the txt2tags python program to converts your txt2tags documents to several supported <A HREF="#targets">targets</A>. <I>(Further reference to the txt2tags python program will simply be labelled "txt2tags".)</I></DT><DD>
  41. <P></P>
  42. Amongs others, there are:
  43. <P></P>
  44. </DL>
  45. <UL>
  46. <LI>popular Wiki markups, such as bbcode, wikipedia pages, markdown, restructuredtext and spip.
  47. <P></P>
  48. <LI>html variations: html transitional, xhtml, html5...
  49. <P></P>
  50. <LI>office documents: RTF, LaTeX documents, Open Document Spreadsheet, SQLite database (imported from tables)
  51. <P></P>
  52. <LI>plain text, including ASCII art variations.
  53. </UL>
  54. <P>
  55. <I>See the <A HREF="#targets">targets chapter</A> to discover the full list.</I>
  56. </P>
  57. <DL>
  58. <DT><B>And more</B>: Beyond those 2 aspects, which deals with defined features and syntax, txt2tags can also manipulate your document with <A HREF="#setting-preproc">powerful input and output filters</A>.</DT><DD>
  59. </DL>
  60. <H3>Why should I use it?</H3>
  61. <P>
  62. You'll find txt2tags really useful if you:
  63. </P>
  64. <UL>
  65. <LI>Need to publish documents in different formats
  66. <LI>Need to maintain updated documents in different formats
  67. <LI>Write technical documents or guides
  68. <LI>Don't know how to write a document in a specific format
  69. <LI>Don't have an editor for a specific format
  70. <LI>Want to use a simple text editor to update your documents
  71. </UL>
  72. <P>
  73. And the main motivation is:
  74. </P>
  75. <UL>
  76. <LI>Save time, writing <B>contents</B> and forgetting about <B>formatting</B>
  77. </UL>
  78. <H3>Why is it a good choice among other tools?</H3>
  79. <P>
  80. Txt2tags has a very straight way of growing, following basic concepts.
  81. These are the highlights:
  82. </P>
  83. <TABLE>
  84. <TR>
  85. <TD><I>Source File Readable</I></TD>
  86. <TD>Txt2tags marks are very simple, almost natural.</TD>
  87. </TR>
  88. <TR>
  89. <TD><I>Target Document Readable</I></TD>
  90. <TD>The target document is also readable, with indentation and spacing.</TD>
  91. </TR>
  92. <TR>
  93. <TD><I>Consistent Marks</I></TD>
  94. <TD>Txt2tags marks are simple symbols, designed to be unique enough to don't mix up with the document contents.</TD>
  95. </TR>
  96. <TR>
  97. <TD><I>Consistent Rules</I></TD>
  98. <TD>As the marks, the rules that applies to them are tied to each other, there are no "exceptions" or "special cases".</TD>
  99. </TR>
  100. <TR>
  101. <TD><I>Simple Structures</I></TD>
  102. <TD>All the supported formatting are <B>simple</B>, with no extra-options or complicated behavior modifiers. A mark is just a mark, with no options at all.</TD>
  103. </TR>
  104. <TR>
  105. <TD><I>Easy to Learn</I></TD>
  106. <TD>With simple marks and readable source, the txt2tags learning curve is user friendly.</TD>
  107. </TR>
  108. <TR>
  109. <TD><I>Nice Examples</I></TD>
  110. <TD>The <B>sample files</B> included on the package gives real life examples of documents written for txt2tags.</TD>
  111. </TR>
  112. <TR>
  113. <TD><I>Valuable Tools</I></TD>
  114. <TD>The <B>syntax files</B> included on the package help you to write documents with no syntax errors.</TD>
  115. </TR>
  116. <TR>
  117. <TD><I>Three User Interfaces</I></TD>
  118. <TD>There is a user friendly <B>Graphical interface</B>, a handy <B>Web interface</B> easy to install in intranets and a <B>Command Line interface</B> for power-users and scripting.</TD>
  119. </TR>
  120. <TR>
  121. <TD><I>Scripting</I></TD>
  122. <TD>With the full featured command line mode, an experienced user can <B>automatize</B> tasks and do <B>post-editing</B> on the converted files.</TD>
  123. </TR>
  124. <TR>
  125. <TD><I>Download and Run / Multi-platform</I></TD>
  126. <TD>Txt2tags is a single <B>Python script</B>. There is no need to compile it or download extra modules. So it runs nicely on *NIX, Linux, Windows and Macs.</TD>
  127. </TR>
  128. <TR>
  129. <TD><I>Mature</I></TD>
  130. <TD>First released in 2001, txt2tags is now a mature program with years of improvements and bug fixes, extensive documentation, translations and an loyal user base.</TD>
  131. </TR>
  132. </TABLE>
  133. <H3>Do I have to pay for it?</H3>
  134. <P>
  135. Absolutely NO!
  136. </P>
  137. <P>
  138. It's free, GPL licensed.
  139. </P>
  140. <A NAME="structures"></A>
  141. <H2>Supported Formatting Structures</H2>
  142. <P>
  143. The following is a list of all the structures supported by txt2tags.
  144. </P>
  145. <UL>
  146. <LI>header (document title, author name, date)
  147. <LI>section title (numbered or not)
  148. <LI>paragraphs
  149. <LI>font beautifiers
  150. <UL>
  151. <LI>bold
  152. <LI>italic
  153. <LI>underline
  154. <LI>strike
  155. </UL>
  156. <LI>monospaced font (verbatim)
  157. <UL>
  158. <LI>monospaced inside paragraph
  159. <LI>monospaced line
  160. <LI>monospaced area (multiline)
  161. </UL>
  162. <LI>quoted area
  163. <LI>link
  164. <UL>
  165. <LI>URL/Internet links
  166. <LI>e-mail links
  167. <LI>local links
  168. <LI>named links
  169. </UL>
  170. <LI>lists
  171. <UL>
  172. <LI>bulleted list
  173. <LI>numbered list
  174. <LI>definition list
  175. </UL>
  176. <LI>horizontal separator line
  177. <LI>image (with smart alignment)
  178. <LI>table (with or without border, smart alignment, column span)
  179. <LI>macros (with flexible formatting):
  180. <UL>
  181. <LI>current date
  182. <LI>file modification time
  183. <LI>input and output file name and path
  184. <LI>automatic table of contents
  185. </UL>
  186. <LI>special mark for raw text (no marks parsed inside)
  187. <LI>special mark for tagged text (no parsing, sent directly to output)
  188. <LI>comments (for self notes, TODO, FIXME)
  189. </UL>
  190. <A NAME="targets"></A>
  191. <H2>Supported Targets</H2>
  192. <H3>Wiki</H3>
  193. <DL>
  194. <DT><B>adoc</B></DT><DD>
  195. AsciiDoc document
  196. <P></P>
  197. <DT><B>bbcode</B></DT><DD>
  198. BBCode document
  199. <P></P>
  200. <DT><B>creole</B></DT><DD>
  201. Creole 1.0 document
  202. <P></P>
  203. <DT><B>DOKU</B></DT><DD>
  204. <A HREF="http://www.dokuwiki.org/dokuwiki">DokuWiki</A> is a standards
  205. compliant, simple to use Wiki, mainly aimed at creating documentation
  206. of any kind. It is targeted at developer teams, workgroups and small
  207. companies. It has a simple but powerful syntax which makes sure the
  208. data files remain readable outside the Wiki and eases the creation of
  209. structured texts. All data is stored in plain text files - no
  210. database is required.
  211. </DL>
  212. <DL>
  213. <DT><B>Foswiki / TWiki</B></DT><DD>
  214. <A HREF="http://foswiki.org/">Foswiki</A> or <A HREF="http://twiki.org">TWiki</A>, is a flexible, powerful,
  215. and easy to use enterprise wiki and collaboration platform.
  216. The structured wiki is typically used to run a project development
  217. space, a document management system, a knowledge base, or any other
  218. groupware tool, on an intranet or on the internet.
  219. <P></P>
  220. <DT><B>GWIKI</B></DT><DD>
  221. Now you can easily paste your project's current documentation into the
  222. <A HREF="http://code.google.com/">Google Code</A> Wiki.
  223. <P></P>
  224. <DT><B>md</B></DT><DD>
  225. Markdown document
  226. <P></P>
  227. <DT><B>MOIN</B></DT><DD>
  228. You don't know what <A HREF="http://moinmo.in/">MoinMoin</A> is?
  229. It is a <A HREF="http://www.c2.com/cgi/wiki">WikiWiki</A>!
  230. <P></P>
  231. Moin syntax is kinda boring when you need to keep
  232. <CODE>{{{'''''adding braces and quotes'''''}}}</CODE>, so txt2tags comes with the
  233. simplified marks and unified solution: one source, multi targets.
  234. <P></P>
  235. <DT><B><A HREF="http://en.wikipedia.org/wiki/PmWiki">PMWIKI</A></B></DT><DD>
  236. <A HREF="http://www.pmwiki.org/">PmWiki</A> is a light and free wiki software written in PHP, and using no SQL database.
  237. <P></P>
  238. <DT><B>red</B> </DT><DD>
  239. Redmine Wiki page
  240. <P></P>
  241. <DT><B>rst</B></DT><DD>
  242. ReStructuredText document
  243. <P></P>
  244. <DT><B>spip</B></DT><DD>
  245. SPIP article
  246. <P></P>
  247. <DT><B>txt2t</B></DT><DD>
  248. Txt2tags document
  249. <P></P>
  250. <DT><B>WIKI</B></DT><DD>
  251. You've heard about the <A HREF="http://wikipedia.org">Wikipedia</A>, right? So you
  252. don't need to learn yet-another markup syntax. Just stick with txt2tags
  253. and let it convert your text to the Wikipedia format, called
  254. <A HREF="http://en.wikipedia.org/wiki/MediaWiki">MediaWiki</A>.
  255. </DL>
  256. <H3>HTML</H3>
  257. <DL>
  258. <DT><B>aapw</B></DT><DD>
  259. ASCII Art Presentation Web
  260. <P></P>
  261. <DT><B>aasw</B></DT><DD>
  262. ASCII Art Spreadsheet Web
  263. <P></P>
  264. <DT><B>aatw</B></DT><DD>
  265. ASCII Art Text Web
  266. <P></P>
  267. <DT><B><A HREF="http://en.wikipedia.org/wiki/HTML">HTML</A></B></DT><DD>
  268. You maybe know what HTML is. (hint: Internet)
  269. <P></P>
  270. Txt2tags generates clean HTML documents, that look pretty and have
  271. its source readable. It DOES NOT use javascript, frames or other
  272. futile formatting techniques, that aren't required for simple, techie
  273. documents. But a separate CSS file can be used if wanted. Txt2tags
  274. generates "<I>HTML 4.0 Transitional</I>" code.
  275. <P></P>
  276. Txt2tags HTML generated code is 100% approved by the <A HREF="http://validator.w3.org/">w3c validator</A>.
  277. <P></P>
  278. <DT><B>html5</B></DT><DD>
  279. HTML5 page
  280. <P></P>
  281. <DT><B>htmls</B></DT><DD>
  282. HTML Spreadsheet
  283. <P></P>
  284. <DT><B>wp</B></DT><DD>
  285. WordPress post
  286. <P></P>
  287. <DT><B><A HREF="http://en.wikipedia.org/wiki/XHTML">XHTML</A></B></DT><DD>
  288. It is the new generation of HTML, with more strict rules.
  289. This makes the code easier to parse and
  290. understand. For the general purpose, consider it HTML. Txt2tags
  291. generates "<I>XHTML 1.0 Transitional</I>" code.
  292. <P></P>
  293. Txt2tags XHTML generated code is 100% approved by the <A HREF="http://validator.w3.org/">w3c validator</A>.
  294. <P></P>
  295. <DT><B>xhtmls</B></DT><DD>
  296. XHTML Strict page
  297. </DL>
  298. <H3>Office</H3>
  299. <DL>
  300. <DT><B>csv</B></DT><DD>
  301. CSV spreadsheet
  302. <P></P>
  303. <DT><B>db</B></DT><DD>
  304. SQLite database
  305. <P></P>
  306. <DT><B>dbk</B></DT><DD>
  307. DocBook document
  308. <P></P>
  309. <DT><B>LOUT</B></DT><DD>
  310. Very similar to LaTeX in power, but with an easier syntax using "@"
  311. instead "\" and avoiding the need of braces in common situations. Its
  312. approach of everything-is-an-object makes the tagging much saner.
  313. <P></P>
  314. Txt2tags generates ready-to-use Lout files, which can be converted do
  315. PS or PDF files using the "lout" command.
  316. <P></P>
  317. <DT><B>MGP</B></DT><DD>
  318. <A HREF="http://en.wikipedia.org/wiki/MagicPoint">MagicPoint</A> is a very handy presentation tool
  319. (hint: Microsoft PowerPoint), that uses a tagged language to define all
  320. the screens. So you can do complex presentations in vi/emacs/notepad.
  321. <P></P>
  322. Txt2tags generates a ready-to-use .mgp file, defining all the
  323. necessary headers for fonts and appearance definitions, as long as
  324. international characters support.
  325. <P></P>
  326. Txt2tags creates "diet" .mgp files: they use the Type1 fonts, so you do not
  327. need to carry TrueType fonts files with your presentation. Also, the color
  328. definitions are simple, so even on a poor color palette system (such as
  329. <CODE>startx -- -bpp 8</CODE>), the presentation will look pretty!
  330. <P></P>
  331. The key is: convert and use. No quick fixes or requirements needed.
  332. <P></P>
  333. <DT><B>ods</B></DT><DD>
  334. Open Document Spreadsheet
  335. <P></P>
  336. <DT><B>PM6</B></DT><DD>
  337. Adobe PageMaker 6.0 has its own tagged
  338. language. Styles, color table, beautifiers, and most of all the
  339. PageMaker mouse-clicking features are also available on its tagged language.
  340. You just need to access the "Import tagged text" menu item. Just for
  341. the records, it's an &lt;HTML "like"&gt; tag format.
  342. <P></P>
  343. Txt2tags generates all the tags and already defines a extensive and
  344. working header, setting paragraph styles and formatting. This is the
  345. hard part.
  346. <P></P>
  347. <B>Author's note:</B>
  348. My entire portuguese <A HREF="http://guia-er.sf.net">regular expression's book</A>
  349. was written in VI, then converted to PageMaker with txt2tags and went to
  350. the publisher. It works :)
  351. <P></P>
  352. <DT><B>rtf</B></DT><DD>
  353. RTF document
  354. <P></P>
  355. <DT><B><A HREF="http://en.wikipedia.org/wiki/SGML">SGML</A></B></DT><DD>
  356. It is a common document format which has powerful conversion applications
  357. (<A HREF="http://packages.debian.org/linuxdoc-tools">linuxdoc-tools</A>). From a
  358. single SGML file you can generate HTML, PDF, PostScript, Info, LaTeX, LyX, RTF
  359. and XML documents. The tools also does automatic TOC and break
  360. sections into subpages.
  361. <P></P>
  362. Txt2tags generates SGML files in the LinuxDoc system type, ready to
  363. be converted with linuxdoc-tools without any extra catalog files or any
  364. SGML annoying requirements.
  365. <P></P>
  366. <DT><B><A HREF="http://en.wikipedia.org/wiki/LaTeX">LATEX</A></B></DT><DD>
  367. The preferred academic document format, it is more powerful than you
  368. ever wondered. Full books, complicated formulas and any complex text
  369. can be written in LaTeX. But prepare to loose your hair when you try
  370. to write the tags by hand...
  371. <P></P>
  372. Txt2tags generates ready-to-use LaTeX files, doing all the complex
  373. escaping tricks and exceptions. The writer just need to worry about
  374. the text.
  375. <P></P>
  376. <DT><B>texs</B></DT><DD>
  377. LaTeX Spreadsheet
  378. </DL>
  379. <H3>Text</H3>
  380. <DL>
  381. <DT><B>aap</B></DT><DD>
  382. ASCII Art Presentation
  383. <P></P>
  384. <DT><B>aas</B></DT><DD>
  385. ASCII Art Spreadsheet
  386. <P></P>
  387. <DT><B>aat</B></DT><DD>
  388. ASCII Art Text
  389. <P></P>
  390. <DT><B>MAN</B></DT><DD>
  391. UNIX man pages resist over the years. Document formats come and go,
  392. and there they are, unbeatable.
  393. <P></P>
  394. There are other tools to generate man documents, but txt2tags has
  395. one advantage: one source, multi targets. So the same man page
  396. contents can be converted to an HTML page, Wiki document and plain text.
  397. <P></P>
  398. <DT><B>TXT</B></DT><DD>
  399. TXT is text. Simple, pure, beautiful.
  400. <P></P>
  401. Although txt2tags marks are very intuitive and discrete, you can remove
  402. them by converting the file to pure TXT.
  403. <P></P>
  404. The titles are underlined, and the text is basically left as is on the
  405. source.
  406. </DL>
  407. <P>
  408. Tip: Use the <CODE>--targets</CODE> command line option to get a complete list of
  409. all the available targets.
  410. </P>
  411. <A NAME="struct-support"></A>
  412. <H2>Status of Supported Structures by Target</H2>
  413. <TABLE ALIGN="center" BORDER="1">
  414. <TR>
  415. <TH>Structure</TH>
  416. <TH>html</TH>
  417. <TH>xhtml</TH>
  418. <TH>sgml</TH>
  419. <TH>dbk</TH>
  420. <TH>tex</TH>
  421. <TH>lout</TH>
  422. <TH>man</TH>
  423. <TH>mgp</TH>
  424. <TH>creole</TH>
  425. <TH>wiki</TH>
  426. <TH>gwiki</TH>
  427. <TH>pmw</TH>
  428. <TH>doku</TH>
  429. <TH>moin</TH>
  430. <TH>pm6</TH>
  431. <TH>adoc</TH>
  432. <TH>art</TH>
  433. <TH>txt</TH>
  434. <TH>tml</TH>
  435. </TR>
  436. <TR>
  437. <TD>headers</TD>
  438. <TD ALIGN="center">Y</TD>
  439. <TD ALIGN="center">Y</TD>
  440. <TD ALIGN="center">Y</TD>
  441. <TD ALIGN="center">Y</TD>
  442. <TD ALIGN="center">Y</TD>
  443. <TD ALIGN="center">Y</TD>
  444. <TD ALIGN="center">Y</TD>
  445. <TD ALIGN="center">Y</TD>
  446. <TD ALIGN="center">-</TD>
  447. <TD ALIGN="center">-</TD>
  448. <TD ALIGN="center">-</TD>
  449. <TD ALIGN="center">Y</TD>
  450. <TD ALIGN="center">-</TD>
  451. <TD ALIGN="center">-</TD>
  452. <TD ALIGN="center">N</TD>
  453. <TD ALIGN="center">-</TD>
  454. <TD ALIGN="center">Y</TD>
  455. <TD ALIGN="center">Y</TD>
  456. <TD ALIGN="center">Y</TD>
  457. </TR>
  458. <TR>
  459. <TD>section title</TD>
  460. <TD ALIGN="center">Y</TD>
  461. <TD ALIGN="center">Y</TD>
  462. <TD ALIGN="center">Y</TD>
  463. <TD ALIGN="center">Y</TD>
  464. <TD ALIGN="center">Y</TD>
  465. <TD ALIGN="center">Y</TD>
  466. <TD ALIGN="center">Y</TD>
  467. <TD ALIGN="center">Y</TD>
  468. <TD ALIGN="center">Y</TD>
  469. <TD ALIGN="center">Y</TD>
  470. <TD ALIGN="center">Y</TD>
  471. <TD ALIGN="center">Y</TD>
  472. <TD ALIGN="center">Y</TD>
  473. <TD ALIGN="center">Y</TD>
  474. <TD ALIGN="center">Y</TD>
  475. <TD ALIGN="center">Y</TD>
  476. <TD ALIGN="center">Y</TD>
  477. <TD ALIGN="center">Y</TD>
  478. <TD ALIGN="center">Y</TD>
  479. </TR>
  480. <TR>
  481. <TD>paragraphs</TD>
  482. <TD ALIGN="center">Y</TD>
  483. <TD ALIGN="center">Y</TD>
  484. <TD ALIGN="center">Y</TD>
  485. <TD ALIGN="center">Y</TD>
  486. <TD ALIGN="center">Y</TD>
  487. <TD ALIGN="center">Y</TD>
  488. <TD ALIGN="center">Y</TD>
  489. <TD ALIGN="center">Y</TD>
  490. <TD ALIGN="center">Y</TD>
  491. <TD ALIGN="center">Y</TD>
  492. <TD ALIGN="center">Y</TD>
  493. <TD ALIGN="center">Y</TD>
  494. <TD ALIGN="center">Y</TD>
  495. <TD ALIGN="center">Y</TD>
  496. <TD ALIGN="center">Y</TD>
  497. <TD ALIGN="center">Y</TD>
  498. <TD ALIGN="center">Y</TD>
  499. <TD ALIGN="center">Y</TD>
  500. <TD ALIGN="center">Y</TD>
  501. </TR>
  502. <TR>
  503. <TD>bold</TD>
  504. <TD ALIGN="center">Y</TD>
  505. <TD ALIGN="center">Y</TD>
  506. <TD ALIGN="center">Y</TD>
  507. <TD ALIGN="center">Y</TD>
  508. <TD ALIGN="center">Y</TD>
  509. <TD ALIGN="center">Y</TD>
  510. <TD ALIGN="center">Y</TD>
  511. <TD ALIGN="center">Y</TD>
  512. <TD ALIGN="center">Y</TD>
  513. <TD ALIGN="center">Y</TD>
  514. <TD ALIGN="center">Y</TD>
  515. <TD ALIGN="center">Y</TD>
  516. <TD ALIGN="center">Y</TD>
  517. <TD ALIGN="center">Y</TD>
  518. <TD ALIGN="center">Y</TD>
  519. <TD ALIGN="center">Y</TD>
  520. <TD ALIGN="center">-</TD>
  521. <TD ALIGN="center">-</TD>
  522. <TD ALIGN="center">Y</TD>
  523. </TR>
  524. <TR>
  525. <TD>italic</TD>
  526. <TD ALIGN="center">Y</TD>
  527. <TD ALIGN="center">Y</TD>
  528. <TD ALIGN="center">Y</TD>
  529. <TD ALIGN="center">Y</TD>
  530. <TD ALIGN="center">Y</TD>
  531. <TD ALIGN="center">Y</TD>
  532. <TD ALIGN="center">Y</TD>
  533. <TD ALIGN="center">Y</TD>
  534. <TD ALIGN="center">Y</TD>
  535. <TD ALIGN="center">Y</TD>
  536. <TD ALIGN="center">Y</TD>
  537. <TD ALIGN="center">Y</TD>
  538. <TD ALIGN="center">Y</TD>
  539. <TD ALIGN="center">Y</TD>
  540. <TD ALIGN="center">Y</TD>
  541. <TD ALIGN="center">Y</TD>
  542. <TD ALIGN="center">-</TD>
  543. <TD ALIGN="center">-</TD>
  544. <TD ALIGN="center">Y</TD>
  545. </TR>
  546. <TR>
  547. <TD>underline</TD>
  548. <TD ALIGN="center">Y</TD>
  549. <TD ALIGN="center">Y</TD>
  550. <TD ALIGN="center">-</TD>
  551. <TD ALIGN="center">Y</TD>
  552. <TD ALIGN="center">Y</TD>
  553. <TD ALIGN="center">Y</TD>
  554. <TD ALIGN="center">-</TD>
  555. <TD ALIGN="center">Y</TD>
  556. <TD ALIGN="center">-</TD>
  557. <TD ALIGN="center">Y</TD>
  558. <TD ALIGN="center">-</TD>
  559. <TD ALIGN="center">Y</TD>
  560. <TD ALIGN="center">Y</TD>
  561. <TD ALIGN="center">Y</TD>
  562. <TD ALIGN="center">Y</TD>
  563. <TD ALIGN="center">N</TD>
  564. <TD ALIGN="center">-</TD>
  565. <TD ALIGN="center">-</TD>
  566. <TD ALIGN="center">Y</TD>
  567. </TR>
  568. <TR>
  569. <TD>strike</TD>
  570. <TD ALIGN="center">Y</TD>
  571. <TD ALIGN="center">Y</TD>
  572. <TD ALIGN="center">N</TD>
  573. <TD ALIGN="center">N</TD>
  574. <TD ALIGN="center">Y</TD>
  575. <TD ALIGN="center">-</TD>
  576. <TD ALIGN="center">-</TD>
  577. <TD ALIGN="center">-</TD>
  578. <TD ALIGN="center">-</TD>
  579. <TD ALIGN="center">Y</TD>
  580. <TD ALIGN="center">Y</TD>
  581. <TD ALIGN="center">Y</TD>
  582. <TD ALIGN="center">Y</TD>
  583. <TD ALIGN="center">Y</TD>
  584. <TD ALIGN="center">N</TD>
  585. <TD ALIGN="center">N</TD>
  586. <TD ALIGN="center">-</TD>
  587. <TD ALIGN="center">-</TD>
  588. <TD ALIGN="center">Y</TD>
  589. </TR>
  590. <TR>
  591. <TD>monospaced font</TD>
  592. <TD ALIGN="center">Y</TD>
  593. <TD ALIGN="center">Y</TD>
  594. <TD ALIGN="center">Y</TD>
  595. <TD ALIGN="center">Y</TD>
  596. <TD ALIGN="center">Y</TD>
  597. <TD ALIGN="center">Y</TD>
  598. <TD ALIGN="center">-</TD>
  599. <TD ALIGN="center">Y</TD>
  600. <TD ALIGN="center">-</TD>
  601. <TD ALIGN="center">Y</TD>
  602. <TD ALIGN="center">Y</TD>
  603. <TD ALIGN="center">Y</TD>
  604. <TD ALIGN="center">Y</TD>
  605. <TD ALIGN="center">Y</TD>
  606. <TD ALIGN="center">Y</TD>
  607. <TD ALIGN="center">Y</TD>
  608. <TD ALIGN="center">-</TD>
  609. <TD ALIGN="center">-</TD>
  610. <TD ALIGN="center">Y</TD>
  611. </TR>
  612. <TR>
  613. <TD>verbatim line</TD>
  614. <TD ALIGN="center">Y</TD>
  615. <TD ALIGN="center">Y</TD>
  616. <TD ALIGN="center">Y</TD>
  617. <TD ALIGN="center">Y</TD>
  618. <TD ALIGN="center">Y</TD>
  619. <TD ALIGN="center">Y</TD>
  620. <TD ALIGN="center">Y</TD>
  621. <TD ALIGN="center">Y</TD>
  622. <TD ALIGN="center">Y</TD>
  623. <TD ALIGN="center">Y</TD>
  624. <TD ALIGN="center">Y</TD>
  625. <TD ALIGN="center">Y</TD>
  626. <TD ALIGN="center">Y</TD>
  627. <TD ALIGN="center">Y</TD>
  628. <TD ALIGN="center">Y</TD>
  629. <TD ALIGN="center">Y</TD>
  630. <TD ALIGN="center">-</TD>
  631. <TD ALIGN="center">-</TD>
  632. <TD ALIGN="center">-</TD>
  633. </TR>
  634. <TR>
  635. <TD>verbatim area</TD>
  636. <TD ALIGN="center">Y</TD>
  637. <TD ALIGN="center">Y</TD>
  638. <TD ALIGN="center">Y</TD>
  639. <TD ALIGN="center">Y</TD>
  640. <TD ALIGN="center">Y</TD>
  641. <TD ALIGN="center">Y</TD>
  642. <TD ALIGN="center">Y</TD>
  643. <TD ALIGN="center">Y</TD>
  644. <TD ALIGN="center">Y</TD>
  645. <TD ALIGN="center">Y</TD>
  646. <TD ALIGN="center">Y</TD>
  647. <TD ALIGN="center">Y</TD>
  648. <TD ALIGN="center">Y</TD>
  649. <TD ALIGN="center">Y</TD>
  650. <TD ALIGN="center">Y</TD>
  651. <TD ALIGN="center">Y</TD>
  652. <TD ALIGN="center">-</TD>
  653. <TD ALIGN="center">-</TD>
  654. <TD ALIGN="center">Y</TD>
  655. </TR>
  656. <TR>
  657. <TD>quoted area</TD>
  658. <TD ALIGN="center">Y</TD>
  659. <TD ALIGN="center">Y</TD>
  660. <TD ALIGN="center">Y</TD>
  661. <TD ALIGN="center">Y</TD>
  662. <TD ALIGN="center">Y</TD>
  663. <TD ALIGN="center">Y</TD>
  664. <TD ALIGN="center">Y</TD>
  665. <TD ALIGN="center">Y</TD>
  666. <TD ALIGN="center">Y</TD>
  667. <TD ALIGN="center">Y</TD>
  668. <TD ALIGN="center">Y</TD>
  669. <TD ALIGN="center">Y</TD>
  670. <TD ALIGN="center">Y</TD>
  671. <TD ALIGN="center">Y</TD>
  672. <TD ALIGN="center">Y</TD>
  673. <TD ALIGN="center">N</TD>
  674. <TD ALIGN="center">Y</TD>
  675. <TD ALIGN="center">Y</TD>
  676. <TD ALIGN="center">-</TD>
  677. </TR>
  678. <TR>
  679. <TD>internet links</TD>
  680. <TD ALIGN="center">Y</TD>
  681. <TD ALIGN="center">Y</TD>
  682. <TD ALIGN="center">Y</TD>
  683. <TD ALIGN="center">Y</TD>
  684. <TD ALIGN="center">-</TD>
  685. <TD ALIGN="center">-</TD>
  686. <TD ALIGN="center">-</TD>
  687. <TD ALIGN="center">-</TD>
  688. <TD ALIGN="center">Y</TD>
  689. <TD ALIGN="center">Y</TD>
  690. <TD ALIGN="center">Y</TD>
  691. <TD ALIGN="center">Y</TD>
  692. <TD ALIGN="center">Y</TD>
  693. <TD ALIGN="center">Y</TD>
  694. <TD ALIGN="center">-</TD>
  695. <TD ALIGN="center">Y</TD>
  696. <TD ALIGN="center">-</TD>
  697. <TD ALIGN="center">-</TD>
  698. <TD ALIGN="center">Y</TD>
  699. </TR>
  700. <TR>
  701. <TD>e-mail links</TD>
  702. <TD ALIGN="center">Y</TD>
  703. <TD ALIGN="center">Y</TD>
  704. <TD ALIGN="center">Y</TD>
  705. <TD ALIGN="center">Y</TD>
  706. <TD ALIGN="center">-</TD>
  707. <TD ALIGN="center">-</TD>
  708. <TD ALIGN="center">-</TD>
  709. <TD ALIGN="center">-</TD>
  710. <TD ALIGN="center">Y</TD>
  711. <TD ALIGN="center">Y</TD>
  712. <TD ALIGN="center">Y</TD>
  713. <TD ALIGN="center">Y</TD>
  714. <TD ALIGN="center">Y</TD>
  715. <TD ALIGN="center">Y</TD>
  716. <TD ALIGN="center">-</TD>
  717. <TD ALIGN="center">Y</TD>
  718. <TD ALIGN="center">-</TD>
  719. <TD ALIGN="center">-</TD>
  720. <TD ALIGN="center">Y</TD>
  721. </TR>
  722. <TR>
  723. <TD>local links</TD>
  724. <TD ALIGN="center">Y</TD>
  725. <TD ALIGN="center">Y</TD>
  726. <TD ALIGN="center">Y</TD>
  727. <TD ALIGN="center">Y</TD>
  728. <TD ALIGN="center">N</TD>
  729. <TD ALIGN="center">N</TD>
  730. <TD ALIGN="center">-</TD>
  731. <TD ALIGN="center">-</TD>
  732. <TD ALIGN="center">N</TD>
  733. <TD ALIGN="center">N</TD>
  734. <TD ALIGN="center">N</TD>
  735. <TD ALIGN="center">Y</TD>
  736. <TD ALIGN="center">Y</TD>
  737. <TD ALIGN="center">Y</TD>
  738. <TD ALIGN="center">-</TD>
  739. <TD ALIGN="center">N</TD>
  740. <TD ALIGN="center">-</TD>
  741. <TD ALIGN="center">-</TD>
  742. <TD ALIGN="center">Y</TD>
  743. </TR>
  744. <TR>
  745. <TD>named links</TD>
  746. <TD ALIGN="center">Y</TD>
  747. <TD ALIGN="center">Y</TD>
  748. <TD ALIGN="center">Y</TD>
  749. <TD ALIGN="center">Y</TD>
  750. <TD ALIGN="center">-</TD>
  751. <TD ALIGN="center">-</TD>
  752. <TD ALIGN="center">-</TD>
  753. <TD ALIGN="center">-</TD>
  754. <TD ALIGN="center">Y</TD>
  755. <TD ALIGN="center">Y</TD>
  756. <TD ALIGN="center">Y</TD>
  757. <TD ALIGN="center">Y</TD>
  758. <TD ALIGN="center">Y</TD>
  759. <TD ALIGN="center">Y</TD>
  760. <TD ALIGN="center">-</TD>
  761. <TD ALIGN="center">Y</TD>
  762. <TD ALIGN="center">-</TD>
  763. <TD ALIGN="center">-</TD>
  764. <TD ALIGN="center">Y</TD>
  765. </TR>
  766. <TR>
  767. <TD>bulleted list</TD>
  768. <TD ALIGN="center">Y</TD>
  769. <TD ALIGN="center">Y</TD>
  770. <TD ALIGN="center">Y</TD>
  771. <TD ALIGN="center">Y</TD>
  772. <TD ALIGN="center">Y</TD>
  773. <TD ALIGN="center">Y</TD>
  774. <TD ALIGN="center">Y</TD>
  775. <TD ALIGN="center">Y</TD>
  776. <TD ALIGN="center">Y</TD>
  777. <TD ALIGN="center">Y</TD>
  778. <TD ALIGN="center">Y</TD>
  779. <TD ALIGN="center">Y</TD>
  780. <TD ALIGN="center">Y</TD>
  781. <TD ALIGN="center">Y</TD>
  782. <TD ALIGN="center">Y</TD>
  783. <TD ALIGN="center">Y</TD>
  784. <TD ALIGN="center">Y</TD>
  785. <TD ALIGN="center">Y</TD>
  786. <TD ALIGN="center">Y</TD>
  787. </TR>
  788. <TR>
  789. <TD>numbered list</TD>
  790. <TD ALIGN="center">Y</TD>
  791. <TD ALIGN="center">Y</TD>
  792. <TD ALIGN="center">Y</TD>
  793. <TD ALIGN="center">Y</TD>
  794. <TD ALIGN="center">Y</TD>
  795. <TD ALIGN="center">Y</TD>
  796. <TD ALIGN="center">Y</TD>
  797. <TD ALIGN="center">Y</TD>
  798. <TD ALIGN="center">Y</TD>
  799. <TD ALIGN="center">Y</TD>
  800. <TD ALIGN="center">Y</TD>
  801. <TD ALIGN="center">Y</TD>
  802. <TD ALIGN="center">Y</TD>
  803. <TD ALIGN="center">Y</TD>
  804. <TD ALIGN="center">Y</TD>
  805. <TD ALIGN="center">Y</TD>
  806. <TD ALIGN="center">Y</TD>
  807. <TD ALIGN="center">Y</TD>
  808. <TD ALIGN="center">Y</TD>
  809. </TR>
  810. <TR>
  811. <TD>definition list</TD>
  812. <TD ALIGN="center">Y</TD>
  813. <TD ALIGN="center">Y</TD>
  814. <TD ALIGN="center">Y</TD>
  815. <TD ALIGN="center">Y</TD>
  816. <TD ALIGN="center">Y</TD>
  817. <TD ALIGN="center">Y</TD>
  818. <TD ALIGN="center">Y</TD>
  819. <TD ALIGN="center">N</TD>
  820. <TD ALIGN="center">Y</TD>
  821. <TD ALIGN="center">Y</TD>
  822. <TD ALIGN="center">-</TD>
  823. <TD ALIGN="center">Y</TD>
  824. <TD ALIGN="center">-</TD>
  825. <TD ALIGN="center">Y</TD>
  826. <TD ALIGN="center">N</TD>
  827. <TD ALIGN="center">N</TD>
  828. <TD ALIGN="center">Y</TD>
  829. <TD ALIGN="center">Y</TD>
  830. <TD ALIGN="center">Y</TD>
  831. </TR>
  832. <TR>
  833. <TD>horizontal line</TD>
  834. <TD ALIGN="center">Y</TD>
  835. <TD ALIGN="center">Y</TD>
  836. <TD ALIGN="center">-</TD>
  837. <TD ALIGN="center">N</TD>
  838. <TD ALIGN="center">Y</TD>
  839. <TD ALIGN="center">Y</TD>
  840. <TD ALIGN="center">-</TD>
  841. <TD ALIGN="center">Y</TD>
  842. <TD ALIGN="center">Y</TD>
  843. <TD ALIGN="center">Y</TD>
  844. <TD ALIGN="center">-</TD>
  845. <TD ALIGN="center">Y</TD>
  846. <TD ALIGN="center">Y</TD>
  847. <TD ALIGN="center">Y</TD>
  848. <TD ALIGN="center">N</TD>
  849. <TD ALIGN="center">N</TD>
  850. <TD ALIGN="center">Y</TD>
  851. <TD ALIGN="center">Y</TD>
  852. <TD ALIGN="center">Y</TD>
  853. </TR>
  854. <TR>
  855. <TD>image</TD>
  856. <TD ALIGN="center">Y</TD>
  857. <TD ALIGN="center">Y</TD>
  858. <TD ALIGN="center">Y</TD>
  859. <TD ALIGN="center">Y</TD>
  860. <TD ALIGN="center">Y</TD>
  861. <TD ALIGN="center">Y</TD>
  862. <TD ALIGN="center">-</TD>
  863. <TD ALIGN="center">Y</TD>
  864. <TD ALIGN="center">Y</TD>
  865. <TD ALIGN="center">Y</TD>
  866. <TD ALIGN="center">Y</TD>
  867. <TD ALIGN="center">Y</TD>
  868. <TD ALIGN="center">Y</TD>
  869. <TD ALIGN="center">Y</TD>
  870. <TD ALIGN="center">N</TD>
  871. <TD ALIGN="center">Y</TD>
  872. <TD ALIGN="center">-</TD>
  873. <TD ALIGN="center">-</TD>
  874. <TD ALIGN="center">Y</TD>
  875. </TR>
  876. <TR>
  877. <TD>table</TD>
  878. <TD ALIGN="center">Y</TD>
  879. <TD ALIGN="center">Y</TD>
  880. <TD ALIGN="center">Y</TD>
  881. <TD ALIGN="center">N</TD>
  882. <TD ALIGN="center">Y</TD>
  883. <TD ALIGN="center">N</TD>
  884. <TD ALIGN="center">Y</TD>
  885. <TD ALIGN="center">N</TD>
  886. <TD ALIGN="center">Y</TD>
  887. <TD ALIGN="center">Y</TD>
  888. <TD ALIGN="center">Y</TD>
  889. <TD ALIGN="center">Y</TD>
  890. <TD ALIGN="center">Y</TD>
  891. <TD ALIGN="center">Y</TD>
  892. <TD ALIGN="center">N</TD>
  893. <TD ALIGN="center">N</TD>
  894. <TD ALIGN="center">N</TD>
  895. <TD ALIGN="center">N</TD>
  896. <TD ALIGN="center">Y</TD>
  897. </TR>
  898. <TR>
  899. <TH>Extras</TH>
  900. <TH>html</TH>
  901. <TH>xhtml</TH>
  902. <TH>sgml</TH>
  903. <TH>dbk</TH>
  904. <TH>tex</TH>
  905. <TH>lout</TH>
  906. <TH>man</TH>
  907. <TH>mgp</TH>
  908. <TH>creole</TH>
  909. <TH>wiki</TH>
  910. <TH>gwiki</TH>
  911. <TH>pmw</TH>
  912. <TH>doku</TH>
  913. <TH>moin</TH>
  914. <TH>pm6</TH>
  915. <TH>adoc</TH>
  916. <TH>art</TH>
  917. <TH>txt</TH>
  918. <TH>Y</TH>
  919. </TR>
  920. <TR>
  921. <TD>image align</TD>
  922. <TD ALIGN="center">Y</TD>
  923. <TD ALIGN="center">Y</TD>
  924. <TD ALIGN="center">N</TD>
  925. <TD ALIGN="center">N</TD>
  926. <TD ALIGN="center">N</TD>
  927. <TD ALIGN="center">Y</TD>
  928. <TD ALIGN="center">-</TD>
  929. <TD ALIGN="center">Y</TD>
  930. <TD ALIGN="center">N</TD>
  931. <TD ALIGN="center">Y</TD>
  932. <TD ALIGN="center">-</TD>
  933. <TD ALIGN="center">N</TD>
  934. <TD ALIGN="center">Y</TD>
  935. <TD ALIGN="center">N</TD>
  936. <TD ALIGN="center">N</TD>
  937. <TD ALIGN="center">N</TD>
  938. <TD ALIGN="center">-</TD>
  939. <TD ALIGN="center">-</TD>
  940. <TD ALIGN="center">Y</TD>
  941. </TR>
  942. <TR>
  943. <TD>table cell align</TD>
  944. <TD ALIGN="center">Y</TD>
  945. <TD ALIGN="center">Y</TD>
  946. <TD ALIGN="center">Y</TD>
  947. <TD ALIGN="center">N</TD>
  948. <TD ALIGN="center">Y</TD>
  949. <TD ALIGN="center">N</TD>
  950. <TD ALIGN="center">Y</TD>
  951. <TD ALIGN="center">N</TD>
  952. <TD ALIGN="center">N</TD>
  953. <TD ALIGN="center">N</TD>
  954. <TD ALIGN="center">-</TD>
  955. <TD ALIGN="center">N</TD>
  956. <TD ALIGN="center">-</TD>
  957. <TD ALIGN="center">Y</TD>
  958. <TD ALIGN="center">N</TD>
  959. <TD ALIGN="center">N</TD>
  960. <TD ALIGN="center">N</TD>
  961. <TD ALIGN="center">N</TD>
  962. <TD ALIGN="center">Y</TD>
  963. </TR>
  964. <TR>
  965. <TD>table column span</TD>
  966. <TD ALIGN="center">Y</TD>
  967. <TD ALIGN="center">Y</TD>
  968. <TD ALIGN="center">N</TD>
  969. <TD ALIGN="center">N</TD>
  970. <TD ALIGN="center">Y</TD>
  971. <TD ALIGN="center">N</TD>
  972. <TD ALIGN="center">N</TD>
  973. <TD ALIGN="center">N</TD>
  974. <TD ALIGN="center">N</TD>
  975. <TD ALIGN="center">N</TD>
  976. <TD ALIGN="center">-</TD>
  977. <TD ALIGN="center">N</TD>
  978. <TD ALIGN="center">-</TD>
  979. <TD ALIGN="center">N</TD>
  980. <TD ALIGN="center">N</TD>
  981. <TD ALIGN="center">N</TD>
  982. <TD ALIGN="center">N</TD>
  983. <TD ALIGN="center">N</TD>
  984. <TD ALIGN="center">Y</TD>
  985. </TR>
  986. </TABLE>
  987. <TABLE ALIGN="center">
  988. <TR>
  989. <TH></TH>
  990. <TH>Legend</TH>
  991. </TR>
  992. <TR>
  993. <TD><B>Y</B></TD>
  994. <TD><I>Supported</I></TD>
  995. </TR>
  996. <TR>
  997. <TD><B>N</B></TD>
  998. <TD><I>Not supported (may be in future releases)</I></TD>
  999. </TR>
  1000. <TR>
  1001. <TD><B>-</B></TD>
  1002. <TD><I>Not supported (can't be done on this target)</I></TD>
  1003. </TR>
  1004. </TABLE>
  1005. <A NAME="interfaces"></A>
  1006. <H2>The Three User Interfaces: Gui, Web and Command Line</H2>
  1007. <P>
  1008. As different users have different needs and environments, txt2tags is
  1009. very flexible on how it runs.
  1010. </P>
  1011. <P>
  1012. There are three User Interfaces for the program, each one with its own
  1013. purpose and features.
  1014. </P>
  1015. <UL>
  1016. <LI><B>Gui</B>: Written in Tk, brings the windowing and clicking to txt2tags.
  1017. <LI><B>Web</B>: Written in PHP, allows users to run txt2tags on the browser,
  1018. requiring no installation on the client side.
  1019. <LI><B>Command Line</B>: Written in Python, it's the program core. All
  1020. features are available as command line options.
  1021. </UL>
  1022. <A NAME="gui"></A>
  1023. <H3>Graphical Interface</H3>
  1024. <P>
  1025. Since version 1.0, there is a nice Graphical Interface, that works on
  1026. Linux, Windows, Mac and others. Just call txt2tags with the <CODE>--gui</CODE>
  1027. option to open it.
  1028. </P>
  1029. <P>
  1030. The interface is pretty simple and intuitive:
  1031. </P>
  1032. <center><IMG ALIGN="middle" SRC="./gui.png" BORDER="0" ALT=""></center>
  1033. <OL>
  1034. <LI>You locate the source .t2t file on the disk and its options are
  1035. loaded.
  1036. <P></P>
  1037. <LI>If the target is still empty, you must choose one.
  1038. <P></P>
  1039. <LI>Then there are some options you may choose, but none of them are
  1040. required.
  1041. <P></P>
  1042. <LI>Finally, press the "Convert!" button.
  1043. </OL>
  1044. <P>
  1045. A nice option is the "<I>Dump to screen</I>", so you can check
  1046. the resulting code on a separate window, no file is saved at all. When
  1047. the code is OK, you uncheck it and the file will be saved.
  1048. </P>
  1049. <P>
  1050. The default interface colors can be changed on the <A HREF="#rc">configuration file</A>,
  1051. using the <CODE>%!guicolors</CODE> settings. For example:
  1052. </P>
  1053. <PRE>
  1054. % set my own colors for the graphical interface (bg1, fg1, bg2, fg2)
  1055. %!guicolors: blue white brown yellow
  1056. </PRE>
  1057. <H3>Web Interface</H3>
  1058. <P>
  1059. The Web Interface is up and running on the Internet at
  1060. <A HREF="http://txt2tags.org/online.php">http://txt2tags.org/online.php</A>, so you can use and test the program
  1061. instantly, before download.
  1062. </P>
  1063. <center><IMG ALIGN="middle" SRC="./web.png" BORDER="0" ALT=""></center>
  1064. <P>
  1065. One can also put this interface on the local intranet avoiding to
  1066. install txt2tags in all machines.
  1067. </P>
  1068. <A NAME="cmdline"></A>
  1069. <H3>Command Line Interface</H3>
  1070. <P>
  1071. For command line power users, the --help should be enough:
  1072. </P>
  1073. <PRE>
  1074. Usage: txt2tags [OPTIONS] [infile.t2t ...]
  1075. --targets print a list of all the available targets and exit
  1076. -t, --target=TYPE set target document type. currently supported:
  1077. adoc, art, creole, dbk, doku, gwiki, html, lout, man,
  1078. mgp, moin, pm6, pmw, sgml, tex, txt, wiki, xhtml
  1079. -i, --infile=FILE set FILE as the input file name ('-' for STDIN)
  1080. -o, --outfile=FILE set FILE as the output file name ('-' for STDOUT)
  1081. --encoding=ENC set target file encoding (utf-8, iso-8859-1, etc)
  1082. --toc add an automatic Table of Contents to the output
  1083. --toc-level=N set maximum TOC level (depth) to N
  1084. --toc-only print the Table of Contents and exit
  1085. -n, --enum-title enumerate all titles as 1, 1.1, 1.1.1, etc
  1086. --style=FILE use FILE as the document style (like HTML CSS)
  1087. --css-sugar insert CSS-friendly tags for HTML/XHTML
  1088. --css-inside insert CSS file contents inside HTML/XHTML headers
  1089. -H, --no-headers suppress header and footer from the output
  1090. --mask-email hide email from spam robots. x@y.z turns &lt;x (a) y z&gt;
  1091. --slides format output as presentation slides (used by -t art)
  1092. --width=N set the output's width to N columns (used by -t art)
  1093. --height=N set the output's height to N rows (used by -t art)
  1094. -C, --config-file=F read configuration from file F
  1095. --gui invoke Graphical Tk Interface
  1096. -q, --quiet quiet mode, suppress all output (except errors)
  1097. -v, --verbose print informative messages during conversion
  1098. -h, --help print this help information and exit
  1099. -V, --version print program version and exit
  1100. --dump-config print all the configuration found and exit
  1101. --dump-source print the document source, with includes expanded
  1102. Turn OFF options:
  1103. --no-css-inside, --no-css-sugar, --no-dump-config, --no-dump-source,
  1104. --no-encoding, --no-enum-title, --no-headers, --no-infile,
  1105. --no-mask-email, --no-outfile, --no-quiet, --no-rc, --no-slides,
  1106. --no-style, --no-targets, --no-toc, --no-toc-only
  1107. Example:
  1108. txt2tags -t html --toc file.t2t
  1109. By default, converted output is saved to 'infile.&lt;target&gt;'.
  1110. Use --outfile to force an output file name.
  1111. If input file is '-', reads from STDIN.
  1112. If output file is '-', dumps output to STDOUT.
  1113. </PRE>
  1114. <P>
  1115. Please read the txt2tags man page for detailed information about options and command line use.
  1116. </P>
  1117. <P>
  1118. Examples:
  1119. </P>
  1120. <TABLE>
  1121. <TR>
  1122. <TD><B>Convert to HTML</B></TD>
  1123. <TD><CODE>$ txt2tags -t html file.t2t</CODE></TD>
  1124. </TR>
  1125. <TR>
  1126. <TD><B>The same, using redirection</B></TD>
  1127. <TD><CODE>$ txt2tags -t html -o - file.t2t &gt; file.html</CODE></TD>
  1128. </TR>
  1129. <TR>
  1130. <TD></TD>
  1131. <TD>.</TD>
  1132. </TR>
  1133. <TR>
  1134. <TD><B>Including Table Of Contents</B></TD>
  1135. <TD><CODE>$ txt2tags -t html --toc file.t2t</CODE></TD>
  1136. </TR>
  1137. <TR>
  1138. <TD><B>And also, numbering titles</B></TD>
  1139. <TD><CODE>$ txt2tags -t html --toc --enum-title file.t2t</CODE></TD>
  1140. </TR>
  1141. <TR>
  1142. <TD></TD>
  1143. <TD>.</TD>
  1144. </TR>
  1145. <TR>
  1146. <TD><B>Contents quick view</B></TD>
  1147. <TD><CODE>$ txt2tags --toc-only file.t2t</CODE></TD>
  1148. </TR>
  1149. <TR>
  1150. <TD><B>Maybe enumerate them?</B></TD>
  1151. <TD><CODE>$ txt2tags --toc-only --enum-title file.t2t</CODE></TD>
  1152. </TR>
  1153. <TR>
  1154. <TD></TD>
  1155. <TD>.</TD>
  1156. </TR>
  1157. <TR>
  1158. <TD><B>One liners from STDIN</B></TD>
  1159. <TD><CODE>$ echo -e "\n**bold**" | txt2tags -t html --no-headers -</CODE></TD>
  1160. </TR>
  1161. <TR>
  1162. <TD><B>Testing Mask Email feature</B></TD>
  1163. <TD><CODE>$ echo -e "\njohn.wayne@farwest.com" | txt2tags -t txt --mask-email --no-headers -</CODE></TD>
  1164. </TR>
  1165. </TABLE>
  1166. <A NAME="install"></A>
  1167. <H1>Part II - Install</H1>
  1168. <P>
  1169. Just download the program and run it on your machine.
  1170. </P>
  1171. <A NAME="download-python"></A>
  1172. <H2>Download &amp; Install Python</H2>
  1173. <P>
  1174. First of all, you must download and install <A HREF="http://www.python.org">Python</A> on
  1175. your system. Txt2tags requires Python version 2.2 or newer.
  1176. </P>
  1177. <P>
  1178. Note that Python is already installed by default in Linux and Mac systems. If you're using those, you're done, just skip this step.
  1179. </P>
  1180. <P>
  1181. If you are not sure if you have Python or not, open a console (tty,
  1182. xterm, MSDOS, Terminal.app) and type <CODE>python</CODE>. If it is not installed, the system
  1183. will tell you.
  1184. </P>
  1185. <A NAME="download-txt2tags"></A>
  1186. <H2>Download txt2tags</H2>
  1187. <P>
  1188. The official location for txt2tags distribution is on the program
  1189. site, at <A HREF="http://txt2tags.org">http://txt2tags.org</A>. Just download and uncompress the package (.tgz file).
  1190. </P>
  1191. <P>
  1192. If you're in Linux, you can also use the automatic installer of your system. Some examples:
  1193. </P>
  1194. <UL>
  1195. <LI>yum install txt2tags
  1196. <LI>sudo apt-get install txt2tags
  1197. </UL>
  1198. <A NAME="install-txt2tags"></A>
  1199. <H2>Install txt2tags</H2>
  1200. <P>
  1201. As a single Python script, txt2tags needs no installation at all.
  1202. </P>
  1203. <P>
  1204. The only file needed to use the program is the txt2tags script. The
  1205. other files of the package are documentation, tools and sample files.
  1206. </P>
  1207. <P>
  1208. The fail-proof way to run txt2tags, is calling Python with it:
  1209. </P>
  1210. <PRE>
  1211. prompt$ python txt2tags
  1212. </PRE>
  1213. <P>
  1214. If you want to install txt2tags on the system as a stand alone
  1215. program, just copy the txt2tags script to a system PATH
  1216. directory and make sure the system knows how to run it.
  1217. </P>
  1218. <DL>
  1219. <DT><B>UNIX/Linux/Mac</B></DT><DD>
  1220. Make the script executable (<CODE>chmod +x txt2tags</CODE>) and copy it to a
  1221. $PATH directory (<CODE>cp txt2tags /usr/local/bin</CODE>)
  1222. <P></P>
  1223. <DT><B>Windows</B></DT><DD>
  1224. Rename the script adding the .py extension
  1225. and copy it to a system PATH directory, such as <CODE>C:\Windows\System32</CODE>.
  1226. </DL>
  1227. <P>
  1228. After that, you can create an icon on your desktop for it, if you want to
  1229. use the program's Graphical Interface.
  1230. </P>
  1231. <A NAME="editor-syntax"></A>
  1232. <H2>Install Text Editor Syntax Highlighting File (optional)</H2>
  1233. <P>
  1234. Txt2tags comes with handy syntax highlighting files to be used by the
  1235. following text editors:
  1236. </P>
  1237. <UL>
  1238. <LI>Vim
  1239. <LI>Emacs
  1240. <LI>Nano
  1241. <LI>Kate
  1242. <LI>Gedit
  1243. <LI>JOE
  1244. <LI>le
  1245. <LI>ne
  1246. <LI>TextMate
  1247. </UL>
  1248. <P>
  1249. This syntax highlighting files have all the txt2tags rules and marks
  1250. registered, helping the user to write error-free documents. Showing the
  1251. marks in colors, you see on-the-fly if you wrote it right.
  1252. </P>
  1253. <TABLE ALIGN="center">
  1254. <TR>
  1255. <TD ALIGN="center"><center><IMG ALIGN="middle" SRC="./vim.png" BORDER="0" ALT=""></center></TD>
  1256. </TR>
  1257. <TR>
  1258. <TD ALIGN="center">Sample file opened in Vim Editor</TD>
  1259. </TR>
  1260. </TABLE>
  1261. <P>
  1262. Each editor has a different install procedure for a syntax highlighting
  1263. file, please read the syntax file headers and the editor documentation.
  1264. </P>
  1265. <A NAME="your-1st-doc"></A>
  1266. <H1>Part III - Writing and Converting Your First Document</H1>
  1267. <H2>Check the Tools</H2>
  1268. <P>
  1269. To make the first conversion you will need three things: txt2tags, a
  1270. text editor and a web browser.
  1271. </P>
  1272. <OL>
  1273. <LI>Make sure txt2tags is installed and running on your system.
  1274. <P></P>
  1275. <UL>
  1276. <LI><B>Command Line Interface:</B> Call "txt2tags" on the command line and
  1277. the program should give you a "Missing input file" message. If it is
  1278. not working, try <CODE>python /path/to/txt2tags</CODE> or even
  1279. <CODE>/path/to/python /path/to/txt2tags</CODE> if Python is not on your PATH.
  1280. <P></P>
  1281. <LI><B>Gui Interface:</B> Click on the program icon to launch the Gui
  1282. Interface or call <CODE>txt2tags --gui</CODE>.
  1283. <P></P>
  1284. </UL>
  1285. <LI>Open the text editor your are comfortable with. It can be <B>any</B> text
  1286. editor, from the good old VI to MS Word or OpenOffice.org. Create a
  1287. brand new empty document to be your first txt2tags one and remember to
  1288. save it as plain text.
  1289. <P></P>
  1290. <LI>Launch your favorite web browser to see the results of the conversion.
  1291. </OL>
  1292. <H2>Write the Document Header</H2>
  1293. <OL>
  1294. <LI>Go to the text editor and on the very first line type the document
  1295. main title: <I>My First Document</I>
  1296. <LI>On the second line make a subtitle, inserting this text:
  1297. <I>A txt2tags test</I>
  1298. <LI>Then, on the third line, put some time information:
  1299. <I>Sunday, 2004</I>
  1300. </OL>
  1301. <P>
  1302. If everything went right, you should be seeing a three line document
  1303. with this contents:
  1304. </P>
  1305. <PRE>
  1306. My First Document
  1307. A txt2tags test
  1308. Sunday, 2004
  1309. </PRE>
  1310. <P>
  1311. This is just a part of the document, but we can already convert it and
  1312. check the results.
  1313. </P>
  1314. <P>
  1315. Now save this document with the name <CODE>test.txt</CODE>. Remember to save it
  1316. as plain text. Pay attention to which folder you are saving the file,
  1317. you will need to remember it soon.
  1318. </P>
  1319. <H2>The First Conversion - Gui Interface</H2>
  1320. <P>
  1321. If you are in the Command Line Interface, please skip this step and read
  1322. the next one.
  1323. </P>
  1324. <P>
  1325. If you are in the Gui Interface, follow this steps:
  1326. </P>
  1327. <center><IMG ALIGN="middle" SRC="./firstdoc.png" BORDER="0" ALT=""></center>
  1328. <OL>
  1329. <LI>Press the "Browse" button and choose the <CODE>test.txt</CODE> you just saved
  1330. (remember the folder!).
  1331. <LI>Back to the first screen, select "HTML page" on the "Target document
  1332. type" combo.
  1333. <LI>Press the "Convert!" button.
  1334. </OL>
  1335. <center><IMG ALIGN="middle" SRC="./firstdoc-done.png" BORDER="0" ALT=""></center>
  1336. <P>
  1337. A dialog box will appear, telling you that the file was converted
  1338. successfully. Note that the generated HTML page was saved on the same
  1339. folder as the text file, with the "html" extension.
  1340. </P>
  1341. <H2>The First Conversion - Command Line Interface</H2>
  1342. <P>
  1343. If you are in the Command Line Interface, move to the folder where the
  1344. file was saved and type this command:
  1345. </P>
  1346. <PRE>
  1347. txt2tags --target html test.txt
  1348. </PRE>
  1349. <P>
  1350. The option <CODE>--target</CODE> is followed
  1351. by the "html" string, which tells the program to what format your text
  1352. file will be converted. The last item is the text filename.
  1353. </P>
  1354. <P>
  1355. The results were saved to the <CODE>test.html</CODE>
  1356. file and then the program will show you the
  1357. "<I>txt2tags wrote test.html</I>" message.
  1358. If some error occurred, read the message carefully.
  1359. </P>
  1360. <P>
  1361. Here is a sample of how it will be shown on your screen:
  1362. </P>
  1363. <PRE>
  1364. prompt$ txt2tags --target html test.txt
  1365. txt2tags wrote test.html
  1366. prompt$
  1367. </PRE>
  1368. <H2>Check the Results</H2>
  1369. <P>
  1370. Open the <CODE>test.html</CODE> file on the web browser to check if everything
  1371. is ok.
  1372. </P>
  1373. <center><IMG ALIGN="middle" SRC="./firstdoc-html.png" BORDER="0" ALT=""></center>
  1374. <P>
  1375. Here it is! You just typed three simple lines of text and txt2tags made
  1376. all the work to set the HTML page heading information, text alignment,
  1377. sizes, spacing and appearance. See that the main title is also placed at the
  1378. browser title bar.
  1379. </P>
  1380. <BLOCKQUOTE>
  1381. You write text, txt2tags does the rest ;)
  1382. </BLOCKQUOTE>
  1383. <P>
  1384. Tip: You can also use CSS files on HTML pages generated by txt2tags, so the
  1385. page appearance is 100% configurable.
  1386. </P>
  1387. <H2>Writing the Document Body</H2>
  1388. <P>
  1389. Now back to the text editor, the next step is to type the document
  1390. contents. You can write plain text as you normally do on email messages.
  1391. You will see that txt2tags recognizes paragraphs and list of items
  1392. automatically, you don't have to "mark" them.
  1393. </P>
  1394. <P>
  1395. Then again: save it, convert and check the results. This is the
  1396. development cycle of a document in txt2tags. You just focus on the
  1397. document contents, finishing documents faster than other editors. No
  1398. mouse clicking, no menus, no windows, no distraction.
  1399. </P>
  1400. <P>
  1401. Considering the following contents for the <CODE>test.txt</CODE> file, which is
  1402. only plain text, compare the generated HTML page:
  1403. </P>
  1404. <PRE>
  1405. My First Document
  1406. A txt2tags test
  1407. Sunday, 2004
  1408. Well, let's try this txt2tags thing.
  1409. I don't know what to write.
  1410. Mmmmmm, I know what I need to do now:
  1411. - Take a shower
  1412. - Eat a pizza
  1413. - Sleep
  1414. </PRE>
  1415. <center><IMG ALIGN="middle" SRC="./firstdoc-fullhtml.png" BORDER="0" ALT=""></center>
  1416. <P>
  1417. You can write a full homepage with 0% of HTML knowledge. You don't need
  1418. to insert any tags. And more, the same text file can be converted to any
  1419. of the other txt2tags supported formats.
  1420. </P>
  1421. <P>
  1422. Besides plain text, txt2tags has some very simple marks, that you'll
  1423. use when you need some other formatting or structures like bold, italic,
  1424. title, images, table and other. As a quick sample,
  1425. <CODE>**stars for bold**</CODE> and <CODE>== equals for title ==</CODE>. You can learn the
  1426. marks on the <A HREF="http://txt2tags.org/markup.html">Txt2tags Markup Demo</A>.
  1427. </P>
  1428. <A NAME="concepts"></A>
  1429. <H1>Part IV - Mastering Txt2tags Concepts</H1>
  1430. <A NAME="areas"></A>
  1431. <H2>The .t2t document Areas</H2>
  1432. <P>
  1433. Txt2tags marked files are divided in 3 areas. Each area has its own
  1434. rules and purpose. They are:
  1435. </P>
  1436. <DL>
  1437. <DT><I>Header Area</I></DT><DD>
  1438. Place for Document Title, Author, Version and Date information.
  1439. <DT><I>Config Area</I></DT><DD>
  1440. Place for general Document Settings and Parser behavior modifiers.
  1441. <DT><I>Body Area</I></DT><DD>
  1442. Place for the Document Content.
  1443. </DL>
  1444. <P>
  1445. All areas are optional. You can write a txt2tags document with just
  1446. headers (such as our first example), or a document with no headers or settings.
  1447. </P>
  1448. <P>
  1449. The areas are delimited by special rules, which will be seen in detail
  1450. on the next chapter. For now, this is a representation of the
  1451. areas on a document:
  1452. </P>
  1453. <PRE>
  1454. ____________
  1455. | |
  1456. | HEADERS | 1. First, the Headers
  1457. | |
  1458. | CONFIG | 2. Then the Settings
  1459. | |
  1460. | BODY | 3. And finally the Document Body,
  1461. | |
  1462. | ... | which goes until the end
  1463. | ... |
  1464. |____________|
  1465. </PRE>
  1466. <P>
  1467. In short, this is how the areas are defined:
  1468. </P>
  1469. <TABLE ALIGN="center">
  1470. <TR>
  1471. <TD ALIGN="center"><B>Headers</B></TD>
  1472. <TD>First 3 lines of the file, or the first line blank for No Headers.</TD>
  1473. </TR>
  1474. <TR>
  1475. <TD ALIGN="center"><B>Config</B></TD>
  1476. <TD>Begins right after the Header (4th or 2nd line) and ends when the <I>Body Area</I> starts.</TD>
  1477. </TR>
  1478. <TR>
  1479. <TD ALIGN="center"><B>Body</B></TD>
  1480. <TD>The first valid text line (not comment or setting) after the <I>Header Area</I>.</TD>
  1481. </TR>
  1482. </TABLE>
  1483. <H3>Full Example</H3>
  1484. <PRE>
  1485. My nice doc Title
  1486. Mr. John Doe
  1487. Last Updated: %%mtime(%c)
  1488. %!target : html
  1489. %!style : fancy.css
  1490. %!encoding: UTF-8
  1491. %!options : --toc --enum-title
  1492. Hi! This is my test document.
  1493. Its content will end here.
  1494. </PRE>
  1495. <A NAME="headers-area"></A>
  1496. <H2>Header Area</H2>
  1497. <P>
  1498. Location:
  1499. </P>
  1500. <UL>
  1501. <LI>Fixed position: <B>First 3 lines</B> of the file. Period.
  1502. <LI>Fixed position: <B>First line</B> of the file if it is blank. This
  1503. means Empty Headers.
  1504. </UL>
  1505. <P>
  1506. The Header Area is the only one that has a fixed position, line
  1507. oriented. They are located at the first three lines of the source file.
  1508. </P>
  1509. <P>
  1510. These lines are content-free, with no static information type needed.
  1511. But the following is recommended:
  1512. </P>
  1513. <UL>
  1514. <LI><I>line 1</I>: document title
  1515. <LI><I>line 2</I>: author name and/or email
  1516. <LI><I>line 3</I>: document date and/or version
  1517. (nice place for <CODE>%%date</CODE>)
  1518. </UL>
  1519. <P>
  1520. Keep in mind that the first 3 lines of the source document will be the
  1521. first 3 lines on the target document, separated and with high contrast
  1522. to the text body (i.e. big letters, bold). If paging is allowed, the
  1523. headers will be alone and centralized on the first page.
  1524. </P>
  1525. <H4>Less (or None) Header lines</H4>
  1526. <P>
  1527. Sometimes the user wants to specify less than three lines for headers,
  1528. giving just the document title and/or date information.
  1529. </P>
  1530. <P>
  1531. Just let the 2nd and/or the 3rd lines empty (blank) and this position
  1532. will not be placed at the target document. But keep in mind that even
  1533. blanks, these lines are still part of the headers, so the document body
  1534. must start <B>after</B> the 3rd line anyway.
  1535. </P>
  1536. <P>
  1537. The title is the only required header (the first line), but if you
  1538. leave it blank, you are saying that your document has <B>no headers</B>.
  1539. So the <I>Body Area</I> will begin right after, on the 2nd line.
  1540. </P>
  1541. <P>
  1542. No headers on the document is often useful if you want to specify your
  1543. own customized headers after converting. The command line option
  1544. <CODE>--no-headers</CODE> is usually required for this kind of operation.
  1545. </P>
  1546. <H4>Straight to the point</H4>
  1547. <P>
  1548. In short: <B>"Headers are just <U>positions</U>, not contents"</B>
  1549. </P>
  1550. <P>
  1551. Place one text on the first line, and it will appear on the target's
  1552. first line. The same for 2nd and 3rd header lines.
  1553. </P>
  1554. <A NAME="config-area"></A>
  1555. <H2>Config Area</H2>
  1556. <P>
  1557. Location:
  1558. </P>
  1559. <UL>
  1560. <LI>Begins right after the Header Area
  1561. <UL>
  1562. <LI>Begins on the <B>4th line</B> of the file if <B>Headers</B> were specified
  1563. <LI>Begins on the <B>2nd line</B> of the file if <B>No Headers</B> were specified
  1564. </UL>
  1565. <LI>Ends when the Body Area starts
  1566. <UL>
  1567. <LI>Ends by a non Setting, Blank or Comment line
  1568. </UL>
  1569. </UL>
  1570. <P>
  1571. The Config Area is optional. An average user can write lots of txt2tags
  1572. files without even know it exists, but the experienced users will
  1573. enjoy the power and control it provides.
  1574. </P>
  1575. <P>
  1576. The Config Area is used to store document-specific settings, so you don't
  1577. have to type them on the command line when converting the document. For
  1578. example, you can set the default document target type and encoding.
  1579. </P>
  1580. <P>
  1581. Please read the <A HREF="#settings-overview">Settings section</A> for more
  1582. information about them.
  1583. </P>
  1584. <A NAME="body-area"></A>
  1585. <H2>Body Area</H2>
  1586. <P>
  1587. Location:
  1588. </P>
  1589. <UL>
  1590. <LI>Begins on the first valid text line of the file
  1591. <UL>
  1592. <LI>Headers, Settings and Comments are <B>not</B> valid text lines
  1593. </UL>
  1594. <LI>Ends at the end of the file (EOF)
  1595. </UL>
  1596. <P>
  1597. The body is anything outside Headers and Config Areas.
  1598. </P>
  1599. <P>
  1600. The body holds the document contents and all formatting and structures
  1601. txt2tags can recognize. Inside the body you can also put comments for
  1602. <I>TODOs</I> and self notes.
  1603. </P>
  1604. <P>
  1605. You can use the <CODE>--no-headers</CODE> command line option to convert only the
  1606. document body, suppressing the headers. This is useful to set your own
  1607. headers on a separate file, then join the converted body.
  1608. </P>
  1609. <A NAME="settings-overview"></A>
  1610. <H2>Settings</H2>
  1611. <P>
  1612. Settings are special configurations placed at the source document's
  1613. Config Area that can affect the conversion process. Their syntax is:
  1614. </P>
  1615. <PRE>
  1616. %! keyword : value
  1617. </PRE>
  1618. <P>
  1619. List of valid keywords:
  1620. </P>
  1621. <TABLE ALIGN="center" BORDER="1">
  1622. <TR>
  1623. <TH>Keyword</TH>
  1624. <TH>Description</TH>
  1625. </TR>
  1626. <TR>
  1627. <TD ALIGN="center">Target</TD>
  1628. <TD>Set the default target to the document be converted to.</TD>
  1629. </TR>
  1630. <TR>
  1631. <TD ALIGN="center">Options</TD>
  1632. <TD>Set the default options to be used on the conversion. The format is the same as the command line options.</TD>
  1633. </TR>
  1634. <TR>
  1635. <TD ALIGN="center">Style</TD>
  1636. <TD>Set the document style. Used to define a CSS file for HTML/XHTML and to load a package in LaTeX.</TD>
  1637. </TR>
  1638. <TR>
  1639. <TD ALIGN="center">Encoding</TD>
  1640. <TD>Set the document Character Set. Used if the document contains accented letters or other not-ASCII characters.</TD>
  1641. </TR>
  1642. <TR>
  1643. <TD ALIGN="center">PreProc</TD>
  1644. <TD>Input filter. Sets "find and replace" rules to be applied on the Body Area of the source document.</TD>
  1645. </TR>
  1646. <TR>
  1647. <TD ALIGN="center">PostProc</TD>
  1648. <TD>Output filter. Sets "find and replace" rules to be applied on the converted document.</TD>
  1649. </TR>
  1650. </TABLE>
  1651. <P>
  1652. Example:
  1653. </P>
  1654. <PRE>
  1655. %!target : html
  1656. %!options : --toc --toc-level 3
  1657. %!style : fancy.css
  1658. %!encoding: UTF-8
  1659. %!preproc : "AMJ" "Aurelio Marinho Jargas"
  1660. %!postproc: '&lt;BODY.*?&gt;' '&lt;BODY bgcolor="yellow"&gt;'
  1661. </PRE>
  1662. <P>
  1663. Note that the spacing and capitalization of the keyword are ignored. So you can also do <CODE>%!Target:html</CODE> and <CODE>%! TARGET :html</CODE>.
  1664. </P>
  1665. <P>
  1666. Learn more about settings in <A HREF="#settings">Part VII - Mastering Settings</A>.
  1667. </P>
  1668. <A NAME="options"></A>
  1669. <H2>Command Line Options</H2>
  1670. <P>
  1671. The fastest way of changing the txt2tags default behavior is to use
  1672. command line options. This options are available on the Command Line
  1673. Interface only, not on Gui or Web.
  1674. </P>
  1675. <P>
  1676. Just like the other system's tools, the program do accept a set of
  1677. predefined options. An option is an hyphen followed by a letter or two
  1678. hyphens followed by one or more words, like <CODE>-t</CODE> and <CODE>--target</CODE>.
  1679. </P>
  1680. <P>
  1681. Options that are generally used are <CODE>--outfile</CODE> to define a customized
  1682. output file name, <CODE>--toc</CODE> to turn on the automatic TOC generation and
  1683. <CODE>--encoding</CODE> to set the document character set. Most of the options
  1684. can be turned off prefixing a "no-" before its name, for example:
  1685. <CODE>--no-encoding</CODE> and <CODE>--no-toc</CODE>.
  1686. </P>
  1687. <P>
  1688. You can register the desired options for a source file inside its
  1689. Config Area, using the <CODE>%!options</CODE> setting. This way you don't have to
  1690. type them on the command line anymore.
  1691. Example:
  1692. </P>
  1693. <PRE>
  1694. %!options: --toc -o mydoc.html
  1695. </PRE>
  1696. <P>
  1697. The exception is the target specification, that has its own setting:
  1698. </P>
  1699. <PRE>
  1700. %!target: html
  1701. </PRE>
  1702. <P>
  1703. Use the <CODE>--help</CODE> option to get a complete list of all the options
  1704. available in txt2tags.
  1705. </P>
  1706. <P>
  1707. Learn more about <A HREF="#setting-options">%!options</A> and <A HREF="#setting-target">%!target</A>.
  1708. </P>
  1709. <A NAME="rc"></A>
  1710. <H2>User Configuration File (RC File)</H2>
  1711. <P>
  1712. The user configuration file (also called RC file) is a central place to
  1713. store the settings that will be shared by ALL converted files. If you
  1714. keep inserting the same settings on every .t2t file you write, move it
  1715. to the RC file and it will be used globally, for existing and future
  1716. source files.
  1717. </P>
  1718. <P>
  1719. The default location of this file depends on your system. It can also be
  1720. specified by the user, using an environment variable.
  1721. </P>
  1722. <TABLE ALIGN="center" BORDER="1">
  1723. <TR>
  1724. <TH COLSPAN="2">RC file location</TH>
  1725. </TR>
  1726. <TR>
  1727. <TD ALIGN="right">Windows</TD>
  1728. <TD><CODE>%HOMEPATH%\_t2trc</CODE></TD>
  1729. </TR>
  1730. <TR>
  1731. <TD>UNIX, Linux, Mac</TD>
  1732. <TD><CODE>$HOME/.txt2tagsrc</CODE></TD>
  1733. </TR>
  1734. <TR>
  1735. <TD ALIGN="right">User defined</TD>
  1736. <TD><CODE>T2TCONFIG</CODE> variable</TD>
  1737. </TR>
  1738. </TABLE>
  1739. <P>
  1740. The format of the settings is exactly the same as the ones used on the
  1741. .t2t files Config Area. There is a sample RC file on the package at
  1742. <CODE>doc/txt2tagsrc</CODE>. Example:
  1743. </P>
  1744. <PRE>
  1745. % my configs
  1746. %%% Always use CSS-friendly tags in HTML
  1747. %!options(html): --css-sugar
  1748. %%% Change the default TOC depth for all targets
  1749. %!options: --toc-level 4
  1750. %%% Set the default encoding for all documents
  1751. %!options: --encoding UTF-8
  1752. </PRE>
  1753. <P>
  1754. Any line that is not blank, a comment or a valid config line will raise
  1755. error when txt2tags runs. So be careful when editing this file.
  1756. </P>
  1757. <P>
  1758. Txt2tags automatically apply the RC file contents into any source file it
  1759. is converting. If you want to disable this behavior for a specific
  1760. file, use the <CODE>--no-rc</CODE> command line option.
  1761. </P>
  1762. <A NAME="config-loading"></A>
  1763. <H2>Configuration Loading Order and Precedence</H2>
  1764. <P>
  1765. There are three ways of telling txt2tags which options and settings to
  1766. use, and this is the order that they are read and applied:
  1767. </P>
  1768. <OL>
  1769. <LI>The user configuration file (RC) settings
  1770. <LI>The source document Config Area settings
  1771. <LI>The command line options
  1772. </OL>
  1773. <P>
  1774. First txt2tags reads the RC file contents (if any) and apply its
  1775. configurations on the current source file. Then it scans the source
  1776. document Config Area for settings and if found, they are applied also,
  1777. overriding the RC ones in case of conflict. Finally comes the command
  1778. line options, stronger than the other two.
  1779. </P>
  1780. <P>
  1781. So, if the document encoding was defined on the three resources, the
  1782. command line will be the one used.
  1783. </P>
  1784. <A NAME="include"></A>
  1785. <H2>%!include command</H2>
  1786. <P>
  1787. The <CODE>include</CODE> command is used to paste the contents of an external
  1788. file into the source document body. It is not a config, but a command,
  1789. and it is valid on the document Body Area.
  1790. </P>
  1791. <P>
  1792. The <CODE>include</CODE> command is useful to split a large document into smaller
  1793. pieces (like chapters in a book) or to include the full contents of an
  1794. external file into the document source. Sample:
  1795. </P>
  1796. <PRE>
  1797. My first book
  1798. Dr. John Doe
  1799. 1st Edition
  1800. %!include: intro.t2t
  1801. %!include: chapter1.t2t
  1802. %!include: chapter2.t2t
  1803. ...
  1804. %!include: chapter9.t2t
  1805. %!include: ending.t2t
  1806. </PRE>
  1807. <P>
  1808. You just inform the filename after the <CODE>%!include</CODE> string. The
  1809. optional target specification is also supported, so this is valid
  1810. either:
  1811. </P>
  1812. <PRE>
  1813. %!include(html): file.t2t
  1814. </PRE>
  1815. <P>
  1816. Note that include will insert the file Body Area into the source
  1817. document. The included file Header and Config Areas are ignored. This
  1818. way you can convert the included file alone or inside the main document.
  1819. </P>
  1820. <P>
  1821. But there's another three types of include:
  1822. </P>
  1823. <UL>
  1824. <LI>Verbatim include
  1825. <LI>Raw include
  1826. <LI>Tagged include
  1827. </UL>
  1828. <P>
  1829. The <B>Verbatim</B> type includes a text file preserving its original
  1830. spaces and formatting, just like if the text was inside the txt2tags
  1831. Verbatim area (```). To specify this type, enclose the filename with
  1832. backquotes:
  1833. </P>
  1834. <PRE>
  1835. %!include: ``/etc/fstab``
  1836. </PRE>
  1837. <P>
  1838. The <B>Raw</B> type includes a text file as is, not trying to find and
  1839. parse txt2tags marks on it, just like if the text was inside the Raw
  1840. area ("""). To specify this type, enclose the filename with double
  1841. quotes:
  1842. </P>
  1843. <PRE>
  1844. %!include: ""nice_text.txt""
  1845. </PRE>
  1846. <P>
  1847. And the <B>Tagged</B> type is passed directly to the resulting document,
  1848. with NO parsing or escaping performed by txt2tags. This way you can
  1849. include additional tagged parts to your document. Useful for default
  1850. header or footer information, or more complicated tagged code,
  1851. unsupported by txt2tags:
  1852. </P>
  1853. <PRE>
  1854. %!include(html): ''footer.html''
  1855. </PRE>
  1856. <P>
  1857. Note that the filename is enclosed with single quotes. As the text
  1858. inserted is already parsed, you should specify the target to avoid
  1859. mistakes.
  1860. </P>
  1861. <A NAME="includeconf"></A>
  1862. <H2>%!includeconf command</H2>
  1863. <P>
  1864. The <CODE>includeconf</CODE> command is used to include configurations from an
  1865. external file into the current one. This command is valid inside the
  1866. source document Config Area only.
  1867. </P>
  1868. <P>
  1869. It is useful to share the same config for multiple files, so you can
  1870. centralize it. On any file do you want to include that central
  1871. configuration, put a <CODE>includeconf</CODE> call. Example:
  1872. </P>
  1873. <PRE>
  1874. My First Document
  1875. John Doe
  1876. July, 2004
  1877. %!includeconf: config.t2t
  1878. Hi, this is my first document.
  1879. </PRE>
  1880. <P>
  1881. The format inside the included file is the same as in the
  1882. <A HREF="#rc">RC file</A>.
  1883. </P>
  1884. <P>
  1885. Note that the optional target specification is NOT supported for this command.
  1886. </P>
  1887. <PRE>
  1888. %!includeconf: config.t2t &lt;--- OK
  1889. %!includeconf(html): config.t2t &lt;--- NOT OK
  1890. </PRE>
  1891. <A NAME="marks"></A>
  1892. <H1>Part V - Mastering Marks</H1>
  1893. <P>
  1894. Overview of all txt2tags marks:
  1895. </P>
  1896. <TABLE ALIGN="center" BORDER="1">
  1897. <TR>
  1898. <TH COLSPAN="2">Basic</TH>
  1899. <TH COLSPAN="2">Beautifiers</TH>
  1900. </TR>
  1901. <TR>
  1902. <TD ALIGN="right"><I>Headers</I></TD>
  1903. <TD ALIGN="center">First 3 lines</TD>
  1904. <TD ALIGN="right"><I>Bold</I></TD>
  1905. <TD ALIGN="center">**words**</TD>
  1906. </TR>
  1907. <TR>
  1908. <TD ALIGN="right"><I>Title</I></TD>
  1909. <TD ALIGN="center">= words =</TD>
  1910. <TD ALIGN="right"><I>Italic</I></TD>
  1911. <TD ALIGN="center">//words//</TD>
  1912. </TR>
  1913. <TR>
  1914. <TD ALIGN="right"><I>Numbered title</I></TD>
  1915. <TD ALIGN="center">+ words +</TD>
  1916. <TD ALIGN="right"><I>Underline</I></TD>
  1917. <TD ALIGN="center">__words__</TD>
  1918. </TR>
  1919. <TR>
  1920. <TD ALIGN="right"><I>Paragraph</I></TD>
  1921. <TD ALIGN="center">words</TD>
  1922. <TD ALIGN="right"><I>Strike</I></TD>
  1923. <TD ALIGN="center">--words--</TD>
  1924. </TR>
  1925. <TR>
  1926. <TD ALIGN="right"><I>Links</I></TD>
  1927. <TD ALIGN="center">[label url]</TD>
  1928. <TD ALIGN="right"><I>Monospaced</I></TD>
  1929. <TD ALIGN="center">``words``</TD>
  1930. </TR>
  1931. <TR>
  1932. <TD ALIGN="right"><I>Image</I></TD>
  1933. <TD ALIGN="center">[filename.jpg]</TD>
  1934. <TD ALIGN="right"><I>Raw text</I></TD>
  1935. <TD ALIGN="center">""words""</TD>
  1936. </TR>
  1937. <TR>
  1938. <TD COLSPAN="2"></TD>
  1939. <TD ALIGN="right"><I>Tagged text</I></TD>
  1940. <TD ALIGN="center">''words''</TD>
  1941. </TR>
  1942. <TR>
  1943. <TH COLSPAN="4">Other</TH>
  1944. </TR>
  1945. <TR>
  1946. <TD ALIGN="right"><I>Quote</I></TD>
  1947. <TD ALIGN="center">&lt;TAB&gt;words</TD>
  1948. <TD ALIGN="right"><I>Separator line</I></TD>
  1949. <TD ALIGN="center"><S>--------</S>...</TD>
  1950. </TR>
  1951. <TR>
  1952. <TD ALIGN="right"><I>List</I></TD>
  1953. <TD ALIGN="center">- words</TD>
  1954. <TD ALIGN="right"><I>Strong line</I></TD>
  1955. <TD ALIGN="center">============...</TD>
  1956. </TR>
  1957. <TR>
  1958. <TD ALIGN="right"><I>Numbered list</I></TD>
  1959. <TD ALIGN="center">+ words</TD>
  1960. <TD ALIGN="right"><I>Table</I></TD>
  1961. <TD ALIGN="center">| cell1 | cell2 | cell3...</TD>
  1962. </TR>
  1963. <TR>
  1964. <TD ALIGN="right"><I>Definition list</I></TD>
  1965. <TD ALIGN="center">: words</TD>
  1966. <TD ALIGN="right"><I>Anchor</I></TD>
  1967. <TD ALIGN="center">= title =[anchor]</TD>
  1968. </TR>
  1969. <TR>
  1970. <TD ALIGN="right"><I>Comment line</I></TD>
  1971. <TD ALIGN="center">% comments</TD>
  1972. <TD ALIGN="right"><I>Comment area</I></TD>
  1973. <TD ALIGN="center">%%%\n comments \n%%%</TD>
  1974. </TR>
  1975. <TR>
  1976. <TD ALIGN="right"><I>Verbatim line</I></TD>
  1977. <TD ALIGN="center">``` word</TD>
  1978. <TD ALIGN="right"><I>Verbatim area</I></TD>
  1979. <TD ALIGN="center">```\n lines \n```</TD>
  1980. </TR>
  1981. <TR>
  1982. <TD ALIGN="right"><I>Raw line</I></TD>
  1983. <TD ALIGN="center">""" words</TD>
  1984. <TD ALIGN="right"><I>Raw area</I></TD>
  1985. <TD ALIGN="center">"""\n lines \n"""</TD>
  1986. </TR>
  1987. <TR>
  1988. <TD ALIGN="right"><I>Tagged line</I></TD>
  1989. <TD ALIGN="center">''' words</TD>
  1990. <TD ALIGN="right"><I>Tagged area</I></TD>
  1991. <TD ALIGN="center">'''\n lines \n'''</TD>
  1992. </TR>
  1993. </TABLE>
  1994. <P>
  1995. General Rules:
  1996. </P>
  1997. <UL>
  1998. <LI><B>Headers</B> are the first three document lines, marks are not interpreted.
  1999. <LI><B>Titles</B> are balanced "=" or "+" chars around the title text. The more chars, more deep is the title.
  2000. <LI><B>Beautifiers</B> don't accept spaces between the marks and its contents.
  2001. <LI>The <B>Comment</B> mark "%" must be at the line beginning (first column).
  2002. <LI><B>Images</B> filename must end in GIF, JPG, PNG or similar.
  2003. <LI>The only <B>multiline</B> marks are the Comment, Verbatim, Raw and Tagged areas.
  2004. <LI>No mark is <B>interpreted</B> inside Verbatim, Raw and Tagged.
  2005. <LI>The <B>Separator/Strong lines</B> must have at least 20 chars.
  2006. <LI>Quote and lists <B>(un)nesting</B> is defined by indent.
  2007. <LI>A <B>Table title</B> line is defined by two || at the beginning of the line.
  2008. </UL>
  2009. <A NAME="mark-headers"></A>
  2010. <H2>Headers</H2>
  2011. <UL>
  2012. <LI><B>Description:</B> Identifies the document headers
  2013. <LI><B>Properties:</B> Multiline, FreeSpaces, !Align, !Nesting
  2014. <LI><B>Contains:</B> Macros
  2015. <LI><B>Syntax:</B>
  2016. <UL>
  2017. <LI>The first 3 lines of the source file.
  2018. <LI>Leave the first line blank to not specify headers at all.
  2019. Nice for command line one-liners or customized headers.
  2020. <LI>Leave the second and/or third lines blank to omit parts of header.
  2021. </UL>
  2022. <LI><B>Details:</B>
  2023. <UL>
  2024. <LI>Marks are NOT interpreted
  2025. <LI>The first 3 lines will be the first 3 lines on the target document,
  2026. with high contrast to text body, or will be placed alone on the
  2027. first page (if paging is allowed).
  2028. <LI>The headers are content-free, with no static information type
  2029. needed. But the following is recommended for the most documents:
  2030. <UL>
  2031. <LI>Line 1: Document title
  2032. <LI>Line 2: Author name and/or email
  2033. <LI>Line 3: Document date and/or version (nice place for %%mtime)
  2034. </UL>
  2035. </UL>
  2036. </UL>
  2037. <A NAME="mark-title"></A>
  2038. <H2>Title, Numbered Title</H2>
  2039. <UL>
  2040. <LI><B>Description:</B> Identifies a (numbered or not) section title
  2041. <LI><B>Properties:</B> !Multiline, FreeSpaces, !Align, !Nesting
  2042. <LI><B>Contains:</B> -
  2043. <LI><B>Syntax:</B>
  2044. <UL>
  2045. <LI>For Numbered Title, just change "=" by "+" on the following rules
  2046. <LI>Balanced equal signs around, <CODE>=like this=</CODE>
  2047. <LI>More signs, more sublevels: <CODE>=title=</CODE>, <CODE>==subtitle==</CODE>,
  2048. <CODE>===subsubtitle===</CODE>, ...
  2049. <LI>There is a maximum of 5 levels, <CODE>=====like this=====</CODE>
  2050. <LI>Unbalanced equals are not title, <CODE>=like this===</CODE>
  2051. <LI>Free spacing inside the marks are allowed, <CODE>= like this =</CODE>
  2052. <LI>Titles can have an anchor <CODE>=like this=[anchor]</CODE>. To link to an anchor
  2053. create a <CODE>[local link #anchor]</CODE>
  2054. <LI>The anchor name can contain only letters, numbers, underscore
  2055. and hyphen (A-Za-z0-9_-)
  2056. </UL>
  2057. <LI><B>Details:</B>
  2058. <UL>
  2059. <LI>Marks are NOT interpreted
  2060. <LI>Macros are NOT interpreted
  2061. </UL>
  2062. </UL>
  2063. <A NAME="mark-paragraph"></A>
  2064. <H2>Paragraph</H2>
  2065. <UL>
  2066. <LI><B>Description:</B> Identifies a paragraph of text
  2067. <LI><B>Properties:</B> Multiline, FreeSpaces, !Align, !Nesting
  2068. <LI><B>Contains:</B> Macros, Beautifiers, Raw, Tagged, Links, Image, Comment
  2069. <LI><B>Syntax:</B>
  2070. <UL>
  2071. <LI>Paragraphs are groups of lines delimited by blank lines
  2072. <LI>Other blocks like lists, quote, table or verbatim also ends a
  2073. paragraph
  2074. </UL>
  2075. </UL>
  2076. <A NAME="mark-comment"></A>
  2077. <H2>Comment</H2>
  2078. <UL>
  2079. <LI><B>Description:</B> Used to insert text that will not appear on the target
  2080. document
  2081. <LI><B>Properties:</B> !Multiline, !FreeSpaces, !Align, !Nesting
  2082. <LI><B>Contains:</B> -
  2083. <LI><B>Syntax:</B>
  2084. <UL>
  2085. <LI>A line beginning with a percent char at the first column, <CODE>% like this</CODE>
  2086. <LI>NO leading spaces
  2087. </UL>
  2088. <LI><B>Details:</B>
  2089. <UL>
  2090. <LI>As comments, they're not showed on the converted text
  2091. <LI>Not a block, so each comment line must begin with %
  2092. <LI>Useful for TODO and FIXME reminders and editor's notes
  2093. </UL>
  2094. </UL>
  2095. <A NAME="mark-comment-block"></A>
  2096. <H2>Comment Area</H2>
  2097. <UL>
  2098. <LI><B>Description:</B> Used to insert text that will not appear on the target
  2099. document
  2100. <LI><B>Properties:</B> Multiline, !FreeSpaces, !Align, !Nesting
  2101. <LI><B>Contains:</B> -
  2102. <LI><B>Syntax:</B>
  2103. <UL>
  2104. <LI>A line with exactly 3 consecutive percents <CODE>%%%</CODE>, followed by
  2105. text lines, followed by another line with exactly 3 consecutive
  2106. percents <CODE>%%%</CODE>
  2107. <LI>NO spaces allowed before or after the marks
  2108. </UL>
  2109. <LI><B>Details:</B>
  2110. <UL>
  2111. <LI>As comments, they're not showed on the converted text
  2112. <LI>Useful for deactivate (not delete) large portions of the contents
  2113. <LI>If the end of the source file (EOF) is hit, the opened Comment Area
  2114. is closed
  2115. </UL>
  2116. </UL>
  2117. <A NAME="mark-beautifiers"></A>
  2118. <H2>Bold, Italic, Underline, Strike</H2>
  2119. <UL>
  2120. <LI><B>Description:</B> Used to insert a bold/italic/underline/strike text inside a
  2121. paragraph, table, list or quote
  2122. <LI><B>Properties:</B> !Multiline, !FreeSpaces, !Align, Nesting
  2123. <LI><B>Contains:</B> Macros, Beautifiers, Raw, Tagged, Links, Image
  2124. <LI><B>Syntax:</B>
  2125. <UL>
  2126. <LI>Two starts around for bold, <CODE>**like this**</CODE>
  2127. <LI>Two slashes around for italic, <CODE>//like this//</CODE>
  2128. <LI>Two underlines around for underline, <CODE>__like this__</CODE>
  2129. <LI>Two hyphens around for strike, <CODE>--like this--</CODE>
  2130. <LI>The marks must be glued with the contents (no spaces):
  2131. <CODE>** this ** is invalid</CODE>
  2132. </UL>
  2133. <LI><B>Details:</B>
  2134. <UL>
  2135. <LI>All the beautified text must be on a single line of the source file,
  2136. no line breaks inside
  2137. <LI>Macros are allowed inside beautifiers: <CODE>**%%date**</CODE>
  2138. <LI>You can mix beautifiers one inside another,
  2139. <CODE>""**__like__ //this//**""</CODE>
  2140. </UL>
  2141. </UL>
  2142. <A NAME="mark-monospaced"></A>
  2143. <H2>Monospaced</H2>
  2144. <UL>
  2145. <LI><B>Description:</B> Used to insert a monospaced text inside a paragraph, table,
  2146. list or quote
  2147. <LI><B>Properties:</B> !Multiline, !FreeSpaces, !Align, !Nesting
  2148. <LI><B>Contains:</B> -
  2149. <LI><B>Syntax:</B>
  2150. <UL>
  2151. <LI>Two backquotes around, <CODE>``like this``</CODE>
  2152. <LI>The marks must be glued with the contents (no spaces):
  2153. <CODE>`` this `` is invalid</CODE>
  2154. </UL>
  2155. <LI><B>Details:</B>
  2156. <UL>
  2157. <LI>Marks are NOT interpreted
  2158. <LI>Macros are NOT interpreted
  2159. <LI>All the monospaced text must be on a single line of the source file,
  2160. no line breaks inside
  2161. <LI>In some targets, the internal spacing is maintained, in others the
  2162. consecutive spaces are squeezed to one
  2163. <LI>You can make a bold monospaced text enclosing it inside bold marks:
  2164. <CODE>""**</CODE>monobold<CODE>**""</CODE>. The same applies to the other beautifiers
  2165. such as <CODE>""//</CODE>italic<CODE>//""</CODE> and <CODE>""__</CODE>underline<CODE>__""</CODE>.
  2166. </UL>
  2167. </UL>
  2168. <A NAME="mark-verbatim"></A>
  2169. <H2>Verbatim Line, Verbatim Area</H2>
  2170. <UL>
  2171. <LI><B>Description:</B> Used to insert programming codes or other pre-formatted text,
  2172. preserving spacing and line breaks, and using a monospaced font
  2173. <LI><B>Properties:</B> Multiline, !FreeSpaces, !Align, !Nesting
  2174. <LI><B>Contains:</B> -
  2175. <LI><B>Syntax:</B> <B>Verbatim Line:</B>
  2176. <UL>
  2177. <LI>A line beginning with 3 consecutive backquotes, followed by a space,
  2178. followed by the text, <CODE>""`</CODE>"" like this``
  2179. <LI>The backquotes must be at the start of the line, no spaces before
  2180. </UL>
  2181. <LI><B>Syntax:</B> <B>Verbatim Area:</B>
  2182. <UL>
  2183. <LI>A line with exactly 3 consecutive backquotes <CODE>```</CODE>, followed by
  2184. text lines, followed by another line with exactly 3 consecutive
  2185. backquotes <CODE>```</CODE>
  2186. <LI>NO spaces allowed before or after the marks
  2187. </UL>
  2188. <LI><B>Details:</B>
  2189. <UL>
  2190. <LI>Marks are NOT interpreted
  2191. <LI>Macros are NOT interpreted
  2192. <LI>If the end of the source file (EOF) is hit, the opened Verbatim Area
  2193. is closed
  2194. </UL>
  2195. </UL>
  2196. <A NAME="mark-separator"></A>
  2197. <H2>Separator Line, Strong Line</H2>
  2198. <UL>
  2199. <LI><B>Description:</B> Identifies a separator or strong line
  2200. <LI><B>Properties:</B> !Multiline, FreeSpaces, !Align, !Nesting
  2201. <LI><B>Contains:</B> -
  2202. <LI><B>Syntax:</B>
  2203. <UL>
  2204. <LI>The separator line can be composed by dashes "-" or underscores "_"
  2205. <LI>The strong line is composed by equals "="
  2206. <LI>Use at least least 20 dashes/underscores/equal signs
  2207. <LI>Optional spaces can be placed at the line start or end
  2208. <LI>Any other characters on the line invalidate the mark
  2209. </UL>
  2210. <LI><B>Details:</B>
  2211. <UL>
  2212. <LI>If the target does not have separator line support, a commented line
  2213. is used instead
  2214. <LI>The strong line may have different behaviors on some targets:
  2215. <UL>
  2216. <LI>A larger separator line
  2217. <LI>A pause on presentation formats, like MagicPoint
  2218. <LI>A page break in paged targets, like LaTeX
  2219. </UL>
  2220. </UL>
  2221. </UL>
  2222. <A NAME="mark-link"></A>
  2223. <H2>Links, Named Links</H2>
  2224. <UL>
  2225. <LI><B>Description:</B> Identifies a remote (Internet) or local link
  2226. <LI><B>Properties:</B> !Multiline, !FreeSpaces, !Align, !Nesting
  2227. <LI><B>Contains:</B> Macros, Raw, Tagged, Image
  2228. <LI><B>Syntax:</B>
  2229. <UL>
  2230. <LI>Any valid internet URL, ftp, news or email address is detected and
  2231. converted automatically
  2232. <LI>The protocol (http, https, ftp) is optional, <CODE>www.likethis.com</CODE>
  2233. <LI>A name can be used for a link: <CODE>[click here www.url.com]</CODE>
  2234. <LI>An image can point to a link: <CODE>[[image.jpg] www.url.com]</CODE>
  2235. <LI>Macros are allowed on the link address: <CODE>[see source %%infile]</CODE>
  2236. <LI>Macros are allowed on the link name: <CODE>[mirror of %%outfile www.url.com]</CODE>
  2237. <LI>All the link specification must be on a single line of the source
  2238. file, no line breaks inside
  2239. </UL>
  2240. <LI><B>Details:</B>
  2241. <UL>
  2242. <LI>If the target does not have link support, they're just underlined
  2243. </UL>
  2244. </UL>
  2245. <A NAME="mark-quote"></A>
  2246. <H2>Quote</H2>
  2247. <UL>
  2248. <LI><B>Description:</B> Identifies a quoted (indented) line
  2249. <LI><B>Properties:</B> Multiline, !FreeSpaces, !Align, Nesting
  2250. <LI><B>Contains:</B> Macros, Beautifiers, Quote, Raw, Tagged, Bars, Links, Image, Comment
  2251. <LI><B>Syntax:</B>
  2252. <UL>
  2253. <LI>A line that starts with a tabulation (TAB) character
  2254. <LI>More TABs at the start increase the quote depth
  2255. <LI>Lists and tables are not allowed inside quote
  2256. </UL>
  2257. <LI><B>Details:</B>
  2258. <UL>
  2259. <LI>If the end of the source file (EOF) is hit, the opened Quote is
  2260. closed
  2261. <LI>Some targets may not support quote nesting, then the subquotes lines
  2262. are moved up to the mother quote level.
  2263. <LI>There is not a limit for subquotes depth. But some targets may have
  2264. restrictions, so the subquotes than are deeper than the maximum level
  2265. are moved up.
  2266. </UL>
  2267. </UL>
  2268. <A NAME="mark-lists"></A>
  2269. <H2>List, Numbered List, Definition List</H2>
  2270. <UL>
  2271. <LI><B>Description:</B> Identifies the start of a list item
  2272. <LI><B>Properties:</B> Multiline, !FreeSpaces, !Align, Nesting
  2273. <LI><B>Contains:</B> Macros, Beautifiers, Lists, Table, Verbatim, Raw, Tagged, Bars, Links, Image, Comment
  2274. <LI><B>Syntax:</B>
  2275. <UL>
  2276. <LI>A line that starts with a dash/plus/colon followed by exactly one
  2277. space
  2278. <LI>The first list char can NOT be a space (exception: definition
  2279. lists)
  2280. <LI>Optional spaces (regular spaces, not TAB) at the line beginning
  2281. define sublists depth (nesting)
  2282. <LI>Sublists end with a less depth item (from parent list) or with an
  2283. empty item
  2284. <LI>All opened lists are closed with two consecutive blank lines
  2285. </UL>
  2286. <LI><B>Details:</B>
  2287. <UL>
  2288. <LI>If the end of the source file (EOF) is hit, all opened lists are
  2289. closed
  2290. <LI>Lists can be mixed, like a definition list inside a numbered list.
  2291. <LI>Some targets may not support list nesting, then the sublists items
  2292. are moved up to the mother list level.
  2293. <LI>There is not a limit for sublists depth. But some targets may have
  2294. restrictions, so the sublists than are deeper than the maximum level
  2295. are moved up.
  2296. </UL>
  2297. </UL>
  2298. <A NAME="mark-image"></A>
  2299. <H2>Image</H2>
  2300. <UL>
  2301. <LI><B>Description:</B> Identifies an image
  2302. <LI><B>Properties:</B> !Multiline, !FreeSpaces, Align, !Nesting
  2303. <LI><B>Contains:</B> Macros
  2304. <LI><B>Syntax:</B>
  2305. <UL>
  2306. <LI>An image filename enclosed between brackets, <CODE>[likethis.jpg]</CODE>
  2307. <LI>The filename must end in an image extension like PNG, JPG, GIF,
  2308. ... (case doesn't matter)
  2309. <LI>Symbols are allowed on the filename, <CODE>[likethis!~1.jpg]</CODE>
  2310. <LI>Macros are allowed on the filename, <CODE>[report-%%date(%Y-%m-%d).png]</CODE>
  2311. <LI>NO spaces allowed on the filename, <CODE>[like this.jpg]</CODE>
  2312. <LI>NO spaces allowed on the brackets, <CODE>[ likethis.jpg ]</CODE>
  2313. </UL>
  2314. <LI><B>Details:</B>
  2315. <UL>
  2316. <LI>If the target does not have image support, the image filename is
  2317. shown inside (parenthesis).
  2318. <LI>The position of the mark on the line defines the image alignment:
  2319. <UL>
  2320. <LI><CODE>[LEFT.jpg]</CODE> blablablabla
  2321. <LI>blablablabla <CODE>[CENTER.jpg]</CODE> blablablabla
  2322. <LI>blablablabla <CODE>[RIGHT.jpg]</CODE>
  2323. </UL>
  2324. </UL>
  2325. </UL>
  2326. <A NAME="mark-table"></A>
  2327. <H2>Table</H2>
  2328. <UL>
  2329. <LI><B>Description:</B> Delimits a table row, with any number of columns
  2330. <LI><B>Properties:</B> Multiline, FreeSpaces, Align, !Nesting
  2331. <LI><B>Contains:</B> Macros, Beautifiers, Raw, Tagged, Links, Image, Comment
  2332. <LI><B>Syntax:</B>
  2333. <UL>
  2334. <LI>A leading pipe "|" identifies a table row
  2335. <LI>A leading double pipe "||" identifies a table title row
  2336. <LI>Leading spaces before first pipe identifies table centered align
  2337. <LI>The fields are separated by the " | " string (space pipe space)
  2338. <LI>A final pipe "|" at the first table row sets visible borders
  2339. <LI>A final pipe "|" at the other table rows are ignored (just cosmetic)
  2340. <LI>Closing a cell with more than one pipe "|" identifies column span:
  2341. "||" for 2 columns, "|||" for 3 and so on
  2342. <LI>Natural spaces inside each cell identifies its alignment
  2343. <LI>Example: <CODE>| table | row | with | five | columns |</CODE>
  2344. </UL>
  2345. <LI><B>Details:</B>
  2346. <UL>
  2347. <LI>All the table row data must be on a single line of the source file,
  2348. no line breaks inside
  2349. <LI>Targets with column-oriented align (like sgml and LaTeX), uses the
  2350. first table row align as the default for the other rows
  2351. <LI>Any non-table line closes the opened table, except comment lines
  2352. <LI>The cell count is flexible, each table row can have a different
  2353. number of cells
  2354. <LI>Currently there's no way to specify row span
  2355. <LI>If the target does not have table support, the table lines are
  2356. considered a Verbatim Area
  2357. </UL>
  2358. </UL>
  2359. <A NAME="mark-raw"></A>
  2360. <H2>Raw, Raw Line, Raw Area</H2>
  2361. <UL>
  2362. <LI><B>Description:</B> Used to "protect" some text from parsing, so marks and macros inside
  2363. it will not be expanded. But escapes are applied.
  2364. <LI><B>Properties:</B> !Multiline, !FreeSpaces, !Align, !Nesting
  2365. <LI><B>Contains:</B> -
  2366. <LI><B>Syntax:</B> <B>Raw:</B>
  2367. <UL>
  2368. <LI>Two double quotes around, <CODE>""like this""</CODE>
  2369. <LI>Marks glued with the contents (no spaces)
  2370. </UL>
  2371. <LI><B>Syntax:</B> <B>Raw Line:</B>
  2372. <UL>
  2373. <LI>A line beginning with 3 consecutive double quotes, <CODE>""" like this</CODE>
  2374. <LI>The double quotes must be at the start of the line, no spaces before
  2375. <LI>Use a space after the double quotes to separate them from the text
  2376. </UL>
  2377. <LI><B>Syntax:</B> <B>Raw Area:</B>
  2378. <UL>
  2379. <LI>A line with exactly 3 consecutive double quotes, followed by text
  2380. lines, followed by another line with exactly 3 consecutive
  2381. double quotes
  2382. <LI>NO spaces allowed before or after the marks
  2383. </UL>
  2384. <LI><B>Details:</B>
  2385. <UL>
  2386. <LI>Marks are NOT interpreted
  2387. <LI>Macros are NOT interpreted
  2388. <LI>If the end of the source file (EOF) is hit, the opened Raw Area is
  2389. closed
  2390. </UL>
  2391. </UL>
  2392. <A NAME="mark-tagged"></A>
  2393. <H2>Tagged, Tagged Line, Tagged Area</H2>
  2394. <UL>
  2395. <LI><B>Description:</B> Used to send text directly to the output, no parsing or escaping is made by txt2tags.
  2396. <LI><B>Properties:</B> !Multiline, !FreeSpaces, !Align, !Nesting
  2397. <LI><B>Contains:</B> -
  2398. <LI><B>Syntax:</B> <B>Tagged:</B>
  2399. <UL>
  2400. <LI>Two apostrophes around, <CODE>''like this''</CODE>
  2401. <LI>Marks glued with the contents (no spaces)
  2402. </UL>
  2403. <LI><B>Syntax:</B> <B>Tagged Line:</B>
  2404. <UL>
  2405. <LI>A line beginning with 3 consecutive apostrophes, <CODE>''' like this</CODE>
  2406. <LI>The apostrophes must be at the start of the line, no spaces before
  2407. <LI>Use a space after the apostrophes to separate them from the text
  2408. </UL>
  2409. <LI><B>Syntax:</B> <B>Tagged Area:</B>
  2410. <UL>
  2411. <LI>A line with exactly 3 consecutive apostrophes, followed by text
  2412. lines, followed by another line with exactly 3 consecutive
  2413. apostrophes
  2414. <LI>NO spaces allowed before or after the marks
  2415. </UL>
  2416. <LI><B>Details:</B>
  2417. <UL>
  2418. <LI>Marks are NOT interpreted
  2419. <LI>Macros are NOT interpreted
  2420. <LI>If the end of the source file (EOF) is hit, the opened Tagged Area is
  2421. closed
  2422. <LI>Use this mark to insert target code. For example, in HTML you could use
  2423. it to insert manual line breaks <CODE>''&lt;br&gt;''</CODE>,
  2424. custom DIVs <CODE>''&lt;div id="myfooter"&gt;''</CODE> or even full blocks of code,
  2425. like the Google Analytics tracking code.
  2426. </UL>
  2427. </UL>
  2428. <A NAME="macros"></A>
  2429. <H1>Part VI - Mastering Macros</H1>
  2430. <P>
  2431. Macros are special purpose keywords, that are expanded on conversion
  2432. time. They are used to insert dynamic information, for example the
  2433. current date or information about the document source.
  2434. </P>
  2435. <P>
  2436. A macro is represented by the <CODE>%%</CODE> chars followed by its name, such as
  2437. <CODE>%%date</CODE>. Some macros do accept an optional formatting string inside
  2438. parenthesis, right after the macro name, such as <CODE>%%date(%Y-%m-%d)</CODE>. This
  2439. format string mixes common text with special directives, identified by a
  2440. percent sign % followed by an identification character. If no format
  2441. string is given, the default format is used.
  2442. </P>
  2443. <TABLE ALIGN="center" BORDER="1">
  2444. <TR>
  2445. <TH>Macro Name</TH>
  2446. <TH>Expands to...</TH>
  2447. <TH>Default Format</TH>
  2448. </TR>
  2449. <TR>
  2450. <TD>%%date</TD>
  2451. <TD>The current date</TD>
  2452. <TD ALIGN="center">%Y%m%d</TD>
  2453. </TR>
  2454. <TR>
  2455. <TD>%%mtime</TD>
  2456. <TD>The source file modification time</TD>
  2457. <TD ALIGN="center">%Y%m%d</TD>
  2458. </TR>
  2459. <TR>
  2460. <TD>%%infile</TD>
  2461. <TD>The source file path</TD>
  2462. <TD ALIGN="center">%f</TD>
  2463. </TR>
  2464. <TR>
  2465. <TD>%%outfile</TD>
  2466. <TD>The output file path</TD>
  2467. <TD ALIGN="center">%f</TD>
  2468. </TR>
  2469. <TR>
  2470. <TD>%%toc</TD>
  2471. <TD>The document TOC (Table of Contents)</TD>
  2472. <TD ALIGN="center">-</TD>
  2473. </TR>
  2474. </TABLE>
  2475. <P>
  2476. General rules:
  2477. </P>
  2478. <UL>
  2479. <LI>The macro name is case-insensitive, so <CODE>%%date</CODE>, <CODE>%%DaTe</CODE> and
  2480. <CODE>%%DATE</CODE> are identical
  2481. <LI>Macros are valid at the document Header Area and Body Area, except
  2482. %%toc that is valid on Body Area only
  2483. <LI>A macro starts the Body Area if it is found in the Config Area
  2484. <LI>A macro can be placed at any part of the line, including various per line
  2485. (except %%toc, valid when alone in a line)
  2486. <LI>A macro can be used inside links and images marks (except %%toc)
  2487. <LI>Macros are not expanded in Titles, Verbatim, Raw and Tagged Areas
  2488. </UL>
  2489. <P>
  2490. Full example (bold text are expanded macros):
  2491. </P>
  2492. <P>
  2493. This is the Txt2tags User Guide, converted to <B>html</B>
  2494. by txt2tags from the <B>userguide.t2t</B> source file. The conversion
  2495. was done at <B>2012-05-28 10:40:36</B>, but the last change on the
  2496. source document was made on <B>2012-05-28 10:39:58</B>. Both
  2497. source and converted file reside on the <B>userguide</B>
  2498. directory.
  2499. </P>
  2500. <A NAME="macro-date"></A>
  2501. <H2>%%date</H2>
  2502. <P>
  2503. The <CODE>%%date</CODE> macro expands to the current date and time. It is very
  2504. useful on the document headers or footer, to register the date when the
  2505. document was generated. To expand to the source document last
  2506. modification time, see the <A HREF="#macro-mtime">%%mtime macro</A>.
  2507. </P>
  2508. <P>
  2509. This macros accepts several formatting directives. The full list can be
  2510. found in the
  2511. <A HREF="http://docs.python.org/library/time.html">Python site</A>.
  2512. Here are the most commonly used:
  2513. </P>
  2514. <TABLE ALIGN="center" BORDER="1">
  2515. <TR>
  2516. <TH>Directive</TH>
  2517. <TH>Description</TH>
  2518. </TR>
  2519. <TR>
  2520. <TD ALIGN="center">%a</TD>
  2521. <TD>Locale's abbreviated weekday name.</TD>
  2522. </TR>
  2523. <TR>
  2524. <TD ALIGN="center">%A</TD>
  2525. <TD>Locale's full weekday name.</TD>
  2526. </TR>
  2527. <TR>
  2528. <TD ALIGN="center">%b</TD>
  2529. <TD>Locale's abbreviated month name.</TD>
  2530. </TR>
  2531. <TR>
  2532. <TD ALIGN="center">%B</TD>
  2533. <TD>Locale's full month name.</TD>
  2534. </TR>
  2535. <TR>
  2536. <TD ALIGN="center">%c</TD>
  2537. <TD>Locale's appropriate date and time representation.</TD>
  2538. </TR>
  2539. <TR>
  2540. <TD ALIGN="center">%d</TD>
  2541. <TD>Day of the month as a decimal number [01,31].</TD>
  2542. </TR>
  2543. <TR>
  2544. <TD ALIGN="center">%H</TD>
  2545. <TD>Hour (24-hour clock) as a decimal number [00,23].</TD>
  2546. </TR>
  2547. <TR>
  2548. <TD ALIGN="center">%I</TD>
  2549. <TD>Hour (12-hour clock) as a decimal number [01,12].</TD>
  2550. </TR>
  2551. <TR>
  2552. <TD ALIGN="center">%m</TD>
  2553. <TD>Month as a decimal number [01,12].</TD>
  2554. </TR>
  2555. <TR>
  2556. <TD ALIGN="center">%M</TD>
  2557. <TD>Minute as a decimal number [00,59].</TD>
  2558. </TR>
  2559. <TR>
  2560. <TD ALIGN="center">%p</TD>
  2561. <TD>Locale's equivalent of either AM or PM.</TD>
  2562. </TR>
  2563. <TR>
  2564. <TD ALIGN="center">%S</TD>
  2565. <TD>Second as a decimal number [00,61]. (1)</TD>
  2566. </TR>
  2567. <TR>
  2568. <TD ALIGN="center">%x</TD>
  2569. <TD>Locale's appropriate date representation.</TD>
  2570. </TR>
  2571. <TR>
  2572. <TD ALIGN="center">%X</TD>
  2573. <TD>Locale's appropriate time representation.</TD>
  2574. </TR>
  2575. <TR>
  2576. <TD ALIGN="center">%y</TD>
  2577. <TD>Year without century as a decimal number [00,99].</TD>
  2578. </TR>
  2579. <TR>
  2580. <TD ALIGN="center">%Y</TD>
  2581. <TD>Year with century as a decimal number.</TD>
  2582. </TR>
  2583. <TR>
  2584. <TD ALIGN="center">%%</TD>
  2585. <TD>A literal "%" character.</TD>
  2586. </TR>
  2587. </TABLE>
  2588. <P>
  2589. Examples:
  2590. </P>
  2591. <TABLE ALIGN="center" BORDER="1">
  2592. <TR>
  2593. <TH>Macro</TH>
  2594. <TH>--&gt;</TH>
  2595. <TH>Results for on 2012, May 28 at 10:40</TH>
  2596. </TR>
  2597. <TR>
  2598. <TD>%%date(Converted on: %c)</TD>
  2599. <TD ALIGN="center">--&gt;</TD>
  2600. <TD>Converted on: Mon May 28 10:40:36 2012</TD>
  2601. </TR>
  2602. <TR>
  2603. <TD>%%date(%Y-%m-%d)</TD>
  2604. <TD ALIGN="center">--&gt;</TD>
  2605. <TD>2012-05-28</TD>
  2606. </TR>
  2607. <TR>
  2608. <TD>%%date(%I:%M %p)</TD>
  2609. <TD ALIGN="center">--&gt;</TD>
  2610. <TD>10:40 AM</TD>
  2611. </TR>
  2612. <TR>
  2613. <TD>%%date(Today is %A, on %B.)</TD>
  2614. <TD ALIGN="center">--&gt;</TD>
  2615. <TD>Today is Monday, on May.</TD>
  2616. </TR>
  2617. </TABLE>
  2618. <A NAME="macro-mtime"></A>
  2619. <H2>%%mtime</H2>
  2620. <P>
  2621. The <CODE>%%mtime</CODE> macro expands to last modification time of the source
  2622. document. It is useful to register when the file was last changed.
  2623. This macro is a "sister" of the <A HREF="#macro-date">%%date macro</A>, so it
  2624. accepts exactly the same formatting directives.
  2625. </P>
  2626. <P>
  2627. As an example, this User Guide source file was last edited on
  2628. <B>Mon May 28 10:39:58 2012</B>. This date was expanded from <CODE>%%mtime(%c)</CODE>.
  2629. </P>
  2630. <A NAME="macro-infile"></A>
  2631. <H2>%%infile</H2>
  2632. <P>
  2633. The <CODE>%%infile</CODE> macro expands to the source file location on the
  2634. system. It is useful to make those "<I>see the source of this file</I>"
  2635. links on HTML pages. Providing such link is a friendly attitude with
  2636. beginners, so they can use your source as a sample for their own page.
  2637. </P>
  2638. <P>
  2639. This macro accepts the following formatting directives:
  2640. </P>
  2641. <TABLE ALIGN="center" BORDER="1">
  2642. <TR>
  2643. <TH>%&lt;char&gt;</TH>
  2644. <TH>Description</TH>
  2645. <TH>Output for this User Guide source</TH>
  2646. </TR>
  2647. <TR>
  2648. <TD ALIGN="center">%f</TD>
  2649. <TD>File name</TD>
  2650. <TD>userguide.t2t</TD>
  2651. </TR>
  2652. <TR>
  2653. <TD ALIGN="center">%F</TD>
  2654. <TD>File name (without extension)</TD>
  2655. <TD>userguide</TD>
  2656. </TR>
  2657. <TR>
  2658. <TD ALIGN="center">%e</TD>
  2659. <TD>File extension</TD>
  2660. <TD>t2t</TD>
  2661. </TR>
  2662. <TR>
  2663. <TD ALIGN="center">%p</TD>
  2664. <TD>Absolute file path</TD>
  2665. <TD>/Users/thierry/Logiciels/txt2tags/dev/txt2tags/doc/English/userguide/userguide.t2t</TD>
  2666. </TR>
  2667. <TR>
  2668. <TD ALIGN="center">%d</TD>
  2669. <TD>File path (directories only)</TD>
  2670. <TD>/Users/thierry/Logiciels/txt2tags/dev/txt2tags/doc/English/userguide</TD>
  2671. </TR>
  2672. <TR>
  2673. <TD ALIGN="center">%D</TD>
  2674. <TD>File path (parent dir only)</TD>
  2675. <TD>userguide</TD>
  2676. </TR>
  2677. <TR>
  2678. <TD ALIGN="center">%%</TD>
  2679. <TD>Literal percent char</TD>
  2680. <TD>%</TD>
  2681. </TR>
  2682. </TABLE>
  2683. <P>
  2684. Examples:
  2685. </P>
  2686. <TABLE ALIGN="center" BORDER="1">
  2687. <TR>
  2688. <TH>Source</TH>
  2689. <TH>--&gt;</TH>
  2690. <TH>Expanded</TH>
  2691. </TR>
  2692. <TR>
  2693. <TD>This Guide parent dir is %%infile(%D).</TD>
  2694. <TD ALIGN="center">--&gt;</TD>
  2695. <TD>This Guide parent dir is userguide.</TD>
  2696. </TR>
  2697. <TR>
  2698. <TD>I do use the %%infile(%e) file extension.</TD>
  2699. <TD ALIGN="center">--&gt;</TD>
  2700. <TD>I do use the t2t file extension.</TD>
  2701. </TR>
  2702. <TR>
  2703. <TD>[See the source %%infile]</TD>
  2704. <TD ALIGN="center">--&gt;</TD>
  2705. <TD><A HREF="userguide.t2t">See the source</A></TD>
  2706. </TR>
  2707. <TR>
  2708. <TD>Converted to XHTML, I'll be %%infile(%F).xhtml</TD>
  2709. <TD ALIGN="center">--&gt;</TD>
  2710. <TD>Converted to XHTML, I'll be userguide.xhtml</TD>
  2711. </TR>
  2712. </TABLE>
  2713. <BLOCKQUOTE>
  2714. <B>Note:</B> The macro is expanded to "-" if the source file is STDIN.
  2715. </BLOCKQUOTE>
  2716. <A NAME="macro-outfile"></A>
  2717. <H2>%%outfile</H2>
  2718. <P>
  2719. The <CODE>%%outfile</CODE> macro expands to the converted file location on the
  2720. system. It is useful to its name inside the document Body or Headers.
  2721. This macro is a sister of the <A HREF="#macro-infile">%%infile macro</A> and
  2722. do accept exactly the same formatting directives.
  2723. </P>
  2724. <P>
  2725. Examples:
  2726. </P>
  2727. <TABLE ALIGN="center" BORDER="1">
  2728. <TR>
  2729. <TH>Source</TH>
  2730. <TH>--&gt;</TH>
  2731. <TH>Expanded</TH>
  2732. </TR>
  2733. <TR>
  2734. <TD>You are reading the %%outfile file.</TD>
  2735. <TD ALIGN="center">--&gt;</TD>
  2736. <TD>You are reading the userguide.html file.</TD>
  2737. </TR>
  2738. <TR>
  2739. <TD>txt2tags -t %%outfile(%e) -i %%infile -o %%outfile</TD>
  2740. <TD ALIGN="center">--&gt;</TD>
  2741. <TD>txt2tags -t html -i userguide.t2t -o userguide.html</TD>
  2742. </TR>
  2743. </TABLE>
  2744. <BLOCKQUOTE>
  2745. <B>Note:</B> The macro is expanded to "-" if the output file is STDOUT.
  2746. </BLOCKQUOTE>
  2747. <A NAME="macro-toc"></A>
  2748. <H2>%%toc</H2>
  2749. <P>
  2750. The <CODE>%%toc</CODE> macro expands to the document's Table of Contents. It is
  2751. useful for you to specify exactly where you want the TOC to be placed.
  2752. You can even use the macro more than one time and place the TOC at the
  2753. end of the document also, for example. This Guide is using %%toc
  2754. to position the TOC.
  2755. </P>
  2756. <P>
  2757. Different from the other macros, this one does not accept a format
  2758. string and has its own special rules:
  2759. </P>
  2760. <UL>
  2761. <LI>Valid at the document Body Area only
  2762. <LI>Must be alone on the line (leading and trailing spaces are allowed)
  2763. <LI>Must be used together with --toc command line option, or it will be
  2764. ignored
  2765. <LI>The default automatic TOC positioning/formatting is disabled when a
  2766. %%toc is found
  2767. </UL>
  2768. <A NAME="settings"></A>
  2769. <H1>Part VII - Mastering Settings</H1>
  2770. <P>
  2771. Settings are special configurations placed at the source document's
  2772. Config Area that can affect the conversion process. The Settings are all
  2773. optional. The average user can live fine without them. But they are
  2774. addictive, if you start using them, you'll never stop :)
  2775. </P>
  2776. <P>
  2777. Setting lines are <I>special comment lines</I>, marked by a leading
  2778. identifier ("!") that makes them different from plain comments. The
  2779. syntax is just as simple as variable setting, composed by a keyword
  2780. and a value, separated from each by a colon (":").
  2781. </P>
  2782. <BLOCKQUOTE>
  2783. <B>%! keyword : value</B>
  2784. </BLOCKQUOTE>
  2785. <P>
  2786. Syntax details:
  2787. </P>
  2788. <UL>
  2789. <LI>The exclamation mark must be placed together with the comment char
  2790. (%!), no spaces between them.
  2791. <P></P>
  2792. <LI>The spaces around the keyword and the separator are optional.
  2793. <P></P>
  2794. <LI>Keywords are case insensitive (case doesn't matter).
  2795. </UL>
  2796. <P>
  2797. Rules:
  2798. </P>
  2799. <UL>
  2800. <LI>Settings are valid only inside the Config Area, and are considered
  2801. plain comments if found on the document Body.
  2802. <P></P>
  2803. <LI>If the same keyword appears more than one time on the Config Area, the
  2804. last found will be the one used. Exception: options, preproc and
  2805. postproc, which are cumulative.
  2806. <P></P>
  2807. <LI>A setting line with an invalid keyword will be considered a plain
  2808. comment line.
  2809. <P></P>
  2810. <LI>This settings have precedence over RC file, but not on command line
  2811. options.
  2812. </UL>
  2813. <A NAME="setting-target"></A>
  2814. <H2>%!target</H2>
  2815. <P>
  2816. Using the target setting, a default target format is defined for the
  2817. document:
  2818. </P>
  2819. <PRE>
  2820. %!target: html
  2821. </PRE>
  2822. <P>
  2823. This way the user can just call
  2824. </P>
  2825. <PRE>
  2826. $ txt2tags file.t2t
  2827. </PRE>
  2828. <P>
  2829. And the conversion will be done, to the specified target.
  2830. </P>
  2831. <P>
  2832. The target setting does not support optional target specification.
  2833. That doesn't make sense, such as <CODE>%!target(tex): html</CODE>.
  2834. </P>
  2835. <A NAME="setting-options"></A>
  2836. <H2>%!options</H2>
  2837. <P>
  2838. Writing long command lines every time you need to convert a document
  2839. is boring and error prone. The Options setting let the user save
  2840. all the converting options together with the source document. This also
  2841. ensures that the document will always be converted the same way, with
  2842. the same options.
  2843. </P>
  2844. <P>
  2845. Just write it with no syntax errors, as you were on the real command
  2846. line. But omit the "txt2tags" program call on the beginning, the target
  2847. specification and the source filename from the ending.
  2848. </P>
  2849. <P>
  2850. For example, if you do use this command line to convert your document:
  2851. </P>
  2852. <PRE>
  2853. $ txt2tags -t html --toc --toc-level 2 --enum-title file.t2t
  2854. </PRE>
  2855. <P>
  2856. You can save yourself from typing pain using this Options setting inside
  2857. the document source:
  2858. </P>
  2859. <PRE>
  2860. %!target: html
  2861. %!options(html): --toc --toc-level 2 --enum-title
  2862. </PRE>
  2863. <P>
  2864. Now the options are registered inside the source file, so you can convert it with this simple command:
  2865. </P>
  2866. <PRE>
  2867. $ txt2tags file.t2t
  2868. </PRE>
  2869. <BLOCKQUOTE>
  2870. Tip for Vim users: To convert the document right inside the editor, just run <CODE>:!txt2tags %</CODE>
  2871. </BLOCKQUOTE>
  2872. <A NAME="setting-encoding"></A>
  2873. <H2>%!encoding</H2>
  2874. <P>
  2875. The Encoding setting is needed by non-english writers, who uses
  2876. accented letters and other locale specific details, so the target
  2877. document <I>Character Set</I> must be customized (if allowed).
  2878. </P>
  2879. <P>
  2880. The valid values for the Encoding setting are the same charset names
  2881. valid for HTML documents, like <I>iso-8859-1</I> and <I>koi8-r</I>. If
  2882. you're not sure which encoding you should use, try <I>utf-8</I>. If that doesn't work,
  2883. <A HREF="http://www.iana.org/assignments/character-sets">this complete (and long!) list</A>
  2884. should help.
  2885. </P>
  2886. <P>
  2887. The LaTeX target uses alias names for encoding. This is not a problem
  2888. for the user, because txt2tags translate the names internally. Some
  2889. examples:
  2890. </P>
  2891. <TABLE ALIGN="center" BORDER="1">
  2892. <TR>
  2893. <TH>txt2tags/HTML</TH>
  2894. <TH>&gt;</TH>
  2895. <TH>LaTeX</TH>
  2896. </TR>
  2897. <TR>
  2898. <TD>windows-1250</TD>
  2899. <TD>&gt;&gt;&gt;</TD>
  2900. <TD>cp1250</TD>
  2901. </TR>
  2902. <TR>
  2903. <TD>windows-1252</TD>
  2904. <TD>&gt;&gt;&gt;</TD>
  2905. <TD>cp1252</TD>
  2906. </TR>
  2907. <TR>
  2908. <TD>ibm850</TD>
  2909. <TD>&gt;&gt;&gt;</TD>
  2910. <TD>cp850</TD>
  2911. </TR>
  2912. <TR>
  2913. <TD>ibm852</TD>
  2914. <TD>&gt;&gt;&gt;</TD>
  2915. <TD>cp852</TD>
  2916. </TR>
  2917. <TR>
  2918. <TD>iso-8859-1</TD>
  2919. <TD>&gt;&gt;&gt;</TD>
  2920. <TD>latin1</TD>
  2921. </TR>
  2922. <TR>
  2923. <TD>iso-8859-2</TD>
  2924. <TD>&gt;&gt;&gt;</TD>
  2925. <TD>latin2</TD>
  2926. </TR>
  2927. <TR>
  2928. <TD>koi8-r</TD>
  2929. <TD>&gt;&gt;&gt;</TD>
  2930. <TD>koi8-r</TD>
  2931. </TR>
  2932. </TABLE>
  2933. <P>
  2934. If the value is unknown to txt2tags, it will be passed "as is",
  2935. allowing the user to specify custom encodings.
  2936. </P>
  2937. <A NAME="setting-preproc"></A>
  2938. <H2>%!preproc</H2>
  2939. <P>
  2940. The PreProc is an input filter that changes the Body Area of the source document. It is a "find
  2941. and replace" feature, applied right after the line is read from the
  2942. document source, before any parsing by txt2tags.
  2943. </P>
  2944. <P>
  2945. It is useful to define some abbreviations for common typed text, as:
  2946. </P>
  2947. <PRE>
  2948. %!preproc: JJS "John J. Smith"
  2949. %!preproc: RELEASE_DATE "2003-05-01"
  2950. %!preproc: BULLET "[images/tiny/bullet_blue.png]"
  2951. </PRE>
  2952. <P>
  2953. So the user can write a line like:
  2954. </P>
  2955. <PRE>
  2956. Hi, I'm JJS. Today is RELEASE_DATE.
  2957. </PRE>
  2958. <P>
  2959. And txt2tags will "see" this line as:
  2960. </P>
  2961. <PRE>
  2962. Hi, I'm John J. Smith. Today is 2003-05-01.
  2963. </PRE>
  2964. <P>
  2965. This filter is a component that acts between the document author
  2966. and the txt2tags conversion. It's like a first conversion before the
  2967. "real" one. This behavior is similar to an external Sed/Perl filter,
  2968. called this way:
  2969. </P>
  2970. <PRE>
  2971. $ cat file.t2t | preproc-script.sh | txt2tags -
  2972. </PRE>
  2973. <P>
  2974. So the txt2tags parsing will begin after all the PreProc substitutions
  2975. were applied.
  2976. </P>
  2977. <BLOCKQUOTE>
  2978. <B>Note:</B> Remember that the preprocessing is applied only to the BODY of the source document, not including the Header Area and Config Area.
  2979. </BLOCKQUOTE>
  2980. <A NAME="setting-postproc"></A>
  2981. <H2>%!postproc</H2>
  2982. <P>
  2983. The PostProc is an output filter that changes the converted document. It is a
  2984. "find and replace" feature, applied after all txt2tags parsing and
  2985. processing is done.
  2986. </P>
  2987. <P>
  2988. It is useful to do some refinements on the generated document, change
  2989. tags and add extra text or tags. Quick samples:
  2990. </P>
  2991. <PRE>
  2992. %!postproc(html): '&lt;BODY.*?&gt;' '&lt;BODY BGCOLOR="green"&gt;'
  2993. %!postproc(tex) : "\\newpage" ""
  2994. </PRE>
  2995. <P>
  2996. These filters change the background color of the HTML page and remove
  2997. the page breaks on the LaTeX target.
  2998. </P>
  2999. <P>
  3000. The PostProc rules are just like an external Sed/Perl filter, called
  3001. this way:
  3002. </P>
  3003. <PRE>
  3004. $ txt2tags -t html -o- file.t2t | postproc-script.sh &gt; file.html
  3005. </PRE>
  3006. <P>
  3007. Before this feature was introduced, it was very common to have little
  3008. scripts to "adjust" the txt2tags results. These scripts were in fact
  3009. just lots of sed (or alike) commands, to do "substitute this for that"
  3010. actions. Now this replacement strings can be saved together with the
  3011. document text, and the plus is to use the Python powerful Regular
  3012. Expression machine to find patterns.
  3013. </P>
  3014. <A NAME="setting-style"></A>
  3015. <H2>%!style</H2>
  3016. <UL>
  3017. <LI>Useful in HTML and XHTML targets, it defines a CSS file for the target
  3018. document.
  3019. <P></P>
  3020. <LI>Useful in LaTeX target, to load <CODE>\usepackage</CODE> modules.
  3021. <P></P>
  3022. <LI>The same effect is achieved with the command line option <CODE>--style</CODE>.
  3023. <P></P>
  3024. <LI>The --style option is stronger than %!style. If both are used, --style
  3025. wins.
  3026. </UL>
  3027. <A NAME="setting-specific"></A>
  3028. <H2>Defining a Setting for a Specific Target</H2>
  3029. <P>
  3030. All the settings (except %!target) can be glued with a specific target
  3031. using the <CODE>%!key(target): value</CODE> syntax. This way user can define
  3032. different config for different targets.
  3033. </P>
  3034. <P>
  3035. This is specially useful in the pre/postproc filters, but is applicable
  3036. to all settings. For example, defining different styles for HTML and
  3037. LaTeX:
  3038. </P>
  3039. <PRE>
  3040. %!style(html): fancy.css
  3041. %!style(tex) : amssymb
  3042. </PRE>
  3043. <P>
  3044. For the options setting it's very useful to adjust the converted
  3045. document:
  3046. </P>
  3047. <PRE>
  3048. %!target: sgml
  3049. %!options(sgml): --toc
  3050. %!options(html): --style foo.css
  3051. %!options(txt ): --toc-only --toc-level 2
  3052. </PRE>
  3053. <P>
  3054. In this example, the default target is Sgml and it will use TOC. If the
  3055. user run <CODE>txt2tags -t html file.t2t</CODE>, only the HTML options will be
  3056. used, so the converted file will use "foo.css" style file and will
  3057. have no TOC.
  3058. </P>
  3059. <A NAME="filters-details"></A>
  3060. <H2>Details for PreProc and PostProc Filters</H2>
  3061. <UL>
  3062. <LI>Filters are a "find and replace" feature (think SED)
  3063. <P></P>
  3064. <LI>Filters do not follow the "last found, one used" schema, they're
  3065. cumulative. You can define as many filters as needed, with no limit.
  3066. They will be applied on the same order as defined.
  3067. <P></P>
  3068. <LI>Different from other settings, both the target specific filters and
  3069. the generic ones (all targets) are used. On the following example,
  3070. both filters are used on the HTML target:
  3071. <PRE>
  3072. %!postproc : this that
  3073. %!postproc(html): that other
  3074. </PRE>
  3075. <P></P>
  3076. <LI>The filters must receive exactly TWO arguments
  3077. <P></P>
  3078. <LI>Special escapes as <CODE>\n</CODE> (line break) and <CODE>\t</CODE> (tabulation) are
  3079. interpreted
  3080. <P></P>
  3081. <LI>To delete some text, change it by an empty string
  3082. <PRE>
  3083. %!postproc: "undesired string" ""
  3084. </PRE>
  3085. <P></P>
  3086. <LI>To avoid problems, always use the explicit target form when using
  3087. PostProc to change tags: <CODE>%!postproc(target): &lt;this&gt; &lt;that&gt;</CODE>
  3088. <P></P>
  3089. <LI>PREproc is applied right after the line is read, and POSTproc is
  3090. applied after all the parsing was made. This is similar to
  3091. (UUOC ahead):
  3092. <PRE>
  3093. $ cat file.t2t | preproc.sh | txt2tags | postproc.sh
  3094. </PRE>
  3095. <P></P>
  3096. <LI>The first part of a filter (the "search for" part) is not read as a
  3097. regular string, but as a Regular Expression pattern. If you don't know
  3098. what these expressions do, don't worry, you may never have to. Just
  3099. keep in mind that you will need to "escape" some characters to use
  3100. them. To escape is to prefix the character with a backslash "\". Here
  3101. is the list:
  3102. <PRE>
  3103. \* \+ \. \^ \$ \? \( \) \{ \[ \| \\
  3104. </PRE>
  3105. <P></P>
  3106. <LI>Python Regular Expressions are available! They're similar to Perl
  3107. Regexes (PCRE). Example: Change all opening and closing "B" tags to
  3108. "STRONG" on HTML:
  3109. <PRE>
  3110. %!postproc(html): '(&lt;/?)B&gt;' '\1STRONG&gt;'
  3111. </PRE>
  3112. <P></P>
  3113. <LI>The filter arguments can be passed on 3 ways:
  3114. <OL>
  3115. <LI>A single unquoted word such as FOO (no spaces)
  3116. <LI>A string double quoted such as "FOO"
  3117. <LI>A string single quoted such as 'FOO'
  3118. <P></P>
  3119. </OL>
  3120. <LI>If your pattern has double quotes, protect it with single quotes and
  3121. vice-versa. Some valid samples:
  3122. <PRE>
  3123. %!postproc: PATT REPLACEMENT
  3124. %!postproc: "PATT" "REPLACEMENT"
  3125. %!postproc: 'PATT' 'REPLACEMENT'
  3126. %!postproc: PATT "REPLACEMENT"
  3127. %!postproc: "PATT" 'REPLACEMENT'
  3128. </PRE>
  3129. </UL>
  3130. <A NAME="black-magic"></A>
  3131. <H1>Part VIII - Black Magic</H1>
  3132. <P>
  3133. This chapter is really not recommended for newbies. It demonstrates how
  3134. to do strange things with txt2tags filters, abusing of complex
  3135. patterns and Regular Expressions.
  3136. </P>
  3137. <BLOCKQUOTE>
  3138. <B>BEWARE!</B> The following procedures are NOT encouraged and can
  3139. break things. Even some text from the document source can be
  3140. lost on the conversion process, not appearing on the target
  3141. document. Just use these tactics if you really need them and
  3142. know what you are doing.
  3143. </BLOCKQUOTE>
  3144. <BLOCKQUOTE>
  3145. <B>Note:</B> Filters are a powerful feature, but can be dangerous!
  3146. </BLOCKQUOTE>
  3147. <BLOCKQUOTE>
  3148. <B>Note:</B> Bad filters do generate unexpected results.
  3149. </BLOCKQUOTE>
  3150. <P>
  3151. Keep that in mind, please.
  3152. </P>
  3153. <A NAME="postproc-multiline"></A>
  3154. <H2>Inserting Multiple Lines with %!postproc (such as CSS rules)</H2>
  3155. <P>
  3156. In filters, the replacement pattern can include multiple lines using the
  3157. <CODE>\n</CODE> line break char.
  3158. </P>
  3159. <P>
  3160. This can be handy for including really short CSS rules on HTML target,
  3161. with no need to create a separate file:
  3162. </P>
  3163. <PRE>
  3164. %!postproc: &lt;HEAD&gt; '&lt;HEAD&gt;\n&lt;STYLE TYPE="text/css"&gt;\n&lt;/STYLE&gt;'
  3165. %!postproc: (&lt;/STYLE&gt;) 'body { margin:3em ;} \n\1'
  3166. %!postproc: (&lt;/STYLE&gt;) 'a { text-decoration:none ;} \n\1'
  3167. %!postproc: (&lt;/STYLE&gt;) 'pre,code { background-color:#ffffcc ;} \n\1'
  3168. %!postproc: (&lt;/STYLE&gt;) 'th { background-color:yellow ;} \n\1'
  3169. </PRE>
  3170. <P>
  3171. All the filters are tied to the first one, by replacing a string that it
  3172. has inserted. So a single "&lt;HEAD&gt;" turns to:
  3173. </P>
  3174. <PRE>
  3175. &lt;HEAD&gt;
  3176. &lt;STYLE TYPE="text/css"&gt;
  3177. body { margin:3em ;}
  3178. a { text-decoration:none ;}
  3179. pre,code { background-color:#ffffcc ;}
  3180. th { background-color:yellow ;}
  3181. &lt;/STYLE&gt;
  3182. </PRE>
  3183. <A NAME="target-specific-contents"></A>
  3184. <H2>Creating "Target-Specific" Contents with %!preproc</H2>
  3185. <P>
  3186. Sometimes you need to insert some text on a specific target, but not on
  3187. the others. This kind of strange behavior can be done using some
  3188. PreProc tricks.
  3189. </P>
  3190. <P>
  3191. The idea is to insert this extra text on the document source as
  3192. comments, but mark it in a way that a target-specific filter will
  3193. "uncomment" those lines.
  3194. </P>
  3195. <P>
  3196. For example, if an extra paragraph must be added only in HTML target.
  3197. Place the text as special comments, like this:
  3198. </P>
  3199. <PRE>
  3200. %html% This HTML page is Powered by [txt2tags http://txt2tags.org].
  3201. %html% See the source TXT file [here source.t2t].
  3202. </PRE>
  3203. <P>
  3204. As those lines start with <CODE>%</CODE>, they are plain comments lines and will be
  3205. ignored. But when adding this special filter:
  3206. </P>
  3207. <PRE>
  3208. %preproc(html): '^%html% ' ''
  3209. </PRE>
  3210. <P>
  3211. The leading string is removed and those lines will be "activated", not
  3212. being comments anymore. As a explicit target config, this filter will be
  3213. processed for HTML targets only.
  3214. </P>
  3215. <A NAME="creating-marks"></A>
  3216. <H2>Changing Txt2tags Marks with %!preproc</H2>
  3217. <P>
  3218. Being a Regular Expressions guru, the user can customize the document
  3219. source syntax, changing the txt2tags default marks to some he find more
  3220. comfortable.
  3221. </P>
  3222. <P>
  3223. For example, a leading TAB is the Quotation mark. If the user doesn't
  3224. like it, or his text editor has some strange relationship with TABs, he
  3225. can define a new mark for Quoted text. Say a leading "&gt;&gt;&gt; " was his
  3226. choice. Then he will do this simple filter:
  3227. </P>
  3228. <PRE>
  3229. %!preproc: '^&gt;&gt;&gt; ' '\t'
  3230. </PRE>
  3231. <P>
  3232. And on the document source, the quoted text will be something like:
  3233. </P>
  3234. <PRE>
  3235. &gt;&gt;&gt; This is a quoted text.
  3236. &gt;&gt;&gt; The user defined this strange mark.
  3237. &gt;&gt;&gt; But they will be converted to TABs by PreProc.
  3238. </PRE>
  3239. <P>
  3240. Before the parsing begins, the strange "&gt;&gt;&gt; " will be converted to
  3241. TABs and txt2tags will recognize the Quote mark.
  3242. </P>
  3243. <BLOCKQUOTE>
  3244. <B>BEWARE!</B> Extreme PreProc rules could eventually
  3245. change the entire marks syntax, even generating conflicts
  3246. between marks. Be really really careful when doing this.
  3247. </BLOCKQUOTE>
  3248. <H1>The End</H1>
  3249. <P>
  3250. Thanks for reading! :)
  3251. </P>
  3252. <P>
  3253. <A HREF="http://txt2tags.org">http://txt2tags.org</A>
  3254. </P>
  3255. <P>
  3256. (<A HREF="userguide.t2t">see source</A>)
  3257. <IMG ALIGN="middle" SRC="../../img/t2tpowered.png" BORDER="0" ALT="">
  3258. </P>
  3259. </DIV>
  3260. <!-- html code generated by txt2tags 2.6 (http://txt2tags.org) -->
  3261. <!-- cmdline: txt2tags -t html userguide.t2t -->
  3262. </BODY></HTML>