XBook - Authoring Text (text.dtd)

Author: Just van den Broecke
Organization: Just Objects B.V.
Email: just@justobjects.nl

FileID: $Id: authoring-text.xml,v 1.5 2003/01/06 10:28:08 just Exp $
Date: July 8, 2002

This document describes how to author documentation using text.dtd provided with XBook. This DTD is used in various other DTDs such as doc.dtd, page.dtd and album.dtd.


1. Overview

1.1. Purpose

text.dtd is a special DTD in the sense that it is reused within other DTDs, specifically doc.dtd and page.dtd. These DTDs define the overall structure of a specialized document. text.dtd is used to define the elements to be used for the text within the actual content. Examples of text.dtd elements are formatting elements like paragraphs, sections, tables and elements for linking and images. In a sense text.dtd is much like (X)HTML in that it defines constructs for textual elements but not the overall structure of a specific document such as a memo or FAQ. The advantage of text.dtd is that it defines only a limited number of elements that have no or few attributes.

Power users may immediately go to the DTD definition.

1.2. Elements

Below is an overview the XML tags defined in text.dtd.

element
purpose
#PCDATA
untagged text (discouraged)
named anchor (like HTML <A name=>)
no formatting (like HTML <PRE>)
boldface text (like HTML <B>)
line break (like HTML <BR>)
center text (like HTML <CENTER>)
code (fixed width usually Courier) text (like HTML <CODE>)
name/definition list
image (like HTML <IMG>)
include file or part of file as escaped text (usually within listing)
italic text (like HTML <I>)
hyperlink (like HTML <A href=>)
(usually) bullet list (like HTML <DL>)
code listing usually outlined in table
paragraph (like HTML <P>)
nested sections (like HTML <H[1-6]>)
sequential (usually numbered) list (like HTML <OL>)
split into left and right column
emphasize text
simple table (like HTML <TABLE>)
escape into using plain HTML through XHTML

2. Text Styling (bold, code, italic, strong)

2.1. Purpose

Provide elements for (hinting) the appearance of text fonts and font styles/face. Although the DTD should in principle specify no styling, it appears that these elements are very handy in practice. Again they are just suggestions to the XSLT stylesheet and CSS file who ultimately decides on the font, font face and font style/decoration.

2.2. Elements

tag
purpose
bold
suggest boldface
code
suggest constant width (usually Courier)
italic
suggest italic
strong
emphasized text

2.3. Example

2.3.1. Construct

115: <para> 116: <bold>This is in bold</bold>. <break/> 117: <code>This is in code</code>. <break/> 118: <italic>This is in italic</italic>. <break/> 119: <strong>This is in strong</strong>. <break/> 120: </para>

2.3.2. Result

This is in bold.
This is in code.
This is in italic.
This is in strong.

3. Text Block Formatting (as-is, break, center, listing, para)

3.1. Purpose

Provide elements for identifying and formatting blocks of text such as paragraphs and code listings. Although some of these suggest style they are again very handy in practice.

3.2. Elements

tag
purpose
as-is
no formatting, text appears as-is
break
a line break
center
center text block
listing
display text block as code listing (usually combine with <include>)
para
paragraph text block
section[1-8]
nested section blocks (H[1-6] HTML equivalents)

3.3. Example

3.3.1. Construct

173: 174: <as-is> 175: This is displayed as-is 176: This is displayed as-is 177: 178: </as-is> 179: 180: <para> 181: This is a line-<break/>break 182: </para> 183: 184: <center>This is centered</center>. 185: 186: <listing> 187: This is a listing. 188: This is a listing. 189: </listing>. 190: 191: <para> 192: This is a a paragraph with para element. This is a a paragraph with para element. 193: This is a a paragraph with para element. This is a a paragraph with para element. 194: This is a a paragraph with para element. This is a a paragraph with para element. 195: </para>.

3.3.2. Result

     This is displayed as-is
     This is displayed as-is
   
   

This is a line-
break

This is centered
.
This is a listing. This is a listing.
.

This is a a paragraph with para element. This is a a paragraph with para element. This is a a paragraph with para element. This is a a paragraph with para element. This is a a paragraph with para element. This is a a paragraph with para element.

.

4. Hyperlinks (link, anchor)

