/doc/English/userguide/userguide.t2t
http://txt2tags.googlecode.com/ · Unknown · 2382 lines · 1736 code · 646 blank · 0 comment · 0 complexity · 624b7a76d66597c9069fb55d09b7b17e MD5 · raw file
Large files are truncated click here to view the full file
- Txt2tags User Guide
- Aurelio, %%mtime(%c)
- %!target: html
- %!options: --toc --toc-level 2 --css-sugar
- % TRANSLATOR:
- % - The HTML output is optimized for the htmldoc tool
- % - Just comment the following lines when translating
- %!options: --css-sugar --no-toc --style userguide.css
- %!postproc(html): '<HTML>' '<!-- This document was generated from userguide.t2t -->\n<HTML>'
- %!postproc: '<H1>Txt2tags User Guide.*' ''
- %!postproc: '<H3>Aurelio, .*' ''
- % TRANSLATOR:
- % - Don't worry about the PDF cover page
- % - Don't worry about PDF at all, translate and check on HTML
- % - Don't worry about the images
- % TRANSLATOR:
- % You can take new screenshots and make new images for the program
- % interface and "first conversion" section. Remember to send them
- % to the author!
- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
- %%% activate those lines when converting to HTML for PDF generation
- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
- %%% htmldoc does TOC
- %pdf%!options(html): --no-toc --no-css-sugar -o userguide-pdf.html
- %%% mask the 'nopdf' marks so they will not be removed
- %pdf%!preproc(html): ^%nopdf %yespdf
- %%% border for all images
- %pdf%!postproc: '(<IMG [^>]*BORDER)="0"' '\1="1"'
- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
- % easy way to change all image locations once, when changing file location
- %!preproc: IMGPATH .
- % TRANSLATOR
- % - Please translate the following macro contents and leave them alone
- % - Remember they are expanded in conversion time, don't remove them
- % normalizing common text
- %!preproc: CONFAREA Config Area
- %!preproc: HEADAREA Header Area
- %!preproc: BODYAREA Body Area
- %!preproc: MARKPROP **Properties:**
- %!preproc: MARKCONT **Contains:**
- %!preproc: MARKDESC **Description:**
- %!preproc: MARKSYN **Syntax:**
- %!preproc: MARKDET **Details:**
- %!preproc: NOMARKS Marks are NOT interpreted
- %!preproc: NOMACRO Macros are NOT interpreted
- %!preproc: URLMARKUP URLWEBSITE/markup.html
- %!preproc: URLWEBSITE http://txt2tags.org
- %!postproc: URLWEBSITE http://txt2tags.org
- % activate the areas disabled on the PDF version
- %!preproc(html): ^%nopdf ''
- % remove separator lines and strong lines
- %!preproc(html): '^ *--------*' ''
- %!preproc(html): '^ *========*' ''
- % highlight NEW topic on TOC
- %%!postproc(html): '(<LI>.*Mastering Macros</A>)$' '\1 <b>[NEW!]</b>'
- %%% Little clean up for less large tables
- %!postproc: /pessoal/sourceforge.net ''
- % 26/Nov/2003: revised by anamimts
- % 26/Jun/2004: updated to v2, new embedded CSS
- % 17/Jul/2004: revised by anamimts
- % 01/Nov/2004: updated to v2.0 and 2.1, new chapters, PDF version
- % 31/Aug/2006: little changes to use htmldoc for splitted HTML
- % TODO Mastering Options [option-help], [option-css-sugar], ...
- ========================================================================
- %%nopdf "Hi! I'm the txt2tags User Guide. Here you'll find all available
- %%nopdf information about the txt2tags text conversion tool. You can
- %%nopdf find my latest version at URLWEBSITE/userguide/. For
- %%nopdf more information please visit
- %%nopdf [the txt2tags website URLWEBSITE]. Enjoy!"
- %%nopdf
- %%nopdf [Download PDF version URLWEBSITE/userguide/userguide.pdf]
- %nopdf= About =
- %nopdf
- %nopdfThis is the [txt2tags URLWEBSITE] User Guide, the
- %nopdfcomplete manual about the program.
- %nopdf
- %nopdf- User Guide official address:
- %nopdf URLWEBSITE/userguide
- %nopdf
- %nopdf- User Guide PDF download:
- %nopdf URLWEBSITE/userguide/userguide.pdf
- %nopdf-
- ========================================================================
- %%nopdf%**This Guide Contains:**
- %%toc
- ========================================================================
- = Part I - Introducing Txt2tags =[intro]
- == The First Questions You May Have ==[1st-questions]
- This chapter is a txt2tags overview, that will introduce the program
- purpose and features.
- ------------------------------------------------------------------------
- === What is it? ===
- Txt2tags is a text formatting and conversion tool.
- : **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.
- : **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".)//
- Amongs others, there are:
- - popular Wiki markups, such as bbcode, wikipedia pages, markdown, restructuredtext and spip.
- - html variations: html transitional, xhtml, html5...
- - office documents: RTF, LaTeX documents, Open Document Spreadsheet, SQLite database (imported from tables)
- - plain text, including ASCII art variations.
- //See the [targets chapter #targets] to discover the full list.//
- : **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].
- ------------------------------------------------------------------------
- === Why should I use it? ===
- You'll find txt2tags really useful if you:
- - Need to publish documents in different formats
- - Need to maintain updated documents in different formats
- - Write technical documents or guides
- - Don't know how to write a document in a specific format
- - Don't have an editor for a specific format
- - Want to use a simple text editor to update your documents
- And the main motivation is:
- - Save time, writing **contents** and forgetting about **formatting**
- ------------------------------------------------------------------------
- === Why is it a good choice among other tools? ===
- Txt2tags has a very straight way of growing, following basic concepts.
- These are the highlights:
- | //Source File Readable// | Txt2tags marks are very simple, almost natural.
- | //Target Document Readable// | The target document is also readable, with indentation and spacing.
- | //Consistent Marks// | Txt2tags marks are simple symbols, designed to be unique enough to don't mix up with the document contents.
- | //Consistent Rules// | As the marks, the rules that applies to them are tied to each other, there are no "exceptions" or "special cases".
- | //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.
- | //Easy to Learn// | With simple marks and readable source, the txt2tags learning curve is user friendly.
- | //Nice Examples// | The **sample files** included on the package gives real life examples of documents written for txt2tags.
- | //Valuable Tools// | The **syntax files** included on the package help you to write documents with no syntax errors.
- | //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.
- | //Scripting// | With the full featured command line mode, an experienced user can **automatize** tasks and do **post-editing** on the converted files.
- | //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.
- | //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.
- ------------------------------------------------------------------------
- === Do I have to pay for it? ===
- Absolutely NO!
- It's free, GPL licensed.
- % It's free, GPL, open source, public domain,
- % //<put-your-favorite-buzzword-here>//.
- %
- % You can copy, use, modify, sell, release as yours. Software
- % politics/copyright is not one of the author's major concerns.
- ------------------------------------------------------------------------
- == Supported Formatting Structures ==[structures]
- The following is a list of all the structures supported by txt2tags.
- - header (document title, author name, date)
- - section title (numbered or not)
- - paragraphs
- - font beautifiers
- - bold
- - italic
- - underline
- - strike
- - monospaced font (verbatim)
- - monospaced inside paragraph
- - monospaced line
- - monospaced area (multiline)
- - quoted area
- - link
- - URL/Internet links
- - e-mail links
- - local links
- - named links
- - lists
- - bulleted list
- - numbered list
- - definition list
- - horizontal separator line
- - image (with smart alignment)
- - table (with or without border, smart alignment, column span)
- - macros (with flexible formatting):
- - current date
- - file modification time
- - input and output file name and path
- - automatic table of contents
- - special mark for raw text (no marks parsed inside)
- - special mark for tagged text (no parsing, sent directly to output)
- - comments (for self notes, TODO, FIXME)
- ------------------------------------------------------------------------
- == Supported Targets ==[targets]
- === Wiki ===
- : **adoc**
- AsciiDoc document
-
- : **bbcode**
- BBCode document
-
- : **creole**
- Creole 1.0 document
- : **DOKU**
- [DokuWiki http://www.dokuwiki.org/dokuwiki] is a standards
- compliant, simple to use Wiki, mainly aimed at creating documentation
- of any kind. It is targeted at developer teams, workgroups and small
- companies. It has a simple but powerful syntax which makes sure the
- data files remain readable outside the Wiki and eases the creation of
- structured texts. All data is stored in plain text files - no
- database is required.
- : **Foswiki / TWiki**
- [Foswiki http://foswiki.org/] or [TWiki http://twiki.org], is a flexible, powerful,
- and easy to use enterprise wiki and collaboration platform.
- The structured wiki is typically used to run a project development
- space, a document management system, a knowledge base, or any other
- groupware tool, on an intranet or on the internet.
- : **GWIKI**
- Now you can easily paste your project's current documentation into the
- [Google Code http://code.google.com/] Wiki.
-
- : **md**
- Markdown document
- : **MOIN**
- You don't know what [MoinMoin http://moinmo.in/] is?
- It is a [WikiWiki http://www.c2.com/cgi/wiki]!
- Moin syntax is kinda boring when you need to keep
- ``{{{'''''adding braces and quotes'''''}}}``, so txt2tags comes with the
- simplified marks and unified solution: one source, multi targets.
-
- : **[PMWIKI http://en.wikipedia.org/wiki/PmWiki]**
- [PmWiki http://www.pmwiki.org/] is a light and free wiki software written in PHP, and using no SQL database.
-
- : **red**
- Redmine Wiki page
-
- : **rst**
- ReStructuredText document
-
- : **spip**
- SPIP article
-
- : **txt2t**
- Txt2tags document
- : **WIKI**
- You've heard about the [Wikipedia http://wikipedia.org], right? So you
- don't need to learn yet-another markup syntax. Just stick with txt2tags
- and let it convert your text to the Wikipedia format, called
- [MediaWiki http://en.wikipedia.org/wiki/MediaWiki].
- === HTML ===
- : **aapw**
- ASCII Art Presentation Web
-
- : **aasw**
- ASCII Art Spreadsheet Web
-
- : **aatw**
- ASCII Art Text Web
- : **[HTML http://en.wikipedia.org/wiki/HTML]**
- You maybe know what HTML is. (hint: Internet)
- Txt2tags generates clean HTML documents, that look pretty and have
- its source readable. It DOES NOT use javascript, frames or other
- futile formatting techniques, that aren't required for simple, techie
- documents. But a separate CSS file can be used if wanted. Txt2tags
- generates "//HTML 4.0 Transitional//" code.
- Txt2tags HTML generated code is 100% approved by the [w3c validator http://validator.w3.org/].
-
- : **html5**
- HTML5 page
-
- : **htmls**
- HTML Spreadsheet
-
- : **wp**
- WordPress post
- : **[XHTML http://en.wikipedia.org/wiki/XHTML]**
- It is the new generation of HTML, with more strict rules.
- This makes the code easier to parse and
- understand. For the general purpose, consider it HTML. Txt2tags
- generates "//XHTML 1.0 Transitional//" code.
- Txt2tags XHTML generated code is 100% approved by the [w3c validator http://validator.w3.org/].
-
- : **xhtmls**
- XHTML Strict page
-
- === Office ===
- : **csv**
- CSV spreadsheet
-
- : **db**
- SQLite database
-
- : **dbk**
- DocBook document
- : **LOUT**
- Very similar to LaTeX in power, but with an easier syntax using "@"
- instead "\" and avoiding the need of braces in common situations. Its
- approach of everything-is-an-object makes the tagging much saner.
- Txt2tags generates ready-to-use Lout files, which can be converted do
- PS or PDF files using the "lout" command.
-
- : **MGP**
- [MagicPoint http://en.wikipedia.org/wiki/MagicPoint] is a very handy presentation tool
- (hint: Microsoft PowerPoint), that uses a tagged language to define all
- the screens. So you can do complex presentations in vi/emacs/notepad.
- Txt2tags generates a ready-to-use .mgp file, defining all the
- necessary headers for fonts and appearance definitions, as long as
- international characters support.
- Txt2tags creates "diet" .mgp files: they use the Type1 fonts, so you do not
- need to carry TrueType fonts files with your presentation. Also, the color
- definitions are simple, so even on a poor color palette system (such as
- ``startx -- -bpp 8``), the presentation will look pretty!
- The key is: convert and use. No quick fixes or requirements needed.
-
- : **ods**
- Open Document Spreadsheet
- : **PM6**
- Adobe PageMaker 6.0 has its own tagged
- language. Styles, color table, beautifiers, and most of all the
- PageMaker mouse-clicking features are also available on its tagged language.
- You just need to access the "Import tagged text" menu item. Just for
- the records, it's an <HTML "like"> tag format.
- Txt2tags generates all the tags and already defines a extensive and
- working header, setting paragraph styles and formatting. This is the
- hard part.
- **Author's note:**
- My entire portuguese [regular expression's book http://guia-er.sf.net]
- was written in VI, then converted to PageMaker with txt2tags and went to
- the publisher. It works :)
-
- : **rtf**
- RTF document
- : **[SGML http://en.wikipedia.org/wiki/SGML]**
- It is a common document format which has powerful conversion applications
- ([linuxdoc-tools http://packages.debian.org/linuxdoc-tools]). From a
- single SGML file you can generate HTML, PDF, PostScript, Info, LaTeX, LyX, RTF
- and XML documents. The tools also does automatic TOC and break
- sections into subpages.
- Txt2tags generates SGML files in the LinuxDoc system type, ready to
- be converted with linuxdoc-tools without any extra catalog files or any
- SGML annoying requirements.
-
- : **[LATEX http://en.wikipedia.org/wiki/LaTeX]**
- The preferred academic document format, it is more powerful than you
- ever wondered. Full books, complicated formulas and any complex text
- can be written in LaTeX. But prepare to loose your hair when you try
- to write the tags by hand...
- Txt2tags generates ready-to-use LaTeX files, doing all the complex
- escaping tricks and exceptions. The writer just need to worry about
- the text.
-
- : **texs**
- LaTeX Spreadsheet
-
- === Text ===
- : **aap**
- ASCII Art Presentation
-
- : **aas**
- ASCII Art Spreadsheet
-
- : **aat**
- ASCII Art Text
- : **MAN**
- UNIX man pages resist over the years. Document formats come and go,
- and there they are, unbeatable.
- There are other tools to generate man documents, but txt2tags has
- one advantage: one source, multi targets. So the same man page
- contents can be converted to an HTML page, Wiki document and plain text.
-
- : **TXT**
- TXT is text. Simple, pure, beautiful.
- Although txt2tags marks are very intuitive and discrete, you can remove
- them by converting the file to pure TXT.
- The titles are underlined, and the text is basically left as is on the
- source.
-
- Tip: Use the ``--targets`` command line option to get a complete list of
- all the available targets.
- ------------------------------------------------------------------------
- == Status of Supported Structures by Target ==[struct-support]
- || Structure | html | xhtml | sgml | dbk | tex | lout | man | mgp | creole | wiki | gwiki | pmw | doku | moin | pm6 | adoc | art | txt | tml |
- | headers | Y | Y | Y | Y | Y | Y | Y | Y | - | - | - | Y | - | - | N | - | Y | Y | Y |
- | section title | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y |
- | paragraphs | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y |
- | bold | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | - | - | Y |
- | italic | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | - | - | Y |
- | underline | Y | Y | - | Y | Y | Y | - | Y | - | Y | - | Y | Y | Y | Y | N | - | - | Y |
- | strike | Y | Y | N | N | Y | - | - | - | - | Y | Y | Y | Y | Y | N | N | - | - | Y |
- | monospaced font | Y | Y | Y | Y | Y | Y | - | Y | - | Y | Y | Y | Y | Y | Y | Y | - | - | Y |
- | verbatim line | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | - | - | - |
- | verbatim area | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | - | - | Y |
- | quoted area | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | N | Y | Y | - |
- | internet links | Y | Y | Y | Y | - | - | - | - | Y | Y | Y | Y | Y | Y | - | Y | - | - | Y |
- | e-mail links | Y | Y | Y | Y | - | - | - | - | Y | Y | Y | Y | Y | Y | - | Y | - | - | Y |
- | local links | Y | Y | Y | Y | N | N | - | - | N | N | N | Y | Y | Y | - | N | - | - | Y |
- | named links | Y | Y | Y | Y | - | - | - | - | Y | Y | Y | Y | Y | Y | - | Y | - | - | Y |
- | bulleted list | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y |
- | numbered list | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y |
- | definition list | Y | Y | Y | Y | Y | Y | Y | N | Y | Y | - | Y | - | Y | N | N | Y | Y | Y |
- | horizontal line | Y | Y | - | N | Y | Y | - | Y | Y | Y | - | Y | Y | Y | N | N | Y | Y | Y |
- | image | Y | Y | Y | Y | Y | Y | - | Y | Y | Y | Y | Y | Y | Y | N | Y | - | - | Y |
- | table | Y | Y | Y | N | Y | N | Y | N | Y | Y | Y | Y | Y | Y | N | N | N | N | Y |
- || Extras | html | xhtml | sgml | dbk | tex | lout | man | mgp | creole | wiki | gwiki | pmw | doku | moin | pm6 | adoc | art | txt | Y |
- | image align | Y | Y | N | N | N | Y | - | Y | N | Y | - | N | Y | N | N | N | - | - | Y |
- | table cell align | Y | Y | Y | N | Y | N | Y | N | N | N | - | N | - | Y | N | N | N | N | Y |
- | table column span | Y | Y | N | N | Y | N | N | N | N | N | - | N | - | N | N | N | N | N | Y |
- || | Legend
- | **Y** | //Supported//
- | **N** | //Not supported (may be in future releases)//
- | **-** | //Not supported (can't be done on this target)//
- ------------------------------------------------------------------------
- == The Three User Interfaces: Gui, Web and Command Line ==[interfaces]
- As different users have different needs and environments, txt2tags is
- very flexible on how it runs.
- There are three User Interfaces for the program, each one with its own
- purpose and features.
- - **Gui**: Written in Tk, brings the windowing and clicking to txt2tags.
- - **Web**: Written in PHP, allows users to run txt2tags on the browser,
- requiring no installation on the client side.
- - **Command Line**: Written in Python, it's the program core. All
- features are available as command line options.
- ------------------------------------------------------------------------
- === Graphical Interface ===[gui]
- Since version 1.0, there is a nice Graphical Interface, that works on
- Linux, Windows, Mac and others. Just call txt2tags with the ``--gui``
- option to open it.
- % If some resources are missing, the program will tell.
- %
- % **Note:** The Tkinter module is needed. As it comes with the
- % standard Python distribution, you may already have it.
- The interface is pretty simple and intuitive:
- [IMGPATH/gui.png]
- + You locate the source .t2t file on the disk and its options are
- loaded.
- + If the target is still empty, you must choose one.
- + Then there are some options you may choose, but none of them are
- required.
- + Finally, press the "Convert!" button.
- A nice option is the "//Dump to screen//", so you can check
- the resulting code on a separate window, no file is saved at all. When
- the code is OK, you uncheck it and the file will be saved.
- The default interface colors can be changed on the [configuration file #rc],
- using the ``%!guicolors`` settings. For example:
- ```
- % set my own colors for the graphical interface (bg1, fg1, bg2, fg2)
- %!guicolors: blue white brown yellow
- ```
- ------------------------------------------------------------------------
- === Web Interface ===
- The Web Interface is up and running on the Internet at
- URLWEBSITE/online.php, so you can use and test the program
- instantly, before download.
- [IMGPATH/web.png]
- One can also put this interface on the local intranet avoiding to
- install txt2tags in all machines.
- ------------------------------------------------------------------------
- === Command Line Interface ===[cmdline]
- For command line power users, the --help should be enough:
- ```
- Usage: txt2tags [OPTIONS] [infile.t2t ...]
- --targets print a list of all the available targets and exit
- -t, --target=TYPE set target document type. currently supported:
- adoc, art, creole, dbk, doku, gwiki, html, lout, man,
- mgp, moin, pm6, pmw, sgml, tex, txt, wiki, xhtml
- -i, --infile=FILE set FILE as the input file name ('-' for STDIN)
- -o, --outfile=FILE set FILE as the output file name ('-' for STDOUT)
- --encoding=ENC set target file encoding (utf-8, iso-8859-1, etc)
- --toc add an automatic Table of Contents to the output
- --toc-level=N set maximum TOC level (depth) to N
- --toc-only print the Table of Contents and exit
- -n, --enum-title enumerate all titles as 1, 1.1, 1.1.1, etc
- --style=FILE use FILE as the document style (like HTML CSS)
- --css-sugar insert CSS-friendly tags for HTML/XHTML
- --css-inside insert CSS file contents inside HTML/XHTML headers
- -H, --no-headers suppress header and footer from the output
- --mask-email hide email from spam robots. x@y.z turns <x (a) y z>
- --slides format output as presentation slides (used by -t art)
- --width=N set the output's width to N columns (used by -t art)
- --height=N set the output's height to N rows (used by -t art)
- -C, --config-file=F read configuration from file F
- --gui invoke Graphical Tk Interface
- -q, --quiet quiet mode, suppress all output (except errors)
- -v, --verbose print informative messages during conversion
- -h, --help print this help information and exit
- -V, --version print program version and exit
- --dump-config print all the configuration found and exit
- --dump-source print the document source, with includes expanded
- Turn OFF options:
- --no-css-inside, --no-css-sugar, --no-dump-config, --no-dump-source,
- --no-encoding, --no-enum-title, --no-headers, --no-infile,
- --no-mask-email, --no-outfile, --no-quiet, --no-rc, --no-slides,
- --no-style, --no-targets, --no-toc, --no-toc-only
- Example:
- txt2tags -t html --toc file.t2t
- By default, converted output is saved to 'infile.<target>'.
- Use --outfile to force an output file name.
- If input file is '-', reads from STDIN.
- If output file is '-', dumps output to STDOUT.
- ```
- Please read the txt2tags man page for detailed information about options and command line use.
- Examples:
- | **Convert to HTML** | ``$ txt2tags -t html file.t2t``
- | **The same, using redirection** | ``$ txt2tags -t html -o - file.t2t > file.html``
- | | .
- | **Including Table Of Contents** | ``$ txt2tags -t html --toc file.t2t``
- | **And also, numbering titles** | ``$ txt2tags -t html --toc --enum-title file.t2t``
- | | .
- | **Contents quick view** | ``$ txt2tags --toc-only file.t2t``
- | **Maybe enumerate them?** | ``$ txt2tags --toc-only --enum-title file.t2t``
- | | .
- | **One liners from STDIN** | ``$ echo -e "\n**bold**" | txt2tags -t html --no-headers -``
- | **Testing Mask Email feature** | ``$ echo -e "\njohn.wayne@farwest.com" | txt2tags -t txt --mask-email --no-headers -``
- ========================================================================
- = Part II - Install =[install]
- Just download the program and run it on your machine.
- == Download & Install Python ==[download-python]
- First of all, you must download and install [Python http://www.python.org] on
- your system. Txt2tags requires Python version 2.2 or newer.
- Note that Python is already installed by default in Linux and Mac systems. If you're using those, you're done, just skip this step.
- If you are not sure if you have Python or not, open a console (tty,
- xterm, MSDOS, Terminal.app) and type ``python``. If it is not installed, the system
- will tell you.
- == Download txt2tags ==[download-txt2tags]
- The official location for txt2tags distribution is on the program
- site, at URLWEBSITE. Just download and uncompress the package (.tgz file).
- If you're in Linux, you can also use the automatic installer of your system. Some examples:
- - yum install txt2tags
- - sudo apt-get install txt2tags
- -
- % All the program's files are on the tarball (.tgz file), which can be
- % expanded by most of the compression utilities (including Winzip).
- % Just get the **latest** one (more recent date, higher version number).
- % The previous versions remains for historical purposes only.
- == Install txt2tags ==[install-txt2tags]
- As a single Python script, txt2tags needs no installation at all.
- The only file needed to use the program is the txt2tags script. The
- other files of the package are documentation, tools and sample files.
- The fail-proof way to run txt2tags, is calling Python with it:
- ``` prompt$ python txt2tags
- If you want to install txt2tags on the system as a stand alone
- program, just copy the txt2tags script to a system PATH
- directory and make sure the system knows how to run it.
- : **UNIX/Linux/Mac**
- Make the script executable (``chmod +x txt2tags``) and copy it to a
- $PATH directory (``cp txt2tags /usr/local/bin``)
- : **Windows**
- Rename the script adding the .py extension
- and copy it to a system PATH directory, such as ``C:\Windows\System32``.
- After that, you can create an icon on your desktop for it, if you want to
- use the program's Graphical Interface.
- % === Special Packages for Windows Users ===
- %
- % There is also two .EXE distribution files for txt2tags, which install
- % the program on Windows machines with just a few clicks:
- %
- % - The single txt2tags script for those who already have the Python
- % interpreted installed
- % - The stand alone version, which doesn't require Python interpreter to
- % run (it has a diet version embedded)
- %
- %
- % Please visit the //Txt2tags-Win// site to download this packages:
- % http://txt2tags-win.sf.net
- == Install Text Editor Syntax Highlighting File (optional)==[editor-syntax]
- Txt2tags comes with handy syntax highlighting files to be used by the
- following text editors:
- - Vim
- - Emacs
- - Nano
- - Kate
- - Gedit
- - JOE
- - le
- - ne
- - TextMate
- This syntax highlighting files have all the txt2tags rules and marks
- registered, helping the user to write error-free documents. Showing the
- marks in colors, you see on-the-fly if you wrote it right.
- | [IMGPATH/vim.png]
- | Sample file opened in Vim Editor
- Each editor has a different install procedure for a syntax highlighting
- file, please read the syntax file headers and the editor documentation.
- ========================================================================
- = Part III - Writing and Converting Your First Document =[your-1st-doc]
- == Check the Tools ==
- To make the first conversion you will need three things: txt2tags, a
- text editor and a web browser.
- + Make sure txt2tags is installed and running on your system.
- - **Command Line Interface:** Call "txt2tags" on the command line and
- the program should give you a "Missing input file" message. If it is
- not working, try ``python /path/to/txt2tags`` or even
- ``/path/to/python /path/to/txt2tags`` if Python is not on your PATH.
- - **Gui Interface:** Click on the program icon to launch the Gui
- Interface or call ``txt2tags --gui``.
- + Open the text editor your are comfortable with. It can be **any** text
- editor, from the good old VI to MS Word or OpenOffice.org. Create a
- brand new empty document to be your first txt2tags one and remember to
- save it as plain text.
- + Launch your favorite web browser to see the results of the conversion.
- ------------------------------------------------------------------------
- == Write the Document Header ==
- + Go to the text editor and on the very first line type the document
- main title: //My First Document//
- + On the second line make a subtitle, inserting this text:
- //A txt2tags test//
- + Then, on the third line, put some time information:
- //Sunday, 2004//
- If everything went right, you should be seeing a three line document
- with this contents:
- ```
- My First Document
- A txt2tags test
- Sunday, 2004
- ```
- This is just a part of the document, but we can already convert it and
- check the results.
- Now save this document with the name ``test.txt``. Remember to save it
- as plain text. Pay attention to which folder you are saving the file,
- you will need to remember it soon.
- ------------------------------------------------------------------------
- == The First Conversion - Gui Interface ==
- If you are in the Command Line Interface, please skip this step and read
- the next one.
- If you are in the Gui Interface, follow this steps:
- [IMGPATH/firstdoc.png]
- + Press the "Browse" button and choose the ``test.txt`` you just saved
- (remember the folder!).
- + Back to the first screen, select "HTML page" on the "Target document
- type" combo.
- + Press the "Convert!" button.
- [IMGPATH/firstdoc-done.png]
- A dialog box will appear, telling you that the file was converted
- successfully. Note that the generated HTML page was saved on the same
- folder as the text file, with the "html" extension.
- ------------------------------------------------------------------------
- == The First Conversion - Command Line Interface ==
- If you are in the Command Line Interface, move to the folder where the
- file was saved and type this command:
- ``` txt2tags --target html test.txt
- The option ``--target`` is followed
- by the "html" string, which tells the program to what format your text
- file will be converted. The last item is the text filename.
- The results were saved to the ``test.html``
- file and then the program will show you the
- "//txt2tags wrote test.html//" message.
- If some error occurred, read the message carefully.
- Here is a sample of how it will be shown on your screen:
- ```
- prompt$ txt2tags --target html test.txt
- txt2tags wrote test.html
- prompt$
- ```
- ------------------------------------------------------------------------
- == Check the Results ==
- Open the ``test.html`` file on the web browser to check if everything
- is ok.
- [IMGPATH/firstdoc-html.png]
- Here it is! You just typed three simple lines of text and txt2tags made
- all the work to set the HTML page heading information, text alignment,
- sizes, spacing and appearance. See that the main title is also placed at the
- browser title bar.
- You write text, txt2tags does the rest ;)
- Tip: You can also use CSS files on HTML pages generated by txt2tags, so the
- page appearance is 100% configurable.
- ------------------------------------------------------------------------
- == Writing the Document Body ==
- Now back to the text editor, the next step is to type the document
- contents. You can write plain text as you normally do on email messages.
- You will see that txt2tags recognizes paragraphs and list of items
- automatically, you don't have to "mark" them.
- Then again: save it, convert and check the results. This is the
- development cycle of a document in txt2tags. You just focus on the
- document contents, finishing documents faster than other editors. No
- mouse clicking, no menus, no windows, no distraction.
- Considering the following contents for the ``test.txt`` file, which is
- only plain text, compare the generated HTML page:
- ```
- My First Document
- A txt2tags test
- Sunday, 2004
- Well, let's try this txt2tags thing.
- I don't know what to write.
- Mmmmmm, I know what I need to do now:
- - Take a shower
- - Eat a pizza
- - Sleep
- ```
- [IMGPATH/firstdoc-fullhtml.png]
- You can write a full homepage with 0% of HTML knowledge. You don't need
- to insert any tags. And more, the same text file can be converted to any
- of the other txt2tags supported formats.
- Besides plain text, txt2tags has some very simple marks, that you'll
- use when you need some other formatting or structures like bold, italic,
- title, images, table and other. As a quick sample,
- ``**stars for bold**`` and ``== equals for title ==``. You can learn the
- marks on the [Txt2tags Markup Demo URLWEBSITE/markup.html].
- =======================================================================
- = Part IV - Mastering Txt2tags Concepts =[concepts]
- == The .t2t document Areas ==[areas]
- Txt2tags marked files are divided in 3 areas. Each area has its own
- rules and purpose. They are:
- : //HEADAREA//
- Place for Document Title, Author, Version and Date information.
- : //CONFAREA//
- Place for general Document Settings and Parser behavior modifiers.
- : //BODYAREA//
- Place for the Document Content.
- All areas are optional. You can write a txt2tags document with just
- headers (such as our first example), or a document with no headers or settings.
- The areas are delimited by special rules, which will be seen in detail
- on the next chapter. For now, this is a representation of the
- areas on a document:
- ```
- ____________
- | |
- | HEADERS | 1. First, the Headers
- | |
- | CONFIG | 2. Then the Settings
- | |
- | BODY | 3. And finally the Document Body,
- | |
- | ... | which goes until the end
- | ... |
- |____________|
- ```
- In short, this is how the areas are defined:
- | **Headers** | First 3 lines of the file, or the first line blank for No Headers.
- | **Config** | Begins right after the Header (4th or 2nd line) and ends when the //BODYAREA// starts.
- | **Body** | The first valid text line (not comment or setting) after the //HEADAREA//.
- === Full Example ===
- ```
- My nice doc Title
- Mr. John Doe
- Last Updated: %%mtime(%c)
- %!target : html
- %!style : fancy.css
- %!encoding: UTF-8
- %!options : --toc --enum-title
- Hi! This is my test document.
- Its content will end here.
- ```
- ------------------------------------------------------------------------
- == HEADAREA ==[headers-area]
- Location:
- - Fixed position: **First 3 lines** of the file. Period.
- - Fixed position: **First line** of the file if it is blank. This
- means Empty Headers.
- The HEADAREA is the only one that has a fixed position, line
- oriented. They are located at the first three lines of the source file.
- These lines are content-free, with no static information type needed.
- But the following is recommended:
- - //line 1//: document title
- - //line 2//: author name and/or email
- - //line 3//: document date and/or version
- (nice place for ``%%date``)
- Keep in mind that the first 3 lines of the source document will be the
- first 3 lines on the target document, separated and with high contrast
- to the text body (i.e. big letters, bold). If paging is allowed, the
- headers will be alone and centralized on the first page.
- ==== Less (or None) Header lines ====
- Sometimes the user wants to specify less than three lines for headers,
- giving just the document title and/or date information.
- Just let the 2nd and/or the 3rd lines empty (blank) and this position
- will not be placed at the target document. But keep in mind that even
- blanks, these lines are still part of the headers, so the document body
- must start **after** the 3rd line anyway.
- The title is the only required header (the first line), but if you
- leave it blank, you are saying that your document has **no headers**.
- So the //BODYAREA// will begin right after, on the 2nd line.
- No headers on the document is often useful if you want to specify your
- own customized headers after converting. The command line option
- ``--no-headers`` is usually required for this kind of operation.
- ==== Straight to the point ====
- In short: **"Headers are just __positions__, not contents"**
- Place one text on the first line, and it will appear on the target's
- first line. The same for 2nd and 3rd header lines.
- ------------------------------------------------------------------------
- == CONFAREA ==[config-area]
- Location:
- - Begins right after the HEADAREA
- - Begins on the **4th line** of the file if **Headers** were specified
- - Begins on the **2nd line** of the file if **No Headers** were specified
- - Ends when the BODYAREA starts
- - Ends by a non Setting, Blank or Comment line
- The CONFAREA is optional. An average user can write lots of txt2tags
- files without even know it exists, but the experienced users will
- enjoy the power and control it provides.
- The CONFAREA is used to store document-specific settings, so you don't
- have to type them on the command line when converting the document. For
- example, you can set the default document target type and encoding.
- Please read the [Settings section #settings-overview] for more
- information about them.
- ----------------------------------------------------------------
- == BODYAREA ==[body-area]
- Location:
- - Begins on the first valid text line of the file
- - Headers, Settings and Comments are **not** valid text lines
- - Ends at the end of the file (EOF)
- The body is anything outside Headers and Config Areas.
- The body holds the document contents and all formatting and structures
- txt2tags can recognize. Inside the body you can also put comments for
- //TODOs// and self notes.
- You can use the ``--no-headers`` command line option to convert only the
- document body, suppressing the headers. This is useful to set your own
- headers on a separate file, then join the converted body.
- ----------------------------------------------------------------
- == Settings ==[settings-overview]
- Settings are special configurations placed at the source document's
- CONFAREA that can affect the conversion process. Their syntax is:
- ``` %! keyword : value
- List of valid keywords:
- || Keyword | Description |
- | Target | Set the default target to the document be converted to.
- | Options | Set the default options to be used on the conversion. The format is the same as the command line options.
- | Style | Set the document style. Used to define a CSS file for HTML/XHTML and to load a package in LaTeX.
- | Encoding | Set the document Character Set. Used if the document contains accented letters or other not-ASCII characters.
- | PreProc | Input filter. Sets "find and replace" rules to be applied on the BODYAREA of the source document.
- | PostProc | Output filter. Sets "find and replace" rules to be applied on the converted document.
- Example:
- ```
- %!target : html
- %!options : --toc --toc-level 3
- %!style : fancy.css
- %!encoding: UTF-8
- %!preproc : "AMJ" "Aurelio Marinho Jargas"
- %!postproc: '<BODY.*?>' '<BODY bgcolor="yellow">'
- ```
- Note that the spacing and capitalization of the keyword are ignored. So you can also do ``%!Target:html`` and ``%! TARGET :html``.
- Learn more about settings in [Part VII - Mastering Settings #settings].
- -----------------------------------------------------------------------
- == Command Line Options ==[options]
- The fastest way of changing the txt2tags default behavior is to use
- command line options. This options are available on the Command Line
- Interface only, not on Gui or Web.
- Just like the other system's tools, the program do accept a set of
- predefined options. An option is an hyphen followed by a letter or two
- hyphens followed by one or more words, like ``-t`` and ``--target``.
- % Talking about the target option, it is the only required one, the others
- % are optional.
- Options that are generally used are ``--outfile`` to define a customized
- output file name, ``--toc`` to turn on the automatic TOC generation and
- ``--encoding`` to set the document character set. Most of the options
- can be turned off prefixing a "no-" before its name, for example:
- ``--no-encoding`` and ``--no-toc``.
- You can register the desired options for a source file inside its
- CONFAREA, using the ``%!options`` setting. This way you don't have to
- type them on the command line anymore.
- Example:
- ``` %!options: --toc -o mydoc.html
- The exception is the target specification, that has its own setting:
- ``` %!target: html
- Use the ``--help`` option to get a complete list of all the options
- available in txt2tags.
- Learn more about [%!options #setting-options] and [%!target #setting-target].
- -----------------------------------------------------------------------
- == User Configuration File (RC File) ==[rc]
- The user configuration file (also called RC file) is a central place to
- store the settings that will be shared by ALL converted files. If you
- keep inserting the same settings on every .t2t file you write, move it
- to the RC file and it will be used globally, for existing and future
- source files.
- The default location of this file depends on your system. It can also be
- specified by the user, using an environment variable.
- || RC file location ||
- | Windows | ``%HOMEPATH%\_t2trc``
- | UNIX, Linux, Mac | ``$HOME/.txt2tagsrc``
- | User defined | ``T2TCONFIG`` variable
- The format of the settings is exactly the same as the ones used on the
- .t2t files CONFAREA. There is a sample RC file on the package at
- ``doc/txt2tagsrc``. Example:
- ```
- % my configs
- %%% Always use CSS-friendly tags in HTML
- %!options(html): --css-sugar
- %%% Change the default TOC depth for all targets
- %!options: --toc-level 4
- %%% Set the default encoding for all documents
- %!options: --encoding UTF-8
- ```
- Any line that is not blank, a comment or a valid config line will raise
- error when txt2tags runs. So be careful when editing this file.
- Txt2tags automatically apply the RC file contents into any source file it
- is converting. If you want to disable this behavior for a specific
- file, use the ``--no-rc`` command line option.
- == Configuration Loading Order and Precedence ==[config-loading]
- There are three ways of telling txt2tags which options and settings to
- use, and this is the order that they are read and applied:
- + The user configuration file (RC) settings
- + The source document CONFAREA settings
- + The command line options
- First txt2tags reads the RC file contents (if any) and apply its
- configurations on the current source file. Then it scans the source
- document CONFAREA for settings and if found, they are applied also,
- overriding the RC ones in case of conflict. Finally comes the command
- line options, stronger than the other two.
- So, if the document encoding was defined on the three resources, the
- command line will be the one used.
- -----------------------------------------------------------------------
- == %!include command ==[include]
- The ``include`` command is used to paste the contents of an external
- file into the source document body. It is not a config, but a command,
- and it is valid on the document BODYAREA.
- The ``include`` command is useful to split a large document into smaller
- pieces (like chapters in a book) or to include the full contents of an
- external file into the document source. Sample:
- ```
- My first book
- Dr. John Doe
- 1st Edition
- %!include: intro.t2t
- %!include: chapter1.t2t
- %!include: chapter2.t2t
- ...
- %!include: chapter9.t2t
- %!include: ending.t2t
- ```
- You just inform the filename after the ``%!include`` string. The
- optional target specification is also supported, so this is valid
- either:
- ``` %!include(html): file.t2t
- Note that include will insert the file BODYAREA into the source
- document. The included file Header and Config Areas are ignored. This
- way you can convert the included file alone or inside the main document.
- But there's another three types of include:
- - Verbatim include
- - Raw include
- - Tagged include
- The **Verbatim** type includes a text file preserving its original
- spaces and formatting, just like if the text was inside the txt2tags
- Verbatim area (```). To specify this type, enclose the filename with
- backquotes:
- ``` %!include: ``/etc/fstab``
- The **Raw** type includes a text file as is, not trying to find and
- parse txt2tags marks on it, just like if the text was inside the Raw
- area ("""). To specify this type, enclose the filename with double
- quotes:
- ``` %!include: ""nice_text.txt""
- And the **Tagged** type is passed directly to the resulting document,
- with NO parsing or escaping performed by txt2tags. This way you can
- include additional tagged parts to your document. Useful for default
- header or footer information, or more complicated tagged code,
- unsupported by txt2tags:
- ``` %!include(html): ''footer.html''
- Note that the filename is enclosed with single quotes. As the text
- inserted is already parsed, you should specify the target to avoid
- mistakes.
- -----------------------------------------------------------------------
- == %!includeconf command ==[includeconf]
- The ``includeconf`` command is used to include configurations from an
- external file into the current one. This command is valid inside the
- source document CONFAREA only.
- It is useful to share the same config for multiple files, so you can
- centralize it. On any file do you want to include that central
- configuration, put a ``includeconf`` call. Example:
- ```
- My First Document
- John Doe
- July, 2004
- %!includeconf: config.t2t
- Hi, this is my first document.
- ```
- The format inside the included file is the same as in the
- [RC file #rc].
- Note that the optional target specification is NOT supported for this command.
- ```
- %!includeconf: config.t2t <--- OK
- %!includeconf(html): config.t2t <--- NOT OK
- ```
- =======================================================================
- = Part V - Mastering Marks =[marks]
- Overview of all txt2tags marks:
- || Basic || Beautifiers ||
- | //Headers// | First 3 lines | //Bold// | ""**words**""
- | //Title// | = words = | //Italic// | ""//words//""
- | //Numbered title// | + words + | //Underline// | ""__words__""
- | //Paragraph// | words | //Strike// | ""--words--""
- | //Links// | ""[label url]"" | //Monospaced// | ""``words``""
- | //Image// | ""[filename.jpg]"" | //Raw text// | """"words""""
- | || //Tagged text// | ""''words''""
- || Other ||||
- | //Quote// | <TAB>words | //Separator line// | ------------...
- | //List// | - words | //Strong line// | ============...
- | //Numbered list// | + words | //Table// | ""| cell1 | cell2 | cell3...""
- | //Definition list// | : words | //Anchor// | = title =[anchor]
- | //Comment line// | % comments | //Comment area// | %%%\n comments \n%%%
- | //Verbatim line// | ""```"" word | //Verbatim area// | ""```\n lines \n```""
- | //Raw line// | """"""" words | //Raw area// | """""""\n lines \n"""""""
- | //Tagged line// | ""'''"" words | //Tagged area// | ""'''""\n lines \n""'''""
- General Rules:
- - **Headers** are the first three document lines, marks are not interpreted.
- - **Titles** are balanced "=" or "+" chars around the title text. The more chars, more deep is the title.
- - **Beautifiers** don't accept spaces between the marks and its contents.
- - The **Comment** mark "%" must be at the line beginning (first column).
- - **Images** filename must end in GIF, JPG, PNG or similar.
- - The only **multiline** marks are the Comment, Verbatim, Raw and Tagged areas.
- - No…