--- /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
projects / helm.git / blobdiff