# txt2tags(1) man page

- NAME
- SYNOPSIS
- DESCRIPTION
- MARKUP
- OPTIONS
- SOURCE FILES
- SETTINGS
- COMMANDS
- MACROS
- EXAMPLES
- FILES
- ENVIRONMENT
- AUTHOR
- BUGS
- COPYRIGHT

# NAME

txt2tags - text formatting and conversion tool

# SYNOPSIS

txt2tags [options] [FILE...]

# DESCRIPTION

txt2tags reads a text file with minimal markup and convert it to: ASCII Art, AsciiDoc, Creole, DocBook, DokuWiki, Google Code Wiki, HTML, LaTeX, Lout, MagicPoint, Man page, MoinMoin, PageMaker, Plain Text, PmWiki, SGML, Wikipedia and XHTML.

This man page was created by txt2tags from a simple text file. The same text file is also converted to HTML for the online version of this manual.

ONE source, MULTI targets - http://txt2tags.org

# MARKUP

      Headers           First 3 lines of the source file
      Title             = words =
      Numbered title    + words +
      Comment           % comments
      Separator line    -----------------------...
      Strong line       =======================...
      Image             [filename.jpg]
      Link              [label url]

      Bold              **words**
      Italic            //words//
      Underline         __words__
      Strike            --words--
      Monospaced        ``words``
      Raw               ""words""
      Tagged            ''words''

      Paragraph         words
      Quote             <TAB>words
      List              - words
      Numbered list     + words
      Definition list   : words
      Table             | cell1 | cell2 | cell3...

      Verbatim line     ``` words
      Raw line          """ words
      Tagged line       ''' words

      Verbatim block    ```
                        lines
                        ```
      Raw block         """
                        lines
                        """
      Tagged block      '''
                        lines
                        '''

# OPTIONS

--art-chars=PATTERN
  Define PATTERN as the pattern of characters used to compose the ASCII Art decorations, in the following order: corner, border, side, bar1, bar2, level2, level3, level4, level5. The default pattern value is +-|-==-^". This option is only used by the ASCII Art target.

-C, --config-file=FILE
  Read configuration from the external file FILE. The configuration must be on the %!keyword:value format. See SETTINGS section for details.

--css-sugar
  Improves the generated HTML/XHTML code to be used with CSS files. Tag attributes are removed, presentation tags are avoided, header is composed by H1, H2 and H3 tags, new DIVs are created: #header, #body, .toc.

--css-inside
  Insert CSS file contents inside HTML/XHTML headers. Use `--style` to specify a CSS file to be read.

--dump-config
  Print all the configuration found and exit.

--dump-source
  Print the document source, with includes (`%!include`) expanded.

--encoding=CODE
  Inform the character set (file encoding) used by the source document. Examples are UTF-8 and iso-8859-1. The encoding is not changed during conversion, so the output document will have the same encoding as the sources.

--gui
  Invoke Graphical Tk Interface.

-h, --help
  Print help information and exit.

-H, --no-headers
  Suppress header and footer from the output. Only the contents (body) will be shown.

--headers
  Show header and footer in the output. Default is ON.

--height=NUM
  Set the output's height to NUM rows. This option is only used by the ASCII Art target, when also using `--slides`.

-i, --infile=FILE
  Set FILE as the input file name, the source document. Use '-' to read the sources from the STDIN.

--mask-email
  Hide emails from spam robots. Removes @ and dots. The address foo@bar.com turns to <foo (a) bar com>.

-n, --enum-title
  Turn on automatic numbering for titles. They will be prefixed by 1, 1.1, 1.1.1, ...

--no-dump-config
  Cancel the `--dump-config` action.

--no-dump-source
  Cancel the `--dump-source` action.

--no-encoding
  Clear the encoding setting.

--no-enum-title
  Turn off the automatic numbering for titles.

--no-infile
  Clear all the previous infile declarations.

--no-targets
  Cancel the `--targets` action.

--no-mask-email
  Turn off the email masking feature.

--no-outfile
  Clear the previous outfile declaration.

--no-quiet
  Show messages, turning off the `--quiet` option.

--no-rc
  Do not read the user configuration file ~/.txt2tagsrc.

--no-slides
  Turn off the slides feature.

--no-style
  Clear all the style settings.

--no-toc
  Remove the Table of Contents from the output.

--no-toc-only
  Turn off the `--toc-only` action.

-o, --outfile=FILE
  Set FILE as the output file name. Use '-' to send the results to STDOUT.

-q, --quiet
  Quiet mode. Suppress all output, except errors.

--rc
  Read the user configuration file ~/.txt2tagsrc. Default is ON.

--slides
  Format output as presentation slides. This option is only used by the ASCII Art target.

--style=FILE
  Use FILE as the document's style file. Used to define CSS files for HTML/XHTML documents and packages for LaTeX. This option can be used multiple times to include multiple files.

-t, --target=TYPE
  Set the output document format to TYPE. Some popular types are: html, xhtml, tex, man, txt. Use the `--targets` option to see all the available formats.

--targets
  Print a list of all the available targets and exit.

--toc
  Include an automatic Table of Contents (TOC) to the output, between the Header and the Body. You can also specify the TOC position using the `%%TOC` macro.

--toc-level=NUM
  Set the maximum TOC level to NUM. All titles deeper than NUM will not be included in the Table of Contents.

--toc-only
  Print the Table of Contents and exit.

-v, --verbose
  Print informative messages during conversion. This option can be used multiple times to increase the number of messages shown.

-V, --version
  Print program version and exit.

--width=NUM
  Set the output's width to NUM columns. This option is only used by the ASCII Art target.

# SOURCE FILES

The source files are usually identified by the .t2t extension (such as `myfile.t2t`). You may have three areas inside your sources:

Header (optional)
  The first three lines of the file. Leave the first line blank if you don't need headers. Used for document title, author, version and date information.

Settings (optional)
  Begins right after the Header (4th or 2nd line) and ends when the Body area starts. Used for settings (configurations) in the `%!keyword:value` format.

Body
  Begins at the first valid text line (not comment or setting) after the Header area and goes until the end of the document. Used for the document contents.

# SETTINGS

Settings let you customize txt2tags, they're similar to options. They can be used at: source document's Settings area, `~/.txt2tagsrc` file, external file called with `--config-file`.

%!target
  Set the output format, just like `--target`. Example:

        %!target: html

%!options(target)
  Set the default options to each target. You must use the command line options. Example:

        %!options(html): --toc --toc-level 3 --css-sugar

%!includeconf
  Include configurations from an external file into the current, just like `--config-file`. Example:

        %!includeconf: myconfig.t2t

%!style
  Set a style file for the document, just like `--style`. Can be used multiple times. Example:

        %!style: colors.css

%!encoding
  Set the character set used by the document, just like `--encoding`. Example:

        %!encoding: UTF-8

%!preproc
  Input search/replace filter used to change the Body of the source document BEFORE any parsing by txt2tags. Search uses Python regular expressions. Example:

        %!preproc:  "JJS"  "John J. Smith"

%!postproc
  Output search/replace filter used to change the generated document AFTER all the txt2tags processing. Search uses Python regular expressions. Example:

        %!postproc(html):  "<B>"  "<STRONG>"

If the same keyword appears more than once, the last found will be the one used (except: options, preproc and postproc, which are cumulative). Invalid keywords are ignored. The parsing order is: `~/.txt2tagsrc`, source document's Config area, `--config-file` option.

# COMMANDS

Commands perform tasks during conversion time. They must be placed at the source document's Body.

%!csv: file.csv
  Includes an external CSV file as a table.

%!include: file.t2t
  Includes a txt2tags file in the document.

%!include: ``file.txt``
  Includes a text file (verbatim) in the document.

%!include: ''file.html''
  Includes an already tagged file in the document.

# MACROS

Macros are handy shortcuts to insert dynamic contents in your document. They must be placed at the source document's Body. Except `%%toc`, all macros can be customized with special directives, like `%Y` and `%f`. See the txt2tags User Guide for details.

%%date
  Insert the current date. The default format is `%%date(%Y%m%d)`, which gives YYYYMMDD.

%%infile
  Insert the source file path. The default format is `%%infile(%f)`. Useful for footer links like `[See source %%infile]`.

%%mtime
  Insert the source file modification time. The default format is `%%date(%Y%m%d)`, which gives YYYYMMDD.

%%outfile
  Insert the output file path. The default format is `%%outfile(%f)`. Useful for self mentioning like "This is the manpage.html file".

%%toc
  Specifies where the Table of Contents will be placed. You can even use it multiple times. Note that you must also use the `--toc` option.

# EXAMPLES

`txt2tags -t html file.t2t`

  Convert to HTML, saving to file.html.

`txt2tags -t html -o - file.t2t`

  Convert to HTML, sending results to STDOUT.

`txt2tags -t html --toc file.t2t`

  Convert to HTML, including automatic Table Of Contents.

`txt2tags -t html --toc --toc-level 2 -n file.t2t`

  Convert to HTML, with a two level Table of Contents and numbered titles.

`txt2tags --toc-only file.t2t`

  Just show the Table of Contents, no conversion is done.

`txt2tags -t html --css-sugar --style base.css --style ui.css file.t2t`

  Convert to HTML, preparing the resulting code to be used with CSS, and also include calls to two external CSS files.

`txt2tags -t art --slides --width 80 --height 25 -o - file.t2t | more`

  Create ASCII Art presentation slides, ready to be shown in a 80x25 terminal screen/window.

`(echo ; echo "**bold**") | txt2tags -t html -H -`

  Handy one-liner for quick tests using STDIN.

`txt2tags -t html -o - file.t2t | tidy > file.html`

  Send results to STDOUT, then fine tune the code with an external program before saving the output file.

# FILES

~/.txt2tagsrc
  Default user configuration file.

# ENVIRONMENT

T2TCONFIG
  If non-null, sets the full pathname for the default user configuration file.

# AUTHOR

Aurelio Jargas <<verde (a) aurelio net>>

# BUGS

http://bugs.txt2tags.org

# COPYRIGHT

Copyright (C) 2001-2012 Aurelio Jargas, GNU GPL v2

« txt2tags.org