4.1. Purpose

Provide constructs to enable linking to internal elements and external documents.

4.2. Elements

tag
attributes
anchor
id - name of anchor
link
href - anchor id or external document or site
section[1-4]
id - defines anchor for section

Note that doc.dtd in addition allows internal links to references in the <back> section. See the doc.dtd authoring document.

4.3. Example

4.3.1. Construct

238: <para> 239: <anchor id="myanchor" /> 240: Here I define an anchor: 241: </para> 242: <para> 243: External link to <link href="http://www.justobjects.nl">www.justobjects</link> 244: </para> 245: <para> 246: External link to <link href="overview.html">overview.html</link> 247: </para> 248: <para> 249: Internal link to <link href="#myanchor">myanchor</link> 250: </para> 251: <para> 252: Internal link to the beginning of this section with id <link href="#text.link">text.link</link>. 253: </para> 254: <para> 255: In the last example the section id attribute was used where the section element was 256: defined as follows: 257: 258: </para> 259: <as-is> 260: &lt;section2 id="text.link" title="link and anchor - using hyperlinks" &gt; 261: </as-is>

4.3.2. Result

Here I define an anchor:

External link to www.justobjects

External link to overview.html

Internal link to myanchor

Internal link to the beginning of this section with id text.link.

In the last example the section id attribute was used where the section element was defined as follows:

      <section2 id="text.link" title="link and anchor - using hyperlinks" >
   

5. Images (image)

5.1. Purpose

Provide an element to show images in the document.

5.2. Elements

tag
attributes
image
href - URL of image file

5.3. Example

5.3.1. Construct

294: <image href="assets/image-merel.jpg" />

5.3.2. Result

6. Lists (dictionary, list, sequence)

6.1. Purpose

Provide elements for several common lists.

6.2. Elements

tag
purpose
list item element
dictionary
a name, value list a.k.a. definition list
defitem with children term and def
list
default (usually bullet) item list
item
sequence
sequential (usually numbered) item list
step

6.3. Example

6.3.1. Construct

337: <para>Bullet list with <code>&lt;list&gt;</code>.</para> 338: <list> 339: <item>This is item number one.</item> 340: <item>This is item number two.</item> 341: <item>This is item number three.</item> 342: </list> 343: <para>Numbered list with <code>&lt;sequence&gt;</code>.</para> 344: <sequence> 345: <step>This is item number one.</step> 346: <step>This is item number two.</step> 347: <step>This is item number three.</step> 348: </sequence> 349: <para>Definition list with <code>&lt;dictionary&gt;</code>.</para> 350: <dictionary> 351: <defitem><term>Term1</term><def>This is item definition number one.</def></defitem> 352: <defitem><term>Term2</term><def>This is item definition number two.</def></defitem> 353: <defitem><term>Term3</term><def>This is item definition number three.</def></defitem> 354: </dictionary> 355:

6.3.2. Result

Bullet list with <list>.

  • This is item number one.
  • This is item number two.
  • This is item number three.

Numbered list with <sequence>.

  1. This is item number one.
  2. This is item number two.
  3. This is item number three.

Definition list with <dictionary>.

Term1
This is item definition number one.
Term2
This is item definition number two.
Term3
This is item definition number three.

7. Tables (table1, split)

7.1. Purpose

Provide elements for tables. Tables can in general be very complex. Here I have initially chosen for a very simple table, historically named table1. The idea is to have tables defined just by their rows and cells and let the styling do the format. The split element is in effect a one row/two cell table that divides the text into two columns.

7.2. Elements

7.2.1. table1

tag
purpose
attributes
child element
table1
define a simple table
optional border="true|false"
row
row
row within a table1
none
cell
cell
single cell in a table/row
optional colspan="num" and rowspan="num"
any from text.dtd

7.2.2. split

tag
purpose
attributes
child element
split
define split (two column) output
none
left and left
left
define left column
none
any from text.dtd
right
define right column
none
any from text.dtd

7.3. Example

7.3.1. Construct

