helm/DEVEL/pxp/pxp/doc/manual/html/x468.html

   1 <HTML
   2 ><HEAD
   3 ><TITLE
   4 >A complete example: The readme DTD</TITLE
   5 ><META
   6 NAME="GENERATOR"
   7 CONTENT="Modular DocBook HTML Stylesheet Version 1.46"><LINK
   8 REL="HOME"
   9 TITLE="The PXP user's guide"
  10 HREF="index.html"><LINK
  11 REL="UP"
  12 TITLE="What is XML?"
  13 HREF="c36.html"><LINK
  14 REL="PREVIOUS"
  15 TITLE="Highlights of XML"
  16 HREF="x107.html"><LINK
  17 REL="NEXT"
  18 TITLE="Using PXP"
  19 HREF="c533.html"><LINK
  20 REL="STYLESHEET"
  21 TYPE="text/css"
  22 HREF="markup.css"></HEAD
  23 ><BODY
  24 CLASS="SECT1"
  25 BGCOLOR="#FFFFFF"
  26 TEXT="#000000"
  27 LINK="#0000FF"
  28 VLINK="#840084"
  29 ALINK="#0000FF"
  30 ><DIV
  31 CLASS="NAVHEADER"
  32 ><TABLE
  33 WIDTH="100%"
  34 BORDER="0"
  35 CELLPADDING="0"
  36 CELLSPACING="0"
  37 ><TR
  38 ><TH
  39 COLSPAN="3"
  40 ALIGN="center"
  41 >The PXP user's guide</TH
  42 ></TR
  43 ><TR
  44 ><TD
  45 WIDTH="10%"
  46 ALIGN="left"
  47 VALIGN="bottom"
  48 ><A
  49 HREF="x107.html"
  50 >Prev</A
  51 ></TD
  52 ><TD
  53 WIDTH="80%"
  54 ALIGN="center"
  55 VALIGN="bottom"
  56 >Chapter 1. What is XML?</TD
  57 ><TD
  58 WIDTH="10%"
  59 ALIGN="right"
  60 VALIGN="bottom"
  61 ><A
  62 HREF="c533.html"
  63 >Next</A
  64 ></TD
  65 ></TR
  66 ></TABLE
  67 ><HR
  68 ALIGN="LEFT"
  69 WIDTH="100%"></DIV
  70 ><DIV
  71 CLASS="SECT1"
  72 ><H1
  73 CLASS="SECT1"
  74 ><A
  75 NAME="SECT.README.DTD"
  76 >1.3. A complete example: The <I
  77 CLASS="EMPHASIS"
  78 >readme</I
  79 > DTD</A
  80 ></H1
  81 ><P
  82 >The reason for <I
  83 CLASS="EMPHASIS"
  84 >readme</I
  85 > was that I often wrote two versions
  86 of files such as README and INSTALL which explain aspects of a distributed
  87 software archive; one version was ASCII-formatted, the other was written in
  88 HTML. Maintaining both versions means double amount of work, and changes
  89 of one version may be forgotten in the other version. To improve this situation
  90 I invented the <I
  91 CLASS="EMPHASIS"
  92 >readme</I
  93 > DTD which allows me to maintain only
  94 one source written as XML document, and to generate the ASCII and the HTML
  95 version from it.</P
  96 ><P
  97 >In this section, I explain only the DTD. The <I
  98 CLASS="EMPHASIS"
  99 >readme</I
 100 > DTD is
 101 contained in the <SPAN
 102 CLASS="ACRONYM"
 103 >PXP</SPAN
 104 > distribution together with the two converters to
 105 produce ASCII and HTML. Another <A
 106 HREF="x738.html"
 107 >section</A
 108 > of this manual describes the HTML
 109 converter.</P
 110 ><P
 111 >The documents have a simple structure: There are up to three levels of nested
 112 sections, paragraphs, item lists, footnotes, hyperlinks, and text emphasis. The
 113 outermost element has usually the type <TT
 114 CLASS="LITERAL"
 115 >readme</TT
 116 >, it is
 117 declared by
 118
 119 <PRE
 120 CLASS="PROGRAMLISTING"
 121 >&#60;!ELEMENT readme (sect1+)&#62;
 122 &#60;!ATTLIST readme
 123           title CDATA #REQUIRED&#62;</PRE
 124 >
 125
 126 This means that this element contains one or more sections of the first level
 127 (element type <TT
 128 CLASS="LITERAL"
 129 >sect1</TT
 130 >), and that the element has a required
 131 attribute <TT
 132 CLASS="LITERAL"
 133 >title</TT
 134 > containing character data (CDATA). Note that
 135 <TT
 136 CLASS="LITERAL"
 137 >readme</TT
 138 > elements must not contain text data.</P
 139 ><P
 140 >The three levels of sections are declared as follows:
 141
 142 <PRE
 143 CLASS="PROGRAMLISTING"
 144 >&#60;!ELEMENT sect1 (title,(sect2|p|ul)+)&#62;
 145
 146 &#60;!ELEMENT sect2 (title,(sect3|p|ul)+)&#62;
 147
 148 &#60;!ELEMENT sect3 (title,(p|ul)+)&#62;</PRE
 149 >
 150
 151 Every section has a <TT
 152 CLASS="LITERAL"
 153 >title</TT
 154 > element as first subelement. After
 155 the title an arbitrary but non-empty sequence of inner sections, paragraphs and
 156 item lists follows. Note that the inner sections must belong to the next higher
 157 section level; <TT
 158 CLASS="LITERAL"
 159 >sect3</TT
 160 > elements must not contain inner
 161 sections because there is no next higher level.</P
 162 ><P
 163 >Obviously, all three declarations allow paragraphs (<TT
 164 CLASS="LITERAL"
 165 >p</TT
 166 >) and
 167 item lists (<TT
 168 CLASS="LITERAL"
 169 >ul</TT
 170 >). The definition can be simplified at this
 171 point by using a parameter entity:
 172
 173 <PRE
 174 CLASS="PROGRAMLISTING"
 175 >&#60;!ENTITY % p.like "p|ul"&#62;
 176
 177 &#60;!ELEMENT sect1 (title,(sect2|%p.like;)+)&#62;
 178
 179 &#60;!ELEMENT sect2 (title,(sect3|%p.like;)+)&#62;
 180
 181 &#60;!ELEMENT sect3 (title,(%p.like;)+)&#62;</PRE
 182 >
 183
 184 Here, the entity <TT
 185 CLASS="LITERAL"
 186 >p.like</TT
 187 > is nothing but a macro abbreviating
 188 the same sequence of declarations; if new elements on the same level as
 189 <TT
 190 CLASS="LITERAL"
 191 >p</TT
 192 > and <TT
 193 CLASS="LITERAL"
 194 >ul</TT
 195 > are later added, it is
 196 sufficient only to change the entity definition. Note that there are some
 197 restrictions on the usage of entities in this context; most important, entities
 198 containing a left paranthesis must also contain the corresponding right
 199 paranthesis. </P
 200 ><P
 201 >Note that the entity <TT
 202 CLASS="LITERAL"
 203 >p.like</TT
 204 > is a
 205 <I
 206 CLASS="EMPHASIS"
 207 >parameter</I
 208 > entity, i.e. the ENTITY declaration contains a
 209 percent sign, and the entity is referred to by
 210 <TT
 211 CLASS="LITERAL"
 212 >%p.like;</TT
 213 >. This kind of entity must be used to abbreviate
 214 parts of the DTD; the <I
 215 CLASS="EMPHASIS"
 216 >general</I
 217 > entities declared without
 218 percent sign and referred to as <TT
 219 CLASS="LITERAL"
 220 >&amp;name;</TT
 221 > are not allowed
 222 in this context.</P
 223 ><P
 224 >The <TT
 225 CLASS="LITERAL"
 226 >title</TT
 227 > element specifies the title of the section in
 228 which it occurs. The title is given as character data, optionally interspersed
 229 with line breaks (<TT
 230 CLASS="LITERAL"
 231 >br</TT
 232 >):
 233
 234 <PRE
 235 CLASS="PROGRAMLISTING"
 236 >&#60;!ELEMENT title (#PCDATA|br)*&#62;</PRE
 237 >
 238
 239 Compared with the <TT
 240 CLASS="LITERAL"
 241 >title</TT
 242 > <I
 243 CLASS="EMPHASIS"
 244 >attribute</I
 245 > of
 246 the <TT
 247 CLASS="LITERAL"
 248 >readme</TT
 249 > element, this element allows inner markup
 250 (i.e. <TT
 251 CLASS="LITERAL"
 252 >br</TT
 253 >) while attribute values do not: It is an error if
 254 an attribute value contains the left angle bracket &lt; literally such that it
 255 is impossible to include inner elements. </P
 256 ><P
 257 >The paragraph element <TT
 258 CLASS="LITERAL"
 259 >p</TT
 260 > has a structure similar to
 261 <TT
 262 CLASS="LITERAL"
 263 >title</TT
 264 >, but it allows more inner elements:
 265
 266 <PRE
 267 CLASS="PROGRAMLISTING"
 268 >&#60;!ENTITY % text "br|code|em|footnote|a"&#62;
 269
 270 &#60;!ELEMENT p (#PCDATA|%text;)*&#62;</PRE
 271 >
 272
 273 Line breaks do not have inner structure, so they are declared as being empty:
 274
 275 <PRE
 276 CLASS="PROGRAMLISTING"
 277 >&#60;!ELEMENT br EMPTY&#62;</PRE
 278 >
 279
 280 This means that really nothing is allowed within <TT
 281 CLASS="LITERAL"
 282 >br</TT
 283 >; you
 284 must always write <TT
 285 CLASS="LITERAL"
 286 >&#60;br&#62;&#60;/br&#62;</TT
 287 > or abbreviated
 288 <TT
 289 CLASS="LITERAL"
 290 >&#60;br/&#62;</TT
 291 >.</P
 292 ><P
 293 >Code samples should be marked up by the <TT
 294 CLASS="LITERAL"
 295 >code</TT
 296 > tag; emphasized
 297 text can be indicated by <TT
 298 CLASS="LITERAL"
 299 >em</TT
 300 >:
 301
 302 <PRE
 303 CLASS="PROGRAMLISTING"
 304 >&#60;!ELEMENT code (#PCDATA)&#62;
 305
 306 &#60;!ELEMENT em (#PCDATA|%text;)*&#62;</PRE
 307 >
 308
 309 That <TT
 310 CLASS="LITERAL"
 311 >code</TT
 312 > elements are not allowed to contain further markup
 313 while <TT
 314 CLASS="LITERAL"
 315 >em</TT
 316 > elements do is a design decision by the author of
 317 the DTD.</P
 318 ><P
 319 >Unordered lists simply consists of one or more list items, and a list item may
 320 contain paragraph-level material:
 321
 322 <PRE
 323 CLASS="PROGRAMLISTING"
 324 >&#60;!ELEMENT ul (li+)&#62;
 325
 326 &#60;!ELEMENT li (%p.like;)*&#62;</PRE
 327 >
 328
 329 Footnotes are described by the text of the note; this text may contain
 330 text-level markup. There is no mechanism to describe the numbering scheme of
 331 footnotes, or to specify how footnote references are printed.
 332
 333 <PRE
 334 CLASS="PROGRAMLISTING"
 335 >&#60;!ELEMENT footnote (#PCDATA|%text;)*&#62;</PRE
 336 >
 337
 338 Hyperlinks are written as in HTML. The anchor tag contains the text describing
 339 where the link points to, and the <TT
 340 CLASS="LITERAL"
 341 >href</TT
 342 > attribute is the
 343 pointer (as URL). There is no way to describe locations of "hash marks". If the
 344 link refers to another <I
 345 CLASS="EMPHASIS"
 346 >readme</I
 347 > document, the attribute
 348 <TT
 349 CLASS="LITERAL"
 350 >readmeref</TT
 351 > should be used instead of <TT
 352 CLASS="LITERAL"
 353 >href</TT
 354 >.
 355 The reason is that the converted document has usually a different system
 356 identifier (file name), and the link to a converted document must be
 357 converted, too.
 358
 359 <PRE
 360 CLASS="PROGRAMLISTING"
 361 >&#60;!ELEMENT a (#PCDATA)*&#62;
 362 &#60;!ATTLIST a
 363           href      CDATA #IMPLIED
 364           readmeref CDATA #IMPLIED
 365 &#62;</PRE
 366 >
 367
 368 Note that although it is only sensible to specify one of the two attributes,
 369 the DTD has no means to express this restriction.</P
 370 ><P
 371 >So far the DTD. Finally, here is a document for it:
 372
 373 <PRE
 374 CLASS="PROGRAMLISTING"
 375 >&#60;?xml version="1.0" encoding="ISO-8859-1"?&#62;
 376 &#60;!DOCTYPE readme SYSTEM "readme.dtd"&#62;
 377 &#60;readme title="How to use the readme converters"&#62;
 378 &#60;sect1&#62;
 379   &#60;title&#62;Usage&#60;/title&#62;
 380   &#60;p&#62;
 381     The &#60;em&#62;readme&#60;/em&#62; converter is invoked on the command line by:
 382   &#60;/p&#62;
 383   &#60;p&#62;
 384     &#60;code&#62;readme [ -text | -html ] input.xml&#60;/code&#62;
 385   &#60;/p&#62;
 386   &#60;p&#62;
 387     Here a list of options:
 388   &#60;/p&#62;
 389   &#60;ul&#62;
 390     &#60;li&#62;
 391       &#60;p&#62;&#60;code&#62;-text&#60;/code&#62;: specifies that ASCII output should be produced&#60;/p&#62;
 392     &#60;/li&#62;
 393     &#60;li&#62;
 394       &#60;p&#62;&#60;code&#62;-html&#60;/code&#62;: specifies that HTML output should be produced&#60;/p&#62;
 395     &#60;/li&#62;
 396   &#60;/ul&#62;
 397   &#60;p&#62;
 398     The input file must be given on the command line. The converted output is
 399     printed to &#60;em&#62;stdout&#60;/em&#62;.
 400   &#60;/p&#62;
 401 &#60;/sect1&#62;
 402 &#60;sect1&#62;
 403   &#60;title&#62;Author&#60;/title&#62;
 404   &#60;p&#62;
 405     The program has been written by
 406     &#60;a href="mailto:Gerd.Stolpmann@darmstadt.netsurf.de"&#62;Gerd Stolpmann&#60;/a&#62;.
 407   &#60;/p&#62;
 408 &#60;/sect1&#62;
 409 &#60;/readme&#62;</PRE
 410 >&#13;</P
 411 ></DIV
 412 ><DIV
 413 CLASS="NAVFOOTER"
 414 ><HR
 415 ALIGN="LEFT"
 416 WIDTH="100%"><TABLE
 417 WIDTH="100%"
 418 BORDER="0"
 419 CELLPADDING="0"
 420 CELLSPACING="0"
 421 ><TR
 422 ><TD
 423 WIDTH="33%"
 424 ALIGN="left"
 425 VALIGN="top"
 426 ><A
 427 HREF="x107.html"
 428 >Prev</A
 429 ></TD
 430 ><TD
 431 WIDTH="34%"
 432 ALIGN="center"
 433 VALIGN="top"
 434 ><A
 435 HREF="index.html"
 436 >Home</A
 437 ></TD
 438 ><TD
 439 WIDTH="33%"
 440 ALIGN="right"
 441 VALIGN="top"
 442 ><A
 443 HREF="c533.html"
 444 >Next</A
 445 ></TD
 446 ></TR
 447 ><TR
 448 ><TD
 449 WIDTH="33%"
 450 ALIGN="left"
 451 VALIGN="top"
 452 >Highlights of XML</TD
 453 ><TD
 454 WIDTH="34%"
 455 ALIGN="center"
 456 VALIGN="top"
 457 ><A
 458 HREF="c36.html"
 459 >Up</A
 460 ></TD
 461 ><TD
 462 WIDTH="33%"
 463 ALIGN="right"
 464 VALIGN="top"
 465 >Using <SPAN
 466 CLASS="ACRONYM"
 467 >PXP</SPAN
 468 ></TD
 469 ></TR
 470 ></TABLE
 471 ></DIV
 472 ></BODY
 473 ></HTML
 474 >