/doc/English/tags-reference.t2t

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

All TAGS Reference


    =Introduction=[Introduction]

This document is a reference for all available TAGS available to
developers for adding new targets, as found in the //getTags()// function.
It is intended for **advanced users** and **developers** who wish to
add a new target to Txt2tags without needing to know the source code
in detail.

This reference will describe all available tags, including how and
where they will appear in the final tagged document, how the various
rules in the //getRules()// function affect them, and what special
characters and macros are expanded in the output.

Txt2tags has fairly complex rules and gotchas, and it can be
difficult searching through the entire source code to see exactly
what each tag does. Often, when creating a new target, a developer
is surprised when the output is not quite how it was expected to be,
and in particular that certain tags did not behave as expected. It
is hoped that this reference will make it easier to create new
targets with fewer bugs and surprises, so txt2tags can continue to
grow as "one source, many targets".


    +The Parts of a Document+[chapter-ThePartsofaDocument]

Before looking at the individual tags, it is important to understand
exactly how the different parts of a document fit together.

A document is built from a **template**, which is filled with the
document's **headers**, **body**, and an optional **table of contents**.

    ++Template++[section-Template]

The template of a document consists of the basic opening and closing
markup that all examples of that type of file must have. All
supported targets have a default template included in the source
code, in the //HEADER_TEMPLATE// area. Alternatively, the user may
use a custom header using the //--template// command line option.

