/doc/English/userguide/userguide.t2t
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