437: <para>Table with border.</para> 438: <table1 border="true"> 439: <row> 440: <cell><strong>head1</strong></cell> 441: <cell><strong>head2</strong></cell> 442: <cell><strong>head3</strong></cell> 443: <cell><strong>head4</strong></cell> 444: </row> 445: <row> 446: <cell>row1/cell1</cell> 447: <cell>row1/cell2</cell> 448: <cell>row1/cell3</cell> 449: <cell>row1/cell4</cell> 450: </row> 451: <row> 452: <cell>row2/cell1</cell> 453: <cell colspan="2">spanning two columns</cell> 454: <cell>row2/cell4</cell> 455: </row> 456: <row> 457: <cell>row3/cell1</cell> 458: <cell>row3/cell2</cell> 459: <cell>row3/cell3</cell> 460: <cell>row3/cell4</cell> 461: </row> 462: </table1> 463: <para>Table without border.</para> 464: <table1> 465: <row> 466: <cell><strong>head1</strong></cell> 467: <cell><strong>head2</strong></cell> 468: <cell><strong>head3</strong></cell> 469: <cell><strong>head4</strong></cell> 470: </row> 471: <row> 472: <cell>row1/cell1</cell> 473: <cell>row1/cell2</cell> 474: <cell>row1/cell3</cell> 475: <cell rowspan="2">spanning two rows</cell> 476: </row> 477: <row> 478: <cell>row2/cell2</cell> 479: <cell>row2/cell3</cell> 480: <cell>row2/cell4</cell> 481: </row> 482: <row> 483: <cell>row3/cell1</cell> 484: <cell>row3/cell2</cell> 485: <cell>row3/cell3</cell> 486: <cell>row3/cell4</cell> 487: </row> 488: </table1> 489: 490: <para>Using split</para> 491: <split> 492: <left>This is the left side of split</left> 493: <right>This is the right side of split</right> 494: </split>

7.3.2. Result

Table with border.

head1
head2
head3
head4
row1/cell1
row1/cell2
row1/cell3
row1/cell4
row2/cell1
spanning two columns
row2/cell4
row3/cell1
row3/cell2
row3/cell3
row3/cell4

Table without border.

head1
head2
head3
head4
row1/cell1
row1/cell2
row1/cell3
spanning two rows
row2/cell2
row2/cell3
row2/cell4
row3/cell1
row3/cell2
row3/cell3
row3/cell4

Using split

This is the left side of split
This is the right side of split

8. Including external text (include)

8.1. Purpose

Provide a way to include files and parts of files as escaped text. This is very useful for code listings since you can keep a single copy of the code file and have any changes synchronized in the document.

An entire file can be included or a range can be specified. You can mark the range in several file types within the comments for that language.

Tip: this document itself makes heavily use of include for all examples.

8.2. Elements

tag
attributes
include
href - name of the local file
range - optional range as demarcated in the file.

The range is specified as and derived from file extension

Java (.java) and C++ (.cpp): //{rangeId . . //}rangeId XML: see example

8.3. Example

8.3.1. Construct

552: <listing> 553: <include href="authoring-text.xml" range="show.text.include" /> 554: </listing> 555:

8.3.2. Result

551: <!--{text.include --> 552: <listing> 553: <include href="authoring-text.xml" range="show.text.include" /> 554: </listing> 555: 556: <!--}text.include -->

9. Using Plain HTML (xhtml)

9.1. Purpose

Provide an escape to use raw HTML within XML. Note that DTD-checking is switched off when this escape is used in your document

Using <xhtml> implies that you must use formal HTML, i.e. as defined in the W3C XHTML 1.0: The Extensible HyperText Markup Language where HTML is specified as XML. This goes especially for elements like <br> and <hr> that must be specified as respectively <br/> and <hr/> in XHTML.

9.2. Example

9.2.1. Construct

587: 588: <xhtml> 589: <i>Here you see the use of the &lt;xhtml&gt; tag. This 590: allows an "escape" into raw HTML, provided you follow the 591: XHTML syntax, i.e. closing all elements. This means for example using 592: &lt;br/&gt; i..s.o. &lt;br&gt;.</i>. 593: <p> 594: xhtml-content will be included as-is 595: within the generated document. 596: </p> 597: <p> 598: A line<br/> 599: break. 600: </p> 601: <p> 602: And a ruler 603: </p> 604: <hr/> 605: <p> 606: Next is a simple html table. 607: </p> 608: <table> 609: <tr> 610: <td width="100" height="100" bgcolor="red">red</td><td bgcolor="white">white</td><td bgcolor="blue">blue</td> 611: </tr> 612: </table> 613: </xhtml>