Templates should make use of the **%(HEADER1)s**, **%(HEADER2)s**,
and **%(HEADER3)s** macros, as well as **%(ENCODING)s** and
**%(STYLE)s** if the target supports character encodings and
external stylesheets. These macros will be replaced with the
appropriate values from the source document. If any value is blank,
the entire line including the macro is removed unless the target has
included the rule ['keepblankheaderline' #keepblankheaderline].

It is not required, but by convention **HEADER1** refers to the title,
**HEADER2** to the author, and **HEADER3** to the date the document was
created. Several targets reflect this convention in their use of the
**HEADER** metadata in their default templates.

Custom templates must also include the **%(BODY)s** macro, which
will be expanded to the fully tagged body of the document. The
default template should not include this, as it is automatically
added to the end of the //HEADER_TEMPLATE// text.

    ++Body Text++[section-BodyText]

The body of a document consists of the fully tagged text converted
from the original source document. It is nothing more or less than
the original document with all txt2tags markup removed, and replaced
with the target-specific markup. All of the tags from //getTags()//
end up in this section, along with all user text.

The document is parsed into blocks, and each block is processed line
by line. Note that this seraration of lines is kept throughout the
process, and in nearly all cases the final tagged text is broken in
the same locations as the original. This is important to remember,
as several tags depend on this line by line behaviour, and their
output changes that line it self, not the block.

    ++Table of Contents++[section-TableofContents]

Txt2tags is able to add a table of contents to the output document.
If the target supports creating a table of contents itself, Txt2tags
can take advantage of that. Otherwise, Txt2tags can generate a table
of contents automatically and insert it where appropriate.

If the command line option //--toc// is used, Txt2tags will add a
table of contents to the output. If the command line option
//--toc-only// is used, then the table of contents will be the only
thing output, and the rest of the body text will not.

By default, the table of contents will be emitted as the first text
in the body of the document. That is, it will be emitted directly
after [bodyOpen #bodyOpen] and before the main text. If this is not
appropriate, the user can insert the **%%toc** macro into the source
text, and it will be emitted there instead.

Full details on how the table of contents is emitted is given in the
section on the Table of Contents tags.

    ++Escapes++[section-Escapes]

One final note, though this is not really part of the document
structures. Most text is processed throught the functions
//doEscape()// and //doFinalEscape()// before being emitted in the
final output. This is used to allow certain characters that may give
problems in Txt2tags, such as backslashes or characters that are the
same as Txt2tags markup.

The emitted tags are not processed by these functions at all. Some
tags also prevent parts of the text from being processed by these
functions. The reference will note when this is the case.


    +Basic Blocks+[chapter-BasicBlocks]

    ++Paragraphs++[section-Paragraphs]

Paragraphs are the most common, and most basic of all text blocks.
They are the simple, regular body text of the document.

If the rule ['blanksaroundpara' #blanksaroundpara] is defined, an empty line will be
emitted before and after the paragraph and tags.

If the rule ['onelinepara' #onelinepara] is defined, the paragraph text will have
all newlines removed and replaced with spaces, emitting the
paragraph as a single line.

    ===paragraphOpen===[paragraphOpen]

This tag is emitted, on its own line, before each paragraph of body
text. If this tag (and [paragraphClose #paragraphClose]) are not defined for a
target, the body text is simply printed as unadorned plain text,
much like the source document.

: Macros:
  : **~D~**
    If this macro is included in the tag, it will be expanded to the
    value of the depth of that particular paragraph. Most paragraphs
    have depth '1', pargraphs inside a top-level list will have
    depth level '2', and so on.

    If the rule ['blockdepthmultiply' #blockdepthmultiply] is defined for the target,
    the depth value will be multiplied by that amount before being
    emitted. If the rule ['depthmultiplyplus' #depthmultiplyplus] is defined, then that
    value will be added to the depth before multiplying by
    ['blockdepthmultiply' #blockdepthmultiply], but only if used with
    ['blockdepthmultiply' #blockdepthmultiply].

    If the rule ['zerodepthpara' #zerodepthpara] is defined, then top-level
    paragraphs (those not nested inside a list) will always have
    **~D~** replaced with '0', regardless of the other rules.


    ===paragraphClose===[paragraphClose]

This tag is emitted, on its own line, after each paragraph of body
text.

: Macros
  None


    ++Block Quotations++[section-BlockQuotations]

Block quotes are paragraphs that are set apart from regular
paragraphs, usually to show that they are quoted from some external
source.

Note that, at this time, Txt2tags is not able to emit multiple
paragraphs within a single block quote. Each separate paragraph
will be emitted as a separate block quote with Open and Close tags.

Nested block quotes are allowed, unless the rule ['quotenotnested' #quotenotnested]
is defined for the target.

If the rule ['keepquoteindent' #keepquoteindent] is defined, then each line of the
block quote will have tab characters added before the text equal to
the depth of that quote.

If the rule ['blanksaroundquote' #blanksaroundquote] is defined, an extra blank line is
emitted before and after the block quote.

    ===blockQuoteOpen===[blockQuoteOpen]

This tag is emitted, on its own line, before each paragraph of a
block quote.

The block depth is given by a number of tab characters.
``blockQuoteOpen`` will have these tabs inserted before the tag,
unless the rule ['tagnotindentable' #tagnotindentable] is defined.

: Macros:
  : **~D~**
    If this macro is included in the tag, it will be expanded to the
    value of the depth of that particular block quote paragraph. The
    first Block Quote has a depth level of '1'. A quote nested
    within the first will have a depth of '2', and so on.

    If the rule ['blockdepthmultiply' #blockdepthmultiply] is defined for the target,
    the depth value will be multiplied by that amount before being
    emitted. If the rule ['depthmultiplyplus' #depthmultiplyplus] is defined, then that
    value will be added to the depth before multiplying by
    ['blockdepthmultiply' #blockdepthmultiply], but only if used with
    ['blockdepthmultiply' #blockdepthmultiply].


    ===blockQuoteLine===[blockQuoteLine]

If this tag is present, it will be added before each line of the
block quote.

This tag is emitted multiple times for nested quotes, one copy of
the tag for each level of depth. For example, if the quote is
defined as '*', then for a third-level nested quote each line
will begin with '***'.

If the rule ['keepquoteindent' #keepquoteindent] is defined, all copies of this tag
are emitted after the tab characters and before the quote text.

: Macros:
  None


    ===blockQuoteClose===[blockQuoteClose]

This tag is emitted, on its own line, at the end of each block
quote.

The block depth is given by a number of tab characters.
``blockQuoteClose`` will have these tabs inserted before the tag,
unless the rule ['tagnotindentable' #tagnotindentable] is defined.

: Macros:
  None


    ++Verbatim Blocks++[section-VerbatimBlocks]

Verbatim blocks are used when the user needs to keep control over
the spaces and line breaks of a block of text. Verbatim blocks are
usually emitted in a monospace font, and all spaces and line breaks
will be the same as in the source text. It is commonly used for
ASCII art and for source code listings.

Note that this is not the same as raw text. Raw text blocks are
emitted exactly as they are in the source text, with no processing.
Verbatim blocks are processed, and are emitted so that they
//appear// the same as in the source text.

By default, verbatim blocks are passed through //doEscape()// but
not //doFinalEscape()//. If the rule ['verbblocknotescaped' #verbblocknotescaped] is
defined, the text will not be passed through //doEscape()//. If the
rule ['verbblockfinalescape' #verbblockfinalescape] is defined, then the text will be be
passed through //doFinalEscape()//.

If the rule ['indentverbblock' #indentverbblock] is defined, then each line of the
text will be emitted with two spaces inserted before the text.

If the rule ['blanksaroundverb' #blanksaroundverb] is defined, an extra blank line
will be emitted before and after the verbatim block.

Note that the entire verbatim area is emitted as a single block.
Blank lines within a verbatim block do not separate paragraphs.

    ===blockVerbOpen===[blockVerbOpen]

This tag is emitted, on its own line, before each block of verbatim
text.

: Macros:
  None


    ===blockVerbLine===[blockVerbLine]

This tag is emitted before each line of text in the verbatim block.
Some targets require this to keep the entire verbatim block
together, or to maintain formatting.

If the rule ['indentverbblock' #indentverbblock] is defined, this tag is emitted
after the spaces used for the indent, before the block text.

: Macros:
  None


    ===blockVerbSep===[blockVerbSep]

This tag is emitted, on a line by itself, in between each line of
text in the verbatim block.

: Macros:
  None


    ===blockVerbClose===[blockVerbClose]

This tag is emitted, on its own line, after each block of verbatim
text.

: Macros:
  None


    +Inline Tags+[chapter-InlineTags]

These tags are used to add additional formatting to text within the
basic blocks. They are useable within regular paragraphs and block
quotes, and unless otherwise noted, within lists and tables as
well.

All of these tags are inline, meaning that they do not begin or end
blocks and do not add or remove lines of text.

    ++Text Beautifiers++[section-TextBeautifiers]

These are the simple tags used to change how text appears in the
final output.

None of these tags use any special macros.

    ===fontItalicOpen, fontItalicClose===[fontItalic]

These tags are emitted, respectively, immediately before and after
some text that should appear in //italics// for emphasis.

    ===fontBoldOpen, fontBoldClose===[fontBold]

These tags are emitted, respectively, immediately before and after
some text that should appear in **bold** for strong emphasis.

    ===fontUnderlineOpen, fontUnderlineClose===[fontUnderline]

These tags are emitted, respectively, immediately before and after
some text that should appear __underlined__.

    ===fontStrikeOpen, fontStrikeClose===[fontStrike]

These tags are emitted, respectively, immediately before and after
some text that should appear --struck out--.

    ===fontMonoOpen, fontMonoClose===[fontMono]

These tags are emitted, respectively, immediately before and after
some text that should appear in a ``monospaced`` font, such as
inline source code.

    ++Links++[section-Links]

These tags are used to insert links to external files, pages, or
resources, as well as internal links within the document itself.

The link text itself is a **url**. Ordinarily, urls are not escaped
so as to preserve all characters within it exactly as typed. It the
rule ['escapeurl' #escapeurl] is defined for a target, the url will be passed
through //doEscape()// after all. Additionally, if the rule
['linkable' #linkable] is not defined, signalling that this target does not
support true links, then the url will be escaped as well.

    ===url===[url]

This tag is used to insert a bare url without a label.

: Macros:
  : **\a**
    This mark within the tag will be expanded into the text of the
    url itself. For example, if the ``url`` tag is '[url=\a]'
    and the url in the source document in 'example.com', then
    the text '[url=example.com]' will be emitted.


    ===urlMark===[urlMark]

This tag is used for a link with a label. The label will appear in
the final document, possibly formatted differently to set it apart,
but it will function as a link to the url.

: Macros:
  : **\a**
    This mark should appear twice in the tag. The first instance is
    expanded to the text of the url, the second instance is expanded
    to the text of the label.

    If the rule ['labelbeforelink' #labelbeforelink] is defined for the target, then
    the first instance is the label, and the second instance is the
    url.

    If the rule ['imglinkable' #imglinkable] is defined for the target, then an
    [img #img] tag (see below) is allowed as the label.


    ===urlMarkAnchor===[urlMarkAnchor]

This tag is used if the url begins with a '#', designating an
internal link to an anchor within the document. Some targets require
a different tag for internal links than for external links.

This tag otherwise behaves identically as [urlMark #urlMark], with the same
macro definitions.


    ===email===[email]

This tag is used if the url is detected as being for an email
address rather than to a webpage or file. Ordinarily Txt2tags will
detect automatically that the url represents an email address.

Just like [url #url], this tag is used for a plain email with no label
defined.

: Macros:
  : **\a**
    This mark is expanded to the full text of the email address.


    ===emailMark===[emailMark]

Similar to [urlMark #urlMark], this tag is used for email addresses that
are assigned a label in the source document.

: Macros:
  : **\a**
    This mark appears twice in the tag, just like [urlMark #urlMark]. The
    first instance is expanded to the text of the email address, and
    the second instance to the text of the label. If the rule
    ['labelbeforelink' #labelbeforelink] is defined, then the first instance is the
    label and the second instance is the email address.


    ++Images++[section-Images]

Many targets allow images to be included in documents, often with a
syntax similar to that of links. These tags are used to insert
images into your documents

    ===img===[img]

This is the basic tag used to insert an image into the output
document. The image is represented by a file path to the image file,
and is linked into the document.

The filename is not escaped, and is assumed to represent a real file
on the same filesystem as the document. As this time, links to
remote files are not supported.

: Macros:
  : **\a**
    This mark is expanded to the text of the file path pointing to
    the inserted image.

  : **~A~**
    This mark represents the alignment of the image. If the rule
    ['imgalignable' #imgalignable] is defined for the target, then this mark will
    be replaced with the contents of [_imgAlignLeft, _imgAlignRight, or _imgAlignCenter #_imgAlign] as appropriate. (Note
    the underscore at the beginning of each tag.)


    ===_imgAlignLeft, _imgAlignRight, _imgAlignCenter===[_imgAlign]

These tags are used to add alignment to the [img #img] tag. If the rule
['imgalignable' #imgalignable] is defined, then whichever of these tags is
appropriate will replace the **~A~** mark within the [img #img] tag.

Note the underscores at the beginning of the tag names. Do not
confuse these with the [imgAlignLeft, imgAlignRight, and imgAlignCenter #imgAlign] tags, explained below.

: Macros:
  None


    ===imgAlignLeft, imgAlignRight, imgAlignCenter===[imgAlign]

These tags are used if the alignment changes the image tags too much
to simply use [img #img] and [_imgAlign* #_imgAlign].

If the rule ['imgalignable' #imgalignable] is defined and these tags are defined,
then they will be used //instead of// the [img #img] tag. Each of these
tags should have whatever markup is needed for image align in them,
and they will not have **~A~** expanded.

: Macros:
  : **\a**
    This mark is expanded to the file path of the image file, just
    as in the [img #img] tag.


    ===imgEmbed===[imgEmbed]

This tag is used to embed image data directly into the document
itself, rather than to link to the image file externally. If the
command-line option //--embed-images// is used, then this tag will be
used //instead of// the [img #img] tag.

Currently this is only used by the **RTF** target, and will require
additional functionality to be added to Txt2tags to add support to
another target.

: Macros:
  : **\a**
    This mark is expanded into the full file data of the embedded
    image file, as well as whatever additional markup may be
    required to make it work with the target.


    +Titles and Sections+[chapter-TitlesandSections]

Txt2tags allows you to specify markup for separating documents into
sections, and for adding titles or headings to each section. It
accomplishes both these tasks with the ``title`` family of tags.

There are two methods used, depending on the tags and rules
specified. By default, the [title* #title1] tags are used simply to mark
up each section heading or subsection heading. Sections are implied
by these headings, but do not have explicit markup.

If the rule ['titleblocks' #titleblocks] is defined for the target, then the
[title*Open* #title1Open] and [blockTitle*Open* #blockTitle1Open] family of tags is used
instead. These explicitly separate sections and subsections and
allow additional markup for section commands as needed.

Either way, the titles are used to generate the automatic table of
contents, if desired. If the target supports its own table of
contents, then markup to add the titles/sections to it should be
included in the tags.

The title text itself does not support any additional Txt2tags
markup. That is, the user may not apply ''//italics//'' to the
title, as the marks will simply appear in the title as is. The title
text is escaped with the //doEscape()// function and, if the rule
['finalescapetitle' #finalescapetitle] is defined, it is escaped by
//doFinalEscape()// as well.

    ++The Anchor++[section-TheAnchor]

    ===anchor===[anchor]

This tag is used to add a linkable anchor the title heading, if the
target supports internal links. This should include all needed
markup to allow a [urlMark #urlMark] or [urlMarkAnchor #urlMarkAnchor] tag to link
directly to it from another part of the document.

If the command-line option //--toc// is specified, then all titles
will have anchors added to them (if they do not have one already)
and the table of contents will include direct links to each section
of the document.

: Macros:
  : **\a**
    This mark is expanded into the label text for the anchor, as
    specified by the user or generated automatically by Txt2tags if
    none has been specified and the //--toc// option is in effect.


    ++Titles++[section-Titles]

The basic title tags are only used if the rule ['titleblocks' #titleblocks] is
not defined for the target. These are for simple markup of headings,
or simple section separators, for targets that do not require any
complicated markup for sections and subsections.

    ===title1, title2, title3, title4, title5===[title1]

These tags are for basic standard headings. ``title1`` is considered
the top level heading, ``title2`` the next level below it, and so
on.

If the rule ['blanksaroundtitle' #blanksaroundtitle] is defined, and extra blank line
will be emitted before and after this tag.

: Macros:
  : **\a**
    This mark is expanded into the text of the title itself,
    unchanged excepts for necessary escapes from the source
    document.
  : **~A~**
    This mark is expanded into the value of the [anchor #anchor] tag,
    along with the text of the label for that anchor. It is removed
    if the title does not have a label specified, and if txt2tags is
    not creating a tabel of contents.


    ===numtitle1, numtitle2, numtitle3, numtitle4, numtitle5===[numtitle1]

These tags are used for sections heading that should be numbered.
They are otherwise treated the same as [title* #title1].

If the rule ['autonumbertitle' #autonumbertitle] is defined, then these tags are
simply emitted as is, and the target is assumed to add the needed
numbers. If this rule is not defined for the target, then it is
assumed that the target does not have automatic numbering. In that
case, Txt2tags will automatically generate the correct
section/heading numbers and add that at the beginning of the title
text.

If the rule ['blanksaroundnumtitle' #blanksaroundnumtitle] is defined, an extra blank line
will be emitted before and after this tag.

: Macros:
  : **\a**
    This mark is expanded into the text of the title itself,
    unchanged excepts for necessary escapes from the source
    document.
  : **~A~**
    This mark is expanded into the value of the [anchor #anchor] tag,
    along with the text of the label for that anchor. It is removed
    if the title does not have a label specified, and if txt2tags is
    not creating a tabel of contents.


    ++Sectioning Tags++[section-SectioningTags]

If the rule ['titleblocks' #titleblocks] is defined for the target, then the
above [title* #title1] tags are not used. Instead, the tags below are used
to separate the sections as a whole while also marking up the
section headings as needed.

    ===title1Open, title2Open, title3Open, title4Open, title5Open===[title1Open]

These tags are used to mark the beginning of a section or
subsection, as well as to mark up the heading for that section. They
work very similarly to the [title* #title1] tags above.

If the rule ['blanksaroundtitle' #blanksaroundtitle] is defined, an extra blank line
will be emitted before and after this tag.

: Macros:
  : **\a**
    This mark is expanded into the text of the title itself,
    unchanged excepts for necessary escapes from the source
    document.
  : **~A~**
    This mark is expanded into the value of the [anchor #anchor] tag,
    along with the text of the label for that anchor. It is removed
    if the title does not have a label specified, and if txt2tags is
    not creating a tabel of contents.


    ===title1Close, title2Close, title3Close, title4Close, title5Close===[title1Close]

These tags are used to mark the end of a section that has been
opened with [title*Open* #title1Open]. It is emitted just before the opening
tag of the next section, as well as at the end of the document to
close all still-open sections.

Note that sections nest. If a second level section is specified just
after a first level section, and then another first level section,
the order of the tags will be: ``title1Open``, ``title2Open``,
``title2Close``, ``title1Close``, ``title1Open``, and so on.

: Macros:
  None


    ===blocktitle1Open, blocktitle2Open, blocktitle3Open===[blocktitle1Open]

These tags are used to open a group of sections that are at the
same level. If multiple sections/titles are given in a row at the
same level, then the same level ``blocktitle*Open`` tag will be emitted
before the first [title*Open* #title1Open].

: Macros:
  None


    ===blocktitle1Close, blocktitle2Close, blocktitle3Close===[blocktitle1Close]

These tags are used to close a group of sections that are at the
same level. If multiple sections/titles are given in a row at the
same level, then the same level ``blocktitle*Close`` tag will be emitted
after the last [title*Close* #title1Close].

: Macros:
  None


    +Lists+[chapter-Lists]

Lists are used to add structure to small groups of items. They can
be numbered or unnumbered, and they can be nested.

If the rule ['compactlist' #compactlist] is defined for a target, then lists will
be considered compact or wide, depending on whether or not an
item in the list includes multiple paragraphs. If even a simple list
item has more then one paragraph (that is, a blank line in the item
that is not immediately followed by another list item), then the
entire list is considered a wide list. If each item in the list is
contained within a single paragraph, then the list is considered
compact.

If the rule ['compactlist' #compactlist] is //not// defined, then there is no
difference bewteen wide and compact lists, and all lists are treated
as wide lists.

If the rule ['parainsidelist' #parainsidelist] is defined for a target, then the
blank lines in wide lists are emitted as an empty paragraph. That
is, [paragraphOpen #paragraphOpen] followed immediately by [paragraphClose #paragraphClose].

The rule ['spacedlistitem' #spacedlistitem] appears to be intended to show that a
target supports wide or spaced lists. However, at this time the rule
appears to be unused by Txt2tags, and does not affect output at all.

The rule ['listmaxdepth' #listmaxdepth] is used to tell Txt2tags how many levels
of lists may be nested within one another for each target.

If the rule ['listnotnested' #listnotnested] is defined for a target, then it does
not support nested lists. Nested lists in the source are emitted as
if all items belonged to the same, top-level list.

If the rule ['listitemnotnested' #listitemnotnested] is defined for a target, then
list items are closed before emitting a nested list, rather than wrapping
around the nested list.

    ++Unordered Lists++[section-UnorderedLists]

These lists do not use numbers to separate each item. Typically each
list item is set off with a bullet symbol, though this can vary for
different targets.

If the rule ['blanksaroundlist' #blanksaroundlist] is defined for a target, an extra
blank line is emitted before and after the top level list. No
additional lines are emitted for nested lists with this rule.

If the rule ['blanksaroundnestedlist' #blanksaroundnestedlist] is defined for a target, an
extra blank line is emitted before and after all lists, including
nested lists.

    ===listOpen===[listOpen]

This tag is emitted to mark the start of a new bulleted list.

By default this tag is emitted on its own line. The rule
['notbreaklistopen' #notbreaklistopen] is intended to allow
``listOpen`` to be on the same line as its first item, however
this rule is not yet supported and does not affect the output.

By default, the indent of a nested list is added (in spaces) at the
beginning of the line this tag is on. If the rule
['tagnotindentable' #tagnotindentable] is defined, or the rule ['keeplistindent' #keeplistindent] is
not defined, these spaces are removed.

If the rule ['compactlist' #compactlist] is defined for a target, then this tag
is only used for wide lists. Otherwise it is used for both.

: Macros:
  None


    ===listCompactOpen===[listCompactOpen]

This tag marks the beginning of a new compact bulleted list.

This tag is only used if the rule ['compactlist' #compactlist] is defined.

By default, the indent of a nested list is added (in spaces) at the
beginning of the line this tag is on. If the rule
['tagnotindentable' #tagnotindentable] is defined, or the rule ['keeplistindent' #keeplistindent] is
not defined, these spaces are removed.

: Macros:
  None


    ===listClose, listCompactClose===[listClose]

These tags are emitted, on their own line, to close the list opened
by the previous tags.

By default, the indent of a nested list is added (in spaces) at the
beginning of the line this tag is on. If the rule
['tagnotindentable' #tagnotindentable] is defined, or the rule ['keeplistindent' #keeplistindent] is
not defined, these spaces are removed.

: Macros:
  None


    ===listItemOpen===[listItemOpen]

This tag is emitted before each item within a bullet list.

By default, the indent of a nested list is added (in spaces) at the
beginning of the line this tag is on. If the rule
['tagnotindentable' #tagnotindentable] is defined, or the rule ['keeplistindent' #keeplistindent] is
not defined, these spaces are removed.

If the tag [listItemLine #listItemLine] is defined, it will be emitted
immediately before ``listItemOpen``. If the rule
['listlineafteropen' #listlineafteropen] is defined,
[listItemLine #listItemLine] will be emitted after ``listItemOpen``.

If the rule ['spacedlistitemopen' #spacedlistitemopen] is defined, then two spaces will
be emitted after ``listItemOpen`` and [listItemLine #listItemLine], before the
list item text.

: Macros:
  : **~D~**
    If this macro is included in the tag, it will be expanded to the
    value of the depth of that particular list. Top level lists
    have depth '1', a nested list inside the top level would have
    depth level '2', and so on.

    If the rule ['blockdepthmultiply' #blockdepthmultiply] is defined for the target,
    the depth value will be multiplied by that amount before being
    emitted. If the rule ['depthmultiplyplus' #depthmultiplyplus] is defined, then that
    value will be added to the depth before multiplying by
    ['blockdepthmultiply' #blockdepthmultiply], but only if used with
    ['blockdepthmultiply' #blockdepthmultiply].
  : **~V~**
    This macro will be expanded to the nesting level of the list. It
    is not affected by ['blockdepthmultiply' #blockdepthmultiply], so the numbers will
    always count one by one.

    If the rule ['listlevelzerobased' #listlevelzerobased] is defined for a target, then
    the top level lists will be level '0', the next level '1',
    and so on. Otherwise, the top level is '1' and the next level
    '2' and so on.


    ===listItemLine===[listItemLine]

This tag is emitted for each item in the list. It is emitted either
right before or after [listItemOpen #listItemOpen] (see above).

This is emitted a number of times equal to the depth level of the
list. For example, if ``listItemLine`` is defined as '*', then
each item in a list nested three levels deep would begin with
'***'.

Despite the name, this is only emitted at the beginning of each
item, and not for every line of the item.

: Macros:
  None


    ===listItemClose===[listItemClose]

This tag is emitted after each item in the list.

: Macros:
  None


    ++Numbered Lists++[section-NumberedLists]

Numbered lists behave much like unordered lists, except (as their
name implies) they have numbers instead of bullets.

Each item in the list will have its own number, counting from '1'.
By default, nested lists will use a dotted number format, as in
'1.', '2.', and so on. This can vary between different
targets, however.

If the rule ['blanksaroundnumlist' #blanksaroundnumlist] is defined for a target, an extra
blank line is emitted before and after the top level list. No
additional lines are emitted for nested lists.

If the rule ['blanksaroundnestedlist' #blanksaroundnestedlist] is defined for a target, an
extra blank line is emitted before and after all lists, including
nested lists.

    ===numlistOpen===[numlistOpen]

This tag is emitted to mark the start of a new numbered list.

By default this tag is emitted on its own line. The rule
['notbreaklistopen' #notbreaklistopen] is intended to allow
``numlistOpen`` to be on the same line as its first item, however
this rule is not yet supported and does not affect the output.

By default, the indent of a nested list is added (in spaces) at the
beginning of the line this tag is on. If the rule
['tagnotindentable' #tagnotindentable] is defined, or the rule ['keeplistindent' #keeplistindent] is
not defined, these spaces are removed.

If the rule ['compactlist' #compactlist] is defined for a target, then this tag
is only used for wide lists. Otherwise it is used for both.

: Macros:
  None


    ===numlistCompactOpen===[numlistCompactOpen]

This tag marks the beginning of a new compact numbered list.

This tag is only used if the rule ['compactlist' #compactlist] is defined.

By default, the indent of a nested list is added (in spaces) at the
beginning of the line this tag is on. If the rule
['tagnotindentable' #tagnotindentable] is defined, or the rule ['keeplistindent' #keeplistindent] is
not defined, these spaces are removed.

: Macros:
  None


    ===numlistClose, numlistCompactClose===[numlistClose]

These tags are emitted, on their own line, to close the list opened
by the previous tags.

By default, the indent of a nested list is added (in spaces) at the
beginning of the line this tag is on. If the rule
['tagnotindentable' #tagnotindentable] is defined, or the rule ['keeplistindent' #keeplistindent] is
not defined, these spaces are removed.

: Macros:
  None


    ===numlistItemOpen===[numlistItemOpen]

This tag is emitted before each item within a numbered list.

If the rule ['autonumberlist' #autonumberlist] is defined, then the target is
assumed to put the numbers in itself. In this case Txt2Tags simply
emits this tag just like [listItemOpen #listItemOpen]. If it is not defined,
then the correct number is calculated and inserted by Txt2tags. It
uses the default number format given at the beginning of this
subsection above.

By default, the indent of a nested list is added (in spaces) at the
beginning of the line this tag is on. If the rule
['tagnotindentable' #tagnotindentable] is defined, or the rule ['keeplistindent' #keeplistindent] is
not defined, these spaces are removed.

If the tag [numlistItemLine #numlistItemLine] is defined, it will be emitted
immediately before ``numlistItemOpen``. If the rule
['listlineafteropen' #listlineafteropen] is defined, [numlistItemLine #numlistItemLine] will be emitted
after ``numlistItemOpen``.

If the rule ['spacednumlistitemopen' #spacednumlistitemopen] is defined, then two spaces will
be emitted after ``numlistItemOpen`` and [numlistItemLine #numlistItemLine], before the
list item text.

: Macros:
  : **\a**
    If the rule ['autonumberlist' #autonumberlist] is //not// defined, then this
    mark is expanded into the correct number for this list item.
  : **~D~**
    If this macro is included in the tag, it will be expanded to the
    value of the depth of that particular list. Top level lists
    have depth '1', a nested list inside the top level would have
    depth level '2', and so on.

    If the rule ['blockdepthmultiply' #blockdepthmultiply] is defined for the target,
    the depth value will be multiplied by that amount before being
    emitted. If the rule ['depthmultiplyplus' #depthmultiplyplus] is defined, then that
    value will be added to the depth before multiplying by
    ['blockdepthmultiply' #blockdepthmultiply], but only if used with
    ['blockdepthmultiply' #blockdepthmultiply].
  : **~V~**
    This macro will be expanded to the nesting level of the list. It
    is not affected by ['blockdepthmultiply' #blockdepthmultiply], so the numbers will
    always count one by one.

    If the rule ['listlevelzerobased' #listlevelzerobased] is defined for a target, then
    the top level lists will be level '0', the next level '1',
    and so on. Otherwise, the top level is '1' and the next level
    '2' and so on.


    ===numlistItemLine===[numlistItemLine]

This tag is emitted for each item in the list. It is emitted either
right before or after [numlistItemOpen #numlistItemOpen] (see above).

This is emitted a number of times equal to the depth level of the
list. For example, if ``numlistItemLine`` is defined as '+', then
each item in a list nested three levels deep would begin with
'+++'.

Despite the name, this is only emitted at the beginning of each
item, and not for every line of the item.

: Macros:
  None


    ===numlistItemClose===[numlistItemClose]

This tag is emitted after each item in the list.

: Macros:
  None


    ++Definition Lists++[section-DefinitionLists]

Definition lists work a little bit differently from standard lists.
Each list item has two parts: the item or word to be defined, and
the definition itself.

If the rule ['deflisttextstrip' #deflisttextstrip] is defined, then each line of the
definition will have extra spaces stripped off, even if
['keeplistindent' #keeplistindent] is also defined.

If the rule ['blanksarounddeflist' #blanksarounddeflist] is defined for a target, an extra
blank line is emitted before and after the top level list. No
additional lines are emitted for nested lists.

If the rule ['blanksaroundnestedlist' #blanksaroundnestedlist] is defined for a target, an
extra blank line is emitted before and after all lists, including
nested lists.

    ===deflistOpen===[deflistOpen]

This tag is emitted to mark the start of a new definition list.

By default this tag is emitted on its own line. The rule
['notbreaklistopen' #notbreaklistopen] is intended to allow [listOpen #listOpen] to be on the
same line as its first item, however this rule is not yet supported
and does not affect the output.

By default, the indent of a nested list is added (in spaces) at the
beginning of the line this tag is on. If the rule
['tagnotindentable' #tagnotindentable] is defined, or the rule ['keeplistindent' #keeplistindent] is
not defined, these spaces are removed.

If the rule ['compactlist' #compactlist] is defined for a target, then this tag
is only used for wide lists. Otherwise it is used for both.

: Macros:
  None


    ===deflistCompactOpen===[deflistCompactOpen]

This tag marks the beginning of a new compact definition list.

This tag is only used if the rule ['compactlist' #compactlist] is defined.

By default, the indent of a nested list is added (in spaces) at the
beginning of the line this tag is on. If the rule
['tagnotindentable' #tagnotindentable] is defined, or the rule ['keeplistindent' #keeplistindent] is
not defined, these spaces are removed.

: Macros:
  None


    ===deflistClose, deflistCompactClose===[deflistClose]

These tags are emitted, on their own line, to close the list opened
by the previous tags.

By default, the indent of a nested list is added (in spaces) at the
beginning of the line this tag is on. If the rule
['tagnotindentable' #tagnotindentable] is defined, or the rule ['keeplistindent' #keeplistindent] is
not defined, these spaces are removed.

: Macros:
  None


    ===deflistItem1Open===[deflistItem1Open]

This tag is emitted before each item within a definition list. It is
specifically meant to go before the term to be defined.

By default, the indent of a nested list is added (in spaces) at the
beginning of the line this tag is on. If the rule
['tagnotindentable' #tagnotindentable] is defined, or the rule ['keeplistindent' #keeplistindent] is
not defined, these spaces are removed.

If the rule ['imgasdefterm' #imgasdefterm] is defined, then a linked image is
allowed as the term to be defined. Otherwise, only text is allowed.

: Macros:
  : **~D~**
    If this macro is included in the tag, it will be expanded to the
    value of the depth of that particular list. Top level lists
    have depth '1', a nested list inside the top level would have
    depth level '2', and so on.

    If the rule ['blockdepthmultiply' #blockdepthmultiply] is defined for the target,
    the depth value will be multiplied by that amount before being
    emitted. If the rule ['depthmultiplyplus' #depthmultiplyplus] is defined, then that
    value will be added to the depth before multiplying by
    ['blockdepthmultiply' #blockdepthmultiply], but only if used with
    ['blockdepthmultiply' #blockdepthmultiply].
  : **~V~**
    This macro will be expanded to the nesting level of the list. It
    is not affected by ['blockdepthmultiply' #blockdepthmultiply], so the numbers will
    always count one by one.

    If the rule ['listlevelzerobased' #listlevelzerobased] is defined for a target, then
    the top level lists will be level '0', the next level '1',
    and so on. Otherwise, the top level is '1' and the next level
    '2' and so on.


    ===deflistItem1Close===[deflistItem1Close]

This tag is emitted after each definition term, but before the
definition itself, for each item in the list.

: Macros:
  None


    ===deflistItem2Open===[deflistItem2Open]

This tag is emitted directly after [deflistItem1Close #deflistItem1Close], and is
used right before the definition text of the item.

: Macros:
  None


    ===deflistItem2LinePrefix===[deflistItem2LinePrefix]

This tag is emitted at the beginning of each line of the definition
text for each item.

Note that it is not multiplied for nexted lists. It is the same for
every level of a nested list.

If the rule ['keeplistindent' #keeplistindent] is defined and ['deflisttextstrip' #deflisttextstrip]
is not defined, then this is emitted after the indent for each line
of the list.

: Macros:
  None


    ===deflistItem2Close===[deflistItem2Close]

This tag is emitted at the end of each definition, and therefor at
the end of each item of the definition list.

For examples, the tags for a definition list are emitted as follows:
``deflistOpen``, ``deflistItem1Open``, ``deflistItem1Close``,
``deflistItem2Open``, (``deflistItem2LinePrefix`` for each line),
``deflistItem2Close``, ``deflistItem1Open``, and so on for the
entire list.

: Macros:
  None



    +Tables+[chapter-Tables]

Tables allow the user to arrange data in rows and columns for better
organization. Some targets support very complicated tables, while
others only support limited options within tables or do not support
tables at all. Txt2tags is limited to the most basic and most common
table options usable by the greatest number of targets.

If the rule ['tableable' #tableable] is //not// defined, then the table markup
is emitted unchanged from the source document and put inside a
verbatim block.

If the rule ['blanksaroundtable' #blanksaroundtable] is defined, then an extra blank
line will be emitted before and after the table markup.

    ++Macros++[section-Macros]

Because of how complicated most table markup can be, there are
several macro tags that can be defined that may be expanded by
several other tags. These tags will all be defined here to be easier
to find in this reference.

    ===_tableBorder===[_tableBorder]

This tag may be inserted into the outer table and row tags to
designate that this table should have a border.

For tags that support it, it will replace the macro **~B~**.

    ===_tableCellBorder===[_tableCellBorder]

This tag may be inserted into the markup of each individual cell to
designate that this table should have a border.

It will replace the macro **~B~**.

    ===_tableAlignLeft, _tableAlignCenter===[_tableAlign]

These tags may be inserted into the outer table and row tags to
designate how the entire table should be aligned within the
document, if the target supports table alignment.

Note that Txt2tags does not currently allow right-aligned tables.

Whichever tag is appropriate will replace the macro **~A~**.

    ===_tableColAlignLeft, _tableColAlignRight, _tableColAlignCenter===[_tableColAlign]

If the rule ['tablecellaligntype' #tablecellaligntype] is set to the value ['column' #column]
for the target, then these tags may be inserted into the outer table
or row tags for that table.

These alignment settings will be used for each cell in the column,
for targets that do not support per-cell alignment.

The column alignment 'group' is made out of several copies of these
tags, one for each column in the table. They may be separated by
[tableColAlignSep #tableColAlignSep]. Then the entire group is inserted into the
appropriate opening tags of the table.

The column alignment group will replace the macro **~C~**.

    ===tableColAlignSep===[tableColAlignSep]

If the table has a border, then each item in the column alignment
group (see above) will be separated by this tag. It is also used in
multicolumn cells (see below) for the same purpose.

Note that, if the table does not have a border, then not only will
this tag not be inserted into the alignment group, but any copies of
the tag already in the relevant tags of the table will also be
removed.

    ===_tableCellAlignLeft, _tableCellAlignRight, _tableCellAlignCenter===[_tableCellAlign]

If the rule ['tablecellaligntype' #tablecellaligntype] is set to the value ['cell' #cell]
for the target, then these tags may be inserted into the cell tags
for the table. This is for targets that support per-cell alignment.

The alignment tag will replace the macro **~A~**.

    ===_tableCellColSpan===[_tableCellColSpan]

If the rule ['tablecellspannable' #tablecellspannable] is defined for a target, then
this tag will be inserted into cells that span more than one column.

It replaces the macro **~S~**.

: Macros:
  : **\a**
    This mark is used inside the tag to give the span of the cell.
    It is replaced with the numeric value of the number of columns
    that this cell spans.

    ``_tableCellColSpan`` will only be emitted for cells that have a
    span value greater than '1'.

    If the rule ['cellspancumulative' #cellspancumulative] is defined for a target, then
    this value will grow for each cell in a row. That is, cell '1'
    will have a span value of '1', cell '2' will have a span value of
    '2', and so on, with spanned cells increasing the value more.

    If the rule ['cellspanmultiplier' #cellspanmultiplier] is defined for a target, then
    the span value will be multiplied by this value, after
    accumulation if appropriate.


    ===_tableCellColSpanChar===[_tableCellColSpanChar]

If the rule ['tablecellspannable' #tablecellspannable] is defined for a target and this
tag is also defined, it will be used instead of
[_tableCellColSpan #_tableCellColSpan].

This tag will be emitted the same number of times as columns that
the cell spans, //minus 1//. For example, if the tag is defined as
'|', and a cell spans three columns, then '||' will be emitted.

The tag, however many need to be emitted, will replace the macro
**~S~**.

    ===_tableAttrDelimiter===[_tableAttrDelimiter]

This tag may be inserted into cells that have either a cell
alignment or a cell span to insert. This may be used to separate the
cell attributes from the body of the cell itself.

If the cell has neither an alignment or span to insert, then the
macro for this tag is removed.

This tag will replace the macro **~Z~**.

    ++Table Structure++[section-TableStructure]

    ===tableOpen, tableClose===[tableOpen]

These tags are the first and last tag emitted for a table. They are
emitted on lines of their own, and are emitted only once for each table.

: Macros:
  : **~A~**
    This will be replaced with [_tableAlign* #_tableAlign] for a left or center
    aligned table.
  : **~B~**
    This will be replaced with the [_tableBorder #_tableBorder] tag for tables
    that have a border, or removed otherwise.
  : **~C~**
    If the rule ['tablecellaligntype' #tablecellaligntype] is set to ['column' #column], then
    this will be replaced with the column alignment group for the
    table. (See [_tableColAlign* #_tableColAlign] above.)


    ===tableRowOpen===[tableRowOpen]

This tag is emitted at the beginning of each row of cells.

By default each row is emitted on a single line. If the rule
['breaktablelineopen' #breaktablelineopen] is defined, then a linebreak will be emitted
after this tag before the cells.

: Macros:
  : **~A~**
    This will be replaced with [_tableAlign* #_tableAlign] for a left or center
    aligned table.
  : **~B~**
    This will be replaced with the [_tableBorder #_tableBorder] tag for tables
    that have a border, or removed otherwise.
  : **~C~**
    If the rule ['tablecellaligntype' #tablecellaligntype] is set to ['column' #column], then
    this will be replaced with the column alignment group for the
    table. (See [_tableColAlign* #_tableColAlign] above.)


    ===tableTitleRowOpen===[tableTitleRowOpen]

This tag, if defined, will be used instead of [tableRowOpen #tableRowOpen] for
title rows. If it is not defined, [tableRowOpen #tableRowOpen] will be used for
all rows.

Note that title rows are not required, and do not need to be the
first row of a table.

If the rule ['breaktablelineopen' #breaktablelineopen] is defined, then a linebreak will
be emitted after this tag before the cells.

: Macros:
  : **~A~**
    This will be replaced with [_tableAlign* #_tableAlign] for a left or center
    aligned table.
  : **~B~**
    This will be replaced with the [_tableBorder #_tableBorder] tag for tables
    that have a border, or r…