/doc/English/userguide/userguide.t2t

http://txt2tags.googlecode.com/ · Unknown · 2382 lines · 1736 code · 646 blank · 0 comment · 0 complexity · 624b7a76d66597c9069fb55d09b7b17e MD5 · raw file

Large files are truncated click here to view the full file

  1. Txt2tags User Guide
  2. Aurelio, %%mtime(%c)
  3. %!target: html
  4. %!options: --toc --toc-level 2 --css-sugar
  5. % TRANSLATOR:
  6. % - The HTML output is optimized for the htmldoc tool
  7. % - Just comment the following lines when translating
  8. %!options: --css-sugar --no-toc --style userguide.css
  9. %!postproc(html): '<HTML>' '<!-- This document was generated from userguide.t2t -->\n<HTML>'
  10. %!postproc: '<H1>Txt2tags User Guide.*' ''
  11. %!postproc: '<H3>Aurelio, .*' ''
  12. % TRANSLATOR:
  13. % - Don't worry about the PDF cover page
  14. % - Don't worry about PDF at all, translate and check on HTML
  15. % - Don't worry about the images
  16. % TRANSLATOR:
  17. % You can take new screenshots and make new images for the program
  18. % interface and "first conversion" section. Remember to send them
  19. % to the author!
  20. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  21. %%% activate those lines when converting to HTML for PDF generation
  22. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  23. %%% htmldoc does TOC
  24. %pdf%!options(html): --no-toc --no-css-sugar -o userguide-pdf.html
  25. %%% mask the 'nopdf' marks so they will not be removed
  26. %pdf%!preproc(html): ^%nopdf %yespdf
  27. %%% border for all images
  28. %pdf%!postproc: '(<IMG [^>]*BORDER)="0"' '\1="1"'
  29. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  30. % easy way to change all image locations once, when changing file location
  31. %!preproc: IMGPATH .
  32. % TRANSLATOR
  33. % - Please translate the following macro contents and leave them alone
  34. % - Remember they are expanded in conversion time, don't remove them
  35. % normalizing common text
  36. %!preproc: CONFAREA Config Area
  37. %!preproc: HEADAREA Header Area
  38. %!preproc: BODYAREA Body Area
  39. %!preproc: MARKPROP **Properties:**
  40. %!preproc: MARKCONT **Contains:**
  41. %!preproc: MARKDESC **Description:**
  42. %!preproc: MARKSYN **Syntax:**
  43. %!preproc: MARKDET **Details:**
  44. %!preproc: NOMARKS Marks are NOT interpreted
  45. %!preproc: NOMACRO Macros are NOT interpreted
  46. %!preproc: URLMARKUP URLWEBSITE/markup.html
  47. %!preproc: URLWEBSITE http://txt2tags.org
  48. %!postproc: URLWEBSITE http://txt2tags.org
  49. % activate the areas disabled on the PDF version
  50. %!preproc(html): ^%nopdf ''
  51. % remove separator lines and strong lines
  52. %!preproc(html): '^ *--------*' ''
  53. %!preproc(html): '^ *========*' ''
  54. % highlight NEW topic on TOC
  55. %%!postproc(html): '(<LI>.*Mastering Macros</A>)$' '\1 <b>[NEW!]</b>'
  56. %%% Little clean up for less large tables
  57. %!postproc: /pessoal/sourceforge.net ''
  58. % 26/Nov/2003: revised by anamimts
  59. % 26/Jun/2004: updated to v2, new embedded CSS
  60. % 17/Jul/2004: revised by anamimts
  61. % 01/Nov/2004: updated to v2.0 and 2.1, new chapters, PDF version
  62. % 31/Aug/2006: little changes to use htmldoc for splitted HTML
  63. % TODO Mastering Options [option-help], [option-css-sugar], ...
  64. ========================================================================
  65. %%nopdf "Hi! I'm the txt2tags User Guide. Here you'll find all available
  66. %%nopdf information about the txt2tags text conversion tool. You can
  67. %%nopdf find my latest version at URLWEBSITE/userguide/. For
  68. %%nopdf more information please visit
  69. %%nopdf [the txt2tags website URLWEBSITE]. Enjoy!"
  70. %%nopdf
  71. %%nopdf [Download PDF version URLWEBSITE/userguide/userguide.pdf]
  72. %nopdf= About =
  73. %nopdf
  74. %nopdfThis is the [txt2tags URLWEBSITE] User Guide, the
  75. %nopdfcomplete manual about the program.
  76. %nopdf
  77. %nopdf- User Guide official address:
  78. %nopdf URLWEBSITE/userguide
  79. %nopdf
  80. %nopdf- User Guide PDF download:
  81. %nopdf URLWEBSITE/userguide/userguide.pdf
  82. %nopdf-
  83. ========================================================================
  84. %%nopdf%**This Guide Contains:**
  85. %%toc
  86. ========================================================================
  87. = Part I - Introducing Txt2tags =[intro]
  88. == The First Questions You May Have ==[1st-questions]
  89. This chapter is a txt2tags overview, that will introduce the program
  90. purpose and features.
  91. ------------------------------------------------------------------------
  92. === What is it? ===
  93. Txt2tags is a text formatting and conversion tool.
  94. : **A text formatting tool**: 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.
  95. : **A conversion tool**: You can use the txt2tags python program to converts your txt2tags documents to several supported [targets #targets]. //(Further reference to the txt2tags python program will simply be labelled "txt2tags".)//
  96. Amongs others, there are:
  97. - popular Wiki markups, such as bbcode, wikipedia pages, markdown, restructuredtext and spip.
  98. - html variations: html transitional, xhtml, html5...
  99. - office documents: RTF, LaTeX documents, Open Document Spreadsheet, SQLite database (imported from tables)
  100. - plain text, including ASCII art variations.
  101. //See the [targets chapter #targets] to discover the full list.//
  102. : **And more**: Beyond those 2 aspects, which deals with defined features and syntax, txt2tags can also manipulate your document with [powerful input and output filters #setting-preproc].
  103. ------------------------------------------------------------------------
  104. === Why should I use it? ===
  105. You'll find txt2tags really useful if you:
  106. - Need to publish documents in different formats
  107. - Need to maintain updated documents in different formats
  108. - Write technical documents or guides
  109. - Don't know how to write a document in a specific format
  110. - Don't have an editor for a specific format
  111. - Want to use a simple text editor to update your documents
  112. And the main motivation is:
  113. - Save time, writing **contents** and forgetting about **formatting**
  114. ------------------------------------------------------------------------
  115. === Why is it a good choice among other tools? ===
  116. Txt2tags has a very straight way of growing, following basic concepts.
  117. These are the highlights:
  118. | //Source File Readable// | Txt2tags marks are very simple, almost natural.
  119. | //Target Document Readable// | The target document is also readable, with indentation and spacing.
  120. | //Consistent Marks// | Txt2tags marks are simple symbols, designed to be unique enough to don't mix up with the document contents.
  121. | //Consistent Rules// | As the marks, the rules that applies to them are tied to each other, there are no "exceptions" or "special cases".
  122. | //Simple Structures// | All the supported formatting are **simple**, with no extra-options or complicated behavior modifiers. A mark is just a mark, with no options at all.
  123. | //Easy to Learn// | With simple marks and readable source, the txt2tags learning curve is user friendly.
  124. | //Nice Examples// | The **sample files** included on the package gives real life examples of documents written for txt2tags.
  125. | //Valuable Tools// | The **syntax files** included on the package help you to write documents with no syntax errors.
  126. | //Three User Interfaces// | There is a user friendly **Graphical interface**, a handy **Web interface** easy to install in intranets and a **Command Line interface** for power-users and scripting.
  127. | //Scripting// | With the full featured command line mode, an experienced user can **automatize** tasks and do **post-editing** on the converted files.
  128. | //Download and Run / Multi-platform// | Txt2tags is a single **Python script**. There is no need to compile it or download extra modules. So it runs nicely on *NIX, Linux, Windows and Macs.
  129. | //Mature// | 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.
  130. ------------------------------------------------------------------------
  131. === Do I have to pay for it? ===
  132. Absolutely NO!
  133. It's free, GPL licensed.
  134. % It's free, GPL, open source, public domain,
  135. % //<put-your-favorite-buzzword-here>//.
  136. %
  137. % You can copy, use, modify, sell, release as yours. Software
  138. % politics/copyright is not one of the author's major concerns.
  139. ------------------------------------------------------------------------
  140. == Supported Formatting Structures ==[structures]
  141. The following is a list of all the structures supported by txt2tags.
  142. - header (document title, author name, date)
  143. - section title (numbered or not)
  144. - paragraphs
  145. - font beautifiers
  146. - bold
  147. - italic
  148. - underline
  149. - strike
  150. - monospaced font (verbatim)
  151. - monospaced inside paragraph
  152. - monospaced line
  153. - monospaced area (multiline)
  154. - quoted area
  155. - link
  156. - URL/Internet links
  157. - e-mail links
  158. - local links
  159. - named links
  160. - lists
  161. - bulleted list
  162. - numbered list
  163. - definition list
  164. - horizontal separator line
  165. - image (with smart alignment)
  166. - table (with or without border, smart alignment, column span)
  167. - macros (with flexible formatting):
  168. - current date
  169. - file modification time
  170. - input and output file name and path
  171. - automatic table of contents
  172. - special mark for raw text (no marks parsed inside)
  173. - special mark for tagged text (no parsing, sent directly to output)
  174. - comments (for self notes, TODO, FIXME)
  175. ------------------------------------------------------------------------
  176. == Supported Targets ==[targets]
  177. === Wiki ===
  178. : **adoc**
  179. AsciiDoc document
  180. : **bbcode**
  181. BBCode document
  182. : **creole**
  183. Creole 1.0 document
  184. : **DOKU**
  185. [DokuWiki http://www.dokuwiki.org/dokuwiki] is a standards
  186. compliant, simple to use Wiki, mainly aimed at creating documentation
  187. of any kind. It is targeted at developer teams, workgroups and small
  188. companies. It has a simple but powerful syntax which makes sure the
  189. data files remain readable outside the Wiki and eases the creation of
  190. structured texts. All data is stored in plain text files - no
  191. database is required.
  192. : **Foswiki / TWiki**
  193. [Foswiki http://foswiki.org/] or [TWiki http://twiki.org], is a flexible, powerful,
  194. and easy to use enterprise wiki and collaboration platform.
  195. The structured wiki is typically used to run a project development
  196. space, a document management system, a knowledge base, or any other
  197. groupware tool, on an intranet or on the internet.
  198. : **GWIKI**
  199. Now you can easily paste your project's current documentation into the
  200. [Google Code http://code.google.com/] Wiki.
  201. : **md**
  202. Markdown document
  203. : **MOIN**
  204. You don't know what [MoinMoin http://moinmo.in/] is?
  205. It is a [WikiWiki http://www.c2.com/cgi/wiki]!
  206. Moin syntax is kinda boring when you need to keep
  207. ``{{{'''''adding braces and quotes'''''}}}``, so txt2tags comes with the
  208. simplified marks and unified solution: one source, multi targets.
  209. : **[PMWIKI http://en.wikipedia.org/wiki/PmWiki]**
  210. [PmWiki http://www.pmwiki.org/] is a light and free wiki software written in PHP, and using no SQL database.
  211. : **red**
  212. Redmine Wiki page
  213. : **rst**
  214. ReStructuredText document
  215. : **spip**
  216. SPIP article
  217. : **txt2t**
  218. Txt2tags document
  219. : **WIKI**
  220. You've heard about the [Wikipedia http://wikipedia.org], right? So you
  221. don't need to learn yet-another markup syntax. Just stick with txt2tags
  222. and let it convert your text to the Wikipedia format, called
  223. [MediaWiki http://en.wikipedia.org/wiki/MediaWiki].
  224. === HTML ===
  225. : **aapw**
  226. ASCII Art Presentation Web
  227. : **aasw**
  228. ASCII Art Spreadsheet Web
  229. : **aatw**
  230. ASCII Art Text Web
  231. : **[HTML http://en.wikipedia.org/wiki/HTML]**
  232. You maybe know what HTML is. (hint: Internet)
  233. Txt2tags generates clean HTML documents, that look pretty and have
  234. its source readable. It DOES NOT use javascript, frames or other
  235. futile formatting techniques, that aren't required for simple, techie
  236. documents. But a separate CSS file can be used if wanted. Txt2tags
  237. generates "//HTML 4.0 Transitional//" code.
  238. Txt2tags HTML generated code is 100% approved by the [w3c validator http://validator.w3.org/].
  239. : **html5**
  240. HTML5 page
  241. : **htmls**
  242. HTML Spreadsheet
  243. : **wp**
  244. WordPress post
  245. : **[XHTML http://en.wikipedia.org/wiki/XHTML]**
  246. It is the new generation of HTML, with more strict rules.
  247. This makes the code easier to parse and
  248. understand. For the general purpose, consider it HTML. Txt2tags
  249. generates "//XHTML 1.0 Transitional//" code.
  250. Txt2tags XHTML generated code is 100% approved by the [w3c validator http://validator.w3.org/].
  251. : **xhtmls**
  252. XHTML Strict page
  253. === Office ===
  254. : **csv**
  255. CSV spreadsheet
  256. : **db**
  257. SQLite database
  258. : **dbk**
  259. DocBook document
  260. : **LOUT**
  261. Very similar to LaTeX in power, but with an easier syntax using "@"
  262. instead "\" and avoiding the need of braces in common situations. Its
  263. approach of everything-is-an-object makes the tagging much saner.
  264. Txt2tags generates ready-to-use Lout files, which can be converted do
  265. PS or PDF files using the "lout" command.
  266. : **MGP**
  267. [MagicPoint http://en.wikipedia.org/wiki/MagicPoint] is a very handy presentation tool
  268. (hint: Microsoft PowerPoint), that uses a tagged language to define all
  269. the screens. So you can do complex presentations in vi/emacs/notepad.
  270. Txt2tags generates a ready-to-use .mgp file, defining all the
  271. necessary headers for fonts and appearance definitions, as long as
  272. international characters support.
  273. Txt2tags creates "diet" .mgp files: they use the Type1 fonts, so you do not
  274. need to carry TrueType fonts files with your presentation. Also, the color
  275. definitions are simple, so even on a poor color palette system (such as
  276. ``startx -- -bpp 8``), the presentation will look pretty!
  277. The key is: convert and use. No quick fixes or requirements needed.
  278. : **ods**
  279. Open Document Spreadsheet
  280. : **PM6**
  281. Adobe PageMaker 6.0 has its own tagged
  282. language. Styles, color table, beautifiers, and most of all the
  283. PageMaker mouse-clicking features are also available on its tagged language.
  284. You just need to access the "Import tagged text" menu item. Just for
  285. the records, it's an <HTML "like"> tag format.
  286. Txt2tags generates all the tags and already defines a extensive and
  287. working header, setting paragraph styles and formatting. This is the
  288. hard part.
  289. **Author's note:**
  290. My entire portuguese [regular expression's book http://guia-er.sf.net]
  291. was written in VI, then converted to PageMaker with txt2tags and went to
  292. the publisher. It works :)
  293. : **rtf**
  294. RTF document
  295. : **[SGML http://en.wikipedia.org/wiki/SGML]**
  296. It is a common document format which has powerful conversion applications
  297. ([linuxdoc-tools http://packages.debian.org/linuxdoc-tools]). From a
  298. single SGML file you can generate HTML, PDF, PostScript, Info, LaTeX, LyX, RTF
  299. and XML documents. The tools also does automatic TOC and break
  300. sections into subpages.
  301. Txt2tags generates SGML files in the LinuxDoc system type, ready to
  302. be converted with linuxdoc-tools without any extra catalog files or any
  303. SGML annoying requirements.
  304. : **[LATEX http://en.wikipedia.org/wiki/LaTeX]**
  305. The preferred academic document format, it is more powerful than you
  306. ever wondered. Full books, complicated formulas and any complex text
  307. can be written in LaTeX. But prepare to loose your hair when you try
  308. to write the tags by hand...
  309. Txt2tags generates ready-to-use LaTeX files, doing all the complex
  310. escaping tricks and exceptions. The writer just need to worry about
  311. the text.
  312. : **texs**
  313. LaTeX Spreadsheet
  314. === Text ===
  315. : **aap**
  316. ASCII Art Presentation
  317. : **aas**
  318. ASCII Art Spreadsheet
  319. : **aat**
  320. ASCII Art Text
  321. : **MAN**
  322. UNIX man pages resist over the years. Document formats come and go,
  323. and there they are, unbeatable.
  324. There are other tools to generate man documents, but txt2tags has
  325. one advantage: one source, multi targets. So the same man page
  326. contents can be converted to an HTML page, Wiki document and plain text.
  327. : **TXT**
  328. TXT is text. Simple, pure, beautiful.
  329. Although txt2tags marks are very intuitive and discrete, you can remove
  330. them by converting the file to pure TXT.
  331. The titles are underlined, and the text is basically left as is on the
  332. source.
  333. Tip: Use the ``--targets`` command line option to get a complete list of
  334. all the available targets.
  335. ------------------------------------------------------------------------
  336. == Status of Supported Structures by Target ==[struct-support]
  337. || Structure | html | xhtml | sgml | dbk | tex | lout | man | mgp | creole | wiki | gwiki | pmw | doku | moin | pm6 | adoc | art | txt | tml |
  338. | headers | Y | Y | Y | Y | Y | Y | Y | Y | - | - | - | Y | - | - | N | - | Y | Y | Y |
  339. | section title | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y |
  340. | paragraphs | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y |
  341. | bold | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | - | - | Y |
  342. | italic | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | - | - | Y |
  343. | underline | Y | Y | - | Y | Y | Y | - | Y | - | Y | - | Y | Y | Y | Y | N | - | - | Y |
  344. | strike | Y | Y | N | N | Y | - | - | - | - | Y | Y | Y | Y | Y | N | N | - | - | Y |
  345. | monospaced font | Y | Y | Y | Y | Y | Y | - | Y | - | Y | Y | Y | Y | Y | Y | Y | - | - | Y |
  346. | verbatim line | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | - | - | - |
  347. | verbatim area | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | - | - | Y |
  348. | quoted area | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | N | Y | Y | - |
  349. | internet links | Y | Y | Y | Y | - | - | - | - | Y | Y | Y | Y | Y | Y | - | Y | - | - | Y |
  350. | e-mail links | Y | Y | Y | Y | - | - | - | - | Y | Y | Y | Y | Y | Y | - | Y | - | - | Y |
  351. | local links | Y | Y | Y | Y | N | N | - | - | N | N | N | Y | Y | Y | - | N | - | - | Y |
  352. | named links | Y | Y | Y | Y | - | - | - | - | Y | Y | Y | Y | Y | Y | - | Y | - | - | Y |
  353. | bulleted list | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y |
  354. | numbered list | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y |
  355. | definition list | Y | Y | Y | Y | Y | Y | Y | N | Y | Y | - | Y | - | Y | N | N | Y | Y | Y |
  356. | horizontal line | Y | Y | - | N | Y | Y | - | Y | Y | Y | - | Y | Y | Y | N | N | Y | Y | Y |
  357. | image | Y | Y | Y | Y | Y | Y | - | Y | Y | Y | Y | Y | Y | Y | N | Y | - | - | Y |
  358. | table | Y | Y | Y | N | Y | N | Y | N | Y | Y | Y | Y | Y | Y | N | N | N | N | Y |
  359. || Extras | html | xhtml | sgml | dbk | tex | lout | man | mgp | creole | wiki | gwiki | pmw | doku | moin | pm6 | adoc | art | txt | Y |
  360. | image align | Y | Y | N | N | N | Y | - | Y | N | Y | - | N | Y | N | N | N | - | - | Y |
  361. | table cell align | Y | Y | Y | N | Y | N | Y | N | N | N | - | N | - | Y | N | N | N | N | Y |
  362. | table column span | Y | Y | N | N | Y | N | N | N | N | N | - | N | - | N | N | N | N | N | Y |
  363. || | Legend
  364. | **Y** | //Supported//
  365. | **N** | //Not supported (may be in future releases)//
  366. | **-** | //Not supported (can't be done on this target)//
  367. ------------------------------------------------------------------------
  368. == The Three User Interfaces: Gui, Web and Command Line ==[interfaces]
  369. As different users have different needs and environments, txt2tags is
  370. very flexible on how it runs.
  371. There are three User Interfaces for the program, each one with its own
  372. purpose and features.
  373. - **Gui**: Written in Tk, brings the windowing and clicking to txt2tags.
  374. - **Web**: Written in PHP, allows users to run txt2tags on the browser,
  375. requiring no installation on the client side.
  376. - **Command Line**: Written in Python, it's the program core. All
  377. features are available as command line options.
  378. ------------------------------------------------------------------------
  379. === Graphical Interface ===[gui]
  380. Since version 1.0, there is a nice Graphical Interface, that works on
  381. Linux, Windows, Mac and others. Just call txt2tags with the ``--gui``
  382. option to open it.
  383. % If some resources are missing, the program will tell.
  384. %
  385. % **Note:** The Tkinter module is needed. As it comes with the
  386. % standard Python distribution, you may already have it.
  387. The interface is pretty simple and intuitive:
  388. [IMGPATH/gui.png]
  389. + You locate the source .t2t file on the disk and its options are
  390. loaded.
  391. + If the target is still empty, you must choose one.
  392. + Then there are some options you may choose, but none of them are
  393. required.
  394. + Finally, press the "Convert!" button.
  395. A nice option is the "//Dump to screen//", so you can check
  396. the resulting code on a separate window, no file is saved at all. When
  397. the code is OK, you uncheck it and the file will be saved.
  398. The default interface colors can be changed on the [configuration file #rc],
  399. using the ``%!guicolors`` settings. For example:
  400. ```
  401. % set my own colors for the graphical interface (bg1, fg1, bg2, fg2)
  402. %!guicolors: blue white brown yellow
  403. ```
  404. ------------------------------------------------------------------------
  405. === Web Interface ===
  406. The Web Interface is up and running on the Internet at
  407. URLWEBSITE/online.php, so you can use and test the program
  408. instantly, before download.
  409. [IMGPATH/web.png]
  410. One can also put this interface on the local intranet avoiding to
  411. install txt2tags in all machines.
  412. ------------------------------------------------------------------------
  413. === Command Line Interface ===[cmdline]
  414. For command line power users, the --help should be enough:
  415. ```
  416. Usage: txt2tags [OPTIONS] [infile.t2t ...]
  417. --targets print a list of all the available targets and exit
  418. -t, --target=TYPE set target document type. currently supported:
  419. adoc, art, creole, dbk, doku, gwiki, html, lout, man,
  420. mgp, moin, pm6, pmw, sgml, tex, txt, wiki, xhtml
  421. -i, --infile=FILE set FILE as the input file name ('-' for STDIN)
  422. -o, --outfile=FILE set FILE as the output file name ('-' for STDOUT)
  423. --encoding=ENC set target file encoding (utf-8, iso-8859-1, etc)
  424. --toc add an automatic Table of Contents to the output
  425. --toc-level=N set maximum TOC level (depth) to N
  426. --toc-only print the Table of Contents and exit
  427. -n, --enum-title enumerate all titles as 1, 1.1, 1.1.1, etc
  428. --style=FILE use FILE as the document style (like HTML CSS)
  429. --css-sugar insert CSS-friendly tags for HTML/XHTML
  430. --css-inside insert CSS file contents inside HTML/XHTML headers
  431. -H, --no-headers suppress header and footer from the output
  432. --mask-email hide email from spam robots. x@y.z turns <x (a) y z>
  433. --slides format output as presentation slides (used by -t art)
  434. --width=N set the output's width to N columns (used by -t art)
  435. --height=N set the output's height to N rows (used by -t art)
  436. -C, --config-file=F read configuration from file F
  437. --gui invoke Graphical Tk Interface
  438. -q, --quiet quiet mode, suppress all output (except errors)
  439. -v, --verbose print informative messages during conversion
  440. -h, --help print this help information and exit
  441. -V, --version print program version and exit
  442. --dump-config print all the configuration found and exit
  443. --dump-source print the document source, with includes expanded
  444. Turn OFF options:
  445. --no-css-inside, --no-css-sugar, --no-dump-config, --no-dump-source,
  446. --no-encoding, --no-enum-title, --no-headers, --no-infile,
  447. --no-mask-email, --no-outfile, --no-quiet, --no-rc, --no-slides,
  448. --no-style, --no-targets, --no-toc, --no-toc-only
  449. Example:
  450. txt2tags -t html --toc file.t2t
  451. By default, converted output is saved to 'infile.<target>'.
  452. Use --outfile to force an output file name.
  453. If input file is '-', reads from STDIN.
  454. If output file is '-', dumps output to STDOUT.
  455. ```
  456. Please read the txt2tags man page for detailed information about options and command line use.
  457. Examples:
  458. | **Convert to HTML** | ``$ txt2tags -t html file.t2t``
  459. | **The same, using redirection** | ``$ txt2tags -t html -o - file.t2t > file.html``
  460. | | .
  461. | **Including Table Of Contents** | ``$ txt2tags -t html --toc file.t2t``
  462. | **And also, numbering titles** | ``$ txt2tags -t html --toc --enum-title file.t2t``
  463. | | .
  464. | **Contents quick view** | ``$ txt2tags --toc-only file.t2t``
  465. | **Maybe enumerate them?** | ``$ txt2tags --toc-only --enum-title file.t2t``
  466. | | .
  467. | **One liners from STDIN** | ``$ echo -e "\n**bold**" | txt2tags -t html --no-headers -``
  468. | **Testing Mask Email feature** | ``$ echo -e "\njohn.wayne@farwest.com" | txt2tags -t txt --mask-email --no-headers -``
  469. ========================================================================
  470. = Part II - Install =[install]
  471. Just download the program and run it on your machine.
  472. == Download & Install Python ==[download-python]
  473. First of all, you must download and install [Python http://www.python.org] on
  474. your system. Txt2tags requires Python version 2.2 or newer.
  475. 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.
  476. If you are not sure if you have Python or not, open a console (tty,
  477. xterm, MSDOS, Terminal.app) and type ``python``. If it is not installed, the system
  478. will tell you.
  479. == Download txt2tags ==[download-txt2tags]
  480. The official location for txt2tags distribution is on the program
  481. site, at URLWEBSITE. Just download and uncompress the package (.tgz file).
  482. If you're in Linux, you can also use the automatic installer of your system. Some examples:
  483. - yum install txt2tags
  484. - sudo apt-get install txt2tags
  485. -
  486. % All the program's files are on the tarball (.tgz file), which can be
  487. % expanded by most of the compression utilities (including Winzip).
  488. % Just get the **latest** one (more recent date, higher version number).
  489. % The previous versions remains for historical purposes only.
  490. == Install txt2tags ==[install-txt2tags]
  491. As a single Python script, txt2tags needs no installation at all.
  492. The only file needed to use the program is the txt2tags script. The
  493. other files of the package are documentation, tools and sample files.
  494. The fail-proof way to run txt2tags, is calling Python with it:
  495. ``` prompt$ python txt2tags
  496. If you want to install txt2tags on the system as a stand alone
  497. program, just copy the txt2tags script to a system PATH
  498. directory and make sure the system knows how to run it.
  499. : **UNIX/Linux/Mac**
  500. Make the script executable (``chmod +x txt2tags``) and copy it to a
  501. $PATH directory (``cp txt2tags /usr/local/bin``)
  502. : **Windows**
  503. Rename the script adding the .py extension
  504. and copy it to a system PATH directory, such as ``C:\Windows\System32``.
  505. After that, you can create an icon on your desktop for it, if you want to
  506. use the program's Graphical Interface.
  507. % === Special Packages for Windows Users ===
  508. %
  509. % There is also two .EXE distribution files for txt2tags, which install
  510. % the program on Windows machines with just a few clicks:
  511. %
  512. % - The single txt2tags script for those who already have the Python
  513. % interpreted installed
  514. % - The stand alone version, which doesn't require Python interpreter to
  515. % run (it has a diet version embedded)
  516. %
  517. %
  518. % Please visit the //Txt2tags-Win// site to download this packages:
  519. % http://txt2tags-win.sf.net
  520. == Install Text Editor Syntax Highlighting File (optional)==[editor-syntax]
  521. Txt2tags comes with handy syntax highlighting files to be used by the
  522. following text editors:
  523. - Vim
  524. - Emacs
  525. - Nano
  526. - Kate
  527. - Gedit
  528. - JOE
  529. - le
  530. - ne
  531. - TextMate
  532. This syntax highlighting files have all the txt2tags rules and marks
  533. registered, helping the user to write error-free documents. Showing the
  534. marks in colors, you see on-the-fly if you wrote it right.
  535. | [IMGPATH/vim.png]
  536. | Sample file opened in Vim Editor
  537. Each editor has a different install procedure for a syntax highlighting
  538. file, please read the syntax file headers and the editor documentation.
  539. ========================================================================
  540. = Part III - Writing and Converting Your First Document =[your-1st-doc]
  541. == Check the Tools ==
  542. To make the first conversion you will need three things: txt2tags, a
  543. text editor and a web browser.
  544. + Make sure txt2tags is installed and running on your system.
  545. - **Command Line Interface:** Call "txt2tags" on the command line and
  546. the program should give you a "Missing input file" message. If it is
  547. not working, try ``python /path/to/txt2tags`` or even
  548. ``/path/to/python /path/to/txt2tags`` if Python is not on your PATH.
  549. - **Gui Interface:** Click on the program icon to launch the Gui
  550. Interface or call ``txt2tags --gui``.
  551. + Open the text editor your are comfortable with. It can be **any** text
  552. editor, from the good old VI to MS Word or OpenOffice.org. Create a
  553. brand new empty document to be your first txt2tags one and remember to
  554. save it as plain text.
  555. + Launch your favorite web browser to see the results of the conversion.
  556. ------------------------------------------------------------------------
  557. == Write the Document Header ==
  558. + Go to the text editor and on the very first line type the document
  559. main title: //My First Document//
  560. + On the second line make a subtitle, inserting this text:
  561. //A txt2tags test//
  562. + Then, on the third line, put some time information:
  563. //Sunday, 2004//
  564. If everything went right, you should be seeing a three line document
  565. with this contents:
  566. ```
  567. My First Document
  568. A txt2tags test
  569. Sunday, 2004
  570. ```
  571. This is just a part of the document, but we can already convert it and
  572. check the results.
  573. Now save this document with the name ``test.txt``. Remember to save it
  574. as plain text. Pay attention to which folder you are saving the file,
  575. you will need to remember it soon.
  576. ------------------------------------------------------------------------
  577. == The First Conversion - Gui Interface ==
  578. If you are in the Command Line Interface, please skip this step and read
  579. the next one.
  580. If you are in the Gui Interface, follow this steps:
  581. [IMGPATH/firstdoc.png]
  582. + Press the "Browse" button and choose the ``test.txt`` you just saved
  583. (remember the folder!).
  584. + Back to the first screen, select "HTML page" on the "Target document
  585. type" combo.
  586. + Press the "Convert!" button.
  587. [IMGPATH/firstdoc-done.png]
  588. A dialog box will appear, telling you that the file was converted
  589. successfully. Note that the generated HTML page was saved on the same
  590. folder as the text file, with the "html" extension.
  591. ------------------------------------------------------------------------
  592. == The First Conversion - Command Line Interface ==
  593. If you are in the Command Line Interface, move to the folder where the
  594. file was saved and type this command:
  595. ``` txt2tags --target html test.txt
  596. The option ``--target`` is followed
  597. by the "html" string, which tells the program to what format your text
  598. file will be converted. The last item is the text filename.
  599. The results were saved to the ``test.html``
  600. file and then the program will show you the
  601. "//txt2tags wrote test.html//" message.
  602. If some error occurred, read the message carefully.
  603. Here is a sample of how it will be shown on your screen:
  604. ```
  605. prompt$ txt2tags --target html test.txt
  606. txt2tags wrote test.html
  607. prompt$
  608. ```
  609. ------------------------------------------------------------------------
  610. == Check the Results ==
  611. Open the ``test.html`` file on the web browser to check if everything
  612. is ok.
  613. [IMGPATH/firstdoc-html.png]
  614. Here it is! You just typed three simple lines of text and txt2tags made
  615. all the work to set the HTML page heading information, text alignment,
  616. sizes, spacing and appearance. See that the main title is also placed at the
  617. browser title bar.
  618. You write text, txt2tags does the rest ;)
  619. Tip: You can also use CSS files on HTML pages generated by txt2tags, so the
  620. page appearance is 100% configurable.
  621. ------------------------------------------------------------------------
  622. == Writing the Document Body ==
  623. Now back to the text editor, the next step is to type the document
  624. contents. You can write plain text as you normally do on email messages.
  625. You will see that txt2tags recognizes paragraphs and list of items
  626. automatically, you don't have to "mark" them.
  627. Then again: save it, convert and check the results. This is the
  628. development cycle of a document in txt2tags. You just focus on the
  629. document contents, finishing documents faster than other editors. No
  630. mouse clicking, no menus, no windows, no distraction.
  631. Considering the following contents for the ``test.txt`` file, which is
  632. only plain text, compare the generated HTML page:
  633. ```
  634. My First Document
  635. A txt2tags test
  636. Sunday, 2004
  637. Well, let's try this txt2tags thing.
  638. I don't know what to write.
  639. Mmmmmm, I know what I need to do now:
  640. - Take a shower
  641. - Eat a pizza
  642. - Sleep
  643. ```
  644. [IMGPATH/firstdoc-fullhtml.png]
  645. You can write a full homepage with 0% of HTML knowledge. You don't need
  646. to insert any tags. And more, the same text file can be converted to any
  647. of the other txt2tags supported formats.
  648. Besides plain text, txt2tags has some very simple marks, that you'll
  649. use when you need some other formatting or structures like bold, italic,
  650. title, images, table and other. As a quick sample,
  651. ``**stars for bold**`` and ``== equals for title ==``. You can learn the
  652. marks on the [Txt2tags Markup Demo URLWEBSITE/markup.html].
  653. =======================================================================
  654. = Part IV - Mastering Txt2tags Concepts =[concepts]
  655. == The .t2t document Areas ==[areas]
  656. Txt2tags marked files are divided in 3 areas. Each area has its own
  657. rules and purpose. They are:
  658. : //HEADAREA//
  659. Place for Document Title, Author, Version and Date information.
  660. : //CONFAREA//
  661. Place for general Document Settings and Parser behavior modifiers.
  662. : //BODYAREA//
  663. Place for the Document Content.
  664. All areas are optional. You can write a txt2tags document with just
  665. headers (such as our first example), or a document with no headers or settings.
  666. The areas are delimited by special rules, which will be seen in detail
  667. on the next chapter. For now, this is a representation of the
  668. areas on a document:
  669. ```
  670. ____________
  671. | |
  672. | HEADERS | 1. First, the Headers
  673. | |
  674. | CONFIG | 2. Then the Settings
  675. | |
  676. | BODY | 3. And finally the Document Body,
  677. | |
  678. | ... | which goes until the end
  679. | ... |
  680. |____________|
  681. ```
  682. In short, this is how the areas are defined:
  683. | **Headers** | First 3 lines of the file, or the first line blank for No Headers.
  684. | **Config** | Begins right after the Header (4th or 2nd line) and ends when the //BODYAREA// starts.
  685. | **Body** | The first valid text line (not comment or setting) after the //HEADAREA//.
  686. === Full Example ===
  687. ```
  688. My nice doc Title
  689. Mr. John Doe
  690. Last Updated: %%mtime(%c)
  691. %!target : html
  692. %!style : fancy.css
  693. %!encoding: UTF-8
  694. %!options : --toc --enum-title
  695. Hi! This is my test document.
  696. Its content will end here.
  697. ```
  698. ------------------------------------------------------------------------
  699. == HEADAREA ==[headers-area]
  700. Location:
  701. - Fixed position: **First 3 lines** of the file. Period.
  702. - Fixed position: **First line** of the file if it is blank. This
  703. means Empty Headers.
  704. The HEADAREA is the only one that has a fixed position, line
  705. oriented. They are located at the first three lines of the source file.
  706. These lines are content-free, with no static information type needed.
  707. But the following is recommended:
  708. - //line 1//: document title
  709. - //line 2//: author name and/or email
  710. - //line 3//: document date and/or version
  711. (nice place for ``%%date``)
  712. Keep in mind that the first 3 lines of the source document will be the
  713. first 3 lines on the target document, separated and with high contrast
  714. to the text body (i.e. big letters, bold). If paging is allowed, the
  715. headers will be alone and centralized on the first page.
  716. ==== Less (or None) Header lines ====
  717. Sometimes the user wants to specify less than three lines for headers,
  718. giving just the document title and/or date information.
  719. Just let the 2nd and/or the 3rd lines empty (blank) and this position
  720. will not be placed at the target document. But keep in mind that even
  721. blanks, these lines are still part of the headers, so the document body
  722. must start **after** the 3rd line anyway.
  723. The title is the only required header (the first line), but if you
  724. leave it blank, you are saying that your document has **no headers**.
  725. So the //BODYAREA// will begin right after, on the 2nd line.
  726. No headers on the document is often useful if you want to specify your
  727. own customized headers after converting. The command line option
  728. ``--no-headers`` is usually required for this kind of operation.
  729. ==== Straight to the point ====
  730. In short: **"Headers are just __positions__, not contents"**
  731. Place one text on the first line, and it will appear on the target's
  732. first line. The same for 2nd and 3rd header lines.
  733. ------------------------------------------------------------------------
  734. == CONFAREA ==[config-area]
  735. Location:
  736. - Begins right after the HEADAREA
  737. - Begins on the **4th line** of the file if **Headers** were specified
  738. - Begins on the **2nd line** of the file if **No Headers** were specified
  739. - Ends when the BODYAREA starts
  740. - Ends by a non Setting, Blank or Comment line
  741. The CONFAREA is optional. An average user can write lots of txt2tags
  742. files without even know it exists, but the experienced users will
  743. enjoy the power and control it provides.
  744. The CONFAREA is used to store document-specific settings, so you don't
  745. have to type them on the command line when converting the document. For
  746. example, you can set the default document target type and encoding.
  747. Please read the [Settings section #settings-overview] for more
  748. information about them.
  749. ----------------------------------------------------------------
  750. == BODYAREA ==[body-area]
  751. Location:
  752. - Begins on the first valid text line of the file
  753. - Headers, Settings and Comments are **not** valid text lines
  754. - Ends at the end of the file (EOF)
  755. The body is anything outside Headers and Config Areas.
  756. The body holds the document contents and all formatting and structures
  757. txt2tags can recognize. Inside the body you can also put comments for
  758. //TODOs// and self notes.
  759. You can use the ``--no-headers`` command line option to convert only the
  760. document body, suppressing the headers. This is useful to set your own
  761. headers on a separate file, then join the converted body.
  762. ----------------------------------------------------------------
  763. == Settings ==[settings-overview]
  764. Settings are special configurations placed at the source document's
  765. CONFAREA that can affect the conversion process. Their syntax is:
  766. ``` %! keyword : value
  767. List of valid keywords:
  768. || Keyword | Description |
  769. | Target | Set the default target to the document be converted to.
  770. | Options | Set the default options to be used on the conversion. The format is the same as the command line options.
  771. | Style | Set the document style. Used to define a CSS file for HTML/XHTML and to load a package in LaTeX.
  772. | Encoding | Set the document Character Set. Used if the document contains accented letters or other not-ASCII characters.
  773. | PreProc | Input filter. Sets "find and replace" rules to be applied on the BODYAREA of the source document.
  774. | PostProc | Output filter. Sets "find and replace" rules to be applied on the converted document.
  775. Example:
  776. ```
  777. %!target : html
  778. %!options : --toc --toc-level 3
  779. %!style : fancy.css
  780. %!encoding: UTF-8
  781. %!preproc : "AMJ" "Aurelio Marinho Jargas"
  782. %!postproc: '<BODY.*?>' '<BODY bgcolor="yellow">'
  783. ```
  784. Note that the spacing and capitalization of the keyword are ignored. So you can also do ``%!Target:html`` and ``%! TARGET :html``.
  785. Learn more about settings in [Part VII - Mastering Settings #settings].
  786. -----------------------------------------------------------------------
  787. == Command Line Options ==[options]
  788. The fastest way of changing the txt2tags default behavior is to use
  789. command line options. This options are available on the Command Line
  790. Interface only, not on Gui or Web.
  791. Just like the other system's tools, the program do accept a set of
  792. predefined options. An option is an hyphen followed by a letter or two
  793. hyphens followed by one or more words, like ``-t`` and ``--target``.
  794. % Talking about the target option, it is the only required one, the others
  795. % are optional.
  796. Options that are generally used are ``--outfile`` to define a customized
  797. output file name, ``--toc`` to turn on the automatic TOC generation and
  798. ``--encoding`` to set the document character set. Most of the options
  799. can be turned off prefixing a "no-" before its name, for example:
  800. ``--no-encoding`` and ``--no-toc``.
  801. You can register the desired options for a source file inside its
  802. CONFAREA, using the ``%!options`` setting. This way you don't have to
  803. type them on the command line anymore.
  804. Example:
  805. ``` %!options: --toc -o mydoc.html
  806. The exception is the target specification, that has its own setting:
  807. ``` %!target: html
  808. Use the ``--help`` option to get a complete list of all the options
  809. available in txt2tags.
  810. Learn more about [%!options #setting-options] and [%!target #setting-target].
  811. -----------------------------------------------------------------------
  812. == User Configuration File (RC File) ==[rc]
  813. The user configuration file (also called RC file) is a central place to
  814. store the settings that will be shared by ALL converted files. If you
  815. keep inserting the same settings on every .t2t file you write, move it
  816. to the RC file and it will be used globally, for existing and future
  817. source files.
  818. The default location of this file depends on your system. It can also be
  819. specified by the user, using an environment variable.
  820. || RC file location ||
  821. | Windows | ``%HOMEPATH%\_t2trc``
  822. | UNIX, Linux, Mac | ``$HOME/.txt2tagsrc``
  823. | User defined | ``T2TCONFIG`` variable
  824. The format of the settings is exactly the same as the ones used on the
  825. .t2t files CONFAREA. There is a sample RC file on the package at
  826. ``doc/txt2tagsrc``. Example:
  827. ```
  828. % my configs
  829. %%% Always use CSS-friendly tags in HTML
  830. %!options(html): --css-sugar
  831. %%% Change the default TOC depth for all targets
  832. %!options: --toc-level 4
  833. %%% Set the default encoding for all documents
  834. %!options: --encoding UTF-8
  835. ```
  836. Any line that is not blank, a comment or a valid config line will raise
  837. error when txt2tags runs. So be careful when editing this file.
  838. Txt2tags automatically apply the RC file contents into any source file it
  839. is converting. If you want to disable this behavior for a specific
  840. file, use the ``--no-rc`` command line option.
  841. == Configuration Loading Order and Precedence ==[config-loading]
  842. There are three ways of telling txt2tags which options and settings to
  843. use, and this is the order that they are read and applied:
  844. + The user configuration file (RC) settings
  845. + The source document CONFAREA settings
  846. + The command line options
  847. First txt2tags reads the RC file contents (if any) and apply its
  848. configurations on the current source file. Then it scans the source
  849. document CONFAREA for settings and if found, they are applied also,
  850. overriding the RC ones in case of conflict. Finally comes the command
  851. line options, stronger than the other two.
  852. So, if the document encoding was defined on the three resources, the
  853. command line will be the one used.
  854. -----------------------------------------------------------------------
  855. == %!include command ==[include]
  856. The ``include`` command is used to paste the contents of an external
  857. file into the source document body. It is not a config, but a command,
  858. and it is valid on the document BODYAREA.
  859. The ``include`` command is useful to split a large document into smaller
  860. pieces (like chapters in a book) or to include the full contents of an
  861. external file into the document source. Sample:
  862. ```
  863. My first book
  864. Dr. John Doe
  865. 1st Edition
  866. %!include: intro.t2t
  867. %!include: chapter1.t2t
  868. %!include: chapter2.t2t
  869. ...
  870. %!include: chapter9.t2t
  871. %!include: ending.t2t
  872. ```
  873. You just inform the filename after the ``%!include`` string. The
  874. optional target specification is also supported, so this is valid
  875. either:
  876. ``` %!include(html): file.t2t
  877. Note that include will insert the file BODYAREA into the source
  878. document. The included file Header and Config Areas are ignored. This
  879. way you can convert the included file alone or inside the main document.
  880. But there's another three types of include:
  881. - Verbatim include
  882. - Raw include
  883. - Tagged include
  884. The **Verbatim** type includes a text file preserving its original
  885. spaces and formatting, just like if the text was inside the txt2tags
  886. Verbatim area (```). To specify this type, enclose the filename with
  887. backquotes:
  888. ``` %!include: ``/etc/fstab``
  889. The **Raw** type includes a text file as is, not trying to find and
  890. parse txt2tags marks on it, just like if the text was inside the Raw
  891. area ("""). To specify this type, enclose the filename with double
  892. quotes:
  893. ``` %!include: ""nice_text.txt""
  894. And the **Tagged** type is passed directly to the resulting document,
  895. with NO parsing or escaping performed by txt2tags. This way you can
  896. include additional tagged parts to your document. Useful for default
  897. header or footer information, or more complicated tagged code,
  898. unsupported by txt2tags:
  899. ``` %!include(html): ''footer.html''
  900. Note that the filename is enclosed with single quotes. As the text
  901. inserted is already parsed, you should specify the target to avoid
  902. mistakes.
  903. -----------------------------------------------------------------------
  904. == %!includeconf command ==[includeconf]
  905. The ``includeconf`` command is used to include configurations from an
  906. external file into the current one. This command is valid inside the
  907. source document CONFAREA only.
  908. It is useful to share the same config for multiple files, so you can
  909. centralize it. On any file do you want to include that central
  910. configuration, put a ``includeconf`` call. Example:
  911. ```
  912. My First Document
  913. John Doe
  914. July, 2004
  915. %!includeconf: config.t2t
  916. Hi, this is my first document.
  917. ```
  918. The format inside the included file is the same as in the
  919. [RC file #rc].
  920. Note that the optional target specification is NOT supported for this command.
  921. ```
  922. %!includeconf: config.t2t <--- OK
  923. %!includeconf(html): config.t2t <--- NOT OK
  924. ```
  925. =======================================================================
  926. = Part V - Mastering Marks =[marks]
  927. Overview of all txt2tags marks:
  928. || Basic || Beautifiers ||
  929. | //Headers// | First 3 lines | //Bold// | ""**words**""
  930. | //Title// | = words = | //Italic// | ""//words//""
  931. | //Numbered title// | + words + | //Underline// | ""__words__""
  932. | //Paragraph// | words | //Strike// | ""--words--""
  933. | //Links// | ""[label url]"" | //Monospaced// | ""``words``""
  934. | //Image// | ""[filename.jpg]"" | //Raw text// | """"words""""
  935. | || //Tagged text// | ""''words''""
  936. || Other ||||
  937. | //Quote// | <TAB>words | //Separator line// | ------------...
  938. | //List// | - words | //Strong line// | ============...
  939. | //Numbered list// | + words | //Table// | ""| cell1 | cell2 | cell3...""
  940. | //Definition list// | : words | //Anchor// | = title =[anchor]
  941. | //Comment line// | % comments | //Comment area// | %%%\n comments \n%%%
  942. | //Verbatim line// | ""```"" word | //Verbatim area// | ""```\n lines \n```""
  943. | //Raw line// | """"""" words | //Raw area// | """""""\n lines \n"""""""
  944. | //Tagged line// | ""'''"" words | //Tagged area// | ""'''""\n lines \n""'''""
  945. General Rules:
  946. - **Headers** are the first three document lines, marks are not interpreted.
  947. - **Titles** are balanced "=" or "+" chars around the title text. The more chars, more deep is the title.
  948. - **Beautifiers** don't accept spaces between the marks and its contents.
  949. - The **Comment** mark "%" must be at the line beginning (first column).
  950. - **Images** filename must end in GIF, JPG, PNG or similar.
  951. - The only **multiline** marks are the Comment, Verbatim, Raw and Tagged areas.
  952. - No