9.2.2. Result

Here you see the use of the <xhtml> tag. This allows an "escape" into raw HTML, provided you follow the XHTML syntax, i.e. closing all elements. This means for example using <br/> i..s.o. <br>.

xhtml-content will be included as-is within the generated document.

A line
break.

And a ruler


Next is a simple html table.

redwhiteblue

10. Tips, Tricks and Gotchas

10.1. Never use untagged text

Always use at least a <para> element to delineate your text. Some browsers in particular Netscape can fall back to the default font (styles).

10.2. Never use para around tables and lists

Tables and list take space by themselves. This issue is related to the "Never use untagged text". If you have text around for example a table, put those text elements in a <para>, but not surround the table with para. Again Netscape gets upset and you may see the e.g. the indentation being lost.

11. DTD Definition

Below is the actual DTD file.

1: <?xml version="1.0" encoding="UTF-8"?> 2: 3: <!-- 4: Definitions for simple HTML-like formatting. 5: 6: $Id: text.dtd,v 1.11 2003/01/06 10:27:22 just Exp $ 7: --> 8: 9: 10: <!-- START DTD data types: 11: 12: entity description 13: ====== =============================================== 14: URI/URL e.g., "http://www.justobjects.nl/" 15: ATEXT printable ASCII text (no line-terminators) for attributes 16: CTEXT printable ASCII text (no line-terminators) for elements 17: TEXT character data for elements 18: --> 19: <!ENTITY % FILEPATH "CDATA"> 20: <!ENTITY % URI "CDATA"> 21: <!ENTITY % URL "CDATA"> 22: <!ENTITY % ATEXT "CDATA"> 23: <!ENTITY % CTEXT "#PCDATA"> 24: <!ENTITY % TEXT "#PCDATA"> 25: 26: <!-- Boolean --> 27: <!ENTITY % boolean "true|false"> 28: 29: <!-- END DTD data types --> 30: 31: <!-- START basic text entities --> 32: 33: <!ENTITY % text "#PCDATA|para|break|strong|bold|italic|center|code|as-is| 34: image|anchor|link|include|list|listing|sequence|dictionary|table1|split|xhtml"> 35: 36: <!-- Standard formatting stuff; --> 37: <!ELEMENT as-is (%text;)*> 38: <!ELEMENT break EMPTY> 39: <!ELEMENT center (%text;)*> 40: <!ELEMENT code (%text;)*> 41: <!ELEMENT bold (%text;)*> 42: <!ELEMENT italic (%text;)*> 43: <!ELEMENT para (%text;)*> 44: <!ELEMENT strong (%text;)*> 45: 46: 47: <!-- Like HTML image tag --> 48: <!ELEMENT image EMPTY> 49: <!ATTLIST image 50: href %URL; #REQUIRED 51: > 52: 53: <!-- Like HTML 'A name=' tag --> 54: <!ELEMENT anchor EMPTY> 55: <!ATTLIST anchor 56: id ID #REQUIRED 57: > 58: 59: <!-- Like HTML 'A' tag --> 60: <!ELEMENT link (%text;)*> 61: <!ATTLIST link 62: href %URL; #REQUIRED 63: target %ATEXT; '_self' 64: > 65: 66: 67: <!-- Allows inclusion of files; either entire file or range within file --> 68: <!ELEMENT include EMPTY> 69: <!ATTLIST include 70: href %FILEPATH; #REQUIRED 71: range NMTOKEN #IMPLIED 72: > 73: 74: <!-- Like HTML list types --> 75: <!ELEMENT list (item)+> 76: <!ELEMENT item (%text;)*> 77: 78: <!-- Code listing types --> 79: <!ELEMENT listing (%text;)*> 80: 81: <!-- Like HTML numbered list types --> 82: <!ELEMENT sequence (step)+> 83: <!ELEMENT step (%text;)*> 84: 85: <!-- Definition list (HTML does not have a usable feature for this) --> 86: <!ELEMENT dictionary (defitem)+> 87: <!ELEMENT defitem (term,def)> 88: <!ELEMENT def (%text;)*> 89: <!ELEMENT term (%text;)*> 90: 91: <!-- Many possibilities for tables, but start simple --> 92: <!ELEMENT table1 (row)+> 93: <!ATTLIST table1 94: title CDATA #IMPLIED 95: border (%boolean;) 'false' 96: > 97: 98: <!ELEMENT row (cell)+> 99: 100: <!ELEMENT cell (%text;)*> 101: <!ATTLIST cell 102: colspan NMTOKEN #IMPLIED 103: rowspan NMTOKEN #IMPLIED 104: > 105: 106: <!ELEMENT split (left,right)> 107: <!ELEMENT left (%text;)*> 108: <!ELEMENT right (%text;)*> 109: 110: <!-- Escape to include raw HTML --> 111: <!ELEMENT xhtml ANY> 112: 113: <!-- END Basic text entities --> 114: 115: <!-- Document Structuring with section* --> 116: 117: <!-- Like HTML H1 tag --> 118: <!ELEMENT section1 (%text; | section2)*> 119: <!ATTLIST section1 120: id ID #IMPLIED 121: title %ATEXT; #REQUIRED> 122: 123: <!-- Like HTML H2 tag --> 124: <!ELEMENT section2 (%text; | section3)*> 125: <!ATTLIST section2 126: id ID #IMPLIED 127: title %ATEXT; #REQUIRED> 128: 129: <!-- Like HTML H3 tag --> 130: <!ELEMENT section3 (%text; | section4)*> 131: <!ATTLIST section3 132: id ID #IMPLIED 133: title %ATEXT; #REQUIRED> 134: 135: <!-- Like HTML H4 tag: not in index. --> 136: <!ELEMENT section4 (%text; | section5)*> 137: <!ATTLIST section4 138: id ID #IMPLIED 139: title %ATEXT; #REQUIRED> 140: 141: <!-- Like HTML H5 tag: not in index. --> 142: <!ELEMENT section5 (%text; | section6)*> 143: <!ATTLIST section5 144: id ID #IMPLIED 145: title %ATEXT; #REQUIRED> 146: 147: <!-- Like HTML H6 tag: not in index. --> 148: <!ELEMENT section6 (%text; | section7)*> 149: <!ATTLIST section6 150: id ID #IMPLIED 151: title %ATEXT; #REQUIRED> 152: 153: <!-- Like HTML H7 tag: not in index. --> 154: <!ELEMENT section7 (%text; | section8)*> 155: <!ATTLIST section7 156: id ID #IMPLIED 157: title %ATEXT; #REQUIRED> 158: 159: <!-- Like HTML H8 tag: not in index. --> 160: <!ELEMENT section8 (%text;)*> 161: <!ATTLIST section8 162: id ID #IMPLIED 163: title %ATEXT; #REQUIRED> 164: 165: <!-- 166: $Log: text.dtd,v $ 167: Revision 1.11 2003/01/06 10:27:22 just 168: removed Arial fonts from default styles 169: 170: Revision 1.10 2002/08/21 21:24:48 just 171: allow sectionN element nesting upto 8 levels 172: 173: Revision 1.9 2002/07/11 12:03:07 just 174: general cleanup 175: 176: Revision 1.8 2002/07/09 11:53:50 just 177: some fixes for term (dictionary) 178: 179: Revision 1.7 2002/07/07 21:49:18 just 180: cleanup text.dtd 181: 182: Revision 1.6 2002/07/05 23:56:00 just 183: introduction of page.dtd and page2html.xsl 184: 185: Revision 1.5 2002/07/04 15:35:34 just 186: comments 187: 188: Revision 1.4 2002/07/01 22:04:29 just 189: updates for refactoring 190: 191: Revision 1.3 2002/03/27 20:08:26 just 192: support for html escape with xhtml tag in text.dtd and text2html.xsl 193: 194: Revision 1.2 2001/12/13 10:13:35 just 195: various changes 196: 197: Revision 1.1 2001/12/11 14:05:35 just 198: new 199: 200: 201: -->

References

[W3C]
World Wide Web Consortium. http://www.w3c.org
[W3C-XML]
World Wide Web Consortium. Extensible Markup Language (XML) 1.0. W3C Recommendation; http://www.w3.org/TR/1998/REC-xml-19980210