The reason for readme 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 readme DTD which allows me to maintain only -one source written as XML document, and to generate the ASCII and the HTML -version from it.
In this section, I explain only the DTD. The readme DTD is -contained in the PXP distribution together with the two converters to -produce ASCII and HTML. Another section of this manual describes the HTML -converter.
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 readme, it is -declared by - -
<!ELEMENT readme (sect1+)> -<!ATTLIST readme - title CDATA #REQUIRED>- -This means that this element contains one or more sections of the first level -(element type sect1), and that the element has a required -attribute title containing character data (CDATA). Note that -readme elements must not contain text data.
The three levels of sections are declared as follows: - -
<!ELEMENT sect1 (title,(sect2|p|ul)+)> - -<!ELEMENT sect2 (title,(sect3|p|ul)+)> - -<!ELEMENT sect3 (title,(p|ul)+)>- -Every section has a title 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; sect3 elements must not contain inner -sections because there is no next higher level.
Obviously, all three declarations allow paragraphs (p) and -item lists (ul). The definition can be simplified at this -point by using a parameter entity: - -
<!ENTITY % p.like "p|ul"> - -<!ELEMENT sect1 (title,(sect2|%p.like;)+)> - -<!ELEMENT sect2 (title,(sect3|%p.like;)+)> - -<!ELEMENT sect3 (title,(%p.like;)+)>- -Here, the entity p.like is nothing but a macro abbreviating -the same sequence of declarations; if new elements on the same level as -p and ul 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.
Note that the entity p.like is a -parameter entity, i.e. the ENTITY declaration contains a -percent sign, and the entity is referred to by -%p.like;. This kind of entity must be used to abbreviate -parts of the DTD; the general entities declared without -percent sign and referred to as &name; are not allowed -in this context.
The title element specifies the title of the section in -which it occurs. The title is given as character data, optionally interspersed -with line breaks (br): - -
<!ELEMENT title (#PCDATA|br)*>- -Compared with the title attribute of -the readme element, this element allows inner markup -(i.e. br) 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.
The paragraph element p has a structure similar to -title, but it allows more inner elements: - -
<!ENTITY % text "br|code|em|footnote|a"> - -<!ELEMENT p (#PCDATA|%text;)*>- -Line breaks do not have inner structure, so they are declared as being empty: - -
<!ELEMENT br EMPTY>- -This means that really nothing is allowed within br; you -must always write <br></br> or abbreviated -<br/>.
Code samples should be marked up by the code tag; emphasized -text can be indicated by em: - -
<!ELEMENT code (#PCDATA)> - -<!ELEMENT em (#PCDATA|%text;)*>- -That code elements are not allowed to contain further markup -while em elements do is a design decision by the author of -the DTD.
Unordered lists simply consists of one or more list items, and a list item may -contain paragraph-level material: - -
<!ELEMENT ul (li+)> - -<!ELEMENT li (%p.like;)*>- -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. - -
<!ELEMENT footnote (#PCDATA|%text;)*>- -Hyperlinks are written as in HTML. The anchor tag contains the text describing -where the link points to, and the href attribute is the -pointer (as URL). There is no way to describe locations of "hash marks". If the -link refers to another readme document, the attribute -readmeref should be used instead of href. -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. - -
<!ELEMENT a (#PCDATA)*> -<!ATTLIST a - href CDATA #IMPLIED - readmeref CDATA #IMPLIED ->- -Note that although it is only sensible to specify one of the two attributes, -the DTD has no means to express this restriction.
So far the DTD. Finally, here is a document for it: - -
<?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>