tags-reference.html | searchcode

/doc/English/tags-reference.html

Large files files are truncated, but you can click here to view the full file
   1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
   2<HTML>
   3<HEAD>
   4<META NAME="generator" CONTENT="http://txt2tags.org">
   5<TITLE>All TAGS Reference</TITLE>
   6</HEAD><BODY BGCOLOR="white" TEXT="black">
   7<CENTER>
   8<H1>All TAGS Reference</H1>
   9</CENTER>
  10
  11
  12<H1 ID="Introduction">Introduction</H1>
  13
  14<P>
  15This document is a reference for all available TAGS available to
  16developers for adding new targets, as found in the <I>getTags()</I> function.
  17It is intended for <B>advanced users</B> and <B>developers</B> who wish to
  18add a new target to Txt2tags without needing to know the source code
  19in detail.
  20</P>
  21<P>
  22This reference will describe all available tags, including how and
  23where they will appear in the final tagged document, how the various
  24rules in the <I>getRules()</I> function affect them, and what special
  25characters and macros are expanded in the output.
  26</P>
  27<P>
  28Txt2tags has fairly complex rules and gotchas, and it can be
  29difficult searching through the entire source code to see exactly
  30what each tag does. Often, when creating a new target, a developer
  31is surprised when the output is not quite how it was expected to be,
  32and in particular that certain tags did not behave as expected. It
  33is hoped that this reference will make it easier to create new
  34targets with fewer bugs and surprises, so txt2tags can continue to
  35grow as "one source, many targets".
  36</P>
  37
  38<H1 ID="chapter-ThePartsofaDocument">1. The Parts of a Document</H1>
  39
  40<P>
  41Before looking at the individual tags, it is important to understand
  42exactly how the different parts of a document fit together.
  43</P>
  44<P>
  45A document is built from a <B>template</B>, which is filled with the
  46document's <B>headers</B>, <B>body</B>, and an optional <B>table of contents</B>.
  47</P>
  48
  49<H2 ID="section-Template">1.1. Template</H2>
  50
  51<P>
  52The template of a document consists of the basic opening and closing
  53markup that all examples of that type of file must have. All
  54supported targets have a default template included in the source
  55code, in the <I>HEADER_TEMPLATE</I> area. Alternatively, the user may
  56use a custom header using the <I>--template</I> command line option.
  57</P>
  58<P>
  59Templates should make use of the <B>%(HEADER1)s</B>, <B>%(HEADER2)s</B>,
  60and <B>%(HEADER3)s</B> macros, as well as <B>%(ENCODING)s</B> and
  61<B>%(STYLE)s</B> if the target supports character encodings and
  62external stylesheets. These macros will be replaced with the
  63appropriate values from the source document. If any value is blank,
  64the entire line including the macro is removed unless the target has
  65included the rule <A HREF="#keepblankheaderline">'keepblankheaderline'</A>.
  66</P>
  67<P>
  68It is not required, but by convention <B>HEADER1</B> refers to the title,
  69<B>HEADER2</B> to the author, and <B>HEADER3</B> to the date the document was
  70created. Several targets reflect this convention in their use of the
  71<B>HEADER</B> metadata in their default templates.
  72</P>
  73<P>
  74Custom templates must also include the <B>%(BODY)s</B> macro, which
  75will be expanded to the fully tagged body of the document. The
  76default template should not include this, as it is automatically
  77added to the end of the <I>HEADER_TEMPLATE</I> text.
  78</P>
  79
  80<H2 ID="section-BodyText">1.2. Body Text</H2>
  81
  82<P>
  83The body of a document consists of the fully tagged text converted
  84from the original source document. It is nothing more or less than
  85the original document with all txt2tags markup removed, and replaced
  86with the target-specific markup. All of the tags from <I>getTags()</I>
  87end up in this section, along with all user text.
  88</P>
  89<P>
  90The document is parsed into blocks, and each block is processed line
  91by line. Note that this seraration of lines is kept throughout the
  92process, and in nearly all cases the final tagged text is broken in
  93the same locations as the original. This is important to remember,
  94as several tags depend on this line by line behaviour, and their
  95output changes that line it self, not the block.
  96</P>
  97
  98<H2 ID="section-TableofContents">1.3. Table of Contents</H2>
  99
 100<P>
 101Txt2tags is able to add a table of contents to the output document.
 102If the target supports creating a table of contents itself, Txt2tags
 103can take advantage of that. Otherwise, Txt2tags can generate a table
 104of contents automatically and insert it where appropriate.
 105</P>
 106<P>
 107If the command line option <I>--toc</I> is used, Txt2tags will add a
 108table of contents to the output. If the command line option
 109<I>--toc-only</I> is used, then the table of contents will be the only
 110thing output, and the rest of the body text will not.
 111</P>
 112<P>
 113By default, the table of contents will be emitted as the first text
 114in the body of the document. That is, it will be emitted directly
 115after <A HREF="#bodyOpen">bodyOpen</A> and before the main text. If this is not
 116appropriate, the user can insert the <B>%%toc</B> macro into the source
 117text, and it will be emitted there instead.
 118</P>
 119<P>
 120Full details on how the table of contents is emitted is given in the
 121section on the Table of Contents tags.
 122</P>
 123
 124<H2 ID="section-Escapes">1.4. Escapes</H2>
 125
 126<P>
 127One final note, though this is not really part of the document
 128structures. Most text is processed throught the functions
 129<I>doEscape()</I> and <I>doFinalEscape()</I> before being emitted in the
 130final output. This is used to allow certain characters that may give
 131problems in Txt2tags, such as backslashes or characters that are the
 132same as Txt2tags markup.
 133</P>
 134<P>
 135The emitted tags are not processed by these functions at all. Some
 136tags also prevent parts of the text from being processed by these
 137functions. The reference will note when this is the case.
 138</P>
 139
 140<H1 ID="chapter-BasicBlocks">2. Basic Blocks</H1>
 141
 142<H2 ID="section-Paragraphs">2.1. Paragraphs</H2>
 143
 144<P>
 145Paragraphs are the most common, and most basic of all text blocks.
 146They are the simple, regular body text of the document.
 147</P>
 148<P>
 149If the rule <A HREF="#blanksaroundpara">'blanksaroundpara'</A> is defined, an empty line will be
 150emitted before and after the paragraph and tags.
 151</P>
 152<P>
 153If the rule <A HREF="#onelinepara">'onelinepara'</A> is defined, the paragraph text will have
 154all newlines removed and replaced with spaces, emitting the
 155paragraph as a single line.
 156</P>
 157
 158<H3 ID="paragraphOpen">paragraphOpen</H3>
 159
 160<P>
 161This tag is emitted, on its own line, before each paragraph of body
 162text. If this tag (and <A HREF="#paragraphClose">paragraphClose</A>) are not defined for a
 163target, the body text is simply printed as unadorned plain text,
 164much like the source document.
 165</P>
 166
 167<DL>
 168<DT>Macros:</DT><DD>
 169  <DL>
 170  <DT><B>~D~</B></DT><DD>
 171    If this macro is included in the tag, it will be expanded to the
 172    value of the depth of that particular paragraph. Most paragraphs
 173    have depth '1', pargraphs inside a top-level list will have
 174    depth level '2', and so on.
 175  <P></P>
 176    If the rule <A HREF="#blockdepthmultiply">'blockdepthmultiply'</A> is defined for the target,
 177    the depth value will be multiplied by that amount before being
 178    emitted. If the rule <A HREF="#depthmultiplyplus">'depthmultiplyplus'</A> is defined, then that
 179    value will be added to the depth before multiplying by
 180    <A HREF="#blockdepthmultiply">'blockdepthmultiply'</A>, but only if used with
 181    <A HREF="#blockdepthmultiply">'blockdepthmultiply'</A>.
 182  <P></P>
 183    If the rule <A HREF="#zerodepthpara">'zerodepthpara'</A> is defined, then top-level
 184    paragraphs (those not nested inside a list) will always have
 185    <B>~D~</B> replaced with '0', regardless of the other rules.
 186  </DL>
 187</DL>
 188
 189<H3 ID="paragraphClose">paragraphClose</H3>
 190
 191<P>
 192This tag is emitted, on its own line, after each paragraph of body
 193text.
 194</P>
 195
 196<DL>
 197<DT>Macros</DT><DD>
 198  None
 199</DL>
 200
 201<H2 ID="section-BlockQuotations">2.2. Block Quotations</H2>
 202
 203<P>
 204Block quotes are paragraphs that are set apart from regular
 205paragraphs, usually to show that they are quoted from some external
 206source.
 207</P>
 208<P>
 209Note that, at this time, Txt2tags is not able to emit multiple
 210paragraphs within a single block quote. Each separate paragraph
 211will be emitted as a separate block quote with Open and Close tags.
 212</P>
 213<P>
 214Nested block quotes are allowed, unless the rule <A HREF="#quotenotnested">'quotenotnested'</A>
 215is defined for the target.
 216</P>
 217<P>
 218If the rule <A HREF="#keepquoteindent">'keepquoteindent'</A> is defined, then each line of the
 219block quote will have tab characters added before the text equal to
 220the depth of that quote.
 221</P>
 222<P>
 223If the rule <A HREF="#blanksaroundquote">'blanksaroundquote'</A> is defined, an extra blank line is
 224emitted before and after the block quote.
 225</P>
 226
 227<H3 ID="blockQuoteOpen">blockQuoteOpen</H3>
 228
 229<P>
 230This tag is emitted, on its own line, before each paragraph of a
 231block quote.
 232</P>
 233<P>
 234The block depth is given by a number of tab characters.
 235<CODE>blockQuoteOpen</CODE> will have these tabs inserted before the tag,
 236unless the rule <A HREF="#tagnotindentable">'tagnotindentable'</A> is defined.
 237</P>
 238
 239<DL>
 240<DT>Macros:</DT><DD>
 241  <DL>
 242  <DT><B>~D~</B></DT><DD>
 243    If this macro is included in the tag, it will be expanded to the
 244    value of the depth of that particular block quote paragraph. The
 245    first Block Quote has a depth level of '1'. A quote nested
 246    within the first will have a depth of '2', and so on.
 247  <P></P>
 248    If the rule <A HREF="#blockdepthmultiply">'blockdepthmultiply'</A> is defined for the target,
 249    the depth value will be multiplied by that amount before being
 250    emitted. If the rule <A HREF="#depthmultiplyplus">'depthmultiplyplus'</A> is defined, then that
 251    value will be added to the depth before multiplying by
 252    <A HREF="#blockdepthmultiply">'blockdepthmultiply'</A>, but only if used with
 253    <A HREF="#blockdepthmultiply">'blockdepthmultiply'</A>.
 254  </DL>
 255</DL>
 256
 257<H3 ID="blockQuoteLine">blockQuoteLine</H3>
 258
 259<P>
 260If this tag is present, it will be added before each line of the
 261block quote.
 262</P>
 263<P>
 264This tag is emitted multiple times for nested quotes, one copy of
 265the tag for each level of depth. For example, if the quote is
 266defined as '*', then for a third-level nested quote each line
 267will begin with '***'.
 268</P>
 269<P>
 270If the rule <A HREF="#keepquoteindent">'keepquoteindent'</A> is defined, all copies of this tag
 271are emitted after the tab characters and before the quote text.
 272</P>
 273
 274<DL>
 275<DT>Macros:</DT><DD>
 276  None
 277</DL>
 278
 279<H3 ID="blockQuoteClose">blockQuoteClose</H3>
 280
 281<P>
 282This tag is emitted, on its own line, at the end of each block
 283quote.
 284</P>
 285<P>
 286The block depth is given by a number of tab characters.
 287<CODE>blockQuoteClose</CODE> will have these tabs inserted before the tag,
 288unless the rule <A HREF="#tagnotindentable">'tagnotindentable'</A> is defined.
 289</P>
 290
 291<DL>
 292<DT>Macros:</DT><DD>
 293  None
 294</DL>
 295
 296<H2 ID="section-VerbatimBlocks">2.3. Verbatim Blocks</H2>
 297
 298<P>
 299Verbatim blocks are used when the user needs to keep control over
 300the spaces and line breaks of a block of text. Verbatim blocks are
 301usually emitted in a monospace font, and all spaces and line breaks
 302will be the same as in the source text. It is commonly used for
 303ASCII art and for source code listings.
 304</P>
 305<P>
 306Note that this is not the same as raw text. Raw text blocks are
 307emitted exactly as they are in the source text, with no processing.
 308Verbatim blocks are processed, and are emitted so that they
 309<I>appear</I> the same as in the source text.
 310</P>
 311<P>
 312By default, verbatim blocks are passed through <I>doEscape()</I> but
 313not <I>doFinalEscape()</I>. If the rule <A HREF="#verbblocknotescaped">'verbblocknotescaped'</A> is
 314defined, the text will not be passed through <I>doEscape()</I>. If the
 315rule <A HREF="#verbblockfinalescape">'verbblockfinalescape'</A> is defined, then the text will be be
 316passed through <I>doFinalEscape()</I>.
 317</P>
 318<P>
 319If the rule <A HREF="#indentverbblock">'indentverbblock'</A> is defined, then each line of the
 320text will be emitted with two spaces inserted before the text.
 321</P>
 322<P>
 323If the rule <A HREF="#blanksaroundverb">'blanksaroundverb'</A> is defined, an extra blank line
 324will be emitted before and after the verbatim block.
 325</P>
 326<P>
 327Note that the entire verbatim area is emitted as a single block.
 328Blank lines within a verbatim block do not separate paragraphs.
 329</P>
 330
 331<H3 ID="blockVerbOpen">blockVerbOpen</H3>
 332
 333<P>
 334This tag is emitted, on its own line, before each block of verbatim
 335text.
 336</P>
 337
 338<DL>
 339<DT>Macros:</DT><DD>
 340  None
 341</DL>
 342
 343<H3 ID="blockVerbLine">blockVerbLine</H3>
 344
 345<P>
 346This tag is emitted before each line of text in the verbatim block.
 347Some targets require this to keep the entire verbatim block
 348together, or to maintain formatting.
 349</P>
 350<P>
 351If the rule <A HREF="#indentverbblock">'indentverbblock'</A> is defined, this tag is emitted
 352after the spaces used for the indent, before the block text.
 353</P>
 354
 355<DL>
 356<DT>Macros:</DT><DD>
 357  None
 358</DL>
 359
 360<H3 ID="blockVerbSep">blockVerbSep</H3>
 361
 362<P>
 363This tag is emitted, on a line by itself, in between each line of
 364text in the verbatim block.
 365</P>
 366
 367<DL>
 368<DT>Macros:</DT><DD>
 369  None
 370</DL>
 371
 372<H3 ID="blockVerbClose">blockVerbClose</H3>
 373
 374<P>
 375This tag is emitted, on its own line, after each block of verbatim
 376text.
 377</P>
 378
 379<DL>
 380<DT>Macros:</DT><DD>
 381  None
 382</DL>
 383
 384<H1 ID="chapter-InlineTags">3. Inline Tags</H1>
 385
 386<P>
 387These tags are used to add additional formatting to text within the
 388basic blocks. They are useable within regular paragraphs and block
 389quotes, and unless otherwise noted, within lists and tables as
 390well.
 391</P>
 392<P>
 393All of these tags are inline, meaning that they do not begin or end
 394blocks and do not add or remove lines of text.
 395</P>
 396
 397<H2 ID="section-TextBeautifiers">3.1. Text Beautifiers</H2>
 398
 399<P>
 400These are the simple tags used to change how text appears in the
 401final output.
 402</P>
 403<P>
 404None of these tags use any special macros.
 405</P>
 406
 407<H3 ID="fontItalic">fontItalicOpen, fontItalicClose</H3>
 408
 409<P>
 410These tags are emitted, respectively, immediately before and after
 411some text that should appear in <I>italics</I> for emphasis.
 412</P>
 413
 414<H3 ID="fontBold">fontBoldOpen, fontBoldClose</H3>
 415
 416<P>
 417These tags are emitted, respectively, immediately before and after
 418some text that should appear in <B>bold</B> for strong emphasis.
 419</P>
 420
 421<H3 ID="fontUnderline">fontUnderlineOpen, fontUnderlineClose</H3>
 422
 423<P>
 424These tags are emitted, respectively, immediately before and after
 425some text that should appear <U>underlined</U>.
 426</P>
 427
 428<H3 ID="fontStrike">fontStrikeOpen, fontStrikeClose</H3>
 429
 430<P>
 431These tags are emitted, respectively, immediately before and after
 432some text that should appear <S>struck out</S>.
 433</P>
 434
 435<H3 ID="fontMono">fontMonoOpen, fontMonoClose</H3>
 436
 437<P>
 438These tags are emitted, respectively, immediately before and after
 439some text that should appear in a <CODE>monospaced</CODE> font, such as
 440inline source code.
 441</P>
 442
 443<H2 ID="section-Links">3.2. Links</H2>
 444
 445<P>
 446These tags are used to insert links to external files, pages, or
 447resources, as well as internal links within the document itself.
 448</P>
 449<P>
 450The link text itself is a <B>url</B>. Ordinarily, urls are not escaped
 451so as to preserve all characters within it exactly as typed. It the
 452rule <A HREF="#escapeurl">'escapeurl'</A> is defined for a target, the url will be passed
 453through <I>doEscape()</I> after all. Additionally, if the rule
 454<A HREF="#linkable">'linkable'</A> is not defined, signalling that this target does not
 455support true links, then the url will be escaped as well.
 456</P>
 457
 458<H3 ID="url">url</H3>
 459
 460<P>
 461This tag is used to insert a bare url without a label.
 462</P>
 463
 464<DL>
 465<DT>Macros:</DT><DD>
 466  <DL>
 467  <DT><B>\a</B></DT><DD>
 468    This mark within the tag will be expanded into the text of the
 469    url itself. For example, if the <CODE>url</CODE> tag is '[url=\a]'
 470    and the url in the source document in 'example.com', then
 471    the text '[url=example.com]' will be emitted.
 472  </DL>
 473</DL>
 474
 475<H3 ID="urlMark">urlMark</H3>
 476
 477<P>
 478This tag is used for a link with a label. The label will appear in
 479the final document, possibly formatted differently to set it apart,
 480but it will function as a link to the url.
 481</P>
 482
 483<DL>
 484<DT>Macros:</DT><DD>
 485  <DL>
 486  <DT><B>\a</B></DT><DD>
 487    This mark should appear twice in the tag. The first instance is
 488    expanded to the text of the url, the second instance is expanded
 489    to the text of the label.
 490  <P></P>
 491    If the rule <A HREF="#labelbeforelink">'labelbeforelink'</A> is defined for the target, then
 492    the first instance is the label, and the second instance is the
 493    url.
 494  <P></P>
 495    If the rule <A HREF="#imglinkable">'imglinkable'</A> is defined for the target, then an
 496    <A HREF="#img">img</A> tag (see below) is allowed as the label.
 497  </DL>
 498</DL>
 499
 500<H3 ID="urlMarkAnchor">urlMarkAnchor</H3>
 501
 502<P>
 503This tag is used if the url begins with a '#', designating an
 504internal link to an anchor within the document. Some targets require
 505a different tag for internal links than for external links.
 506</P>
 507<P>
 508This tag otherwise behaves identically as <A HREF="#urlMark">urlMark</A>, with the same
 509macro definitions.
 510</P>
 511
 512<H3 ID="email">email</H3>
 513
 514<P>
 515This tag is used if the url is detected as being for an email
 516address rather than to a webpage or file. Ordinarily Txt2tags will
 517detect automatically that the url represents an email address.
 518</P>
 519<P>
 520Just like <A HREF="#url">url</A>, this tag is used for a plain email with no label
 521defined.
 522</P>
 523
 524<DL>
 525<DT>Macros:</DT><DD>
 526  <DL>
 527  <DT><B>\a</B></DT><DD>
 528    This mark is expanded to the full text of the email address.
 529  </DL>
 530</DL>
 531
 532<H3 ID="emailMark">emailMark</H3>
 533
 534<P>
 535Similar to <A HREF="#urlMark">urlMark</A>, this tag is used for email addresses that
 536are assigned a label in the source document.
 537</P>
 538
 539<DL>
 540<DT>Macros:</DT><DD>
 541  <DL>
 542  <DT><B>\a</B></DT><DD>
 543    This mark appears twice in the tag, just like <A HREF="#urlMark">urlMark</A>. The
 544    first instance is expanded to the text of the email address, and
 545    the second instance to the text of the label. If the rule
 546    <A HREF="#labelbeforelink">'labelbeforelink'</A> is defined, then the first instance is the
 547    label and the second instance is the email address.
 548  </DL>
 549</DL>
 550
 551<H2 ID="section-Images">3.3. Images</H2>
 552
 553<P>
 554Many targets allow images to be included in documents, often with a
 555syntax similar to that of links. These tags are used to insert
 556images into your documents
 557</P>
 558
 559<H3 ID="img">img</H3>
 560
 561<P>
 562This is the basic tag used to insert an image into the output
 563document. The image is represented by a file path to the image file,
 564and is linked into the document.
 565</P>
 566<P>
 567The filename is not escaped, and is assumed to represent a real file
 568on the same filesystem as the document. As this time, links to
 569remote files are not supported.
 570</P>
 571
 572<DL>
 573<DT>Macros:</DT><DD>
 574  <DL>
 575  <DT><B>\a</B></DT><DD>
 576    This mark is expanded to the text of the file path pointing to
 577    the inserted image.
 578  <P></P>
 579  <DT><B>~A~</B></DT><DD>
 580    This mark represents the alignment of the image. If the rule
 581    <A HREF="#imgalignable">'imgalignable'</A> is defined for the target, then this mark will
 582    be replaced with the contents of <A HREF="#_imgAlign">_imgAlignLeft, _imgAlignRight, or _imgAlignCenter</A> as appropriate. (Note
 583    the underscore at the beginning of each tag.)
 584  </DL>
 585</DL>
 586
 587<H3 ID="_imgAlign">_imgAlignLeft, _imgAlignRight, _imgAlignCenter</H3>
 588
 589<P>
 590These tags are used to add alignment to the <A HREF="#img">img</A> tag. If the rule
 591<A HREF="#imgalignable">'imgalignable'</A> is defined, then whichever of these tags is
 592appropriate will replace the <B>~A~</B> mark within the <A HREF="#img">img</A> tag.
 593</P>
 594<P>
 595Note the underscores at the beginning of the tag names. Do not
 596confuse these with the <A HREF="#imgAlign">imgAlignLeft, imgAlignRight, and imgAlignCenter</A> tags, explained below.
 597</P>
 598
 599<DL>
 600<DT>Macros:</DT><DD>
 601  None
 602</DL>
 603
 604<H3 ID="imgAlign">imgAlignLeft, imgAlignRight, imgAlignCenter</H3>
 605
 606<P>
 607These tags are used if the alignment changes the image tags too much
 608to simply use <A HREF="#img">img</A> and <A HREF="#_imgAlign">_imgAlign*</A>.
 609</P>
 610<P>
 611If the rule <A HREF="#imgalignable">'imgalignable'</A> is defined and these tags are defined,
 612then they will be used <I>instead of</I> the <A HREF="#img">img</A> tag. Each of these
 613tags should have whatever markup is needed for image align in them,
 614and they will not have <B>~A~</B> expanded.
 615</P>
 616
 617<DL>
 618<DT>Macros:</DT><DD>
 619  <DL>
 620  <DT><B>\a</B></DT><DD>
 621    This mark is expanded to the file path of the image file, just
 622    as in the <A HREF="#img">img</A> tag.
 623  </DL>
 624</DL>
 625
 626<H3 ID="imgEmbed">imgEmbed</H3>
 627
 628<P>
 629This tag is used to embed image data directly into the document
 630itself, rather than to link to the image file externally. If the
 631command-line option <I>--embed-images</I> is used, then this tag will be
 632used <I>instead of</I> the <A HREF="#img">img</A> tag.
 633</P>
 634<P>
 635Currently this is only used by the <B>RTF</B> target, and will require
 636additional functionality to be added to Txt2tags to add support to
 637another target.
 638</P>
 639
 640<DL>
 641<DT>Macros:</DT><DD>
 642  <DL>
 643  <DT><B>\a</B></DT><DD>
 644    This mark is expanded into the full file data of the embedded
 645    image file, as well as whatever additional markup may be
 646    required to make it work with the target.
 647  </DL>
 648</DL>
 649
 650<H1 ID="chapter-TitlesandSections">4. Titles and Sections</H1>
 651
 652<P>
 653Txt2tags allows you to specify markup for separating documents into
 654sections, and for adding titles or headings to each section. It
 655accomplishes both these tasks with the <CODE>title</CODE> family of tags.
 656</P>
 657<P>
 658There are two methods used, depending on the tags and rules
 659specified. By default, the <A HREF="#title1">title*</A> tags are used simply to mark
 660up each section heading or subsection heading. Sections are implied
 661by these headings, but do not have explicit markup.
 662</P>
 663<P>
 664If the rule <A HREF="#titleblocks">'titleblocks'</A> is defined for the target, then the
 665<A HREF="#title1Open">title*Open*</A> and <A HREF="#blockTitle1Open">blockTitle*Open*</A> family of tags is used
 666instead. These explicitly separate sections and subsections and
 667allow additional markup for section commands as needed.
 668</P>
 669<P>
 670Either way, the titles are used to generate the automatic table of
 671contents, if desired. If the target supports its own table of
 672contents, then markup to add the titles/sections to it should be
 673included in the tags.
 674</P>
 675<P>
 676The title text itself does not support any additional Txt2tags
 677markup. That is, the user may not apply //italics// to the
 678title, as the marks will simply appear in the title as is. The title
 679text is escaped with the <I>doEscape()</I> function and, if the rule
 680<A HREF="#finalescapetitle">'finalescapetitle'</A> is defined, it is escaped by
 681<I>doFinalEscape()</I> as well.
 682</P>
 683
 684<H2 ID="section-TheAnchor">4.1. The Anchor</H2>
 685
 686<H3 ID="anchor">anchor</H3>
 687
 688<P>
 689This tag is used to add a linkable anchor the title heading, if the
 690target supports internal links. This should include all needed
 691markup to allow a <A HREF="#urlMark">urlMark</A> or <A HREF="#urlMarkAnchor">urlMarkAnchor</A> tag to link
 692directly to it from another part of the document.
 693</P>
 694<P>
 695If the command-line option <I>--toc</I> is specified, then all titles
 696will have anchors added to them (if they do not have one already)
 697and the table of contents will include direct links to each section
 698of the document.
 699</P>
 700
 701<DL>
 702<DT>Macros:</DT><DD>
 703  <DL>
 704  <DT><B>\a</B></DT><DD>
 705    This mark is expanded into the label text for the anchor, as
 706    specified by the user or generated automatically by Txt2tags if
 707    none has been specified and the <I>--toc</I> option is in effect.
 708  </DL>
 709</DL>
 710
 711<H2 ID="section-Titles">4.2. Titles</H2>
 712
 713<P>
 714The basic title tags are only used if the rule <A HREF="#titleblocks">'titleblocks'</A> is
 715not defined for the target. These are for simple markup of headings,
 716or simple section separators, for targets that do not require any
 717complicated markup for sections and subsections.
 718</P>
 719
 720<H3 ID="title1">title1, title2, title3, title4, title5</H3>
 721
 722<P>
 723These tags are for basic standard headings. <CODE>title1</CODE> is considered
 724the top level heading, <CODE>title2</CODE> the next level below it, and so
 725on.
 726</P>
 727<P>
 728If the rule <A HREF="#blanksaroundtitle">'blanksaroundtitle'</A> is defined, and extra blank line
 729will be emitted before and after this tag.
 730</P>
 731
 732<DL>
 733<DT>Macros:</DT><DD>
 734  <DL>
 735  <DT><B>\a</B></DT><DD>
 736    This mark is expanded into the text of the title itself,
 737    unchanged excepts for necessary escapes from the source
 738    document.
 739  <DT><B>~A~</B></DT><DD>
 740    This mark is expanded into the value of the <A HREF="#anchor">anchor</A> tag,
 741    along with the text of the label for that anchor. It is removed
 742    if the title does not have a label specified, and if txt2tags is
 743    not creating a tabel of contents.
 744  </DL>
 745</DL>
 746
 747<H3 ID="numtitle1">numtitle1, numtitle2, numtitle3, numtitle4, numtitle5</H3>
 748
 749<P>
 750These tags are used for sections heading that should be numbered.
 751They are otherwise treated the same as <A HREF="#title1">title*</A>.
 752</P>
 753<P>
 754If the rule <A HREF="#autonumbertitle">'autonumbertitle'</A> is defined, then these tags are
 755simply emitted as is, and the target is assumed to add the needed
 756numbers. If this rule is not defined for the target, then it is
 757assumed that the target does not have automatic numbering. In that
 758case, Txt2tags will automatically generate the correct
 759section/heading numbers and add that at the beginning of the title
 760text.
 761</P>
 762<P>
 763If the rule <A HREF="#blanksaroundnumtitle">'blanksaroundnumtitle'</A> is defined, an extra blank line
 764will be emitted before and after this tag.
 765</P>
 766
 767<DL>
 768<DT>Macros:</DT><DD>
 769  <DL>
 770  <DT><B>\a</B></DT><DD>
 771    This mark is expanded into the text of the title itself,
 772    unchanged excepts for necessary escapes from the source
 773    document.
 774  <DT><B>~A~</B></DT><DD>
 775    This mark is expanded into the value of the <A HREF="#anchor">anchor</A> tag,
 776    along with the text of the label for that anchor. It is removed
 777    if the title does not have a label specified, and if txt2tags is
 778    not creating a tabel of contents.
 779  </DL>
 780</DL>
 781
 782<H2 ID="section-SectioningTags">4.3. Sectioning Tags</H2>
 783
 784<P>
 785If the rule <A HREF="#titleblocks">'titleblocks'</A> is defined for the target, then the
 786above <A HREF="#title1">title*</A> tags are not used. Instead, the tags below are used
 787to separate the sections as a whole while also marking up the
 788section headings as needed.
 789</P>
 790
 791<H3 ID="title1Open">title1Open, title2Open, title3Open, title4Open, title5Open</H3>
 792
 793<P>
 794These tags are used to mark the beginning of a section or
 795subsection, as well as to mark up the heading for that section. They
 796work very similarly to the <A HREF="#title1">title*</A> tags above.
 797</P>
 798<P>
 799If the rule <A HREF="#blanksaroundtitle">'blanksaroundtitle'</A> is defined, an extra blank line
 800will be emitted before and after this tag.
 801</P>
 802
 803<DL>
 804<DT>Macros:</DT><DD>
 805  <DL>
 806  <DT><B>\a</B></DT><DD>
 807    This mark is expanded into the text of the title itself,
 808    unchanged excepts for necessary escapes from the source
 809    document.
 810  <DT><B>~A~</B></DT><DD>
 811    This mark is expanded into the value of the <A HREF="#anchor">anchor</A> tag,
 812    along with the text of the label for that anchor. It is removed
 813    if the title does not have a label specified, and if txt2tags is
 814    not creating a tabel of contents.
 815  </DL>
 816</DL>
 817
 818<H3 ID="title1Close">title1Close, title2Close, title3Close, title4Close, title5Close</H3>
 819
 820<P>
 821These tags are used to mark the end of a section that has been
 822opened with <A HREF="#title1Open">title*Open*</A>. It is emitted just before the opening
 823tag of the next section, as well as at the end of the document to
 824close all still-open sections.
 825</P>
 826<P>
 827Note that sections nest. If a second level section is specified just
 828after a first level section, and then another first level section,
 829the order of the tags will be: <CODE>title1Open</CODE>, <CODE>title2Open</CODE>,
 830<CODE>title2Close</CODE>, <CODE>title1Close</CODE>, <CODE>title1Open</CODE>, and so on.
 831</P>
 832
 833<DL>
 834<DT>Macros:</DT><DD>
 835  None
 836</DL>
 837
 838<H3 ID="blocktitle1Open">blocktitle1Open, blocktitle2Open, blocktitle3Open</H3>
 839
 840<P>
 841These tags are used to open a group of sections that are at the
 842same level. If multiple sections/titles are given in a row at the
 843same level, then the same level <CODE>blocktitle*Open</CODE> tag will be emitted
 844before the first <A HREF="#title1Open">title*Open*</A>.
 845</P>
 846
 847<DL>
 848<DT>Macros:</DT><DD>
 849  None
 850</DL>
 851
 852<H3 ID="blocktitle1Close">blocktitle1Close, blocktitle2Close, blocktitle3Close</H3>
 853
 854<P>
 855These tags are used to close a group of sections that are at the
 856same level. If multiple sections/titles are given in a row at the
 857same level, then the same level <CODE>blocktitle*Close</CODE> tag will be emitted
 858after the last <A HREF="#title1Close">title*Close*</A>.
 859</P>
 860
 861<DL>
 862<DT>Macros:</DT><DD>
 863  None
 864</DL>
 865
 866<H1 ID="chapter-Lists">5. Lists</H1>
 867
 868<P>
 869Lists are used to add structure to small groups of items. They can
 870be numbered or unnumbered, and they can be nested.
 871</P>
 872<P>
 873If the rule <A HREF="#compactlist">'compactlist'</A> is defined for a target, then lists will
 874be considered compact or wide, depending on whether or not an
 875item in the list includes multiple paragraphs. If even a simple list
 876item has more then one paragraph (that is, a blank line in the item
 877that is not immediately followed by another list item), then the
 878entire list is considered a wide list. If each item in the list is
 879contained within a single paragraph, then the list is considered
 880compact.
 881</P>
 882<P>
 883If the rule <A HREF="#compactlist">'compactlist'</A> is <I>not</I> defined, then there is no
 884difference bewteen wide and compact lists, and all lists are treated
 885as wide lists.
 886</P>
 887<P>
 888If the rule <A HREF="#parainsidelist">'parainsidelist'</A> is defined for a target, then the
 889blank lines in wide lists are emitted as an empty paragraph. That
 890is, <A HREF="#paragraphOpen">paragraphOpen</A> followed immediately by <A HREF="#paragraphClose">paragraphClose</A>.
 891</P>
 892<P>
 893The rule <A HREF="#spacedlistitem">'spacedlistitem'</A> appears to be intended to show that a
 894target supports wide or spaced lists. However, at this time the rule
 895appears to be unused by Txt2tags, and does not affect output at all.
 896</P>
 897<P>
 898The rule <A HREF="#listmaxdepth">'listmaxdepth'</A> is used to tell Txt2tags how many levels
 899of lists may be nested within one another for each target.
 900</P>
 901<P>
 902If the rule <A HREF="#listnotnested">'listnotnested'</A> is defined for a target, then it does
 903not support nested lists. Nested lists in the source are emitted as
 904if all items belonged to the same, top-level list.
 905</P>
 906<P>
 907If the rule <A HREF="#listitemnotnested">'listitemnotnested'</A> is defined for a target, then
 908list items are closed before emitting a nested list, rather than wrapping
 909around the nested list.
 910</P>
 911
 912<H2 ID="section-UnorderedLists">5.1. Unordered Lists</H2>
 913
 914<P>
 915These lists do not use numbers to separate each item. Typically each
 916list item is set off with a bullet symbol, though this can vary for
 917different targets.
 918</P>
 919<P>
 920If the rule <A HREF="#blanksaroundlist">'blanksaroundlist'</A> is defined for a target, an extra
 921blank line is emitted before and after the top level list. No
 922additional lines are emitted for nested lists with this rule.
 923</P>
 924<P>
 925If the rule <A HREF="#blanksaroundnestedlist">'blanksaroundnestedlist'</A> is defined for a target, an
 926extra blank line is emitted before and after all lists, including
 927nested lists.
 928</P>
 929
 930<H3 ID="listOpen">listOpen</H3>
 931
 932<P>
 933This tag is emitted to mark the start of a new bulleted list.
 934</P>
 935<P>
 936By default this tag is emitted on its own line. The rule
 937<A HREF="#notbreaklistopen">'notbreaklistopen'</A> is intended to allow
 938<CODE>listOpen</CODE> to be on the same line as its first item, however
 939this rule is not yet supported and does not affect the output.
 940</P>
 941<P>
 942By default, the indent of a nested list is added (in spaces) at the
 943beginning of the line this tag is on. If the rule
 944<A HREF="#tagnotindentable">'tagnotindentable'</A> is defined, or the rule <A HREF="#keeplistindent">'keeplistindent'</A> is
 945not defined, these spaces are removed.
 946</P>
 947<P>
 948If the rule <A HREF="#compactlist">'compactlist'</A> is defined for a target, then this tag
 949is only used for wide lists. Otherwise it is used for both.
 950</P>
 951
 952<DL>
 953<DT>Macros:</DT><DD>
 954  None
 955</DL>
 956
 957<H3 ID="listCompactOpen">listCompactOpen</H3>
 958
 959<P>
 960This tag marks the beginning of a new compact bulleted list.
 961</P>
 962<P>
 963This tag is only used if the rule <A HREF="#compactlist">'compactlist'</A> is defined.
 964</P>
 965<P>
 966By default, the indent of a nested list is added (in spaces) at the
 967beginning of the line this tag is on. If the rule
 968<A HREF="#tagnotindentable">'tagnotindentable'</A> is defined, or the rule <A HREF="#keeplistindent">'keeplistindent'</A> is
 969not defined, these spaces are removed.
 970</P>
 971
 972<DL>
 973<DT>Macros:</DT><DD>
 974  None
 975</DL>
 976
 977<H3 ID="listClose">listClose, listCompactClose</H3>
 978
 979<P>
 980These tags are emitted, on their own line, to close the list opened
 981by the previous tags.
 982</P>
 983<P>
 984By default, the indent of a nested list is added (in spaces) at the
 985beginning of the line this tag is on. If the rule
 986<A HREF="#tagnotindentable">'tagnotindentable'</A> is defined, or the rule <A HREF="#keeplistindent">'keeplistindent'</A> is
 987not defined, these spaces are removed.
 988</P>
 989
 990<DL>
 991<DT>Macros:</DT><DD>
 992  None
 993</DL>
 994
 995<H3 ID="listItemOpen">listItemOpen</H3>
 996
 997<P>
 998This tag is emitted before each item within a bullet list.
 999</P>
