PageRenderTime 123ms CodeModel.GetById 42ms app.highlight 66ms RepoModel.GetById 1ms app.codeStats 0ms

/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 files are truncated, but you can click here to view the full file

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

Large files files are truncated, but you can click here to view the full file