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 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.) ===tableRowClose, tableTitleRowClose===[tableRowClose] These tags are emitted at the end of each row begun by the tags above. If ``tableTitleRowClose`` is not defined, ``tableRowClose`` will be used instead. : 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.) ===tableRowSep===[tableRowSep] This tag will be emitted in between each row of cells. Note that if this tag is defined, then [tableRowOpen #tableRowOpen] and [tableRowClose #tableRowClose] will not be used at all. : 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.) ++Cells++[section-Cells] Each cell of data for a table may be marked up separately. By default, each row of cells is emitted on a single line. If the rule ['breaktablecell' #breaktablecell] is defined for a target, then a linebreak will be emitted after each cell. If the rule ['tablecellstrip' #tablecellstrip] is defined for a target, then any extra spaces will be stripped from each cell before it is emitted. Otherwise, all spaces from the source document (including that used to determine cell alignment) will be included in the final output. If the rule ['tabletitlerowinbold' #tabletitlerowinbold] is defined, then all cells considered part of a title row will have their contents wrapped in [fontBoldOpen and fontBoldClose #fontBold] tags. ===tableCellOpen, tableTitleCellOpen===[tableCellOpen] These tags are emitted at the beginning of each cell within the table. If ``tableTitleCellOpen`` is defined, then it will be used for the cells on a title row. Otherwise, ``tableCellOpen`` will be used for all cells. : Macros: : **~A~** If the rule ['tablecellaligntype' #tablecellaligntype] is set to the value ['cell' #cell] for a target, then this will be replaced with the appropriate [_tableCellAlign* #_tableCellAlign] tag. : **~B~** If the table has a border, this will be replaced with the [_tableCellBorder #_tableCellBorder] tag, or removed if not. : **~S~** If the rule ['tablecellspannable' #tablecellspannable] is defined, and the cell spans multiple columns, then this tag will be replaced with the value of either [_tableCellColSpanChar #_tableCellColSpanChar] or [_tableCellColSpan #_tableCellColSpan] as appropriate. : **~Z~** If the cell has and alignment or column span to be inserted, then this tag will be replaced with [_tableAttrDelimiter #_tableAttrDelimiter]. If the cell has neither, then it will be removed. ===tableCellClose, tableTitleCellClose===[tableCellClose] These tags are emitted at the end of each cell within the table. If ``tableTitleCellClose`` is defined, then it will be used for the cells on a title row. Otherwise, ``tableCellClose`` will be used for all cells. : Macros: : **~A~** If the rule ['tablecellaligntype' #tablecellaligntype] is set to the value ['cell' #cell] for a target, then this will be replaced with the appropriate [_tableCellAlign* #_tableCellAlign] tag. : **~B~** If the table has a border, this will be replaced with the [_tableCellBorder #_tableCellBorder] tag, or removed if not. : **~S~** If the rule ['tablecellspannable' #tablecellspannable] is defined, and the cell spans multiple columns, then this tag will be replaced with the value of either [_tableCellColSpanChar #_tableCellColSpanChar] or [_tableCellColSpan #_tableCellColSpan] as appropriate. ===tableCellSep, tableTitleCellSep===[tableCellSep] These tags are emitted in between each cell of a row. If ``tableTitleCellSep`` is defined, then it will be used for the cells on a title row. Otherwise, ``tableCellSep`` will be used for all cells. These tags are only emited between cells. They do not appear before the first cell of a row or after the last cell of a row. Note that, unlike [tableRowSep #tableRowSep], these tags are used as well as [tableCellOpen #tableCellOpen] and [tableCellClose #tableCellClose]. If all are defined, then ``tableCellSep`` will be emitted after ``tableCellClose`` and before the next ``tableCellOpen``. : Macros: None ===_tableCellMulticolOpen===[_tableCellMulticolOpen] If the rule ['tablecellmulticol' #tablecellmulticol] is defined for a target, and a cell spans more than one column, then this tag will be used instead of [tableCellOpen #tableCellOpen]. : Macros: : **\a** This will be replaced with the current cell's column span value. See [_tableCellColSpan #_tableCellColSpan] above for an explanation of this value. : **~A~** If the rule ['tablecellaligntype' #tablecellaligntype] is set to the value ['cell' #cell] for a target, then this will be replaced with the appropriate [_tableCellAlign* #_tableCellAlign] tag. : **~Z~** If the cell has an alignment or column span to be inserted, then this tag will be replaced with [_tableAttrDelimiter #_tableAttrDelimiter]. If the cell has neither, then it will be removed. ===_tableCellMulticolClose===[_tableCellMulticolClose] If the rule ['tablecellmulticol' #tablecellmulticol] is defined for a target, and a cell spans more than one column, then this tag will be used instead of [tableCellClose #tableCellClose]. : Macros: None ===tableCellHead, tableTitleCellHead===[tableCellHead] These tags are use to define 'headers', one for each cell, that are inserted at the beginning of a row before the cell data itself. For example, the order of tags for a row with three cells may be ``tableRowOpen``, ``tableCellHead``, ``tableCellHead``, ``tableCellHead``, ``tableCellOpen``, and so on. If ``tableTitleCellHead`` is defined, it will be used for cells in a title row, otherwise ``tableCellHead`` will be used for all rows. : Macros: : **~A~** If the rule ['tablecellaligntype' #tablecellaligntype] is set to the value ['cell' #cell] for a target, then this will be replaced with the appropriate [_tableCellAlign* #_tableCellAlign] tag. : **~B~** If the table has a border, this will be replaced with the [_tableCellBorder #_tableCellBorder] tag, or removed if not. : **~S~** If the rule ['tablecellspannable' #tablecellspannable] is defined, and the cell spans multiple columns, then this tag will be replaced with the value of either [_tableCellColSpanChar #_tableCellColSpanChar] or [_tableCellColSpan #_tableCellColSpan] as appropriate. ===tableCellAlignLeft, tableCellAlignRight, tableCellAlignCenter===[tableCellAlign] If these tags are defined and a cell has an alignment attribute, then the cell text will be wrapped by the appropriate tag before it is emitted. Note that these cells do not begin with an underscore. Do not get them confused with the [_tableCellAlign* #_tableCellAlign] tags, which replace macros within the other cell tags. : Macros: : **\a** This will be replaced by the text of the cell itself. +Miscellaneous+[chapter-Miscellaneous] These tags are useful or necessary for a fully implemented target, but did not fit well within the other categories. ++Document Structure and Formatting++[section-DocumentStructureandFormatting] ===pageBreak===[pageBreak] For targets that support separation into pages, this tag is used to force a page break in the output. ===bar1, bar2===[bar1] These tags are used to insert a horizontal line in the output, usually used as a lesser section break without beginning a new section. ``bar1`` is considered a normal line, and ``bar2`` is considered a strong or thick line. If the rule ['barinsidequote' #barinsidequote] is defined, then a bar is allowed inside a block quote. Otherwise the block quote must be closed and reopened around the bar. If the rule ['mapbar2pagebreak' #mapbar2pagebreak] is defined, then the value of ``bar2`` is ignored and a [pageBreak #pageBreak] is emitted instead. : Macros: : **\a** If this mark is present, it will be replaced with the text of the actual marks used for the bar in the source document. ===EOD===[EOD] This is the End Of Document tag, and is the very last thing emitted to the output. Any tags that were opened in the default //HEADER_TEMPLATE// should be closed in this tag. If the command line option //--template// is used, then this tag is not emitted. Anything necessary for a complete document should be included in the template. The default template can thus be considered: //HEADER_TEMPLATE// + **%%body** + ``EOD``. ===bodyOpen, bodyClose===[bodyOpen] These are the first and last tags emitted for the document body text itself. ``bodyOpen`` is emitted immediately after //HEADER_TEMPLATE// and ``bodyClose`` is immediately before [EOD #EOD]. ++HTML++[section-HTML] ===cssOpen, cssClose===[cssOpen] These tags are used to insert a stylesheet directly into the text of the output document itself. If the command line option //--css-inside// is used, then the contents of external stylesheets will be inserted into the document header. Each stylesheet will be wrapped in these tags before being emitted. Currently this option, and these tags, are only used by the HTML family of targets, are have no effect on any other target. ++Comments++[section-Comments] ===comment===[comment] This tag is used to insert a single line comment into the output. It should be such that it will not appear to readers in the final document, only in the tagged source of the document. It is used, if available, to insert a comment at the end of the docment stating the date and version of Txt2tags used to generate the output document. : Macros: : **\a** This is replaced with the text of the comment generated by Txt2tags. ===blockCommentOpen, blockCommentClose===[blockComment] These are intended to be used before and after multiline comments in the output. Currently, all comments in the source are ignored, so these tags are unused. ++Table Of Contents++[section-TableOfContents] The automatic table of contents is emitted as a [list #chapter-Lists], with each list item corresponding to a [title* #title1] within the document. Lower level titles will be emitted as nested lists. If the target supports them, each list item in the list will be a link to the corresponding title. Each title will have an anchor added automatically if they do not have one already. If the rule ['autotocwithbars' #autotocwithbars] is defined, then a [bar1 #bar1] will be added before and after the table of contents. If the rule ['blankendautotoc' #blankendautotoc] is defined, then an extra blank line will be added after the table of contents. If the rule ['autotocnewpagebefore' #autotocnewpagebefore] is defined, then a [pageBreak #pageBreak] will be emitted before the table of contents. If the rule ['autotocnewpageafter' #autotocnewpageafter] is defined, then a [pageBreak #pageBreak] will be emitted after the table of contents. ===tocOpen, tocClose===[tocOpen] These tags will be emitted directly before and after the automatically generated table of contents. ===TOC===[TOC] This tag is used for targets that support their own table of contents. If this tag is defined, then it will be emitted, on its own, instead of the automatically generated table of contents. No other processing will be done and all of the rules pretaining to the automatic table of contents will be ignored. =Appendix: Rules=[Appendix] ===linkable===[linkable] This target supports external links. It affects the output of [url #url], [urlMark #urlMark], [urlMarkAnchor #urlMarkAnchor], [email #email], [emailMark #emailMark]. ===tableable===[tableable] This target supports tables. If this is not defined, then all tags in the [Table #chapter-Tables] section are ignored. ===imglinkable===[imglinkable] This target supports images as links. It may affect the output of [url #url] and [img #img]. ===imgalignable===[imgalignable] This target supports image alignment. If it is not defined, then all [_imgAlign #_imgAlign] and [imgAlign #imgAlign] tags are ignored. It affects the output of [img #img]. ===imgasdefterm===[imgasdefterm] This target supports images as definition terms. It may affect the output of [deflistItem1Open #deflistItem1Open]. ===autonumberlist===[autonumberlist] This target supports numbered lists natively. If this is defined, then numbers will not be generated by Txt2tags for numbered lists. It affects the output of [numlistItemOpen #numlistItemOpen]. ===autonumbertitle===[autonumbertitle] This target supports numbered titles natively. If this is defined, then numbers will not be generated by Txt2tags for numbered titles. It affects the output of [numtitle* #numtitle1]. ===stylable===[stylable] This target supports external style files. If this is defined, then the **%(STYLE)s** macros may be expanded. Otherwise style definitions are ignored. It affects the output of the [Template #section-Template] ===parainsidelist===[parainsidelist] This target supports paragraph tags inside lists. If this is defined, then [paragraphOpen #paragraphOpen] and [paragraphClose #paragraphClose] tags may be inserted into [lists #chapter-Lists]. ===compactlist===[compactlist] This target has separate enclosing tags for compact lists. If this is not defined, then [listCompactOpen #listCompactOpen], [numlistCompactOpen #numlistCompactOpen], and [deflistCompactOpen #deflistCompactOpen] are ignored. ===spacedlistitem===[spacedlistitem] This target supports blank lines between items in lists. This rule is currently unused and ignored. ===listnotnested===[listnotnested] This target does not support nested lists. If this is defined, then all lists are emitted as a single, top-level list. It affects the output of [lists #chapter-Lists]. ===listitemnotnested===[listitemnotnested] This target does not allow nested lists to be inside a list item. If this is defined, then list items are closed before sublists are emitted. If it is not defined, then list items are closed after the sublists they contain. It affects the output of [lists #chapter-Lists]. ===quotenotnested===[quotenotnested] This target does not support nested quotes. If this is defines, all block quotations are emitted at the same, top level. If affects the output of [block quotes #section-BlockQuotations]. ===verbblocknotescaped===[verbblocknotescaped] This target should not run verbatim blocks through //doEscape()//. It affects the output of [verbatim blocks #section-VerbatimBlocks]. ===verbblockfinalescape===[verbblockfinalescape] This target //should// run verbatim blocks through //doFinalEscape()//. It affects the output of [verbatim blocks #section-VerbatimBlocks]. ===escapeurl===[escapeurl] This target should run **URLs** through //doEscape()//. It affects the output of [url #url], [urlMark #urlMark], [urlMarkAnchor #urlMarkAnchor], [email #email], and [emailMark #emailMark]. ===labelbeforelink===[labelbeforelink] For this target, labels should come before the link in a **URL**. It affects the output of [urlMark #urlMark], [urlMarkAnchor #urlMarkAnchor], and [emailMark #emailMark]. ===onelinepara===[onelinepara] This target should emit paragraphs as a single long line. It affects the output of [paragraphs #section-Paragraphs]. ===tabletitlerowinbold===[tabletitlerowinbold] This target should manually emit table title rows in bold face. It affects the output of [table cells #section-Cells]. ===tablecellstrip===[tablecellstrip] This target should strip extra spaces from each table cell. It affects the output of [table cells #section-Cells]. ===tablecellspannable===[tablecellspannable] This target supports the span attribute in table cells. It may affect the output of [tableCellOpen #tableCellOpen], [tableCellClose #tableCellClose], and [tableCellHead #tableCellHead]. ===tablecellmulticol===[tablecellmulticol] This target has separate open and close tags for multicolumn cells. If it is defined, then [_tableCellMulticolOpen #_tableCellMulticolOpen] will be used for multicolumn cells instead of [tableCellOpen #tableCellOpen]. ===barinsidequote===[barinsidequote] This target allows horizontal bars inside block quotes. It affects the output of [block quotes #section-BlockQuotations], and uses [bar1 #bar1]. ===finalescapetitle===[finalescapetitle] This target should run the text of titles through //doFinalEscape()// It affects the output of [titles #chapter-TitlesandSections]. ===autotocnewpagebefore===[autotocnewpagebefore] This target should emit a [pageBreak #pageBreak] before the automatic Table of Contents. ===autotocnewpageafter===[autotocnewpageafter] This target should emit a [pageBreak #pageBreak] after the automatic Table of Contents. ===autotocwithbars===[autotocwithbars] This target should emit a [bar1 #bar1] before and after the automatic Table of Contents. ===mapbar2pagebreak===[mapbar2pagebreak] This target should use a [pageBreak #pageBreak] instead of [bar2 #bar1]. If it is defined, the anything defined for ``bar2`` is ignored. ===titleblocks===[titleblocks] This target uses title and section blocks. If it is defined, then [title* #title1] tags are ignored. Instead [title*Open #title1open] and [blockTitle*Open #blockTitle1Open] tags will be used to set off titles and sections. This affects the output of [titles #chapter-TitlesandSections]. ===listlineafteropen===[listlineafteropen] This target should emit [listItemLine #listItemLine] after [listItemOpen #listItemOpen]. ===escapexmlchars===[escapexmlchars] This target should escape the XML special characters: < > & ===listlevelzerobased===[listlevelzerobased] This target should start list levels at 0 when encoding the level into list tags. It affects the output of [listItemOpen #listItemOpen], [numlistItemOpen #numlistItemOpen], and [deflistItemOpen #deflistItemOpen]. ===zerodepthparagraph===[zerodepthparagraph] For this target, non-nested paragraphs should have block depth of 0 instead of 1 when the block depth is encoded into the output. This affects the output of [paragraphOpen #paragraphOpen]. ===cellspancumulative===[cellspancumulative] For this target, cell span values add up for each cell of a row. It affects the output of [_tableCellColSpan #_tableCellColSpan], and from that it may affect the output of [tableCellOpen #tableCellOpen], [tableCellClose #tableCellClose], [tableCellHead #tableCellHead], and [_tableCellMulticolOpen #_tableCellMulticolOpen]. ===keepblankheaderline===[keepblankheaderline] For this target, template lines are not removed if the macros being inserted are blank. This affects the output of [the template #section-Template]. ===indentverbblock===[indentverbblock] This target should add leading spaces to verb block lines. It affects the output of [verbatim blocks #section-VerbatimBlocks]. ===breaktablecell===[breaktablecell] This target should insert line breaks after every table cell. If affects the output of [table cells #section-Cells]. ===breaktablelineopen===[breaktablelineopen] This target should insert a line break after [tableRowOpen #tableRowOpen] and [tableTitleRowOpen #tableTitleRowOpen]. ===notbreaklistopen===[notbreaklistopen] This target should //not// insert a line break after [listOpen #listOpen], [numlistOpen #numlistOpen] or [deflistOpen #deflistOpen]. ===keepquoteindent===[keepquoteindent] This target should not remove the leading TABs in block quotes. It affects the output of [block quotations #section-BlockQuotations]. ===keeplistindent===[keeplistindent] This target should not remove the leading spaces on list tags. It affects the output of all tags for [lists #chapter-Lists]. ===blankendautotoc===[blankendautotoc] This target should append a blank line at the end of the automatic Table of Contents. ===tagnotindentable===[tagnotindentable] For this target, tags must be placed at the line beginning. If affects the tags for [block quotes #section-BlockQuotations] and [lists #chapter-Lists]. ===spacedlistitemopen===[spacedlistitemopen] This target should append a space after [listItemOpen #listItemOpen]. ===spacednumlistitemopen===[spacednumlistitemopen] This target should append a space after [numlistItemOpen #numlistItemOpen]. ===deflisttextstrip===[deflisttextstrip] This target should strip the whitespace off of the definition list text. It affects the output of [definition lists #section-DefinitionLists]. ===blanksaroundpara===[blanksaroundpara] This target should put a blank line before and after paragraphs. It affects the output of [paragraphs #section-Paragraphs]. ===blanksaroundverb===[blanksaroundverb] This target should put a blank line before and after verb blocks. It affects the output of [verbatim blocks #section-VerbatimBlocks]. ===blanksaroundquote===[blanksaroundquote] This target should put a blank line before and after quotes. It affects the output of [block quotations #section-BlockQuotations]. ===blanksaroundlist===[blanksaroundlist] This target should put a blank line before and after lists. It affects the output of [regular lists #section-UnorderedLists]. ===blanksaroundnumlist===[blanksaroundnumlist] This target should put a blank line before and after numbered lists. It affects the output of [numbered lists [#section-NumberedLists]. ===blanksarounddeflist===[blanksarounddeflist] This target should put a blank line before and after definition lists. It affects the output of [definition lists [#section-DefinitionLists]. ===blanksaroundnestedlist===[blanksaroundnestedlist] This target should put a blank line before and after all types of nested lists. It affects the output of all [lists #chapter-Lists]. ===blanksaroundtable===[blanksaroundtable] This target should put a blank line before and after tables. It affects the output of [tables #chapter-Tables]. ===blanksaroundbar===[blanksaroundbar] This target should put a blank line before and after horizontal lines. It affects the output of [bar1 and bar2 #bar1]. ===blanksaroundtitle===[blanksaroundtitle] This target should put a blank line before and after titles. It affects the output of [title* #title1] and [title*Open #title1open]. ===blanksaroundnumtitle===[blanksaroundnumtitle] This target should put a blank line before and after numbered titles. If affects the output of [numtitle* #numtitle1]. ===listmaxdepth===[listmaxdepth] This is a value rule defining the maximum nesting depth for lists. It affects the output of [lists #chapter-Lists]. ===quotemaxdepth===[quotemaxdepth] This is a value rule defining the maximum nesting depth for block quotes. It affects the output of [block quotations #section-BlockQuotations]. ===tablecellaligntype===[tablecellaligntype] This is a value rule defining the type of alignment allowed for tables cells. The legal values are 'cell' or 'column'. Its value affects whether [_tableColAlign* #_tableColAlign] or [_tableCellAlign* #_tableCellAlign] tags are used. It may affect the output of [tableOpen #tableOpen], [tableRowOpen #tableRowOpen], [tableRowSep #tableRowSep], [tableCellOpen #tableCellOpen], [_tableCellMulticolOpen #_tableCellMulticolOpen], [tableCellHead #tableCellHead], and other related tags. ===blockdepthmultiply===[blockdepthmultiply] This value rule changes the value of a blocks depth value, for targets that encode depth into the output tags. It may affect the output of [paragraphOpen #paragraphOpen], [blockQuoteOpen #blockQuoteOpen], [listItemOpen #listItemOpen], [numlistItemOpen #numlistItemOpen], and [deflistItemOpen #deflistItemOpen]. ===depthmultiplyplus===[depthmultiplyplus] This value rule is added to add to the block depth before multiplying by 'blockdepthmultiply'. It may affect the output of [paragraphOpen #paragraphOpen], [blockQuoteOpen #blockQuoteOpen], [listItemOpen #listItemOpen], [numlistItemOpen #numlistItemOpen], and [deflistItemOpen #deflistItemOpen]. ===cellspanmultiplier===[cellspanmultiplier] This value rule changes the value of a table cell span. It affects the output of [_tableCellColSpan #_tableCellColSpan], and from that may affect the output of [tableCellOpen #tableCellOpen], [tableCellClose #tableCellClose], [_tableCellMulticolOpen #_tableCellMulticolOpen] and [tableCellHead #tableCellHead].