1000<P>
1001By default, the indent of a nested list is added (in spaces) at the
1002beginning of the line this tag is on. If the rule
1003<A HREF="#tagnotindentable">'tagnotindentable'</A> is defined, or the rule <A HREF="#keeplistindent">'keeplistindent'</A> is
1004not defined, these spaces are removed.
1005</P>
1006<P>
1007If the tag <A HREF="#listItemLine">listItemLine</A> is defined, it will be emitted
1008immediately before <CODE>listItemOpen</CODE>. If the rule
1009<A HREF="#listlineafteropen">'listlineafteropen'</A> is defined,
1010<A HREF="#listItemLine">listItemLine</A> will be emitted after <CODE>listItemOpen</CODE>.
1011</P>
1012<P>
1013If the rule <A HREF="#spacedlistitemopen">'spacedlistitemopen'</A> is defined, then two spaces will
1014be emitted after <CODE>listItemOpen</CODE> and <A HREF="#listItemLine">listItemLine</A>, before the
1015list item text.
1016</P>
1017
1018<DL>
1019<DT>Macros:</DT><DD>
1020  <DL>
1021  <DT><B>~D~</B></DT><DD>
1022    If this macro is included in the tag, it will be expanded to the
1023    value of the depth of that particular list. Top level lists
1024    have depth '1', a nested list inside the top level would have
1025    depth level '2', and so on.
1026  <P></P>
1027    If the rule <A HREF="#blockdepthmultiply">'blockdepthmultiply'</A> is defined for the target,
1028    the depth value will be multiplied by that amount before being
1029    emitted. If the rule <A HREF="#depthmultiplyplus">'depthmultiplyplus'</A> is defined, then that
1030    value will be added to the depth before multiplying by
1031    <A HREF="#blockdepthmultiply">'blockdepthmultiply'</A>, but only if used with
1032    <A HREF="#blockdepthmultiply">'blockdepthmultiply'</A>.
1033  <DT><B>~V~</B></DT><DD>
1034    This macro will be expanded to the nesting level of the list. It
1035    is not affected by <A HREF="#blockdepthmultiply">'blockdepthmultiply'</A>, so the numbers will
1036    always count one by one.
1037  <P></P>
1038    If the rule <A HREF="#listlevelzerobased">'listlevelzerobased'</A> is defined for a target, then
1039    the top level lists will be level '0', the next level '1',
1040    and so on. Otherwise, the top level is '1' and the next level
1041    '2' and so on.
1042  </DL>
1043</DL>
1044
1045<H3 ID="listItemLine">listItemLine</H3>
1046
1047<P>
1048This tag is emitted for each item in the list. It is emitted either
1049right before or after <A HREF="#listItemOpen">listItemOpen</A> (see above).
1050</P>
1051<P>
1052This is emitted a number of times equal to the depth level of the
1053list. For example, if <CODE>listItemLine</CODE> is defined as '*', then
1054each item in a list nested three levels deep would begin with
1055'***'.
1056</P>
1057<P>
1058Despite the name, this is only emitted at the beginning of each
1059item, and not for every line of the item.
1060</P>
1061
1062<DL>
1063<DT>Macros:</DT><DD>
1064  None
1065</DL>
1066
1067<H3 ID="listItemClose">listItemClose</H3>
1068
1069<P>
1070This tag is emitted after each item in the list.
1071</P>
1072
1073<DL>
1074<DT>Macros:</DT><DD>
1075  None
1076</DL>
1077
1078<H2 ID="section-NumberedLists">5.2. Numbered Lists</H2>
1079
1080<P>
1081Numbered lists behave much like unordered lists, except (as their
1082name implies) they have numbers instead of bullets.
1083</P>
1084<P>
1085Each item in the list will have its own number, counting from '1'.
1086By default, nested lists will use a dotted number format, as in
1087'1.', '2.', and so on. This can vary between different
1088targets, however.
1089</P>
1090<P>
1091If the rule <A HREF="#blanksaroundnumlist">'blanksaroundnumlist'</A> is defined for a target, an extra
1092blank line is emitted before and after the top level list. No
1093additional lines are emitted for nested lists.
1094</P>
1095<P>
1096If the rule <A HREF="#blanksaroundnestedlist">'blanksaroundnestedlist'</A> is defined for a target, an
1097extra blank line is emitted before and after all lists, including
1098nested lists.
1099</P>
1100
1101<H3 ID="numlistOpen">numlistOpen</H3>
1102
1103<P>
1104This tag is emitted to mark the start of a new numbered list.
1105</P>
1106<P>
1107By default this tag is emitted on its own line. The rule
1108<A HREF="#notbreaklistopen">'notbreaklistopen'</A> is intended to allow
1109<CODE>numlistOpen</CODE> to be on the same line as its first item, however
1110this rule is not yet supported and does not affect the output.
1111</P>
1112<P>
1113By default, the indent of a nested list is added (in spaces) at the
1114beginning of the line this tag is on. If the rule
1115<A HREF="#tagnotindentable">'tagnotindentable'</A> is defined, or the rule <A HREF="#keeplistindent">'keeplistindent'</A> is
1116not defined, these spaces are removed.
1117</P>
1118<P>
1119If the rule <A HREF="#compactlist">'compactlist'</A> is defined for a target, then this tag
1120is only used for wide lists. Otherwise it is used for both.
1121</P>
1122
1123<DL>
1124<DT>Macros:</DT><DD>
1125  None
1126</DL>
1127
1128<H3 ID="numlistCompactOpen">numlistCompactOpen</H3>
1129
1130<P>
1131This tag marks the beginning of a new compact numbered list.
1132</P>
1133<P>
1134This tag is only used if the rule <A HREF="#compactlist">'compactlist'</A> is defined.
1135</P>
1136<P>
1137By default, the indent of a nested list is added (in spaces) at the
1138beginning of the line this tag is on. If the rule
1139<A HREF="#tagnotindentable">'tagnotindentable'</A> is defined, or the rule <A HREF="#keeplistindent">'keeplistindent'</A> is
1140not defined, these spaces are removed.
1141</P>
1142
1143<DL>
1144<DT>Macros:</DT><DD>
1145  None
1146</DL>
1147
1148<H3 ID="numlistClose">numlistClose, numlistCompactClose</H3>
1149
1150<P>
1151These tags are emitted, on their own line, to close the list opened
1152by the previous tags.
1153</P>
1154<P>
1155By default, the indent of a nested list is added (in spaces) at the
1156beginning of the line this tag is on. If the rule
1157<A HREF="#tagnotindentable">'tagnotindentable'</A> is defined, or the rule <A HREF="#keeplistindent">'keeplistindent'</A> is
1158not defined, these spaces are removed.
1159</P>
1160
1161<DL>
1162<DT>Macros:</DT><DD>
1163  None
1164</DL>
1165
1166<H3 ID="numlistItemOpen">numlistItemOpen</H3>
1167
1168<P>
1169This tag is emitted before each item within a numbered list.
1170</P>
1171<P>
1172If the rule <A HREF="#autonumberlist">'autonumberlist'</A> is defined, then the target is
1173assumed to put the numbers in itself. In this case Txt2Tags simply
1174emits this tag just like <A HREF="#listItemOpen">listItemOpen</A>. If it is not defined,
1175then the correct number is calculated and inserted by Txt2tags. It
1176uses the default number format given at the beginning of this
1177subsection above.
1178</P>
1179<P>
1180By default, the indent of a nested list is added (in spaces) at the
1181beginning of the line this tag is on. If the rule
1182<A HREF="#tagnotindentable">'tagnotindentable'</A> is defined, or the rule <A HREF="#keeplistindent">'keeplistindent'</A> is
1183not defined, these spaces are removed.
1184</P>
1185<P>
1186If the tag <A HREF="#numlistItemLine">numlistItemLine</A> is defined, it will be emitted
1187immediately before <CODE>numlistItemOpen</CODE>. If the rule
1188<A HREF="#listlineafteropen">'listlineafteropen'</A> is defined, <A HREF="#numlistItemLine">numlistItemLine</A> will be emitted
1189after <CODE>numlistItemOpen</CODE>.
1190</P>
1191<P>
1192If the rule <A HREF="#spacednumlistitemopen">'spacednumlistitemopen'</A> is defined, then two spaces will
1193be emitted after <CODE>numlistItemOpen</CODE> and <A HREF="#numlistItemLine">numlistItemLine</A>, before the
1194list item text.
1195</P>
1196
1197<DL>
1198<DT>Macros:</DT><DD>
1199  <DL>
1200  <DT><B>\a</B></DT><DD>
1201    If the rule <A HREF="#autonumberlist">'autonumberlist'</A> is <I>not</I> defined, then this
1202    mark is expanded into the correct number for this list item.
1203  <DT><B>~D~</B></DT><DD>
1204    If this macro is included in the tag, it will be expanded to the
1205    value of the depth of that particular list. Top level lists
1206    have depth '1', a nested list inside the top level would have
1207    depth level '2', and so on.
1208  <P></P>
1209    If the rule <A HREF="#blockdepthmultiply">'blockdepthmultiply'</A> is defined for the target,
1210    the depth value will be multiplied by that amount before being
1211    emitted. If the rule <A HREF="#depthmultiplyplus">'depthmultiplyplus'</A> is defined, then that
1212    value will be added to the depth before multiplying by
1213    <A HREF="#blockdepthmultiply">'blockdepthmultiply'</A>, but only if used with
1214    <A HREF="#blockdepthmultiply">'blockdepthmultiply'</A>.
1215  <DT><B>~V~</B></DT><DD>
1216    This macro will be expanded to the nesting level of the list. It
1217    is not affected by <A HREF="#blockdepthmultiply">'blockdepthmultiply'</A>, so the numbers will
1218    always count one by one.
1219  <P></P>
1220    If the rule <A HREF="#listlevelzerobased">'listlevelzerobased'</A> is defined for a target, then
1221    the top level lists will be level '0', the next level '1',
1222    and so on. Otherwise, the top level is '1' and the next level
1223    '2' and so on.
1224  </DL>
1225</DL>
1226
1227<H3 ID="numlistItemLine">numlistItemLine</H3>
1228
1229<P>
1230This tag is emitted for each item in the list. It is emitted either
1231right before or after <A HREF="#numlistItemOpen">numlistItemOpen</A> (see above).
1232</P>
1233<P>
1234This is emitted a number of times equal to the depth level of the
1235list. For example, if <CODE>numlistItemLine</CODE> is defined as '+', then
1236each item in a list nested three levels deep would begin with
1237'+++'.
1238</P>
1239<P>
1240Despite the name, this is only emitted at the beginning of each
1241item, and not for every line of the item.
1242</P>
1243
1244<DL>
1245<DT>Macros:</DT><DD>
1246  None
1247</DL>
1248
1249<H3 ID="numlistItemClose">numlistItemClose</H3>
1250
1251<P>
1252This tag is emitted after each item in the list.
1253</P>
1254
1255<DL>
1256<DT>Macros:</DT><DD>
1257  None
1258</DL>
1259
1260<H2 ID="section-DefinitionLists">5.3. Definition Lists</H2>
1261
1262<P>
1263Definition lists work a little bit differently from standard lists.
1264Each list item has two parts: the item or word to be defined, and
1265the definition itself.
1266</P>
1267<P>
1268If the rule <A HREF="#deflisttextstrip">'deflisttextstrip'</A> is defined, then each line of the
1269definition will have extra spaces stripped off, even if
1270<A HREF="#keeplistindent">'keeplistindent'</A> is also defined.
1271</P>
1272<P>
1273If the rule <A HREF="#blanksarounddeflist">'blanksarounddeflist'</A> is defined for a target, an extra
1274blank line is emitted before and after the top level list. No
1275additional lines are emitted for nested lists.
1276</P>
1277<P>
1278If the rule <A HREF="#blanksaroundnestedlist">'blanksaroundnestedlist'</A> is defined for a target, an
1279extra blank line is emitted before and after all lists, including
1280nested lists.
1281</P>
1282
1283<H3 ID="deflistOpen">deflistOpen</H3>
1284
1285<P>
1286This tag is emitted to mark the start of a new definition list.
1287</P>
1288<P>
1289By default this tag is emitted on its own line. The rule
1290<A HREF="#notbreaklistopen">'notbreaklistopen'</A> is intended to allow <A HREF="#listOpen">listOpen</A> to be on the
1291same line as its first item, however this rule is not yet supported
1292and does not affect the output.
1293</P>
1294<P>
1295By default, the indent of a nested list is added (in spaces) at the
1296beginning of the line this tag is on. If the rule
1297<A HREF="#tagnotindentable">'tagnotindentable'</A> is defined, or the rule <A HREF="#keeplistindent">'keeplistindent'</A> is
1298not defined, these spaces are removed.
1299</P>
1300<P>
1301If the rule <A HREF="#compactlist">'compactlist'</A> is defined for a target, then this tag
1302is only used for wide lists. Otherwise it is used for both.
1303</P>
1304
1305<DL>
1306<DT>Macros:</DT><DD>
1307  None
1308</DL>
1309
1310<H3 ID="deflistCompactOpen">deflistCompactOpen</H3>
1311
1312<P>
1313This tag marks the beginning of a new compact definition list.
1314</P>
1315<P>
1316This tag is only used if the rule <A HREF="#compactlist">'compactlist'</A> is defined.
1317</P>
1318<P>
1319By default, the indent of a nested list is added (in spaces) at the
1320beginning of the line this tag is on. If the rule
1321<A HREF="#tagnotindentable">'tagnotindentable'</A> is defined, or the rule <A HREF="#keeplistindent">'keeplistindent'</A> is
1322not defined, these spaces are removed.
1323</P>
1324
1325<DL>
1326<DT>Macros:</DT><DD>
1327  None
1328</DL>
1329
1330<H3 ID="deflistClose">deflistClose, deflistCompactClose</H3>
1331
1332<P>
1333These tags are emitted, on their own line, to close the list opened
1334by the previous tags.
1335</P>
1336<P>
1337By default, the indent of a nested list is added (in spaces) at the
1338beginning of the line this tag is on. If the rule
1339<A HREF="#tagnotindentable">'tagnotindentable'</A> is defined, or the rule <A HREF="#keeplistindent">'keeplistindent'</A> is
1340not defined, these spaces are removed.
1341</P>
1342
1343<DL>
1344<DT>Macros:</DT><DD>
1345  None
1346</DL>
1347
1348<H3 ID="deflistItem1Open">deflistItem1Open</H3>
1349
1350<P>
1351This tag is emitted before each item within a definition list. It is
1352specifically meant to go before the term to be defined.
1353</P>
1354<P>
1355By default, the indent of a nested list is added (in spaces) at the
1356beginning of the line this tag is on. If the rule
1357<A HREF="#tagnotindentable">'tagnotindentable'</A> is defined, or the rule <A HREF="#keeplistindent">'keeplistindent'</A> is
1358not defined, these spaces are removed.
1359</P>
1360<P>
1361If the rule <A HREF="#imgasdefterm">'imgasdefterm'</A> is defined, then a linked image is
1362allowed as the term to be defined. Otherwise, only text is allowed.
1363</P>
1364
1365<DL>
1366<DT>Macros:</DT><DD>
1367  <DL>
1368  <DT><B>~D~</B></DT><DD>
1369    If this macro is included in the tag, it will be expanded to the
1370    value of the depth of that particular list. Top level lists
1371    have depth '1', a nested list inside the top level would have
1372    depth level '2', and so on.
1373  <P></P>
1374    If the rule <A HREF="#blockdepthmultiply">'blockdepthmultiply'</A> is defined for the target,
1375    the depth value will be multiplied by that amount before being
1376    emitted. If the rule <A HREF="#depthmultiplyplus">'depthmultiplyplus'</A> is defined, then that
1377    value will be added to the depth before multiplying by
1378    <A HREF="#blockdepthmultiply">'blockdepthmultiply'</A>, but only if used with
1379    <A HREF="#blockdepthmultiply">'blockdepthmultiply'</A>.
1380  <DT><B>~V~</B></DT><DD>
1381    This macro will be expanded to the nesting level of the list. It
1382    is not affected by <A HREF="#blockdepthmultiply">'blockdepthmultiply'</A>, so the numbers will
1383    always count one by one.
1384  <P></P>
1385    If the rule <A HREF="#listlevelzerobased">'listlevelzerobased'</A> is defined for a target, then
1386    the top level lists will be level '0', the next level '1',
1387    and so on. Otherwise, the top level is '1' and the next level
1388    '2' and so on.
1389  </DL>
1390</DL>
1391
1392<H3 ID="deflistItem1Close">deflistItem1Close</H3>
1393
1394<P>
1395This tag is emitted after each definition term, but before the
1396definition itself, for each item in the list.
1397</P>
1398
1399<DL>
1400<DT>Macros:</DT><DD>
1401  None
1402</DL>
1403
1404<H3 ID="deflistItem2Open">deflistItem2Open</H3>
1405
1406<P>
1407This tag is emitted directly after <A HREF="#deflistItem1Close">deflistItem1Close</A>, and is
1408used right before the definition text of the item.
1409</P>
1410
1411<DL>
1412<DT>Macros:</DT><DD>
1413  None
1414</DL>
1415
1416<H3 ID="deflistItem2LinePrefix">deflistItem2LinePrefix</H3>
1417
1418<P>
1419This tag is emitted at the beginning of each line of the definition
1420text for each item.
1421</P>
1422<P>
1423Note that it is not multiplied for nexted lists. It is the same for
1424every level of a nested list.
1425</P>
1426<P>
1427If the rule <A HREF="#keeplistindent">'keeplistindent'</A> is defined and <A HREF="#deflisttextstrip">'deflisttextstrip'</A>
1428is not defined, then this is emitted after the indent for each line
1429of the list.
1430</P>
1431
1432<DL>
1433<DT>Macros:</DT><DD>
1434  None
1435</DL>
1436
1437<H3 ID="deflistItem2Close">deflistItem2Close</H3>
1438
1439<P>
1440This tag is emitted at the end of each definition, and therefor at
1441the end of each item of the definition list.
1442</P>
1443<P>
1444For examples, the tags for a definition list are emitted as follows:
1445<CODE>deflistOpen</CODE>, <CODE>deflistItem1Open</CODE>, <CODE>deflistItem1Close</CODE>,
1446<CODE>deflistItem2Open</CODE>, (<CODE>deflistItem2LinePrefix</CODE> for each line),
1447<CODE>deflistItem2Close</CODE>, <CODE>deflistItem1Open</CODE>, and so on for the
1448entire list.
1449</P>
1450
1451<DL>
1452<DT>Macros:</DT><DD>
1453  None
1454</DL>
1455
1456<H1 ID="chapter-Tables">6. Tables</H1>
1457
1458<P>
1459Tables allow the user to arrange data in rows and columns for better
1460organization. Some targets support very complicated tables, while
1461others only support limited options within tables or do not support
1462tables at all. Txt2tags is limited to the most basic and most common
1463table options usable by the greatest number of targets.
1464</P>
1465<P>
1466If the rule <A HREF="#tableable">'tableable'</A> is <I>not</I> defined, then the table markup
1467is emitted unchanged from the source document and put inside a
1468verbatim block.
1469</P>
1470<P>
1471If the rule <A HREF="#blanksaroundtable">'blanksaroundtable'</A> is defined, then an extra blank
1472line will be emitted before and after the table markup.
1473</P>
1474
1475<H2 ID="section-Macros">6.1. Macros</H2>
1476
1477<P>
1478Because of how complicated most table markup can be, there are
1479several macro tags that can be defined that may be expanded by
1480several other tags. These tags will all be defined here to be easier
1481to find in this reference.
1482</P>
1483
1484<H3 ID="_tableBorder">_tableBorder</H3>
1485
1486<P>
1487This tag may be inserted into the outer table and row tags to
1488designate that this table should have a border.
1489</P>
1490<P>
1491For tags that support it, it will replace the macro <B>~B~</B>.
1492</P>
1493
1494<H3 ID="_tableCellBorder">_tableCellBorder</H3>
1495
1496<P>
1497This tag may be inserted into the markup of each individual cell to
1498desi…
Large files files are truncated, but you can click here to view the full file