/doc/English/tags-reference.html

http://txt2tags.googlecode.com/ · HTML · 2737 lines · 2329 code · 406 blank · 2 comment · 0 complexity · ee2cbfb0f5396e258acb153620cf0665 MD5 · raw file

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