+++ /dev/null
-<HTML
-><HEAD
-><TITLE
->A complete example: The readme DTD</TITLE
-><META
-NAME="GENERATOR"
-CONTENT="Modular DocBook HTML Stylesheet Version 1.46"><LINK
-REL="HOME"
-TITLE="The PXP user's guide"
-HREF="index.html"><LINK
-REL="UP"
-TITLE="What is XML?"
-HREF="c36.html"><LINK
-REL="PREVIOUS"
-TITLE="Highlights of XML"
-HREF="x107.html"><LINK
-REL="NEXT"
-TITLE="Using PXP"
-HREF="c533.html"><LINK
-REL="STYLESHEET"
-TYPE="text/css"
-HREF="markup.css"></HEAD
-><BODY
-CLASS="SECT1"
-BGCOLOR="#FFFFFF"
-TEXT="#000000"
-LINK="#0000FF"
-VLINK="#840084"
-ALINK="#0000FF"
-><DIV
-CLASS="NAVHEADER"
-><TABLE
-WIDTH="100%"
-BORDER="0"
-CELLPADDING="0"
-CELLSPACING="0"
-><TR
-><TH
-COLSPAN="3"
-ALIGN="center"
->The PXP user's guide</TH
-></TR
-><TR
-><TD
-WIDTH="10%"
-ALIGN="left"
-VALIGN="bottom"
-><A
-HREF="x107.html"
->Prev</A
-></TD
-><TD
-WIDTH="80%"
-ALIGN="center"
-VALIGN="bottom"
->Chapter 1. What is XML?</TD
-><TD
-WIDTH="10%"
-ALIGN="right"
-VALIGN="bottom"
-><A
-HREF="c533.html"
->Next</A
-></TD
-></TR
-></TABLE
-><HR
-ALIGN="LEFT"
-WIDTH="100%"></DIV
-><DIV
-CLASS="SECT1"
-><H1
-CLASS="SECT1"
-><A
-NAME="SECT.README.DTD"
->1.3. A complete example: The <I
-CLASS="EMPHASIS"
->readme</I
-> DTD</A
-></H1
-><P
->The reason for <I
-CLASS="EMPHASIS"
->readme</I
-> was that I often wrote two versions
-of files such as README and INSTALL which explain aspects of a distributed
-software archive; one version was ASCII-formatted, the other was written in
-HTML. Maintaining both versions means double amount of work, and changes
-of one version may be forgotten in the other version. To improve this situation
-I invented the <I
-CLASS="EMPHASIS"
->readme</I
-> DTD which allows me to maintain only
-one source written as XML document, and to generate the ASCII and the HTML
-version from it.</P
-><P
->In this section, I explain only the DTD. The <I
-CLASS="EMPHASIS"
->readme</I
-> DTD is
-contained in the <SPAN
-CLASS="ACRONYM"
->PXP</SPAN
-> distribution together with the two converters to
-produce ASCII and HTML. Another <A
-HREF="x738.html"
->section</A
-> of this manual describes the HTML
-converter.</P
-><P
->The documents have a simple structure: There are up to three levels of nested
-sections, paragraphs, item lists, footnotes, hyperlinks, and text emphasis. The
-outermost element has usually the type <TT
-CLASS="LITERAL"
->readme</TT
->, it is
-declared by
-
-<PRE
-CLASS="PROGRAMLISTING"
-><!ELEMENT readme (sect1+)>
-<!ATTLIST readme
- title CDATA #REQUIRED></PRE
->
-
-This means that this element contains one or more sections of the first level
-(element type <TT
-CLASS="LITERAL"
->sect1</TT
->), and that the element has a required
-attribute <TT
-CLASS="LITERAL"
->title</TT
-> containing character data (CDATA). Note that
-<TT
-CLASS="LITERAL"
->readme</TT
-> elements must not contain text data.</P
-><P
->The three levels of sections are declared as follows:
-
-<PRE
-CLASS="PROGRAMLISTING"
-><!ELEMENT sect1 (title,(sect2|p|ul)+)>
-
-<!ELEMENT sect2 (title,(sect3|p|ul)+)>
-
-<!ELEMENT sect3 (title,(p|ul)+)></PRE
->
-
-Every section has a <TT
-CLASS="LITERAL"
->title</TT
-> element as first subelement. After
-the title an arbitrary but non-empty sequence of inner sections, paragraphs and
-item lists follows. Note that the inner sections must belong to the next higher
-section level; <TT
-CLASS="LITERAL"
->sect3</TT
-> elements must not contain inner
-sections because there is no next higher level.</P
-><P
->Obviously, all three declarations allow paragraphs (<TT
-CLASS="LITERAL"
->p</TT
->) and
-item lists (<TT
-CLASS="LITERAL"
->ul</TT
->). The definition can be simplified at this
-point by using a parameter entity:
-
-<PRE
-CLASS="PROGRAMLISTING"
-><!ENTITY % p.like "p|ul">
-
-<!ELEMENT sect1 (title,(sect2|%p.like;)+)>
-
-<!ELEMENT sect2 (title,(sect3|%p.like;)+)>
-
-<!ELEMENT sect3 (title,(%p.like;)+)></PRE
->
-
-Here, the entity <TT
-CLASS="LITERAL"
->p.like</TT
-> is nothing but a macro abbreviating
-the same sequence of declarations; if new elements on the same level as
-<TT
-CLASS="LITERAL"
->p</TT
-> and <TT
-CLASS="LITERAL"
->ul</TT
-> are later added, it is
-sufficient only to change the entity definition. Note that there are some
-restrictions on the usage of entities in this context; most important, entities
-containing a left paranthesis must also contain the corresponding right
-paranthesis. </P
-><P
->Note that the entity <TT
-CLASS="LITERAL"
->p.like</TT
-> is a
-<I
-CLASS="EMPHASIS"
->parameter</I
-> entity, i.e. the ENTITY declaration contains a
-percent sign, and the entity is referred to by
-<TT
-CLASS="LITERAL"
->%p.like;</TT
->. This kind of entity must be used to abbreviate
-parts of the DTD; the <I
-CLASS="EMPHASIS"
->general</I
-> entities declared without
-percent sign and referred to as <TT
-CLASS="LITERAL"
->&name;</TT
-> are not allowed
-in this context.</P
-><P
->The <TT
-CLASS="LITERAL"
->title</TT
-> element specifies the title of the section in
-which it occurs. The title is given as character data, optionally interspersed
-with line breaks (<TT
-CLASS="LITERAL"
->br</TT
->):
-
-<PRE
-CLASS="PROGRAMLISTING"
-><!ELEMENT title (#PCDATA|br)*></PRE
->
-
-Compared with the <TT
-CLASS="LITERAL"
->title</TT
-> <I
-CLASS="EMPHASIS"
->attribute</I
-> of
-the <TT
-CLASS="LITERAL"
->readme</TT
-> element, this element allows inner markup
-(i.e. <TT
-CLASS="LITERAL"
->br</TT
->) while attribute values do not: It is an error if
-an attribute value contains the left angle bracket < literally such that it
-is impossible to include inner elements. </P
-><P
->The paragraph element <TT
-CLASS="LITERAL"
->p</TT
-> has a structure similar to
-<TT
-CLASS="LITERAL"
->title</TT
->, but it allows more inner elements:
-
-<PRE
-CLASS="PROGRAMLISTING"
-><!ENTITY % text "br|code|em|footnote|a">
-
-<!ELEMENT p (#PCDATA|%text;)*></PRE
->
-
-Line breaks do not have inner structure, so they are declared as being empty:
-
-<PRE
-CLASS="PROGRAMLISTING"
-><!ELEMENT br EMPTY></PRE
->
-
-This means that really nothing is allowed within <TT
-CLASS="LITERAL"
->br</TT
->; you
-must always write <TT
-CLASS="LITERAL"
-><br></br></TT
-> or abbreviated
-<TT
-CLASS="LITERAL"
-><br/></TT
->.</P
-><P
->Code samples should be marked up by the <TT
-CLASS="LITERAL"
->code</TT
-> tag; emphasized
-text can be indicated by <TT
-CLASS="LITERAL"
->em</TT
->:
-
-<PRE
-CLASS="PROGRAMLISTING"
-><!ELEMENT code (#PCDATA)>
-
-<!ELEMENT em (#PCDATA|%text;)*></PRE
->
-
-That <TT
-CLASS="LITERAL"
->code</TT
-> elements are not allowed to contain further markup
-while <TT
-CLASS="LITERAL"
->em</TT
-> elements do is a design decision by the author of
-the DTD.</P
-><P
->Unordered lists simply consists of one or more list items, and a list item may
-contain paragraph-level material:
-
-<PRE
-CLASS="PROGRAMLISTING"
-><!ELEMENT ul (li+)>
-
-<!ELEMENT li (%p.like;)*></PRE
->
-
-Footnotes are described by the text of the note; this text may contain
-text-level markup. There is no mechanism to describe the numbering scheme of
-footnotes, or to specify how footnote references are printed.
-
-<PRE
-CLASS="PROGRAMLISTING"
-><!ELEMENT footnote (#PCDATA|%text;)*></PRE
->
-
-Hyperlinks are written as in HTML. The anchor tag contains the text describing
-where the link points to, and the <TT
-CLASS="LITERAL"
->href</TT
-> attribute is the
-pointer (as URL). There is no way to describe locations of "hash marks". If the
-link refers to another <I
-CLASS="EMPHASIS"
->readme</I
-> document, the attribute
-<TT
-CLASS="LITERAL"
->readmeref</TT
-> should be used instead of <TT
-CLASS="LITERAL"
->href</TT
->.
-The reason is that the converted document has usually a different system
-identifier (file name), and the link to a converted document must be
-converted, too.
-
-<PRE
-CLASS="PROGRAMLISTING"
-><!ELEMENT a (#PCDATA)*>
-<!ATTLIST a
- href CDATA #IMPLIED
- readmeref CDATA #IMPLIED
-></PRE
->
-
-Note that although it is only sensible to specify one of the two attributes,
-the DTD has no means to express this restriction.</P
-><P
->So far the DTD. Finally, here is a document for it:
-
-<PRE
-CLASS="PROGRAMLISTING"
-><?xml version="1.0" encoding="ISO-8859-1"?>
-<!DOCTYPE readme SYSTEM "readme.dtd">
-<readme title="How to use the readme converters">
-<sect1>
- <title>Usage</title>
- <p>
- The <em>readme</em> converter is invoked on the command line by:
- </p>
- <p>
- <code>readme [ -text | -html ] input.xml</code>
- </p>
- <p>
- Here a list of options:
- </p>
- <ul>
- <li>
- <p><code>-text</code>: specifies that ASCII output should be produced</p>
- </li>
- <li>
- <p><code>-html</code>: specifies that HTML output should be produced</p>
- </li>
- </ul>
- <p>
- The input file must be given on the command line. The converted output is
- printed to <em>stdout</em>.
- </p>
-</sect1>
-<sect1>
- <title>Author</title>
- <p>
- The program has been written by
- <a href="mailto:Gerd.Stolpmann@darmstadt.netsurf.de">Gerd Stolpmann</a>.
- </p>
-</sect1>
-</readme></PRE
-> </P
-></DIV
-><DIV
-CLASS="NAVFOOTER"
-><HR
-ALIGN="LEFT"
-WIDTH="100%"><TABLE
-WIDTH="100%"
-BORDER="0"
-CELLPADDING="0"
-CELLSPACING="0"
-><TR
-><TD
-WIDTH="33%"
-ALIGN="left"
-VALIGN="top"
-><A
-HREF="x107.html"
->Prev</A
-></TD
-><TD
-WIDTH="34%"
-ALIGN="center"
-VALIGN="top"
-><A
-HREF="index.html"
->Home</A
-></TD
-><TD
-WIDTH="33%"
-ALIGN="right"
-VALIGN="top"
-><A
-HREF="c533.html"
->Next</A
-></TD
-></TR
-><TR
-><TD
-WIDTH="33%"
-ALIGN="left"
-VALIGN="top"
->Highlights of XML</TD
-><TD
-WIDTH="34%"
-ALIGN="center"
-VALIGN="top"
-><A
-HREF="c36.html"
->Up</A
-></TD
-><TD
-WIDTH="33%"
-ALIGN="right"
-VALIGN="top"
->Using <SPAN
-CLASS="ACRONYM"
->PXP</SPAN
-></TD
-></TR
-></TABLE
-></DIV
-></BODY
-></HTML
->
\ No newline at end of file