/doc/English/tags-reference.html
HTML | 2737 lines | 2329 code | 406 blank | 2 comment | 0 complexity | ee2cbfb0f5396e258acb153620cf0665 MD5 | raw file
Possible License(s): GPL-2.0, GPL-3.0, WTFPL
- <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
- <HTML>
- <HEAD>
- <META NAME="generator" CONTENT="http://txt2tags.org">
- <TITLE>All TAGS Reference</TITLE>
- </HEAD><BODY BGCOLOR="white" TEXT="black">
- <CENTER>
- <H1>All TAGS Reference</H1>
- </CENTER>
- <H1 ID="Introduction">Introduction</H1>
- <P>
- This document is a reference for all available TAGS available to
- developers for adding new targets, as found in the <I>getTags()</I> function.
- It is intended for <B>advanced users</B> and <B>developers</B> who wish to
- add a new target to Txt2tags without needing to know the source code
- in detail.
- </P>
- <P>
- 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 <I>getRules()</I> function affect them, and what special
- characters and macros are expanded in the output.
- </P>
- <P>
- 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".
- </P>
- <H1 ID="chapter-ThePartsofaDocument">1. The Parts of a Document</H1>
- <P>
- Before looking at the individual tags, it is important to understand
- exactly how the different parts of a document fit together.
- </P>
- <P>
- A document is built from a <B>template</B>, which is filled with the
- document's <B>headers</B>, <B>body</B>, and an optional <B>table of contents</B>.
- </P>
- <H2 ID="section-Template">1.1. Template</H2>
- <P>
- 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 <I>HEADER_TEMPLATE</I> area. Alternatively, the user may
- use a custom header using the <I>--template</I> command line option.
- </P>
- <P>
- Templates should make use of the <B>%(HEADER1)s</B>, <B>%(HEADER2)s</B>,
- and <B>%(HEADER3)s</B> macros, as well as <B>%(ENCODING)s</B> and
- <B>%(STYLE)s</B> 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 <A HREF="#keepblankheaderline">'keepblankheaderline'</A>.
- </P>
- <P>
- It is not required, but by convention <B>HEADER1</B> refers to the title,
- <B>HEADER2</B> to the author, and <B>HEADER3</B> to the date the document was
- created. Several targets reflect this convention in their use of the
- <B>HEADER</B> metadata in their default templates.
- </P>
- <P>
- Custom templates must also include the <B>%(BODY)s</B> 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 <I>HEADER_TEMPLATE</I> text.
- </P>
- <H2 ID="section-BodyText">1.2. Body Text</H2>
- <P>
- 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 <I>getTags()</I>
- end up in this section, along with all user text.
- </P>
- <P>
- 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.
- </P>
- <H2 ID="section-TableofContents">1.3. Table of Contents</H2>
- <P>
- 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.
- </P>
- <P>
- If the command line option <I>--toc</I> is used, Txt2tags will add a
- table of contents to the output. If the command line option
- <I>--toc-only</I> is used, then the table of contents will be the only
- thing output, and the rest of the body text will not.
- </P>
- <P>
- 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 <A HREF="#bodyOpen">bodyOpen</A> and before the main text. If this is not
- appropriate, the user can insert the <B>%%toc</B> macro into the source
- text, and it will be emitted there instead.
- </P>
- <P>
- Full details on how the table of contents is emitted is given in the
- section on the Table of Contents tags.
- </P>
- <H2 ID="section-Escapes">1.4. Escapes</H2>
- <P>
- One final note, though this is not really part of the document
- structures. Most text is processed throught the functions
- <I>doEscape()</I> and <I>doFinalEscape()</I> 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.
- </P>
- <P>
- 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.
- </P>
- <H1 ID="chapter-BasicBlocks">2. Basic Blocks</H1>
- <H2 ID="section-Paragraphs">2.1. Paragraphs</H2>
- <P>
- Paragraphs are the most common, and most basic of all text blocks.
- They are the simple, regular body text of the document.
- </P>
- <P>
- If the rule <A HREF="#blanksaroundpara">'blanksaroundpara'</A> is defined, an empty line will be
- emitted before and after the paragraph and tags.
- </P>
- <P>
- If the rule <A HREF="#onelinepara">'onelinepara'</A> is defined, the paragraph text will have
- all newlines removed and replaced with spaces, emitting the
- paragraph as a single line.
- </P>
- <H3 ID="paragraphOpen">paragraphOpen</H3>
- <P>
- This tag is emitted, on its own line, before each paragraph of body
- text. If this tag (and <A HREF="#paragraphClose">paragraphClose</A>) are not defined for a
- target, the body text is simply printed as unadorned plain text,
- much like the source document.
- </P>
- <DL>
- <DT>Macros:</DT><DD>
- <DL>
- <DT><B>~D~</B></DT><DD>
- 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.
- <P></P>
- If the rule <A HREF="#blockdepthmultiply">'blockdepthmultiply'</A> is defined for the target,
- the depth value will be multiplied by that amount before being
- emitted. If the rule <A HREF="#depthmultiplyplus">'depthmultiplyplus'</A> is defined, then that
- value will be added to the depth before multiplying by
- <A HREF="#blockdepthmultiply">'blockdepthmultiply'</A>, but only if used with
- <A HREF="#blockdepthmultiply">'blockdepthmultiply'</A>.
- <P></P>
- If the rule <A HREF="#zerodepthpara">'zerodepthpara'</A> is defined, then top-level
- paragraphs (those not nested inside a list) will always have
- <B>~D~</B> replaced with '0', regardless of the other rules.
- </DL>
- </DL>
- <H3 ID="paragraphClose">paragraphClose</H3>
- <P>
- This tag is emitted, on its own line, after each paragraph of body
- text.
- </P>
- <DL>
- <DT>Macros</DT><DD>
- None
- </DL>
- <H2 ID="section-BlockQuotations">2.2. Block Quotations</H2>
- <P>
- Block quotes are paragraphs that are set apart from regular
- paragraphs, usually to show that they are quoted from some external
- source.
- </P>
- <P>
- 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.
- </P>
- <P>
- Nested block quotes are allowed, unless the rule <A HREF="#quotenotnested">'quotenotnested'</A>
- is defined for the target.
- </P>
- <P>
- If the rule <A HREF="#keepquoteindent">'keepquoteindent'</A> is defined, then each line of the
- block quote will have tab characters added before the text equal to
- the depth of that quote.
- </P>
- <P>
- If the rule <A HREF="#blanksaroundquote">'blanksaroundquote'</A> is defined, an extra blank line is
- emitted before and after the block quote.
- </P>
- <H3 ID="blockQuoteOpen">blockQuoteOpen</H3>
- <P>
- This tag is emitted, on its own line, before each paragraph of a
- block quote.
- </P>
- <P>
- The block depth is given by a number of tab characters.
- <CODE>blockQuoteOpen</CODE> will have these tabs inserted before the tag,
- unless the rule <A HREF="#tagnotindentable">'tagnotindentable'</A> is defined.
- </P>
- <DL>
- <DT>Macros:</DT><DD>
- <DL>
- <DT><B>~D~</B></DT><DD>
- 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.
- <P></P>
- If the rule <A HREF="#blockdepthmultiply">'blockdepthmultiply'</A> is defined for the target,
- the depth value will be multiplied by that amount before being
- emitted. If the rule <A HREF="#depthmultiplyplus">'depthmultiplyplus'</A> is defined, then that
- value will be added to the depth before multiplying by
- <A HREF="#blockdepthmultiply">'blockdepthmultiply'</A>, but only if used with
- <A HREF="#blockdepthmultiply">'blockdepthmultiply'</A>.
- </DL>
- </DL>
- <H3 ID="blockQuoteLine">blockQuoteLine</H3>
- <P>
- If this tag is present, it will be added before each line of the
- block quote.
- </P>
- <P>
- 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 '***'.
- </P>
- <P>
- If the rule <A HREF="#keepquoteindent">'keepquoteindent'</A> is defined, all copies of this tag
- are emitted after the tab characters and before the quote text.
- </P>
- <DL>
- <DT>Macros:</DT><DD>
- None
- </DL>
- <H3 ID="blockQuoteClose">blockQuoteClose</H3>
- <P>
- This tag is emitted, on its own line, at the end of each block
- quote.
- </P>
- <P>
- The block depth is given by a number of tab characters.
- <CODE>blockQuoteClose</CODE> will have these tabs inserted before the tag,
- unless the rule <A HREF="#tagnotindentable">'tagnotindentable'</A> is defined.
- </P>
- <DL>
- <DT>Macros:</DT><DD>
- None
- </DL>
- <H2 ID="section-VerbatimBlocks">2.3. Verbatim Blocks</H2>
- <P>
- 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.
- </P>
- <P>
- 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
- <I>appear</I> the same as in the source text.
- </P>
- <P>
- By default, verbatim blocks are passed through <I>doEscape()</I> but
- not <I>doFinalEscape()</I>. If the rule <A HREF="#verbblocknotescaped">'verbblocknotescaped'</A> is
- defined, the text will not be passed through <I>doEscape()</I>. If the
- rule <A HREF="#verbblockfinalescape">'verbblockfinalescape'</A> is defined, then the text will be be
- passed through <I>doFinalEscape()</I>.
- </P>
- <P>
- If the rule <A HREF="#indentverbblock">'indentverbblock'</A> is defined, then each line of the
- text will be emitted with two spaces inserted before the text.
- </P>
- <P>
- If the rule <A HREF="#blanksaroundverb">'blanksaroundverb'</A> is defined, an extra blank line
- will be emitted before and after the verbatim block.
- </P>
- <P>
- Note that the entire verbatim area is emitted as a single block.
- Blank lines within a verbatim block do not separate paragraphs.
- </P>
- <H3 ID="blockVerbOpen">blockVerbOpen</H3>
- <P>
- This tag is emitted, on its own line, before each block of verbatim
- text.
- </P>
- <DL>
- <DT>Macros:</DT><DD>
- None
- </DL>
- <H3 ID="blockVerbLine">blockVerbLine</H3>
- <P>
- 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.
- </P>
- <P>
- If the rule <A HREF="#indentverbblock">'indentverbblock'</A> is defined, this tag is emitted
- after the spaces used for the indent, before the block text.
- </P>
- <DL>
- <DT>Macros:</DT><DD>
- None
- </DL>
- <H3 ID="blockVerbSep">blockVerbSep</H3>
- <P>
- This tag is emitted, on a line by itself, in between each line of
- text in the verbatim block.
- </P>
- <DL>
- <DT>Macros:</DT><DD>
- None
- </DL>
- <H3 ID="blockVerbClose">blockVerbClose</H3>
- <P>
- This tag is emitted, on its own line, after each block of verbatim
- text.
- </P>
- <DL>
- <DT>Macros:</DT><DD>
- None
- </DL>
- <H1 ID="chapter-InlineTags">3. Inline Tags</H1>
- <P>
- 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.
- </P>
- <P>
- All of these tags are inline, meaning that they do not begin or end
- blocks and do not add or remove lines of text.
- </P>
- <H2 ID="section-TextBeautifiers">3.1. Text Beautifiers</H2>
- <P>
- These are the simple tags used to change how text appears in the
- final output.
- </P>
- <P>
- None of these tags use any special macros.
- </P>
- <H3 ID="fontItalic">fontItalicOpen, fontItalicClose</H3>
- <P>
- These tags are emitted, respectively, immediately before and after
- some text that should appear in <I>italics</I> for emphasis.
- </P>
- <H3 ID="fontBold">fontBoldOpen, fontBoldClose</H3>
- <P>
- These tags are emitted, respectively, immediately before and after
- some text that should appear in <B>bold</B> for strong emphasis.
- </P>
- <H3 ID="fontUnderline">fontUnderlineOpen, fontUnderlineClose</H3>
- <P>
- These tags are emitted, respectively, immediately before and after
- some text that should appear <U>underlined</U>.
- </P>
- <H3 ID="fontStrike">fontStrikeOpen, fontStrikeClose</H3>
- <P>
- These tags are emitted, respectively, immediately before and after
- some text that should appear <S>struck out</S>.
- </P>
- <H3 ID="fontMono">fontMonoOpen, fontMonoClose</H3>
- <P>
- These tags are emitted, respectively, immediately before and after
- some text that should appear in a <CODE>monospaced</CODE> font, such as
- inline source code.
- </P>
- <H2 ID="section-Links">3.2. Links</H2>
- <P>
- These tags are used to insert links to external files, pages, or
- resources, as well as internal links within the document itself.
- </P>
- <P>
- The link text itself is a <B>url</B>. Ordinarily, urls are not escaped
- so as to preserve all characters within it exactly as typed. It the
- rule <A HREF="#escapeurl">'escapeurl'</A> is defined for a target, the url will be passed
- through <I>doEscape()</I> after all. Additionally, if the rule
- <A HREF="#linkable">'linkable'</A> is not defined, signalling that this target does not
- support true links, then the url will be escaped as well.
- </P>
- <H3 ID="url">url</H3>
- <P>
- This tag is used to insert a bare url without a label.
- </P>
- <DL>
- <DT>Macros:</DT><DD>
- <DL>
- <DT><B>\a</B></DT><DD>
- This mark within the tag will be expanded into the text of the
- url itself. For example, if the <CODE>url</CODE> tag is '[url=\a]'
- and the url in the source document in 'example.com', then
- the text '[url=example.com]' will be emitted.
- </DL>
- </DL>
- <H3 ID="urlMark">urlMark</H3>
- <P>
- 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.
- </P>
- <DL>
- <DT>Macros:</DT><DD>
- <DL>
- <DT><B>\a</B></DT><DD>
- 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.
- <P></P>
- If the rule <A HREF="#labelbeforelink">'labelbeforelink'</A> is defined for the target, then
- the first instance is the label, and the second instance is the
- url.
- <P></P>
- If the rule <A HREF="#imglinkable">'imglinkable'</A> is defined for the target, then an
- <A HREF="#img">img</A> tag (see below) is allowed as the label.
- </DL>
- </DL>
- <H3 ID="urlMarkAnchor">urlMarkAnchor</H3>
- <P>
- 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.
- </P>
- <P>
- This tag otherwise behaves identically as <A HREF="#urlMark">urlMark</A>, with the same
- macro definitions.
- </P>
- <H3 ID="email">email</H3>
- <P>
- 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.
- </P>
- <P>
- Just like <A HREF="#url">url</A>, this tag is used for a plain email with no label
- defined.
- </P>
- <DL>
- <DT>Macros:</DT><DD>
- <DL>
- <DT><B>\a</B></DT><DD>
- This mark is expanded to the full text of the email address.
- </DL>
- </DL>
- <H3 ID="emailMark">emailMark</H3>
- <P>
- Similar to <A HREF="#urlMark">urlMark</A>, this tag is used for email addresses that
- are assigned a label in the source document.
- </P>
- <DL>
- <DT>Macros:</DT><DD>
- <DL>
- <DT><B>\a</B></DT><DD>
- This mark appears twice in the tag, just like <A HREF="#urlMark">urlMark</A>. 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
- <A HREF="#labelbeforelink">'labelbeforelink'</A> is defined, then the first instance is the
- label and the second instance is the email address.
- </DL>
- </DL>
- <H2 ID="section-Images">3.3. Images</H2>
- <P>
- 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
- </P>
- <H3 ID="img">img</H3>
- <P>
- 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.
- </P>
- <P>
- 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.
- </P>
- <DL>
- <DT>Macros:</DT><DD>
- <DL>
- <DT><B>\a</B></DT><DD>
- This mark is expanded to the text of the file path pointing to
- the inserted image.
- <P></P>
- <DT><B>~A~</B></DT><DD>
- This mark represents the alignment of the image. If the rule
- <A HREF="#imgalignable">'imgalignable'</A> is defined for the target, then this mark will
- be replaced with the contents of <A HREF="#_imgAlign">_imgAlignLeft, _imgAlignRight, or _imgAlignCenter</A> as appropriate. (Note
- the underscore at the beginning of each tag.)
- </DL>
- </DL>
- <H3 ID="_imgAlign">_imgAlignLeft, _imgAlignRight, _imgAlignCenter</H3>
- <P>
- These tags are used to add alignment to the <A HREF="#img">img</A> tag. If the rule
- <A HREF="#imgalignable">'imgalignable'</A> is defined, then whichever of these tags is
- appropriate will replace the <B>~A~</B> mark within the <A HREF="#img">img</A> tag.
- </P>
- <P>
- Note the underscores at the beginning of the tag names. Do not
- confuse these with the <A HREF="#imgAlign">imgAlignLeft, imgAlignRight, and imgAlignCenter</A> tags, explained below.
- </P>
- <DL>
- <DT>Macros:</DT><DD>
- None
- </DL>
- <H3 ID="imgAlign">imgAlignLeft, imgAlignRight, imgAlignCenter</H3>
- <P>
- These tags are used if the alignment changes the image tags too much
- to simply use <A HREF="#img">img</A> and <A HREF="#_imgAlign">_imgAlign*</A>.
- </P>
- <P>
- If the rule <A HREF="#imgalignable">'imgalignable'</A> is defined and these tags are defined,
- then they will be used <I>instead of</I> the <A HREF="#img">img</A> tag. Each of these
- tags should have whatever markup is needed for image align in them,
- and they will not have <B>~A~</B> expanded.
- </P>
- <DL>
- <DT>Macros:</DT><DD>
- <DL>
- <DT><B>\a</B></DT><DD>
- This mark is expanded to the file path of the image file, just
- as in the <A HREF="#img">img</A> tag.
- </DL>
- </DL>
- <H3 ID="imgEmbed">imgEmbed</H3>
- <P>
- 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 <I>--embed-images</I> is used, then this tag will be
- used <I>instead of</I> the <A HREF="#img">img</A> tag.
- </P>
- <P>
- Currently this is only used by the <B>RTF</B> target, and will require
- additional functionality to be added to Txt2tags to add support to
- another target.
- </P>
- <DL>
- <DT>Macros:</DT><DD>
- <DL>
- <DT><B>\a</B></DT><DD>
- 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.
- </DL>
- </DL>
- <H1 ID="chapter-TitlesandSections">4. Titles and Sections</H1>
- <P>
- 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 <CODE>title</CODE> family of tags.
- </P>
- <P>
- There are two methods used, depending on the tags and rules
- specified. By default, the <A HREF="#title1">title*</A> 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.
- </P>
- <P>
- If the rule <A HREF="#titleblocks">'titleblocks'</A> is defined for the target, then the
- <A HREF="#title1Open">title*Open*</A> and <A HREF="#blockTitle1Open">blockTitle*Open*</A> family of tags is used
- instead. These explicitly separate sections and subsections and
- allow additional markup for section commands as needed.
- </P>
- <P>
- 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.
- </P>
- <P>
- 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 <I>doEscape()</I> function and, if the rule
- <A HREF="#finalescapetitle">'finalescapetitle'</A> is defined, it is escaped by
- <I>doFinalEscape()</I> as well.
- </P>
- <H2 ID="section-TheAnchor">4.1. The Anchor</H2>
- <H3 ID="anchor">anchor</H3>
- <P>
- 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 <A HREF="#urlMark">urlMark</A> or <A HREF="#urlMarkAnchor">urlMarkAnchor</A> tag to link
- directly to it from another part of the document.
- </P>
- <P>
- If the command-line option <I>--toc</I> 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.
- </P>
- <DL>
- <DT>Macros:</DT><DD>
- <DL>
- <DT><B>\a</B></DT><DD>
- 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 <I>--toc</I> option is in effect.
- </DL>
- </DL>
- <H2 ID="section-Titles">4.2. Titles</H2>
- <P>
- The basic title tags are only used if the rule <A HREF="#titleblocks">'titleblocks'</A> 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.
- </P>
- <H3 ID="title1">title1, title2, title3, title4, title5</H3>
- <P>
- These tags are for basic standard headings. <CODE>title1</CODE> is considered
- the top level heading, <CODE>title2</CODE> the next level below it, and so
- on.
- </P>
- <P>
- If the rule <A HREF="#blanksaroundtitle">'blanksaroundtitle'</A> is defined, and extra blank line
- will be emitted before and after this tag.
- </P>
- <DL>
- <DT>Macros:</DT><DD>
- <DL>
- <DT><B>\a</B></DT><DD>
- This mark is expanded into the text of the title itself,
- unchanged excepts for necessary escapes from the source
- document.
- <DT><B>~A~</B></DT><DD>
- This mark is expanded into the value of the <A HREF="#anchor">anchor</A> 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.
- </DL>
- </DL>
- <H3 ID="numtitle1">numtitle1, numtitle2, numtitle3, numtitle4, numtitle5</H3>
- <P>
- These tags are used for sections heading that should be numbered.
- They are otherwise treated the same as <A HREF="#title1">title*</A>.
- </P>
- <P>
- If the rule <A HREF="#autonumbertitle">'autonumbertitle'</A> 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.
- </P>
- <P>
- If the rule <A HREF="#blanksaroundnumtitle">'blanksaroundnumtitle'</A> is defined, an extra blank line
- will be emitted before and after this tag.
- </P>
- <DL>
- <DT>Macros:</DT><DD>
- <DL>
- <DT><B>\a</B></DT><DD>
- This mark is expanded into the text of the title itself,
- unchanged excepts for necessary escapes from the source
- document.
- <DT><B>~A~</B></DT><DD>
- This mark is expanded into the value of the <A HREF="#anchor">anchor</A> 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.
- </DL>
- </DL>
- <H2 ID="section-SectioningTags">4.3. Sectioning Tags</H2>
- <P>
- If the rule <A HREF="#titleblocks">'titleblocks'</A> is defined for the target, then the
- above <A HREF="#title1">title*</A> 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.
- </P>
- <H3 ID="title1Open">title1Open, title2Open, title3Open, title4Open, title5Open</H3>
- <P>
- 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 <A HREF="#title1">title*</A> tags above.
- </P>
- <P>
- If the rule <A HREF="#blanksaroundtitle">'blanksaroundtitle'</A> is defined, an extra blank line
- will be emitted before and after this tag.
- </P>
- <DL>
- <DT>Macros:</DT><DD>
- <DL>
- <DT><B>\a</B></DT><DD>
- This mark is expanded into the text of the title itself,
- unchanged excepts for necessary escapes from the source
- document.
- <DT><B>~A~</B></DT><DD>
- This mark is expanded into the value of the <A HREF="#anchor">anchor</A> 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.
- </DL>
- </DL>
- <H3 ID="title1Close">title1Close, title2Close, title3Close, title4Close, title5Close</H3>
- <P>
- These tags are used to mark the end of a section that has been
- opened with <A HREF="#title1Open">title*Open*</A>. 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.
- </P>
- <P>
- 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: <CODE>title1Open</CODE>, <CODE>title2Open</CODE>,
- <CODE>title2Close</CODE>, <CODE>title1Close</CODE>, <CODE>title1Open</CODE>, and so on.
- </P>
- <DL>
- <DT>Macros:</DT><DD>
- None
- </DL>
- <H3 ID="blocktitle1Open">blocktitle1Open, blocktitle2Open, blocktitle3Open</H3>
- <P>
- 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 <CODE>blocktitle*Open</CODE> tag will be emitted
- before the first <A HREF="#title1Open">title*Open*</A>.
- </P>
- <DL>
- <DT>Macros:</DT><DD>
- None
- </DL>
- <H3 ID="blocktitle1Close">blocktitle1Close, blocktitle2Close, blocktitle3Close</H3>
- <P>
- 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 <CODE>blocktitle*Close</CODE> tag will be emitted
- after the last <A HREF="#title1Close">title*Close*</A>.
- </P>
- <DL>
- <DT>Macros:</DT><DD>
- None
- </DL>
- <H1 ID="chapter-Lists">5. Lists</H1>
- <P>
- Lists are used to add structure to small groups of items. They can
- be numbered or unnumbered, and they can be nested.
- </P>
- <P>
- If the rule <A HREF="#compactlist">'compactlist'</A> 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.
- </P>
- <P>
- If the rule <A HREF="#compactlist">'compactlist'</A> is <I>not</I> defined, then there is no
- difference bewteen wide and compact lists, and all lists are treated
- as wide lists.
- </P>
- <P>
- If the rule <A HREF="#parainsidelist">'parainsidelist'</A> is defined for a target, then the
- blank lines in wide lists are emitted as an empty paragraph. That
- is, <A HREF="#paragraphOpen">paragraphOpen</A> followed immediately by <A HREF="#paragraphClose">paragraphClose</A>.
- </P>
- <P>
- The rule <A HREF="#spacedlistitem">'spacedlistitem'</A> 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.
- </P>
- <P>
- The rule <A HREF="#listmaxdepth">'listmaxdepth'</A> is used to tell Txt2tags how many levels
- of lists may be nested within one another for each target.
- </P>
- <P>
- If the rule <A HREF="#listnotnested">'listnotnested'</A> 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.
- </P>
- <P>
- If the rule <A HREF="#listitemnotnested">'listitemnotnested'</A> is defined for a target, then
- list items are closed before emitting a nested list, rather than wrapping
- around the nested list.
- </P>
- <H2 ID="section-UnorderedLists">5.1. Unordered Lists</H2>
- <P>
- 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.
- </P>
- <P>
- If the rule <A HREF="#blanksaroundlist">'blanksaroundlist'</A> 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.
- </P>
- <P>
- If the rule <A HREF="#blanksaroundnestedlist">'blanksaroundnestedlist'</A> is defined for a target, an
- extra blank line is emitted before and after all lists, including
- nested lists.
- </P>
- <H3 ID="listOpen">listOpen</H3>
- <P>
- This tag is emitted to mark the start of a new bulleted list.
- </P>
- <P>
- By default this tag is emitted on its own line. The rule
- <A HREF="#notbreaklistopen">'notbreaklistopen'</A> is intended to allow
- <CODE>listOpen</CODE> to be on the same line as its first item, however
- this rule is not yet supported and does not affect the output.
- </P>
- <P>
- 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
- <A HREF="#tagnotindentable">'tagnotindentable'</A> is defined, or the rule <A HREF="#keeplistindent">'keeplistindent'</A> is
- not defined, these spaces are removed.
- </P>
- <P>
- If the rule <A HREF="#compactlist">'compactlist'</A> is defined for a target, then this tag
- is only used for wide lists. Otherwise it is used for both.
- </P>
- <DL>
- <DT>Macros:</DT><DD>
- None
- </DL>
- <H3 ID="listCompactOpen">listCompactOpen</H3>
- <P>
- This tag marks the beginning of a new compact bulleted list.
- </P>
- <P>
- This tag is only used if the rule <A HREF="#compactlist">'compactlist'</A> is defined.
- </P>
- <P>
- 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
- <A HREF="#tagnotindentable">'tagnotindentable'</A> is defined, or the rule <A HREF="#keeplistindent">'keeplistindent'</A> is
- not defined, these spaces are removed.
- </P>
- <DL>
- <DT>Macros:</DT><DD>
- None
- </DL>
- <H3 ID="listClose">listClose, listCompactClose</H3>
- <P>
- These tags are emitted, on their own line, to close the list opened
- by the previous tags.
- </P>
- <P>
- 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
- <A HREF="#tagnotindentable">'tagnotindentable'</A> is defined, or the rule <A HREF="#keeplistindent">'keeplistindent'</A> is
- not defined, these spaces are removed.
- </P>
- <DL>
- <DT>Macros:</DT><DD>
- None
- </DL>
- <H3 ID="listItemOpen">listItemOpen</H3>
- <P>
- This tag is emitted before each item within a bullet list.
- </P>
- <P>
- 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
- <A HREF="#tagnotindentable">'tagnotindentable'</A> is defined, or the rule <A HREF="#keeplistindent">'keeplistindent'</A> is
- not defined, these spaces are removed.
- </P>
- <P>
- If the tag <A HREF="#listItemLine">listItemLine</A> is defined, it will be emitted
- immediately before <CODE>listItemOpen</CODE>. If the rule
- <A HREF="#listlineafteropen">'listlineafteropen'</A> is defined,
- <A HREF="#listItemLine">listItemLine</A> will be emitted after <CODE>listItemOpen</CODE>.
- </P>
- <P>
- If the rule <A HREF="#spacedlistitemopen">'spacedlistitemopen'</A> is defined, then two spaces will
- be emitted after <CODE>listItemOpen</CODE> and <A HREF="#listItemLine">listItemLine</A>, before the
- list item text.
- </P>
- <DL>
- <DT>Macros:</DT><DD>
- <DL>
- <DT><B>~D~</B></DT><DD>
- 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.
- <P></P>
- If the rule <A HREF="#blockdepthmultiply">'blockdepthmultiply'</A> is defined for the target,
- the depth value will be multiplied by that amount before being
- emitted. If the rule <A HREF="#depthmultiplyplus">'depthmultiplyplus'</A> is defined, then that
- value will be added to the depth before multiplying by
- <A HREF="#blockdepthmultiply">'blockdepthmultiply'</A>, but only if used with
- <A HREF="#blockdepthmultiply">'blockdepthmultiply'</A>.
- <DT><B>~V~</B></DT><DD>
- This macro will be expanded to the nesting level of the list. It
- is not affected by <A HREF="#blockdepthmultiply">'blockdepthmultiply'</A>, so the numbers will
- always count one by one.
- <P></P>
- If the rule <A HREF="#listlevelzerobased">'listlevelzerobased'</A> 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.
- </DL>
- </DL>
- <H3 ID="listItemLine">listItemLine</H3>
- <P>
- This tag is emitted for each item in the list. It is emitted either
- right before or after <A HREF="#listItemOpen">listItemOpen</A> (see above).
- </P>
- <P>
- This is emitted a number of times equal to the depth level of the
- list. For example, if <CODE>listItemLine</CODE> is defined as '*', then
- each item in a list nested three levels deep would begin with
- '***'.
- </P>
- <P>
- Despite the name, this is only emitted at the beginning of each
- item, and not for every line of the item.
- </P>
- <DL>
- <DT>Macros:</DT><DD>
- None
- </DL>
- <H3 ID="listItemClose">listItemClose</H3>
- <P>
- This tag is emitted after each item in the list.
- </P>
- <DL>
- <DT>Macros:</DT><DD>
- None
- </DL>
- <H2 ID="section-NumberedLists">5.2. Numbered Lists</H2>
- <P>
- Numbered lists behave much like unordered lists, except (as their
- name implies) they have numbers instead of bullets.
- </P>
- <P>
- 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.
- </P>
- <P>
- If the rule <A HREF="#blanksaroundnumlist">'blanksaroundnumlist'</A> 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.
- </P>
- <P>
- If the rule <A HREF="#blanksaroundnestedlist">'blanksaroundnestedlist'</A> is defined for a target, an
- extra blank line is emitted before and after all lists, including
- nested lists.
- </P>
- <H3 ID="numlistOpen">numlistOpen</H3>
- <P>
- This tag is emitted to mark the start of a new numbered list.
- </P>
- <P>
- By default this tag is emitted on its own line. The rule
- <A HREF="#notbreaklistopen">'notbreaklistopen'</A> is intended to allow
- <CODE>numlistOpen</CODE> to be on the same line as its first item, however
- this rule is not yet supported and does not affect the output.
- </P>
- <P>
- 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
- <A HREF="#tagnotindentable">'tagnotindentable'</A> is defined, or the rule <A HREF="#keeplistindent">'keeplistindent'</A> is
- not defined, these spaces are removed.
- </P>
- <P>
- If the rule <A HREF="#compactlist">'compactlist'</A> is defined for a target, then this tag
- is only used for wide lists. Otherwise it is used for both.
- </P>
- <DL>
- <DT>Macros:</DT><DD>
- None
- </DL>
- <H3 ID="numlistCompactOpen">numlistCompactOpen</H3>
- <P>
- This tag marks the beginning of a new compact numbered list.
- </P>
- <P>
- This tag is only used if the rule <A HREF="#compactlist">'compactlist'</A> is defined.
- </P>
- <P>
- 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
- <A HREF="#tagnotindentable">'tagnotindentable'</A> is defined, or the rule <A HREF="#keeplistindent">'keeplistindent'</A> is
- not defined, these spaces are removed.
- </P>
- <DL>
- <DT>Macros:</DT><DD>
- None
- </DL>
- <H3 ID="numlistClose">numlistClose, numlistCompactClose</H3>
- <P>
- These tags are emitted, on their own line, to close the list opened
- by the previous tags.
- </P>
- <P>
- 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
- <A HREF="#tagnotindentable">'tagnotindentable'</A> is defined, or the rule <A HREF="#keeplistindent">'keeplistindent'</A> is
- not defined, these spaces are removed.
- </P>
- <DL>
- <DT>Macros:</DT><DD>
- None
- </DL>
- <H3 ID="numlistItemOpen">numlistItemOpen</H3>
- <P>
- This tag is emitted before each item within a numbered list.
- </P>
- <P>
- If the rule <A HREF="#autonumberlist">'autonumberlist'</A> is defined, then the target is
- assumed to put the numbers in itself. In this case Txt2Tags simply
- emits this tag just like <A HREF="#listItemOpen">listItemOpen</A>. 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.
- </P>
- <P>
- 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
- <A HREF="#tagnotindentable">'tagnotindentable'</A> is defined, or the rule <A HREF="#keeplistindent">'keeplistindent'</A> is
- not defined, these spaces are removed.
- </P>
- <P>
- If the tag <A HREF="#numlistItemLine">numlistItemLine</A> is defined, it will be emitted
- immediately before <CODE>numlistItemOpen</CODE>. If the rule
- <A HREF="#listlineafteropen">'listlineafteropen'</A> is defined, <A HREF="#numlistItemLine">numlistItemLine</A> will be emitted
- after <CODE>numlistItemOpen</CODE>.
- </P>
- <P>
- If the rule <A HREF="#spacednumlistitemopen">'spacednumlistitemopen'</A> is defined, then two spaces will
- be emitted after <CODE>numlistItemOpen</CODE> and <A HREF="#numlistItemLine">numlistItemLine</A>, before the
- list item text.
- </P>
- <DL>
- <DT>Macros:</DT><DD>
- <DL>
- <DT><B>\a</B></DT><DD>
- If the rule <A HREF="#autonumberlist">'autonumberlist'</A> is <I>not</I> defined, then this
- mark is expanded into the correct number for this list item.
- <DT><B>~D~</B></DT><DD>
- 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.
- <P></P>
- If the rule <A HREF="#blockdepthmultiply">'blockdepthmultiply'</A> is defined for the target,
- the depth value will be multiplied by that amount before being
- emitted. If the rule <A HREF="#depthmultiplyplus">'depthmultiplyplus'</A> is defined, then that
- value will be added to the depth before multiplying by
- <A HREF="#blockdepthmultiply">'blockdepthmultiply'</A>, but only if used with
- <A HREF="#blockdepthmultiply">'blockdepthmultiply'</A>.
- <DT><B>~V~</B></DT><DD>
- This macro will be expanded to the nesting level of the list. It
- is not affected by <A HREF="#blockdepthmultiply">'blockdepthmultiply'</A>, so the numbers will
- always count one by one.
- <P></P>
- If the rule <A HREF="#listlevelzerobased">'listlevelzerobased'</A> 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.
- </DL>
- </DL>
- <H3 ID="numlistItemLine">numlistItemLine</H3>
- <P>
- This tag is emitted for each item in the list. It is emitted either
- right before or after <A HREF="#numlistItemOpen">numlistItemOpen</A> (see above).
- </P>
- <P>
- This is emitted a number of times equal to the depth level of the
- list. For example, if <CODE>numlistItemLine</CODE> is defined as '+', then
- each item in a list nested three levels deep would begin with
- '+++'.
- </P>
- <P>
- Despite the name, this is only emitted at the beginning of each
- item, and not for every line of the item.
- </P>
- <DL>
- <DT>Macros:</DT><DD>
- None
- </DL>
- <H3 ID="numlistItemClose">numlistItemClose</H3>
- <P>
- This tag is emitted after each item in the list.
- </P>
- <DL>
- <DT>Macros:</DT><DD>
- None
- </DL>
- <H2 ID="section-DefinitionLists">5.3. Definition Lists</H2>
- <P>
- 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.
- </P>
- <P>
- If the rule <A HREF="#deflisttextstrip">'deflisttextstrip'</A> is defined, then each line of the
- definition will have extra spaces stripped off, even if
- <A HREF="#keeplistindent">'keeplistindent'</A> is also defined.
- </P>
- <P>
- If the rule <A HREF="#blanksarounddeflist">'blanksarounddeflist'</A> 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.
- </P>
- <P>
- If the rule <A HREF="#blanksaroundnestedlist">'blanksaroundnestedlist'</A> is defined for a target, an
- extra blank line is emitted before and after all lists, including
- nested lists.
- </P>
- <H3 ID="deflistOpen">deflistOpen</H3>
- <P>
- This tag is emitted to mark the start of a new definition list.
- </P>
- <P>
- By default this tag is emitted on its own line. The rule
- <A HREF="#notbreaklistopen">'notbreaklistopen'</A> is intended to allow <A HREF="#listOpen">listOpen</A> to be on the
- same line as its first item, however this rule is not yet supported
- and does not affect the output.
- </P>
- <P>
- 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
- <A HREF="#tagnotindentable">'tagnotindentable'</A> is defined, or the rule <A HREF="#keeplistindent">'keeplistindent'</A> is
- not defined, these spaces are removed.
- </P>
- <P>
- If the rule <A HREF="#compactlist">'compactlist'</A> is defined for a target, then this tag
- is only used for wide lists. Otherwise it is used for both.
- </P>
- <DL>
- <DT>Macros:</DT><DD>
- None
- </DL>
- <H3 ID="deflistCompactOpen">deflistCompactOpen</H3>
- <P>
- This tag marks the beginning of a new compact definition list.
- </P>
- <P>
- This tag is only used if the rule <A HREF="#compactlist">'compactlist'</A> is defined.
- </P>
- <P>
- 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
- <A HREF="#tagnotindentable">'tagnotindentable'</A> is defined, or the rule <A HREF="#keeplistindent">'keeplistindent'</A> is
- not defined, these spaces are removed.
- </P>
- <DL>
- <DT>Macros:</DT><DD>
- None
- </DL>
- <H3 ID="deflistClose">deflistClose, deflistCompactClose</H3>
- <P>
- These tags are emitted, on their own line, to close the list opened
- by the previous tags.
- </P>
- <P>
- 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
- <A HREF="#tagnotindentable">'tagnotindentable'</A> is defined, or the rule <A HREF="#keeplistindent">'keeplistindent'</A> is
- not defined, these spaces are removed.
- </P>
- <DL>
- <DT>Macros:</DT><DD>
- None
- </DL>
- <H3 ID="deflistItem1Open">deflistItem1Open</H3>
- <P>
- This tag is emitted before each item within a definition list. It is
- specifically meant to go before the term to be defined.
- </P>
- <P>
- 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
- <A HREF="#tagnotindentable">'tagnotindentable'</A> is defined, or the rule <A HREF="#keeplistindent">'keeplistindent'</A> is
- not defined, these spaces are removed.
- </P>
- <P>
- If the rule <A HREF="#imgasdefterm">'imgasdefterm'</A> is defined, then a linked image is
- allowed as the term to be defined. Otherwise, only text is allowed.
- </P>
- <DL>
- <DT>Macros:</DT><DD>
- <DL>
- <DT><B>~D~</B></DT><DD>
- 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.
- <P></P>
- If the rule <A HREF="#blockdepthmultiply">'blockdepthmultiply'</A> is defined for the target,
- the depth value will be multiplied by that amount before being
- emitted. If the rule <A HREF="#depthmultiplyplus">'depthmultiplyplus'</A> is defined, then that
- value will be added to the depth before multiplying by
- <A HREF="#blockdepthmultiply">'blockdepthmultiply'</A>, but only if used with
- <A HREF="#blockdepthmultiply">'blockdepthmultiply'</A>.
- <DT><B>~V~</B></DT><DD>
- This macro will be expanded to the nesting level of the list. It
- is not affected by <A HREF="#blockdepthmultiply">'blockdepthmultiply'</A>, so the numbers will
- always count one by one.
- <P></P>
- If the rule <A HREF="#listlevelzerobased">'listlevelzerobased'</A> 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.
- </DL>
- </DL>
- <H3 ID="deflistItem1Close">deflistItem1Close</H3>
- <P>
- This tag is emitted after each definition term, but before the
- definition itself, for each item in the list.
- </P>
- <DL>
- <DT>Macros:</DT><DD>
- None
- </DL>
- <H3 ID="deflistItem2Open">deflistItem2Open</H3>
- <P>
- This tag is emitted directly after <A HREF="#deflistItem1Close">deflistItem1Close</A>, and is
- used right before the definition text of the item.
- </P>
- <DL>
- <DT>Macros:</DT><DD>
- None
- </DL>
- <H3 ID="deflistItem2LinePrefix">deflistItem2LinePrefix</H3>
- <P>
- This tag is emitted at the beginning of each line of the definition
- text for each item.
- </P>
- <P>
- Note that it is not multiplied for nexted lists. It is the same for
- every level of a nested list.
- </P>
- <P>
- If the rule <A HREF="#keeplistindent">'keeplistindent'</A> is defined and <A HREF="#deflisttextstrip">'deflisttextstrip'</A>
- is not defined, then this is emitted after the indent for each line
- of the list.
- </P>
- <DL>
- <DT>Macros:</DT><DD>
- None
- </DL>
- <H3 ID="deflistItem2Close">deflistItem2Close</H3>
- <P>
- This tag is emitted at the end of each definition, and therefor at
- the end of each item of the definition list.
- </P>
- <P>
- For examples, the tags for a definition list are emitted as follows:
- <CODE>deflistOpen</CODE>, <CODE>deflistItem1Open</CODE>, <CODE>deflistItem1Close</CODE>,
- <CODE>deflistItem2Open</CODE>, (<CODE>deflistItem2LinePrefix</CODE> for each line),
- <CODE>deflistItem2Close</CODE>, <CODE>deflistItem1Open</CODE>, and so on for the
- entire list.
- </P>
- <DL>
- <DT>Macros:</DT><DD>
- None
- </DL>
- <H1 ID="chapter-Tables">6. Tables</H1>
- <P>
- 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.
- </P>
- <P>
- If the rule <A HREF="#tableable">'tableable'</A> is <I>not</I> defined, then the table markup
- is emitted unchanged from the source document and put inside a
- verbatim block.
- </P>
- <P>
- If the rule <A HREF="#blanksaroundtable">'blanksaroundtable'</A> is defined, then an extra blank
- line will be emitted before and after the table markup.
- </P>
- <H2 ID="section-Macros">6.1. Macros</H2>
- <P>
- 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.
- </P>
- <H3 ID="_tableBorder">_tableBorder</H3>
- <P>
- This tag may be inserted into the outer table and row tags to
- designate that this table should have a border.
- </P>
- <P>
- For tags that support it, it will replace the macro <B>~B~</B>.
- </P>
- <H3 ID="_tableCellBorder">_tableCellBorder</H3>
- <P>
- This tag may be inserted into the markup of each individual cell to
- designate that this table should have a border.
- </P>
- <P>
- It will replace the macro <B>~B~</B>.
- </P>
- <H3 ID="_tableAlign">_tableAlignLeft, _tableAlignCenter</H3>
- <P>
- 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.
- </P>
- <P>
- Note that Txt2tags does not currently allow right-aligned tables.
- </P>
- <P>
- Whichever tag is appropriate will replace the macro <B>~A~</B>.
- </P>
- <H3 ID="_tableColAlign">_tableColAlignLeft, _tableColAlignRight, _tableColAlignCenter</H3>
- <P>
- If the rule <A HREF="#tablecellaligntype">'tablecellaligntype'</A> is set to the value <A HREF="#column">'column'</A>
- for the target, then these tags may be inserted into the outer table
- or row tags for that table.
- </P>
- <P>
- These alignment settings will be used for each cell in the column,
- for targets that do not support per-cell alignment.
- </P>
- <P>
- 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
- <A HREF="#tableColAlignSep">tableColAlignSep</A>. Then the entire group is inserted into the
- appropriate opening tags of the table.
- </P>
- <P>
- The column alignment group will replace the macro <B>~C~</B>.
- </P>
- <H3 ID="tableColAlignSep">tableColAlignSep</H3>
- <P>
- 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.
- </P>
- <P>
- 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.
- </P>
- <H3 ID="_tableCellAlign">_tableCellAlignLeft, _tableCellAlignRight, _tableCellAlignCenter</H3>
- <P>
- If the rule <A HREF="#tablecellaligntype">'tablecellaligntype'</A> is set to the value <A HREF="#cell">'cell'</A>
- 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.
- </P>
- <P>
- The alignment tag will replace the macro <B>~A~</B>.
- </P>
- <H3 ID="_tableCellColSpan">_tableCellColSpan</H3>
- <P>
- If the rule <A HREF="#tablecellspannable">'tablecellspannable'</A> is defined for a target, then
- this tag will be inserted into cells that span more than one column.
- </P>
- <P>
- It replaces the macro <B>~S~</B>.
- </P>
- <DL>
- <DT>Macros:</DT><DD>
- <DL>
- <DT><B>\a</B></DT><DD>
- 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.
- <P></P>
- <CODE>_tableCellColSpan</CODE> will only be emitted for cells that have a
- span value greater than '1'.
- <P></P>
- If the rule <A HREF="#cellspancumulative">'cellspancumulative'</A> 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.
- <P></P>
- If the rule <A HREF="#cellspanmultiplier">'cellspanmultiplier'</A> is defined for a target, then
- the span value will be multiplied by this value, after
- accumulation if appropriate.
- </DL>
- </DL>
- <H3 ID="_tableCellColSpanChar">_tableCellColSpanChar</H3>
- <P>
- If the rule <A HREF="#tablecellspannable">'tablecellspannable'</A> is defined for a target and this
- tag is also defined, it will be used instead of
- <A HREF="#_tableCellColSpan">_tableCellColSpan</A>.
- </P>
- <P>
- This tag will be emitted the same number of times as columns that
- the cell spans, <I>minus 1</I>. For example, if the tag is defined as
- '|', and a cell spans three columns, then '||' will be emitted.
- </P>
- <P>
- The tag, however many need to be emitted, will replace the macro
- <B>~S~</B>.
- </P>
- <H3 ID="_tableAttrDelimiter">_tableAttrDelimiter</H3>
- <P>
- 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.
- </P>
- <P>
- If the cell has neither an alignment or span to insert, then the
- macro for this tag is removed.
- </P>
- <P>
- This tag will replace the macro <B>~Z~</B>.
- </P>
- <H2 ID="section-TableStructure">6.2. Table Structure</H2>
- <H3 ID="tableOpen">tableOpen, tableClose</H3>
- <P>
- 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.
- </P>
- <DL>
- <DT>Macros:</DT><DD>
- <DL>
- <DT><B>~A~</B></DT><DD>
- This will be replaced with <A HREF="#_tableAlign">_tableAlign*</A> for a left or center
- aligned table.
- <DT><B>~B~</B></DT><DD>
- This will be replaced with the <A HREF="#_tableBorder">_tableBorder</A> tag for tables
- that have a border, or removed otherwise.
- <DT><B>~C~</B></DT><DD>
- If the rule <A HREF="#tablecellaligntype">'tablecellaligntype'</A> is set to <A HREF="#column">'column'</A>, then
- this will be replaced with the column alignment group for the
- table. (See <A HREF="#_tableColAlign">_tableColAlign*</A> above.)
- </DL>
- </DL>
- <H3 ID="tableRowOpen">tableRowOpen</H3>
- <P>
- This tag is emitted at the beginning of each row of cells.
- </P>
- <P>
- By default each row is emitted on a single line. If the rule
- <A HREF="#breaktablelineopen">'breaktablelineopen'</A> is defined, then a linebreak will be emitted
- after this tag before the cells.
- </P>
- <DL>
- <DT>Macros:</DT><DD>
- <DL>
- <DT><B>~A~</B></DT><DD>
- This will be replaced with <A HREF="#_tableAlign">_tableAlign*</A> for a left or center
- aligned table.
- <DT><B>~B~</B></DT><DD>
- This will be replaced with the <A HREF="#_tableBorder">_tableBorder</A> tag for tables
- that have a border, or removed otherwise.
- <DT><B>~C~</B></DT><DD>
- If the rule <A HREF="#tablecellaligntype">'tablecellaligntype'</A> is set to <A HREF="#column">'column'</A>, then
- this will be replaced with the column alignment group for the
- table. (See <A HREF="#_tableColAlign">_tableColAlign*</A> above.)
- </DL>
- </DL>
- <H3 ID="tableTitleRowOpen">tableTitleRowOpen</H3>
- <P>
- This tag, if defined, will be used instead of <A HREF="#tableRowOpen">tableRowOpen</A> for
- title rows. If it is not defined, <A HREF="#tableRowOpen">tableRowOpen</A> will be used for
- all rows.
- </P>
- <P>
- Note that title rows are not required, and do not need to be the
- first row of a table.
- </P>
- <P>
- If the rule <A HREF="#breaktablelineopen">'breaktablelineopen'</A> is defined, then a linebreak will
- be emitted after this tag before the cells.
- </P>
- <DL>
- <DT>Macros:</DT><DD>
- <DL>
- <DT><B>~A~</B></DT><DD>
- This will be replaced with <A HREF="#_tableAlign">_tableAlign*</A> for a left or center
- aligned table.
- <DT><B>~B~</B></DT><DD>
- This will be replaced with the <A HREF="#_tableBorder">_tableBorder</A> tag for tables
- that have a border, or removed otherwise.
- <DT><B>~C~</B></DT><DD>
- If the rule <A HREF="#tablecellaligntype">'tablecellaligntype'</A> is set to <A HREF="#column">'column'</A>, then
- this will be replaced with the column alignment group for the
- table. (See <A HREF="#_tableColAlign">_tableColAlign*</A> above.)
- </DL>
- </DL>
- <H3 ID="tableRowClose">tableRowClose, tableTitleRowClose</H3>
- <P>
- These tags are emitted at the end of each row begun by the tags
- above.
- </P>
- <P>
- If <CODE>tableTitleRowClose</CODE> is not defined, <CODE>tableRowClose</CODE> will be
- used instead.
- </P>
- <DL>
- <DT>Macros:</DT><DD>
- <DL>
- <DT><B>~A~</B></DT><DD>
- This will be replaced with <A HREF="#_tableAlign">_tableAlign*</A> for a left or center
- aligned table.
- <DT><B>~B~</B></DT><DD>
- This will be replaced with the <A HREF="#_tableBorder">_tableBorder</A> tag for tables
- that have a border, or removed otherwise.
- <DT><B>~C~</B></DT><DD>
- If the rule <A HREF="#tablecellaligntype">'tablecellaligntype'</A> is set to <A HREF="#column">'column'</A>, then
- this will be replaced with the column alignment group for the
- table. (See <A HREF="#_tableColAlign">_tableColAlign*</A> above.)
- </DL>
- </DL>
- <H3 ID="tableRowSep">tableRowSep</H3>
- <P>
- This tag will be emitted in between each row of cells.
- </P>
- <P>
- Note that if this tag is defined, then <A HREF="#tableRowOpen">tableRowOpen</A> and
- <A HREF="#tableRowClose">tableRowClose</A> will not be used at all.
- </P>
- <DL>
- <DT>Macros:</DT><DD>
- <DL>
- <DT><B>~A~</B></DT><DD>
- This will be replaced with <A HREF="#_tableAlign">_tableAlign*</A> for a left or center
- aligned table.
- <DT><B>~B~</B></DT><DD>
- This will be replaced with the <A HREF="#_tableBorder">_tableBorder</A> tag for tables
- that have a border, or removed otherwise.
- <DT><B>~C~</B></DT><DD>
- If the rule <A HREF="#tablecellaligntype">'tablecellaligntype'</A> is set to <A HREF="#column">'column'</A>, then
- this will be replaced with the column alignment group for the
- table. (See <A HREF="#_tableColAlign">_tableColAlign*</A> above.)
- </DL>
- </DL>
- <H2 ID="section-Cells">6.3. Cells</H2>
- <P>
- Each cell of data for a table may be marked up separately.
- </P>
- <P>
- By default, each row of cells is emitted on a single line. If the
- rule <A HREF="#breaktablecell">'breaktablecell'</A> is defined for a target, then a linebreak
- will be emitted after each cell.
- </P>
- <P>
- If the rule <A HREF="#tablecellstrip">'tablecellstrip'</A> 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.
- </P>
- <P>
- If the rule <A HREF="#tabletitlerowinbold">'tabletitlerowinbold'</A> is defined, then all cells
- considered part of a title row will have their contents wrapped in
- <A HREF="#fontBold">fontBoldOpen and fontBoldClose</A> tags.
- </P>
- <H3 ID="tableCellOpen">tableCellOpen, tableTitleCellOpen</H3>
- <P>
- These tags are emitted at the beginning of each cell within the
- table. If <CODE>tableTitleCellOpen</CODE> is defined, then it will be used
- for the cells on a title row. Otherwise, <CODE>tableCellOpen</CODE> will be
- used for all cells.
- </P>
- <DL>
- <DT>Macros:</DT><DD>
- <DL>
- <DT><B>~A~</B></DT><DD>
- If the rule <A HREF="#tablecellaligntype">'tablecellaligntype'</A> is set to the value
- <A HREF="#cell">'cell'</A> for a target, then this will be replaced with the
- appropriate <A HREF="#_tableCellAlign">_tableCellAlign*</A> tag.
- <DT><B>~B~</B></DT><DD>
- If the table has a border, this will be replaced with the
- <A HREF="#_tableCellBorder">_tableCellBorder</A> tag, or removed if not.
- <DT><B>~S~</B></DT><DD>
- If the rule <A HREF="#tablecellspannable">'tablecellspannable'</A> is defined, and the cell
- spans multiple columns, then this tag will be replaced with the
- value of either <A HREF="#_tableCellColSpanChar">_tableCellColSpanChar</A> or
- <A HREF="#_tableCellColSpan">_tableCellColSpan</A> as appropriate.
- <DT><B>~Z~</B></DT><DD>
- If the cell has and alignment or column span to be inserted,
- then this tag will be replaced with <A HREF="#_tableAttrDelimiter">_tableAttrDelimiter</A>. If
- the cell has neither, then it will be removed.
- </DL>
- </DL>
- <H3 ID="tableCellClose">tableCellClose, tableTitleCellClose</H3>
- <P>
- These tags are emitted at the end of each cell within the table. If
- <CODE>tableTitleCellClose</CODE> is defined, then it will be used for the
- cells on a title row. Otherwise, <CODE>tableCellClose</CODE> will be used for
- all cells.
- </P>
- <DL>
- <DT>Macros:</DT><DD>
- <DL>
- <DT><B>~A~</B></DT><DD>
- If the rule <A HREF="#tablecellaligntype">'tablecellaligntype'</A> is set to the value
- <A HREF="#cell">'cell'</A> for a target, then this will be replaced with the
- appropriate <A HREF="#_tableCellAlign">_tableCellAlign*</A> tag.
- <DT><B>~B~</B></DT><DD>
- If the table has a border, this will be replaced with the
- <A HREF="#_tableCellBorder">_tableCellBorder</A> tag, or removed if not.
- <DT><B>~S~</B></DT><DD>
- If the rule <A HREF="#tablecellspannable">'tablecellspannable'</A> is defined, and the cell
- spans multiple columns, then this tag will be replaced with the
- value of either <A HREF="#_tableCellColSpanChar">_tableCellColSpanChar</A> or
- <A HREF="#_tableCellColSpan">_tableCellColSpan</A> as appropriate.
- </DL>
- </DL>
- <H3 ID="tableCellSep">tableCellSep, tableTitleCellSep</H3>
- <P>
- These tags are emitted in between each cell of a row. If
- <CODE>tableTitleCellSep</CODE> is defined, then it will be used for the cells
- on a title row. Otherwise, <CODE>tableCellSep</CODE> will be used for all
- cells.
- </P>
- <P>
- 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.
- </P>
- <P>
- Note that, unlike <A HREF="#tableRowSep">tableRowSep</A>, these tags are used as well as
- <A HREF="#tableCellOpen">tableCellOpen</A> and <A HREF="#tableCellClose">tableCellClose</A>. If all are defined, then
- <CODE>tableCellSep</CODE> will be emitted after <CODE>tableCellClose</CODE> and before
- the next <CODE>tableCellOpen</CODE>.
- </P>
- <DL>
- <DT>Macros:</DT><DD>
- None
- </DL>
- <H3 ID="_tableCellMulticolOpen">_tableCellMulticolOpen</H3>
- <P>
- If the rule <A HREF="#tablecellmulticol">'tablecellmulticol'</A> is defined for a target, and a
- cell spans more than one column, then this tag will be used instead
- of <A HREF="#tableCellOpen">tableCellOpen</A>.
- </P>
- <DL>
- <DT>Macros:</DT><DD>
- <DL>
- <DT><B>\a</B></DT><DD>
- This will be replaced with the current cell's column span value.
- See <A HREF="#_tableCellColSpan">_tableCellColSpan</A> above for an explanation of this
- value.
- <DT><B>~A~</B></DT><DD>
- If the rule <A HREF="#tablecellaligntype">'tablecellaligntype'</A> is set to the value
- <A HREF="#cell">'cell'</A> for a target, then this will be replaced with the
- appropriate <A HREF="#_tableCellAlign">_tableCellAlign*</A> tag.
- <DT><B>~Z~</B></DT><DD>
- If the cell has an alignment or column span to be inserted,
- then this tag will be replaced with <A HREF="#_tableAttrDelimiter">_tableAttrDelimiter</A>. If
- the cell has neither, then it will be removed.
- </DL>
- </DL>
- <H3 ID="_tableCellMulticolClose">_tableCellMulticolClose</H3>
- <P>
- If the rule <A HREF="#tablecellmulticol">'tablecellmulticol'</A> is defined for a target, and a
- cell spans more than one column, then this tag will be used instead
- of <A HREF="#tableCellClose">tableCellClose</A>.
- </P>
- <DL>
- <DT>Macros:</DT><DD>
- None
- </DL>
- <H3 ID="tableCellHead">tableCellHead, tableTitleCellHead</H3>
- <P>
- 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.
- </P>
- <P>
- For example, the order of tags for a row with three cells may be
- <CODE>tableRowOpen</CODE>, <CODE>tableCellHead</CODE>, <CODE>tableCellHead</CODE>,
- <CODE>tableCellHead</CODE>, <CODE>tableCellOpen</CODE>, and so on.
- </P>
- <P>
- If <CODE>tableTitleCellHead</CODE> is defined, it will be used for cells in a
- title row, otherwise <CODE>tableCellHead</CODE> will be used for all rows.
- </P>
- <DL>
- <DT>Macros:</DT><DD>
- <DL>
- <DT><B>~A~</B></DT><DD>
- If the rule <A HREF="#tablecellaligntype">'tablecellaligntype'</A> is set to the value
- <A HREF="#cell">'cell'</A> for a target, then this will be replaced with the
- appropriate <A HREF="#_tableCellAlign">_tableCellAlign*</A> tag.
- <DT><B>~B~</B></DT><DD>
- If the table has a border, this will be replaced with the
- <A HREF="#_tableCellBorder">_tableCellBorder</A> tag, or removed if not.
- <DT><B>~S~</B></DT><DD>
- If the rule <A HREF="#tablecellspannable">'tablecellspannable'</A> is defined, and the cell
- spans multiple columns, then this tag will be replaced with the
- value of either <A HREF="#_tableCellColSpanChar">_tableCellColSpanChar</A> or
- <A HREF="#_tableCellColSpan">_tableCellColSpan</A> as appropriate.
- </DL>
- </DL>
- <H3 ID="tableCellAlign">tableCellAlignLeft, tableCellAlignRight, tableCellAlignCenter</H3>
- <P>
- 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.
- </P>
- <P>
- Note that these cells do not begin with an underscore. Do not get
- them confused with the <A HREF="#_tableCellAlign">_tableCellAlign*</A> tags, which replace
- macros within the other cell tags.
- </P>
- <DL>
- <DT>Macros:</DT><DD>
- <DL>
- <DT><B>\a</B></DT><DD>
- This will be replaced by the text of the cell itself.
- </DL>
- </DL>
- <H1 ID="chapter-Miscellaneous">7. Miscellaneous</H1>
- <P>
- These tags are useful or necessary for a fully implemented target,
- but did not fit well within the other categories.
- </P>
- <H2 ID="section-DocumentStructureandFormatting">7.1. Document Structure and Formatting</H2>
- <H3 ID="pageBreak">pageBreak</H3>
- <P>
- For targets that support separation into pages, this tag is used to
- force a page break in the output.
- </P>
- <H3 ID="bar1">bar1, bar2</H3>
- <P>
- These tags are used to insert a horizontal line in the output,
- usually used as a lesser section break without beginning a new
- section.
- </P>
- <P>
- <CODE>bar1</CODE> is considered a normal line, and <CODE>bar2</CODE> is considered a
- strong or thick line.
- </P>
- <P>
- If the rule <A HREF="#barinsidequote">'barinsidequote'</A> is defined, then a bar is allowed
- inside a block quote. Otherwise the block quote must be closed and
- reopened around the bar.
- </P>
- <P>
- If the rule <A HREF="#mapbar2pagebreak">'mapbar2pagebreak'</A> is defined, then the value of
- <CODE>bar2</CODE> is ignored and a <A HREF="#pageBreak">pageBreak</A> is emitted instead.
- </P>
- <DL>
- <DT>Macros:</DT><DD>
- <DL>
- <DT><B>\a</B></DT><DD>
- If this mark is present, it will be replaced with the text of
- the actual marks used for the bar in the source document.
- </DL>
- </DL>
- <H3 ID="EOD">EOD</H3>
- <P>
- This is the End Of Document tag, and is the very last thing emitted
- to the output.
- </P>
- <P>
- Any tags that were opened in the default <I>HEADER_TEMPLATE</I> should be
- closed in this tag.
- </P>
- <P>
- If the command line option <I>--template</I> is used, then this tag is
- not emitted. Anything necessary for a complete document should be
- included in the template.
- </P>
- <P>
- The default template can thus be considered: <I>HEADER_TEMPLATE</I> +
- <B>%%body</B> + <CODE>EOD</CODE>.
- </P>
- <H3 ID="bodyOpen">bodyOpen, bodyClose</H3>
- <P>
- These are the first and last tags emitted for the document body text
- itself. <CODE>bodyOpen</CODE> is emitted immediately after
- <I>HEADER_TEMPLATE</I> and <CODE>bodyClose</CODE> is immediately before <A HREF="#EOD">EOD</A>.
- </P>
- <H2 ID="section-HTML">7.2. HTML</H2>
- <H3 ID="cssOpen">cssOpen, cssClose</H3>
- <P>
- These tags are used to insert a stylesheet directly into the text of
- the output document itself.
- </P>
- <P>
- If the command line option <I>--css-inside</I> 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.
- </P>
- <P>
- Currently this option, and these tags, are only used by the HTML
- family of targets, are have no effect on any other target.
- </P>
- <H2 ID="section-Comments">7.3. Comments</H2>
- <H3 ID="comment">comment</H3>
- <P>
- 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.
- </P>
- <P>
- 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.
- </P>
- <DL>
- <DT>Macros:</DT><DD>
- <DL>
- <DT><B>\a</B></DT><DD>
- This is replaced with the text of the comment generated by
- Txt2tags.
- </DL>
- </DL>
- <H3 ID="blockComment">blockCommentOpen, blockCommentClose</H3>
- <P>
- These are intended to be used before and after multiline comments in
- the output.
- </P>
- <P>
- Currently, all comments in the source are ignored, so these tags are
- unused.
- </P>
- <H2 ID="section-TableOfContents">7.4. Table Of Contents</H2>
- <P>
- The automatic table of contents is emitted as a <A HREF="#chapter-Lists">list</A>, with each
- list item corresponding to a <A HREF="#title1">title*</A> within the document. Lower
- level titles will be emitted as nested lists.
- </P>
- <P>
- 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.
- </P>
- <P>
- If the rule <A HREF="#autotocwithbars">'autotocwithbars'</A> is defined, then a <A HREF="#bar1">bar1</A> will be
- added before and after the table of contents.
- </P>
- <P>
- If the rule <A HREF="#blankendautotoc">'blankendautotoc'</A> is defined, then an extra blank line
- will be added after the table of contents.
- </P>
- <P>
- If the rule <A HREF="#autotocnewpagebefore">'autotocnewpagebefore'</A> is defined, then a
- <A HREF="#pageBreak">pageBreak</A> will be emitted before the table of contents.
- </P>
- <P>
- If the rule <A HREF="#autotocnewpageafter">'autotocnewpageafter'</A> is defined, then a
- <A HREF="#pageBreak">pageBreak</A> will be emitted after the table of contents.
- </P>
- <H3 ID="tocOpen">tocOpen, tocClose</H3>
- <P>
- These tags will be emitted directly before and after the
- automatically generated table of contents.
- </P>
- <H3 ID="TOC">TOC</H3>
- <P>
- 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.
- </P>
- <H1 ID="Appendix">Appendix: Rules</H1>
- <H3 ID="linkable">linkable</H3>
- <P>
- This target supports external links.
- </P>
- <P>
- It affects the output of <A HREF="#url">url</A>, <A HREF="#urlMark">urlMark</A>, <A HREF="#urlMarkAnchor">urlMarkAnchor</A>,
- <A HREF="#email">email</A>, <A HREF="#emailMark">emailMark</A>.
- </P>
- <H3 ID="tableable">tableable</H3>
- <P>
- This target supports tables. If this is not defined, then all tags
- in the <A HREF="#chapter-Tables">Table</A> section are ignored.
- </P>
- <H3 ID="imglinkable">imglinkable</H3>
- <P>
- This target supports images as links.
- </P>
- <P>
- It may affect the output of <A HREF="#url">url</A> and <A HREF="#img">img</A>.
- </P>
- <H3 ID="imgalignable">imgalignable</H3>
- <P>
- This target supports image alignment. If it is not defined, then all
- <A HREF="#_imgAlign">_imgAlign</A> and <A HREF="#imgAlign">imgAlign</A> tags are ignored.
- </P>
- <P>
- It affects the output of <A HREF="#img">img</A>.
- </P>
- <H3 ID="imgasdefterm">imgasdefterm</H3>
- <P>
- This target supports images as definition terms.
- </P>
- <P>
- It may affect the output of <A HREF="#deflistItem1Open">deflistItem1Open</A>.
- </P>
- <H3 ID="autonumberlist">autonumberlist</H3>
- <P>
- This target supports numbered lists natively. If this is defined,
- then numbers will not be generated by Txt2tags for numbered lists.
- </P>
- <P>
- It affects the output of <A HREF="#numlistItemOpen">numlistItemOpen</A>.
- </P>
- <H3 ID="autonumbertitle">autonumbertitle</H3>
- <P>
- This target supports numbered titles natively. If this is defined,
- then numbers will not be generated by Txt2tags for numbered titles.
- </P>
- <P>
- It affects the output of <A HREF="#numtitle1">numtitle*</A>.
- </P>
- <H3 ID="stylable">stylable</H3>
- <P>
- This target supports external style files. If this is defined, then
- the <B>%(STYLE)s</B> macros may be expanded. Otherwise style
- definitions are ignored.
- </P>
- <P>
- It affects the output of the <A HREF="#section-Template">Template</A>
- </P>
- <H3 ID="parainsidelist">parainsidelist</H3>
- <P>
- This target supports paragraph tags inside lists. If this is
- defined, then <A HREF="#paragraphOpen">paragraphOpen</A> and <A HREF="#paragraphClose">paragraphClose</A> tags may be
- inserted into <A HREF="#chapter-Lists">lists</A>.
- </P>
- <H3 ID="compactlist">compactlist</H3>
- <P>
- This target has separate enclosing tags for compact lists. If this
- is not defined, then <A HREF="#listCompactOpen">listCompactOpen</A>, <A HREF="#numlistCompactOpen">numlistCompactOpen</A>,
- and <A HREF="#deflistCompactOpen">deflistCompactOpen</A> are ignored.
- </P>
- <H3 ID="spacedlistitem">spacedlistitem</H3>
- <P>
- This target supports blank lines between items in lists.
- </P>
- <P>
- This rule is currently unused and ignored.
- </P>
- <H3 ID="listnotnested">listnotnested</H3>
- <P>
- This target does not support nested lists.
- </P>
- <P>
- If this is defined, then all lists are emitted as a single,
- top-level list. It affects the output of <A HREF="#chapter-Lists">lists</A>.
- </P>
- <H3 ID="listitemnotnested">listitemnotnested</H3>
- <P>
- This target does not allow nested lists to be inside a list
- item.
- </P>
- <P>
- 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
- <A HREF="#chapter-Lists">lists</A>.
- </P>
- <H3 ID="quotenotnested">quotenotnested</H3>
- <P>
- This target does not support nested quotes.
- </P>
- <P>
- If this is defines, all block quotations are emitted at the same,
- top level. If affects the output of <A HREF="#section-BlockQuotations">block quotes</A>.
- </P>
- <H3 ID="verbblocknotescaped">verbblocknotescaped</H3>
- <P>
- This target should not run verbatim blocks through <I>doEscape()</I>.
- </P>
- <P>
- It affects the output of <A HREF="#section-VerbatimBlocks">verbatim blocks</A>.
- </P>
- <H3 ID="verbblockfinalescape">verbblockfinalescape</H3>
- <P>
- This target <I>should</I> run verbatim blocks through
- <I>doFinalEscape()</I>.
- </P>
- <P>
- It affects the output of <A HREF="#section-VerbatimBlocks">verbatim blocks</A>.
- </P>
- <H3 ID="escapeurl">escapeurl</H3>
- <P>
- This target should run <B>URLs</B> through <I>doEscape()</I>.
- </P>
- <P>
- It affects the output of <A HREF="#url">url</A>, <A HREF="#urlMark">urlMark</A>, <A HREF="#urlMarkAnchor">urlMarkAnchor</A>,
- <A HREF="#email">email</A>, and <A HREF="#emailMark">emailMark</A>.
- </P>
- <H3 ID="labelbeforelink">labelbeforelink</H3>
- <P>
- For this target, labels should come before the link in a <B>URL</B>.
- </P>
- <P>
- It affects the output of <A HREF="#urlMark">urlMark</A>, <A HREF="#urlMarkAnchor">urlMarkAnchor</A>, and
- <A HREF="#emailMark">emailMark</A>.
- </P>
- <H3 ID="onelinepara">onelinepara</H3>
- <P>
- This target should emit paragraphs as a single long line.
- </P>
- <P>
- It affects the output of <A HREF="#section-Paragraphs">paragraphs</A>.
- </P>
- <H3 ID="tabletitlerowinbold">tabletitlerowinbold</H3>
- <P>
- This target should manually emit table title rows in bold face.
- </P>
- <P>
- It affects the output of <A HREF="#section-Cells">table cells</A>.
- </P>
- <H3 ID="tablecellstrip">tablecellstrip</H3>
- <P>
- This target should strip extra spaces from each table cell.
- </P>
- <P>
- It affects the output of <A HREF="#section-Cells">table cells</A>.
- </P>
- <H3 ID="tablecellspannable">tablecellspannable</H3>
- <P>
- This target supports the span attribute in table cells.
- </P>
- <P>
- It may affect the output of <A HREF="#tableCellOpen">tableCellOpen</A>, <A HREF="#tableCellClose">tableCellClose</A>,
- and <A HREF="#tableCellHead">tableCellHead</A>.
- </P>
- <H3 ID="tablecellmulticol">tablecellmulticol</H3>
- <P>
- This target has separate open and close tags for multicolumn cells.
- </P>
- <P>
- If it is defined, then <A HREF="#_tableCellMulticolOpen">_tableCellMulticolOpen</A> will be used for
- multicolumn cells instead of <A HREF="#tableCellOpen">tableCellOpen</A>.
- </P>
- <H3 ID="barinsidequote">barinsidequote</H3>
- <P>
- This target allows horizontal bars inside block quotes.
- </P>
- <P>
- It affects the output of <A HREF="#section-BlockQuotations">block quotes</A>,
- and uses <A HREF="#bar1">bar1</A>.
- </P>
- <H3 ID="finalescapetitle">finalescapetitle</H3>
- <P>
- This target should run the text of titles through
- <I>doFinalEscape()</I>
- </P>
- <P>
- It affects the output of <A HREF="#chapter-TitlesandSections">titles</A>.
- </P>
- <H3 ID="autotocnewpagebefore">autotocnewpagebefore</H3>
- <P>
- This target should emit a <A HREF="#pageBreak">pageBreak</A> before the automatic Table
- of Contents.
- </P>
- <H3 ID="autotocnewpageafter">autotocnewpageafter</H3>
- <P>
- This target should emit a <A HREF="#pageBreak">pageBreak</A> after the automatic Table
- of Contents.
- </P>
- <H3 ID="autotocwithbars">autotocwithbars</H3>
- <P>
- This target should emit a <A HREF="#bar1">bar1</A> before and after the automatic
- Table of Contents.
- </P>
- <H3 ID="mapbar2pagebreak">mapbar2pagebreak</H3>
- <P>
- This target should use a <A HREF="#pageBreak">pageBreak</A> instead of <A HREF="#bar1">bar2</A>. If
- it is defined, the anything defined for <CODE>bar2</CODE> is ignored.
- </P>
- <H3 ID="titleblocks">titleblocks</H3>
- <P>
- This target uses title and section blocks.
- </P>
- <P>
- If it is defined, then <A HREF="#title1">title*</A> tags are ignored. Instead
- <A HREF="#title1open">title*Open</A> and <A HREF="#blockTitle1Open">blockTitle*Open</A> tags
- will be used to set off titles and sections.
- </P>
- <P>
- This affects the output of <A HREF="#chapter-TitlesandSections">titles</A>.
- </P>
- <H3 ID="listlineafteropen">listlineafteropen</H3>
- <P>
- This target should emit <A HREF="#listItemLine">listItemLine</A> after <A HREF="#listItemOpen">listItemOpen</A>.
- </P>
- <H3 ID="escapexmlchars">escapexmlchars</H3>
- <P>
- This target should escape the XML special characters: < > &
- </P>
- <H3 ID="listlevelzerobased">listlevelzerobased</H3>
- <P>
- This target should start list levels at 0 when encoding the level
- into list tags.
- </P>
- <P>
- It affects the output of <A HREF="#listItemOpen">listItemOpen</A>, <A HREF="#numlistItemOpen">numlistItemOpen</A>, and
- <A HREF="#deflistItemOpen">deflistItemOpen</A>.
- </P>
- <H3 ID="zerodepthparagraph">zerodepthparagraph</H3>
- <P>
- For this target, non-nested paragraphs should have block depth of 0
- instead of 1 when the block depth is encoded into the output.
- </P>
- <P>
- This affects the output of <A HREF="#paragraphOpen">paragraphOpen</A>.
- </P>
- <H3 ID="cellspancumulative">cellspancumulative</H3>
- <P>
- For this target, cell span values add up for each cell of a row.
- </P>
- <P>
- It affects the output of <A HREF="#_tableCellColSpan">_tableCellColSpan</A>, and from that it may
- affect the output of <A HREF="#tableCellOpen">tableCellOpen</A>, <A HREF="#tableCellClose">tableCellClose</A>,
- <A HREF="#tableCellHead">tableCellHead</A>, and <A HREF="#_tableCellMulticolOpen">_tableCellMulticolOpen</A>.
- </P>
- <H3 ID="keepblankheaderline">keepblankheaderline</H3>
- <P>
- For this target, template lines are not removed if the macros being
- inserted are blank.
- </P>
- <P>
- This affects the output of <A HREF="#section-Template">the template</A>.
- </P>
- <H3 ID="indentverbblock">indentverbblock</H3>
- <P>
- This target should add leading spaces to verb block lines.
- </P>
- <P>
- It affects the output of <A HREF="#section-VerbatimBlocks">verbatim blocks</A>.
- </P>
- <H3 ID="breaktablecell">breaktablecell</H3>
- <P>
- This target should insert line breaks after every table cell.
- </P>
- <P>
- If affects the output of <A HREF="#section-Cells">table cells</A>.
- </P>
- <H3 ID="breaktablelineopen">breaktablelineopen</H3>
- <P>
- This target should insert a line break after <A HREF="#tableRowOpen">tableRowOpen</A> and
- <A HREF="#tableTitleRowOpen">tableTitleRowOpen</A>.
- </P>
- <H3 ID="notbreaklistopen">notbreaklistopen</H3>
- <P>
- This target should <I>not</I> insert a line break after <A HREF="#listOpen">listOpen</A>,
- <A HREF="#numlistOpen">numlistOpen</A> or <A HREF="#deflistOpen">deflistOpen</A>.
- </P>
- <H3 ID="keepquoteindent">keepquoteindent</H3>
- <P>
- This target should not remove the leading TABs in block quotes.
- </P>
- <P>
- It affects the output of <A HREF="#section-BlockQuotations">block quotations</A>.
- </P>
- <H3 ID="keeplistindent">keeplistindent</H3>
- <P>
- This target should not remove the leading spaces on list tags.
- </P>
- <P>
- It affects the output of all tags for <A HREF="#chapter-Lists">lists</A>.
- </P>
- <H3 ID="blankendautotoc">blankendautotoc</H3>
- <P>
- This target should append a blank line at the end of the automatic
- Table of Contents.
- </P>
- <H3 ID="tagnotindentable">tagnotindentable</H3>
- <P>
- For this target, tags must be placed at the line beginning.
- </P>
- <P>
- If affects the tags for <A HREF="#section-BlockQuotations">block quotes</A> and
- <A HREF="#chapter-Lists">lists</A>.
- </P>
- <H3 ID="spacedlistitemopen">spacedlistitemopen</H3>
- <P>
- This target should append a space after <A HREF="#listItemOpen">listItemOpen</A>.
- </P>
- <H3 ID="spacednumlistitemopen">spacednumlistitemopen</H3>
- <P>
- This target should append a space after <A HREF="#numlistItemOpen">numlistItemOpen</A>.
- </P>
- <H3 ID="deflisttextstrip">deflisttextstrip</H3>
- <P>
- This target should strip the whitespace off of the definition list
- text.
- </P>
- <P>
- It affects the output of <A HREF="#section-DefinitionLists">definition lists</A>.
- </P>
- <H3 ID="blanksaroundpara">blanksaroundpara</H3>
- <P>
- This target should put a blank line before and after paragraphs.
- </P>
- <P>
- It affects the output of <A HREF="#section-Paragraphs">paragraphs</A>.
- </P>
- <H3 ID="blanksaroundverb">blanksaroundverb</H3>
- <P>
- This target should put a blank line before and after verb blocks.
- </P>
- <P>
- It affects the output of <A HREF="#section-VerbatimBlocks">verbatim blocks</A>.
- </P>
- <H3 ID="blanksaroundquote">blanksaroundquote</H3>
- <P>
- This target should put a blank line before and after quotes.
- </P>
- <P>
- It affects the output of <A HREF="#section-BlockQuotations">block quotations</A>.
- </P>
- <H3 ID="blanksaroundlist">blanksaroundlist</H3>
- <P>
- This target should put a blank line before and after lists.
- </P>
- <P>
- It affects the output of <A HREF="#section-UnorderedLists">regular lists</A>.
- </P>
- <H3 ID="blanksaroundnumlist">blanksaroundnumlist</H3>
- <P>
- This target should put a blank line before and after numbered lists.
- </P>
- <P>
- It affects the output of [numbered lists [#section-NumberedLists].
- </P>
- <H3 ID="blanksarounddeflist">blanksarounddeflist</H3>
- <P>
- This target should put a blank line before and after definition
- lists.
- </P>
- <P>
- It affects the output of [definition lists [#section-DefinitionLists].
- </P>
- <H3 ID="blanksaroundnestedlist">blanksaroundnestedlist</H3>
- <P>
- This target should put a blank line before and after all types of
- nested lists.
- </P>
- <P>
- It affects the output of all <A HREF="#chapter-Lists">lists</A>.
- </P>
- <H3 ID="blanksaroundtable">blanksaroundtable</H3>
- <P>
- This target should put a blank line before and after tables.
- </P>
- <P>
- It affects the output of <A HREF="#chapter-Tables">tables</A>.
- </P>
- <H3 ID="blanksaroundbar">blanksaroundbar</H3>
- <P>
- This target should put a blank line before and after horizontal
- lines.
- </P>
- <P>
- It affects the output of <A HREF="#bar1">bar1 and bar2</A>.
- </P>
- <H3 ID="blanksaroundtitle">blanksaroundtitle</H3>
- <P>
- This target should put a blank line before and after titles.
- </P>
- <P>
- It affects the output of <A HREF="#title1">title*</A> and <A HREF="#title1open">title*Open</A>.
- </P>
- <H3 ID="blanksaroundnumtitle">blanksaroundnumtitle</H3>
- <P>
- This target should put a blank line before and after numbered
- titles.
- </P>
- <P>
- If affects the output of <A HREF="#numtitle1">numtitle*</A>.
- </P>
- <H3 ID="listmaxdepth">listmaxdepth</H3>
- <P>
- This is a value rule defining the maximum nesting depth for lists.
- </P>
- <P>
- It affects the output of <A HREF="#chapter-Lists">lists</A>.
- </P>
- <H3 ID="quotemaxdepth">quotemaxdepth</H3>
- <P>
- This is a value rule defining the maximum nesting depth for block
- quotes.
- </P>
- <P>
- It affects the output of <A HREF="#section-BlockQuotations">block quotations</A>.
- </P>
- <H3 ID="tablecellaligntype">tablecellaligntype</H3>
- <P>
- This is a value rule defining the type of alignment allowed for
- tables cells. The legal values are 'cell' or 'column'.
- </P>
- <P>
- Its value affects whether <A HREF="#_tableColAlign">_tableColAlign*</A> or
- <A HREF="#_tableCellAlign">_tableCellAlign*</A> tags are used.
- </P>
- <P>
- It may affect the output of <A HREF="#tableOpen">tableOpen</A>, <A HREF="#tableRowOpen">tableRowOpen</A>,
- <A HREF="#tableRowSep">tableRowSep</A>, <A HREF="#tableCellOpen">tableCellOpen</A>, <A HREF="#_tableCellMulticolOpen">_tableCellMulticolOpen</A>,
- <A HREF="#tableCellHead">tableCellHead</A>, and other related tags.
- </P>
- <H3 ID="blockdepthmultiply">blockdepthmultiply</H3>
- <P>
- This value rule changes the value of a blocks depth value, for
- targets that encode depth into the output tags.
- </P>
- <P>
- It may affect the output of <A HREF="#paragraphOpen">paragraphOpen</A>, <A HREF="#blockQuoteOpen">blockQuoteOpen</A>,
- <A HREF="#listItemOpen">listItemOpen</A>, <A HREF="#numlistItemOpen">numlistItemOpen</A>, and <A HREF="#deflistItemOpen">deflistItemOpen</A>.
- </P>
- <H3 ID="depthmultiplyplus">depthmultiplyplus</H3>
- <P>
- This value rule is added to add to the block depth before
- multiplying by 'blockdepthmultiply'.
- </P>
- <P>
- It may affect the output of <A HREF="#paragraphOpen">paragraphOpen</A>, <A HREF="#blockQuoteOpen">blockQuoteOpen</A>,
- <A HREF="#listItemOpen">listItemOpen</A>, <A HREF="#numlistItemOpen">numlistItemOpen</A>, and <A HREF="#deflistItemOpen">deflistItemOpen</A>.
- </P>
- <H3 ID="cellspanmultiplier">cellspanmultiplier</H3>
- <P>
- This value rule changes the value of a table cell span.
- </P>
- <P>
- It affects the output of <A HREF="#_tableCellColSpan">_tableCellColSpan</A>, and from that may
- affect the output of <A HREF="#tableCellOpen">tableCellOpen</A>, <A HREF="#tableCellClose">tableCellClose</A>,
- <A HREF="#_tableCellMulticolOpen">_tableCellMulticolOpen</A> and <A HREF="#tableCellHead">tableCellHead</A>.
- </P>
- <!-- html code generated by txt2tags 2.6.668 (http://txt2tags.org) -->
- <!-- cmdline: txt2tags -t html doc/English/tags-reference.t2t -->
- </BODY></HTML>