path: root/en_US.ISO8859-1/books/fdp-primer/sgml-primer/chapter.xml

<?xml version="1.0" encoding="iso-8859-1" standalone="no"?>
<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.

     Redistribution and use in source (SGML DocBook) and 'compiled' forms
     (SGML, HTML, PDF, PostScript, RTF and so forth) with or without
     modification, are permitted provided that the following conditions
     are met:

      1. Redistributions of source code (SGML DocBook) must retain the above
         copyright notice, this list of conditions and the following
         disclaimer as the first lines of this file unmodified.

      2. Redistributions in compiled form (transformed to other DTDs,
         converted to PDF, PostScript, RTF and other formats) must reproduce
         the above copyright notice, this list of conditions and the
         following disclaimer in the documentation and/or other materials
         provided with the distribution.

     THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
     IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
     OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
     DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
     INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
     (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
     SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
     HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
     STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
     ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
     POSSIBILITY OF SUCH DAMAGE.

     $FreeBSD$
-->

<chapter id="xml-primer">
  <title>XML Primer</title>

  <para>The majority of FDP documentation is written in applications
    of XML.  This chapter explains exactly what that means, how to
    read and understand the source to the documentation, and the sort
    of XML tricks you will see used in the documentation.</para>

  <para>Portions of this section were inspired by Mark Galassi's
    <ulink
      url="http://www.galassi.org/mark/mydocs/docbook-intro/docbook-intro.html">Get
      Going With DocBook</ulink>.</para>

  <sect1 id="xml-primer-overview">
    <title>Overview</title>

    <para>Way back when, electronic text was simple to deal with.
      Admittedly, you had to know which character set your document
      was written in (ASCII, EBCDIC, or one of a number of others) but
      that was about it.  Text was text, and what you saw really was
      what you got.  No frills, no formatting, no intelligence.</para>

    <para>Inevitably, this was not enough.  Once you have text in a
      machine-usable format, you expect machines to be able to use it
      and manipulate it intelligently.  You would like to indicate
      that certain phrases should be emphasized, or added to a
      glossary, or be hyperlinks.  You might want filenames to be
      shown in a <quote>typewriter</quote> style font for viewing on
      screen, but as <quote>italics</quote> when printed, or any of a
      myriad of other options for presentation.</para>

    <para>It was once hoped that Artificial Intelligence (AI) would
      make this easy.  Your computer would read in the document and
      automatically identify key phrases, filenames, text that the
      reader should type in, examples, and more.  Unfortunately, real
      life has not happened quite like that, and our computers require
      some assistance before they can meaningfully process our
      text.</para>

    <para>More precisely, they need help identifying what is what.
      Let's look at this text:</para>

    <blockquote>
      <para>To remove <filename>/tmp/foo</filename> use
	&man.rm.1;.</para>

      <screen>&prompt.user; <userinput>rm /tmp/foo</userinput></screen>
    </blockquote>

    <para>It is easy to see which parts are filenames, which are
      commands to be typed in, which parts are references to manual
      pages, and so on.  But the computer processing the document
      cannot.  For this we need markup.</para>

    <para><quote>Markup</quote> is commonly used to describe
      <quote>adding value</quote> or <quote>increasing cost</quote>.
      The term takes on both these meanings when applied to text.
      Markup is additional text included in the document,
      distinguished from the document's content in some way, so that
      programs that process the document can read the markup and use
      it when making decisions about the document.  Editors can hide
      the markup from the user, so the user is not distracted by
      it.</para>

    <para>The extra information stored in the markup <emphasis>adds
	value</emphasis> to the document.  Adding the markup to the
      document must typically be done by a person&mdash;after all, if
      computers could recognize the text sufficiently well to add the
      markup then there would be no need to add it in the first place.
      This <emphasis>increases the cost</emphasis> (i.e., the effort
      required) to create the document.</para>

    <para>The previous example is actually represented in this
      document like this:</para>

    <programlisting><![CDATA[
<para>To remove <filename>/tmp/foo</filename> use &man.rm.1;.</para>

<screen>&prompt.user; <userinput>rm /tmp/foo</userinput></screen>]]></programlisting>

    <para>As you can see, the markup is clearly separate from the
      content.</para>

    <para>Obviously, if you are going to use markup you need to define
      what your markup means, and how it should be interpreted.  You
      will need a markup language that you can follow when marking up
      your documents.</para>

    <para>Of course, one markup language might not be enough.  A
      markup language for technical documentation has very different
      requirements than a markup language that was to be used for
      cookery recipes.  This, in turn, would be very different from a
      markup language used to describe poetry.  What you really need
      is a first language that you use to write these other markup
      languages.  A <emphasis>meta markup language</emphasis>.</para>

    <para>This is exactly what the eXtensible Markup
      Language (XML) is.  Many markup languages have been written in
      XML, including the two most used by the FDP, XHTML and
      DocBook.</para>

    <para>Each language definition is more properly called a grammar,
      vocabulary, schema or Document Type Definition (DTD).  There
      are various languages to specify an XML grammar, for example,
      DTD (yes, it also means the specification language itself),
      XML Schema (XSD) or RELANG NG.  The schema specifies the name
      of the elements that can be used, what order they appear in (and
      whether some markup can be used inside other markup) and related
      information.</para>

    <para id="xml-primer-validating">A schema is a
      <emphasis>complete</emphasis> specification of all the elements
      that are allowed to appear, the order in which they should
      appear, which elements are mandatory, which are optional, and so
      forth.  This makes it possible to write an XML
      <emphasis>parser</emphasis> which reads in both the schema and a
      document which claims to conform to the schema.  The parser can
      then confirm whether or not all the elements required by the vocabulary
      are in the document in the right order, and whether there are
      any errors in the markup.  This is normally referred to as
      <quote>validating the document</quote>.</para>

    <note>
      <para>This processing simply confirms that the choice of
	elements, their ordering, and so on, conforms to that listed
	in the grammar.  It does <emphasis>not</emphasis> check that you
	have used <emphasis>appropriate</emphasis> markup for the
	content.  If you tried to mark up all the filenames in your
	document as function names, the parser would not flag this as
	an error (assuming, of course, that your schema defines elements
	for filenames and functions, and that they are allowed to
	appear in the same place).</para>
    </note>

    <para>It is likely that most of your contributions to the
      Documentation Project will consist of content marked up in
      either XHTML or DocBook, rather than alterations to the schemas.
      For this reason this book will not touch on how to write a
      vocabulary.</para>
  </sect1>

  <sect1 id="xml-primer-elements">
    <title>Elements, Tags, and Attributes</title>

    <para>All the vocabularies written in XML share certain characteristics.
      This is hardly surprising, as the philosophy behind XML will
      inevitably show through.  One of the most obvious manifestations
      of this philosophy is that of <emphasis>content</emphasis> and
      <emphasis>elements</emphasis>.</para>

    <para>Your documentation (whether it is a single web page, or a
      lengthy book) is considered to consist of content.  This content
      is then divided (and further subdivided) into elements.  The
      purpose of adding markup is to name and identify the boundaries
      of these elements for further processing.</para>

    <para>For example, consider a typical book.  At the very top
      level, the book is itself an element.  This <quote>book</quote>
      element obviously contains chapters, which can be considered to
      be elements in their own right.  Each chapter will contain more
      elements, such as paragraphs, quotations, and footnotes.  Each
      paragraph might contain further elements, identifying content
      that was direct speech, or the name of a character in the
      story.</para>

    <para>You might like to think of this as <quote>chunking</quote>
      content.  At the very top level you have one chunk, the book.
      Look a little deeper, and you have more chunks, the individual
      chapters.  These are chunked further into paragraphs, footnotes,
      character names, and so on.</para>

    <para>Notice how you can make this differentiation between
      different elements of the content without resorting to any XML
      terms.  It really is surprisingly straightforward.  You could do
      this with a highlighter pen and a printout of the book, using
      different colors to indicate different chunks of content.</para>

    <para>Of course, we do not have an electronic highlighter pen, so
      we need some other way of indicating which element each piece of
      content belongs to.  In languages written in XML (XHTML,
      DocBook, et al) this is done by means of
      <emphasis>tags</emphasis>.</para>

    <para>A tag is used to identify where a particular element starts,
      and where the element ends.  <emphasis>The tag is not part of
      the element itself</emphasis>. Because each grammar was normally
      written to mark up specific types of information, each one will
      recognize different elements, and will therefore have different
      names for the tags.</para>

    <para>For an element called
      <replaceable>element-name</replaceable> the start tag will
      normally look like
      <sgmltag><replaceable>element-name</replaceable></sgmltag>.  The
      corresponding closing tag for this element is
      <sgmltag>/<replaceable>element-name</replaceable></sgmltag>.</para>

    <example>
      <title>Using an Element (Start and End Tags)</title>

      <para>XHTML has an element for indicating that the content
	enclosed by the element is a paragraph, called
	<sgmltag>p</sgmltag>.</para>

      <programlisting><![CDATA[<p>This is a paragraph.  It starts with the start tag for
  the 'p' element, and it will end with the end tag for the 'p'
  element.</p>

<p>This is another paragraph.  But this one is much shorter.</p>]]></programlisting>
    </example>

    <para>Some elements have no
      content.  For example, in XHTML you can indicate that you want a
      horizontal line to appear in the document.</para>

    <para>For such elements, that have no content at all, XML introduced
      a shorthand form, which is ccompletely equivalent to the above
      form:</para>

    <programlisting><![CDATA[<hr/>]]></programlisting>

    <example>
      <title>Using an Element (Without Content)</title>

      <para>XHTML has an element for indicating a horizontal rule,
	called <sgmltag>hr</sgmltag>.  This element does not wrap
	content, so it looks like this.</para>

      <programlisting><![CDATA[<p>One paragraph.</p>
<hr></hr>

<p>This is another paragraph.  A horizontal rule separates this
  from the previous paragraph.</p>]]></programlisting>

      <para>For such elements, that have no content at all, XML introduced
	a shorthand form, which is ccompletely equivalent to the above
	form:</para>

      <programlisting><![CDATA[<p>One paragraph.</p>
<hr/>

<p>This is another paragraph.  A horizontal rule separates this
  from the previous paragraph.</p>]]></programlisting>
    </example>

    <para>If it is not obvious by now, elements can contain other
      elements.  In the book example earlier, the book element
      contained all the chapter elements, which in turn contained all
      the paragraph elements, and so on.</para>

    <example>
      <title>Elements within Elements; <sgmltag>em</sgmltag></title>

      <programlisting><![CDATA[<p>This is a simple <em>paragraph</em> where some
  of the <em>words</em> have been <em>emphasized</em>.</p>]]></programlisting>
    </example>

    <para>The grammar will specify the rules detailing which elements can
      contain other elements, and exactly what they can
      contain.</para>

    <important>
      <para>People often confuse the terms tags and elements, and use
	the terms as if they were interchangeable.  They are
	not.</para>

      <para>An element is a conceptual part of your document.  An
	element has a defined start and end.  The tags mark where the
	element starts and end.</para>

      <para>When this document (or anyone else knowledgeable about
	XML) refers to <quote>the <sgmltag>p</sgmltag> tag</quote>
	they mean the literal text consisting of the three characters
	<literal>&lt;</literal>, <literal>p</literal>, and
	<literal>&gt;</literal>.  But the phrase <quote>the
	  <sgmltag>p</sgmltag> element</quote> refers to the whole
	element.</para>

      <para>This distinction <emphasis>is</emphasis> very subtle.  But
	keep it in mind.</para>
    </important>

    <para>Elements can have attributes.  An attribute has a name and a
      value, and is used for adding extra information to the element.
      This might be information that indicates how the content should
      be rendered, or might be something that uniquely identifies that
      occurrence of the element, or it might be something else.</para>

    <para>An element's attributes are written
      <emphasis>inside</emphasis> the start tag for that element, and
      take the form
      <literal><replaceable>attribute-name</replaceable>="<replaceable>attribute-value</replaceable>"</literal>.</para>

    <para>In XHTML, the
      <sgmltag>p</sgmltag> element has an attribute called
      <sgmltag>align</sgmltag>, which suggests an alignment
      (justification) for the paragraph to the program displaying the
      XHTML.</para>

    <para>The <literal>align</literal> attribute can take one of four
      defined values, <literal>left</literal>,
      <literal>center</literal>, <literal>right</literal> and
      <literal>justify</literal>.  If the attribute is not specified
      then the default is <literal>left</literal>.</para>

    <example>
      <title>Using An Element with An Attribute</title>

      <programlisting><![CDATA[<p align="left">The inclusion of the align attribute
  on this paragraph was superfluous, since the default is left.</p>

<p align="center">This may appear in the center.</p>]]></programlisting>
    </example>

    <para>Some attributes will only take specific values, such as
      <literal>left</literal> or <literal>justify</literal>.  Others
      will allow you to enter anything you want.</para>

    <example>
      <title>Single Quotes Around Attributes</title>

      <programlisting><![CDATA[<p align='right'>I am on the right!</p>]]></programlisting>
    </example>

    <para>XML requires you to quote each attribute value with either
      single or double quotes.  It is more habitual to use double quotes
      but you may use single quotes, as well.  Using single quotes is
      practical if you want to include double quotes in the attribute
      value.</para>

    <para>The information on attributes, elements, and tags is stored
      in XML catalogs.  The various Documentation Project tools use
      these catalog files to validate your work.  The tools in
      <filename role="package">textproc/docproj</filename> include a
      variety of XML catalog files.  The FreeBSD Documentation
      Project includes its own set of catalog files.  Your tools need
      to know about both sorts of catalog files.</para>

    <sect2>
      <title>For You to Do&hellip;</title>

      <para>In order to run the examples in this document you will
	need to install some software on your system and ensure that
	an environment variable is set correctly.</para>

      <procedure>
	<step>
	  <para>Download and install
	    <filename role="package">textproc/docproj</filename> from
	    the FreeBSD ports system.  This is a
	    <emphasis>meta-port</emphasis> that should download and
	    install all of the programs and supporting files that are
	    used by the Documentation Project.</para>
	</step>

	<step>
	  <para>Add lines to your shell startup files to set
	    <envar>SGML_CATALOG_FILES</envar>. (If you are not working
	    on the English version of the documentation, you will want
	    to substitute the correct directory for your
	    language.)</para>

	  <example id="xml-primer-envars">
	    <title><filename>.profile</filename>, for &man.sh.1; and
	      &man.bash.1; Users</title>

	    <programlisting>SGML_ROOT=/usr/local/share/xml
SGML_CATALOG_FILES=${SGML_ROOT}/jade/catalog
SGML_CATALOG_FILES=${SGML_ROOT}/docbook/4.1/catalog:$SGML_CATALOG_FILES
SGML_CATALOG_FILES=${SGML_ROOT}/html/catalog:$SGML_CATALOG_FILES
SGML_CATALOG_FILES=${SGML_ROOT}/iso8879/catalog:$SGML_CATALOG_FILES
SGML_CATALOG_FILES=/usr/doc/share/xml/catalog:$SGML_CATALOG_FILES
SGML_CATALOG_FILES=/usr/doc/en_US.ISO8859-1/share/xml/catalog:$SGML_CATALOG_FILES
export SGML_CATALOG_FILES</programlisting>
	  </example>

	  <example>
	    <title><filename>.cshrc</filename>, for &man.csh.1; and
	      &man.tcsh.1; Users</title>

	    <programlisting>setenv SGML_ROOT /usr/local/share/xml
setenv SGML_CATALOG_FILES ${SGML_ROOT}/jade/catalog
setenv SGML_CATALOG_FILES ${SGML_ROOT}/docbook/4.1/catalog:$SGML_CATALOG_FILES
setenv SGML_CATALOG_FILES ${SGML_ROOT}/html/catalog:$SGML_CATALOG_FILES
setenv SGML_CATALOG_FILES ${SGML_ROOT}/iso8879/catalog:$SGML_CATALOG_FILES
setenv SGML_CATALOG_FILES /usr/doc/share/xml/catalog:$SGML_CATALOG_FILES
setenv SGML_CATALOG_FILES /usr/doc/en_US.ISO8859-1/share/xml/catalog:$SGML_CATALOG_FILES</programlisting>
	  </example>

	  <para>Then either log out, and log back in again, or run
	    those commands from the command line to set the variable
	    values.</para>
	</step>
      </procedure>

      <procedure>
	<step>
	  <para>Create <filename>example.xml</filename>, and enter
	    the following text:</para>

	  <programlisting><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <title>An Example XHTML File</title>
  </head>

  <body>
    <p>This is a paragraph containing some text.</p>

    <p>This paragraph contains some more text.</p>

    <p align="right">This paragraph might be right-justified.</p>
  </body>
</html>]]></programlisting>
	</step>

	<step>
	  <para>Try to validate this file using an XML parser.</para>

	  <para>Part of
	    <filename role="package">textproc/docproj</filename> is
	    the <command>xmllint</command>
	    <link linkend="xml-primer-validating">validating
	      parser</link>.</para>

	  <para>Use <command>xmllint</command> in the following way to
	    check that your document is valid:</para>

	  <screen>&prompt.user; <userinput>xmllint --valid --noout example.xml</userinput></screen>

	  <para>As you will see, <command>xmllint</command> returns
	    without displaying any output.  This means that your
	    document validated successfully.</para>
	</step>

	<step>
	  <para>See what happens when required elements are omitted.
	    Try removing the <sgmltag>title</sgmltag> and
	    <sgmltag>/title</sgmltag> tags, and re-run the
	    validation.</para>

	  <screen>&prompt.user; <userinput>xmllint --valid --noout example.xml</userinput>
example.xml:5: element head: validity error : Element head content does not follow the DTD, expecting ((script | style | meta | link | object | isindex)* , ((title , (script | style | meta | link | object | isindex)* , (base , (script | style | meta | link | object | isindex)*)?) | (base , (script | style | meta | link | object | isindex)* , title , (script | style | meta | link | object | isindex)*))), got ()</screen>

	  <para>This line tells you that the validation error comes from
	    the <replaceable>fifth</replaceable> line of the
	    <replaceable>example.xml</replaceable> file and that the
	    content of the <sgmltag>head</sgmltag> is the part, which
	    does not follow the rules described by the XHTML grammar.</para>

	  <para>Below this line <command>xmllint</command> will show you
	    the line where the error has been found and will also mark the
	    exact character position with a ^ sign.</para>
	</step>

	<step>
	  <para>Put the <sgmltag>title</sgmltag> element back
	    in.</para>
	</step>
      </procedure>
    </sect2>
  </sect1>

  <sect1 id="xml-primer-doctype-declaration">
    <title>The DOCTYPE Declaration</title>

    <para>The beginning of each document that you write may specify
      the name of the DTD that the document conforms to in case you use
      the DTD specification language.  Other specification languages, like
      XML Schema and RELAX NG are not referred in the source document.
      This DOCTYPE declaration serves the XML parsers so that they can
      determine the DTD and ensure that the document does conform to it.</para>

    <para>A typical declaration for a document written to conform with
      version 1.0 of the XHTML DTD looks like this:</para>

    <programlisting><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">]]></programlisting>

    <para>That line contains a number of different components.</para>

    <variablelist>
      <varlistentry>
	<term><literal>&lt;!</literal></term>

	<listitem>
	  <para>Is the <emphasis>indicator</emphasis> that indicates
	    that this is an XML declaration.  This line is declaring
	    the document type.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><literal>DOCTYPE</literal></term>

	<listitem>
	  <para>Shows that this is an XML declaration for the
	    document type.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><literal>html</literal></term>

	<listitem>
	  <para>Names the first
	    <link linkend="xml-primer-elements">element</link> that
	    will appear in the document.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><literal>PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"</literal></term>

	<listitem>
	  <para>Lists the Formal Public Identifier (FPI)
	    <indexterm>
	      <primary>Formal Public Identifier</primary>
	    </indexterm>
	    for the DTD that this document conforms to.  Your XML
	    parser will use this to find the correct DTD when
	    processing this document.</para>

	  <para><literal>PUBLIC</literal> is not a part of the FPI,
	    but indicates to the XML processor how to find the DTD
	    referenced in the FPI.  Other ways of telling the XML
	    parser how to find the DTD are shown <link
	      linkend="xml-primer-fpi-alternatives">later</link>.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><literal>"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"</literal></term>

	<listitem>
          <para>A local filename or an URL to find the DTD.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><literal>&gt;</literal></term>

	<listitem>
	  <para>Returns to the document.</para>
	</listitem>
      </varlistentry>
    </variablelist>

    <sect2>
      <title>Formal Public Identifiers (FPIs)
	<indexterm significance="preferred">
	  <primary>Formal Public Identifier</primary>
	</indexterm></title>

      <note>
	<para>You do not need to know this, but it is useful
	  background, and might help you debug problems when your XML
	  processor can not locate the DTD you are using.</para>
      </note>

      <para>FPIs must follow a specific syntax.  This syntax is as
	follows:</para>

      <programlisting>"<replaceable>Owner</replaceable>//<replaceable>Keyword</replaceable> <replaceable>Description</replaceable>//<replaceable>Language</replaceable>"</programlisting>

      <variablelist>
	<varlistentry>
	  <term><replaceable>Owner</replaceable></term>

	  <listitem>
	    <para>This indicates the owner of the FPI.</para>

	    <para>If this string starts with <quote>ISO</quote> then
	      this is an ISO owned FPI.  For example, the FPI
	      <literal>"ISO 8879:1986//ENTITIES Greek
		Symbols//EN"</literal> lists
	      <literal>ISO 8879:1986</literal> as being the owner for
	      the set of entities for Greek symbols.  ISO 8879:1986 is
	      the ISO number for the SGML standard, the predecessor
	      (and a superset) of XML.</para>

	    <para>Otherwise, this string will either look like
	      <literal>-//<replaceable>Owner</replaceable></literal>
	      or
	      <literal>+//<replaceable>Owner</replaceable></literal>
	      (notice the only difference is the leading
	      <literal>+</literal> or <literal>-</literal>).</para>

	    <para>If the string starts with <literal>-</literal> then
	      the owner information is unregistered, with a
	      <literal>+</literal> it identifies it as being
	      registered.</para>

	    <para>ISO 9070:1991 defines how registered names are
	      generated; it might be derived from the number of an ISO
	      publication, an ISBN code, or an organization code
	      assigned according to ISO 6523.  In addition, a
	      registration authority could be created in order to
	      assign registered names.  The ISO council delegated this
	      to the American National Standards Institute
	      (ANSI).</para>

	    <para>Because the FreeBSD Project has not been registered
	      the owner string is <literal>-//FreeBSD</literal>.  And
	      as you can see, the W3C are not a registered owner
	      either.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><replaceable>Keyword</replaceable></term>

	  <listitem>
	    <para>There are several keywords that indicate the type of
	      information in the file.  Some of the most common
	      keywords are <literal>DTD</literal>,
	      <literal>ELEMENT</literal>, <literal>ENTITIES</literal>,
	      and <literal>TEXT</literal>. <literal>DTD</literal> is
	      used only for DTD files, <literal>ELEMENT</literal> is
	      usually used for DTD fragments that contain only entity
	      or element declarations.  <literal>TEXT</literal> is
	      used for XML content (text and tags).</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><replaceable>Description</replaceable></term>

	  <listitem>
	    <para>Any description you want to supply for the contents
	      of this file.  This may include version numbers or any
	      short text that is meaningful to you and unique for the
	      XML system.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><replaceable>Language</replaceable></term>

	  <listitem>
	    <para>This is an ISO two-character code that identifies
	      the native language for the file.  <literal>EN</literal>
	      is used for English.</para>
	  </listitem>
	</varlistentry>
      </variablelist>

      <sect3>
	<title><filename>catalog</filename> Files</title>

	<para>If you use the syntax above and process this document
	  using an XML processor, the processor will need to have
	  some way of turning the FPI into the name of the file on
	  your computer that contains the DTD.</para>

	<para>In order to do this it can use a catalog file.  A
	  catalog file (typically called <filename>catalog</filename>)
	  contains lines that map FPIs to filenames.  For example, if
	  the catalog file contained the line:</para>

<!-- XXX: mention XML catalog or maybe replace this totally and only cover XML catalog -->

	<programlisting>PUBLIC  "-//W3C//DTD XHTML 1.0 Transitional//EN"             "1.0/transitional.dtd"</programlisting>

	<para>The XML processor would know to look up the DTD from
	  <filename>transitional.dtd</filename> in the
	  <filename>1.0</filename> subdirectory of whichever directory
	  held the <filename>catalog</filename> file that contained
	  that line.</para>

	<para>Look at the contents of
	  <filename>/usr/local/share/xml/dtd/xhtml/catalog.xml</filename>.
	  This is the catalog file for the XHTML DTDs that will have
	  been installed as part of the <filename
	    role="package">textproc/docproj</filename> port.</para>
      </sect3>

      <sect3>
	<title><envar>SGML_CATALOG_FILES</envar></title>

	<para>In order to locate a <filename>catalog</filename> file,
	  your XML processor will need to know where to look.  Many
	  of them feature command line parameters for specifying the
	  path to one or more catalogs.</para>

	<para>In addition, you can set
	  <envar>SGML_CATALOG_FILES</envar> to point to the files.
	  This environment variable should consist of a
	  colon-separated list of catalog files (including their full
	  path).</para>

	<para>Typically, you will want to include the following
	  files:</para>

	<itemizedlist>
	  <listitem>
	    <para><filename>/usr/local/share/xml/docbook/4.1/catalog</filename></para>
	  </listitem>

	  <listitem>
	    <para><filename>/usr/local/share/xml/html/catalog</filename></para>
	  </listitem>

	  <listitem>
	    <para><filename>/usr/local/share/xml/iso8879/catalog</filename></para>
	  </listitem>

	  <listitem>
	    <para><filename>/usr/local/share/xml/jade/catalog</filename></para>
	  </listitem>
	</itemizedlist>

	<para>You should <link linkend="xml-primer-envars">already
	    have done this</link>.</para>
      </sect3>
    </sect2>

    <sect2 id="xml-primer-fpi-alternatives">
      <title>Alternatives to FPIs</title>

      <para>Instead of using an FPI to indicate the DTD that the
	document conforms to (and therefore, which file on the system
	contains the DTD) you can explicitly specify the name of the
	file.</para>

      <para>The syntax for this is slightly different:</para>

      <programlisting><![CDATA[<!DOCTYPE html SYSTEM "/path/to/file.dtd">]]></programlisting>

      <para>The <literal>SYSTEM</literal> keyword indicates that the
	XML processor should locate the DTD in a system specific
	fashion.  This typically (but not always) means the DTD will
	be provided as a filename.</para>

      <para>Using FPIs is preferred for reasons of portability.  You
	do not want to have to ship a copy of the DTD around with your
	document, and if you used the <literal>SYSTEM</literal>
	identifier then everyone would need to keep their DTDs in the
	same place.</para>
    </sect2>
  </sect1>

  <sect1 id="xml-primer-xml-escape">
    <title>Escaping Back to SGML</title>

    <para>As mentioned earlier, XML is only used when writing a DTD.
      This is not strictly true.  There is certain XML syntax that
      you will want to be able to use within your documents.  For
      example, comments can be included in your document, and will be
      ignored by the parser.  Comments are entered using XML syntax.
      Other uses for XML syntax in your document will be shown later
      too.</para>

    <para>Obviously, you need some way of indicating to the XML
      processor that the following content is not elements within the
      document, but is XML that the parser should act upon.</para>

    <para>These sections are marked by
      <literal>&lt;! ... &gt;</literal> in your document.  Everything
      between these delimiters is XML syntax as you might find within
      a DTD.</para>

    <para>As you may just have realized, the
      <link linkend="xml-primer-doctype-declaration">DOCTYPE
	declaration</link> is an example of XML syntax that you need
      to include in your document&hellip;</para>
  </sect1>

  <sect1 id="xml-primer-comments">
    <title>Comments</title>

    <para>Comments are an XML construction, and are normally only
      valid inside a DTD.  However, as
      <xref linkend="xml-primer-xml-escape"/> shows, it is possible
      to use XML syntax within your document.</para>

    <para>The delimiter for XML comments is the string
      <quote><literal>--</literal></quote>.  The first occurrence of
      this string opens a comment, and the second closes it.</para>

    <example>
      <title>XML Generic Comment</title>

      <programlisting>&lt;!-- test comment --></programlisting>

      <programlisting><![CDATA[
<!-- This is inside the comment -->

<!-- This is another comment    -->

<!-- This is one way
     of doing multiline comments -->

<!-- This is another way of   --
  -- doing multiline comments -->]]></programlisting>
    </example>

    <![%output.print;[
    <important>
      <title>Use 2 Dashes</title>

      <para>There is a problem with producing the Postscript and PDF
	versions of this document.  The above example probably shows
	just one hyphen symbol, <literal>-</literal> after the
	<literal>&lt;!</literal> and before the
	<literal>&gt;</literal>.</para>

      <para>You <emphasis>must</emphasis> use two
	<literal>-</literal>, <emphasis>not</emphasis> one.  The
	Postscript and PDF versions have translated the two
	<literal>-</literal> in the original to a longer, more
	professional <emphasis>em-dash</emphasis>, and broken this
	example in the process.</para>

      <para>The XHTML, plain text, and RTF versions of this document
	are not affected.</para>
    </important>
    ]]>

    <para>If you have used XHTML before you may have been shown
      different rules for comments.  In particular, you may think that
      the string <literal>&lt;!--</literal> opens a comment, and it is
      only closed by <literal>--&gt;</literal>.</para>

    <para>This is <emphasis>not</emphasis> the case.  A lot of web
      browsers have broken XHTML parsers, and will accept that as
      valid.  However, the XML parsers used by the Documentation
      Project are much stricter, and will reject documents that make
      that error.</para>

    <example>
      <title>Erroneous XML Comments</title>

      <programlisting><![CDATA[
<!-- This is in the comment --

     THIS IS OUTSIDE THE COMMENT!

  -- back inside the comment -->]]></programlisting>

      <para>The XML parser will treat this as though it were
	actually:</para>

      <programlisting>&lt;!THIS IS OUTSIDE THE COMMENT&gt;</programlisting>

      <para>This is not valid XML, and may give confusing error
	messages.</para>

      <programlisting><![CDATA[<!--------------- This is a very bad idea --------------->]]></programlisting>

      <para>As the example suggests, <emphasis>do not</emphasis> write
	comments like that.</para>

      <programlisting><![CDATA[<!--===================================================-->]]></programlisting>

      <para>That is a (slightly) better approach, but it still
	potentially confusing to people new to XML.</para>
    </example>

    <sect2>
      <title>For You to Do&hellip;</title>

      <procedure>
	<step>
	  <para>Add some comments to
	    <filename>example.xml</filename>, and check that the file
	    still validates using <command>xmllint</command>.</para>
	</step>

	<step>
	  <para>Add some invalid comments to
	    <filename>example.xml</filename>, and see the error
	    messages that <command>xmllint</command> gives when it
	    encounters an invalid comment.</para>
	</step>
      </procedure>
    </sect2>
  </sect1>

  <sect1 id="xml-primer-entities">
    <title>Entities</title>

    <para>Entities are a mechanism for assigning names to chunks of
      content.  As an XML parser processes your document, any
      entities it finds are replaced by the content of the
      entity.</para>

    <para>This is a good way to have re-usable, easily changeable
      chunks of content in your XML documents.  It is also the only
      way to include one marked up file inside another using
      XML.</para>

    <para>There are two types of entities which can be used in two
      different situations; <emphasis>general entities</emphasis> and
      <emphasis>parameter entities</emphasis>.</para>

    <sect2 id="xml-primer-general-entities">
      <title>General Entities</title>

      <para>You cannot use general entities in an XML context
	(although you define them in one).  They can only be used in
	your document.  Contrast this with <link
	  linkend="xml-primer-parameter-entities">parameter
	  entities</link>.</para>

      <para>Each general entity has a name.  When you want to
	reference a general entity (and therefore include whatever
	text it represents in your document), you write
	<literal>&amp;<replaceable>entity-name</replaceable>;</literal>.
	For example, suppose you had an entity called
	<literal>current.version</literal> which expanded to the
	current version number of your product.  You could
	write:</para>

      <programlisting><![CDATA[<para>The current version of our product is
  &current.version;.</para>]]></programlisting>

      <para>When the version number changes you can simply change the
	definition of the value of the general entity and reprocess
	your document.</para>

      <para>You can also use general entities to enter characters that
	you could not otherwise include in an XML document.  For
	example, <literal>&lt;</literal> and <literal>&amp;</literal>
	cannot normally appear in an XML document.  When the XML
	parser sees the <literal>&lt;</literal> symbol it assumes that
	a tag (either a start tag or an end tag) is about to appear,
	and when it sees the <literal>&amp;</literal> symbol it
	assumes the next text will be the name of an entity.</para>

      <para>Fortunately, you can use the two general entities
	<literal>&amp;lt;</literal> and <literal>&amp;amp;</literal>
	whenever you need to include one or other of these.</para>

      <para>A general entity can only be defined within an XML
	context.  Typically, this is done immediately after the
	DOCTYPE declaration.</para>

      <example>
	<title>Defining General Entities</title>

	<programlisting><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [
<!ENTITY current.version    "3.0-RELEASE">
<!ENTITY last.version       "2.2.7-RELEASE">
]>]]></programlisting>

	<para>Notice how the DOCTYPE declaration has been extended by
	  adding a square bracket at the end of the first line.  The
	  two entities are then defined over the next two lines,
	  before the square bracket is closed, and then the DOCTYPE
	  declaration is closed.</para>

	<para>The square brackets are necessary to indicate that we
	  are extending the DTD indicated by the DOCTYPE
	  declaration.</para>
      </example>
    </sect2>

    <sect2 id="xml-primer-parameter-entities">
      <title>Parameter Entities</title>

      <para>Like <link linkend="xml-primer-general-entities">general
	  entities</link>, parameter entities are used to assign names
	to reusable chunks of text.  However, whereas general entities
	can only be used within your document, parameter entities can
	only be used within an <link
	  linkend="xml-primer-xml-escape">XML
	  context</link>.</para>

      <para>Parameter entities are defined in a similar way to general
	entities.  However, instead of using
	<literal>&amp;<replaceable>entity-name</replaceable>;</literal>
	to refer to them, use
	<literal>%<replaceable>entity-name</replaceable>;</literal>
	<footnote><para><emphasis>P</emphasis>arameter entities use
	    the <emphasis>P</emphasis>ercent
	    symbol.</para></footnote>.  The definition also includes
	the <literal>%</literal> between the <literal>ENTITY</literal>
	keyword and the name of the entity.</para>

      <example>
	<title>Defining Parameter Entities</title>

	<programlisting><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [
<!ENTITY % param.some "some">
<!ENTITY % param.text "text">
<!ENTITY % param.new  "%param.some more %param.text">

<!-- %param.new now contains "some more text" -->
]>]]></programlisting>
      </example>

      <para>This may not seem particularly useful.  It will be.</para>
    </sect2>

    <sect2>
      <title>For You to Do&hellip;</title>

      <procedure>
	<step>
	  <para>Add a general entity to
	    <filename>example.xml</filename>.</para>

	  <programlisting><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [
<!ENTITY version "1.1">
]>

<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <title>An Example XHTML File</title>
  </head>

  <!-- You might well have some comments in here as well -->

  <body>
    <p>This is a paragraph containing some text.</p>

    <p>This paragraph contains some more text.</p>

    <p align="right">This paragraph might be right-justified.</p>

    <p>The current version of this document is: &version;</p>
  </body>
</html>]]></programlisting>
	</step>

	<step>
	  <para>Validate the document using
	    <command>xmllint</command>.</para>
	</step>

	<step>
	  <para>Load <filename>example.xml</filename> into your web
	    browser (you may need to copy it to
	    <filename>example.html</filename> before your browser
	    recognizes it as an XHTML document).</para>

	  <para>Unless your browser is very advanced, you will not see
	    the entity reference <literal>&amp;version;</literal>
	    replaced with the version number.  Most web browsers have
	    very simplistic parsers which do not handle XML DTD
	    constructs.  Furthermore, the closing <literal>]&lt;</literal>
	    of the XML context are not recognized properly by browser and
	    will probably be rendered.</para>
	</step>

	<step>
	  <para>The solution is to <emphasis>normalize</emphasis> your
	    document using an XML normalizer.  The normalizer reads
	    in valid XML and outputs equally valid XML which has
	    been transformed in some way.  One of the ways in which
	    the normalizer transforms the XML is to expand all the
	    entity references in the document, replacing the entities
	    with the text that they represent.</para>

	  <para>You can use <command>xmllint</command> to do
	    this.  It also has an option to drop the initial
	    DTD section so that the closing <literal>]&lt;</literal>
	    does not confuse browsers:</para>

	  <screen>&prompt.user; <userinput>xmllint --noent --dropdtd example.xml &gt; example.html</userinput></screen>

	  <para>You should find a normalized (i.e., entity references
	    expanded) copy of your document in
	    <filename>example.html</filename>, ready to load into your
	    web browser.</para>
	</step>
      </procedure>
    </sect2>
  </sect1>

  <sect1 id="xml-primer-include">
    <title>Using Entities to Include Files</title>

    <para>Entities (both
      <link linkend="xml-primer-general-entities">general</link> and
      <link linkend="xml-primer-parameter-entities">parameter</link>)
      are particularly useful when used to include one file inside
      another.</para>

    <sect2 id="xml-primer-include-using-gen-entities">
      <title>Using General Entities to Include Files</title>

      <para>Suppose you have some content for an XML book organized
	into files, one file per chapter, called
	<filename>chapter1.xml</filename>,
	<filename>chapter2.xml</filename>, and so forth, with a
	<filename>book.xml</filename> file that will contain these
	chapters.</para>

      <para>In order to use the contents of these files as the values
	for your entities, you declare them with the
	<literal>SYSTEM</literal> keyword.  This directs the XML
	parser to use the contents of the named file as the value of
	the entity.</para>

      <example>
	<title>Using General Entities to Include Files</title>

	<programlisting><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [
<!ENTITY chapter.1 SYSTEM "chapter1.xml">
<!ENTITY chapter.2 SYSTEM "chapter2.xml">
<!ENTITY chapter.3 SYSTEM "chapter3.xml">
<!-- And so forth -->
]>

<html xmlns="http://www.w3.org/1999/xhtml">
  <!-- Use the entities to load in the chapters -->

  &chapter.1;
  &chapter.2;
  &chapter.3;
</html>]]></programlisting>
      </example>

      <warning>
	<para>When using general entities to include other files
	  within a document, the files being included
	  (<filename>chapter1.xml</filename>,
	  <filename>chapter2.xml</filename>, and so on)
	  <emphasis>must not</emphasis> start with a DOCTYPE
	  declaration.  This is a syntax error because entities
	  are low-level constructs and they are resolved before
	  any parsing happens.</para>
      </warning>
    </sect2>

    <sect2>
      <title>Using Parameter Entities to Include Files</title>

      <para>Recall that parameter entities can only be used inside an
	XML context.  Why then would you want to include a file
	within an XML context?</para>

      <para>You can use this to ensure that you can reuse your general
	entities.</para>

      <para>Suppose that you had many chapters in your document, and
	you reused these chapters in two different books, each book
	organizing the chapters in a different fashion.</para>

      <para>You could list the entities at the top of each book, but
	this quickly becomes cumbersome to manage.</para>

      <para>Instead, place the general entity definitions inside one
	file, and use a parameter entity to include that file within
	your document.</para>

      <example>
	<title>Using Parameter Entities to Include Files</title>

	<para>First, place your entity definitions in a separate file,
	  called <filename>chapters.ent</filename>.  This file
	  contains the following:</para>

	<programlisting><![CDATA[<!ENTITY chapter.1 SYSTEM "chapter1.xml">
<!ENTITY chapter.2 SYSTEM "chapter2.xml">
<!ENTITY chapter.3 SYSTEM "chapter3.xml">]]></programlisting>

	<para>Now create a parameter entity to refer to the contents
	  of the file.  Then use the parameter entity to load the file
	  into the document, which will then make all the general
	  entities available for use.  Then use the general entities
	  as before:</para>

	<programlisting><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [
<!-- Define a parameter entity to load in the chapter general entities -->
<!ENTITY % chapters SYSTEM "chapters.ent">

<!-- Now use the parameter entity to load in this file -->
%chapters;
]>

<html xmlns="http://www.w3.org/1999/xhtml">
  &chapter.1;
  &chapter.2;
  &chapter.3;
</html>]]></programlisting>
      </example>
    </sect2>

    <sect2>
      <title>For You to Do&hellip;</title>

      <sect3>
	<title>Use General Entities to Include Files</title>

	<procedure>
	  <step>
	    <para>Create three files, <filename>para1.xml</filename>,
	      <filename>para2.xml</filename>, and
	      <filename>para3.xml</filename>.</para>

	    <para>Put content similar to the following in each
	      file:</para>

	    <programlisting><![CDATA[<p>This is the first paragraph.</p>]]></programlisting>
	  </step>

	  <step>
	    <para>Edit <filename>example.xml</filename> so that it
	      looks like this:</para>

	    <programlisting><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [
<!ENTITY version "1.1">
<!ENTITY para1 SYSTEM "para1.xml">
<!ENTITY para2 SYSTEM "para2.xml">
<!ENTITY para3 SYSTEM "para3.xml">
]>

<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <title>An Example XHTML File</title>
  </head>

  <body>
    <p>The current version of this document is: &version;</p>

    &para1;
    &para2;
    &para3;
  </body>
</html>]]></programlisting>
	  </step>

	  <step>
	    <para>Produce <filename>example.html</filename> by
	      normalizing <filename>example.xml</filename>.</para>

	    <screen>&prompt.user; <userinput>xmllint --dropdtd --noent example.xml &gt; example.html</userinput></screen>
	  </step>

	  <step>
	    <para>Load <filename>example.html</filename> into your web
	      browser, and confirm that the
	      <filename>para<replaceable>n</replaceable>.xml</filename>
	      files have been included in
	      <filename>example.html</filename>.</para>
	  </step>
	</procedure>
      </sect3>

      <sect3>
	<title>Use Parameter Entities to Include Files</title>

	<note>
	  <para>You must have taken the previous steps first.</para>
	</note>

	<procedure>
	  <step>
	    <para>Edit <filename>example.xml</filename> so that it
	      looks like this:</para>

	    <programlisting><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [
<!ENTITY % entities SYSTEM "entities.ent"> %entities;
]>

<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <title>An Example XHTML File</title>
  </head>

  <body>
    <p>The current version of this document is: &version;</p>

    &para1;
    &para2;
    &para3;
  </body>
</html>]]></programlisting>
	  </step>

	  <step>
	    <para>Create a new file,
	      <filename>entities.ent</filename>, with this
	      content:</para>

	    <programlisting><![CDATA[<!ENTITY version "1.1">
<!ENTITY para1 SYSTEM "para1.xml">
<!ENTITY para2 SYSTEM "para2.xml">
<!ENTITY para3 SYSTEM "para3.xml">]]></programlisting>
	  </step>

	  <step>
	    <para>Produce <filename>example.html</filename> by
	      normalizing <filename>example.xml</filename>.</para>

	    <screen>&prompt.user; <userinput>xmllint --dropdtd --noent example.xml &gt; example.html</userinput></screen>
	  </step>

	  <step>
	    <para>Load <filename>example.html</filename> into your web
	      browser, and confirm that the
	      <filename>para<replaceable>n</replaceable>.xml</filename>
	      files have been included in
	      <filename>example.html</filename>.</para>
	  </step>
	</procedure>
      </sect3>
    </sect2>
  </sect1>

  <sect1 id="xml-primer-marked-sections">
    <title>Marked Sections</title>

    <para>XML provides a mechanism to indicate that particular pieces
      of the document should be processed in a special way.  These are
      termed <quote>marked sections</quote>.</para>

    <example>
      <title>Structure of A Marked Section</title>

      <programlisting>&lt;![<replaceable>KEYWORD</replaceable>[
  Contents of marked section
]]&gt;</programlisting>
    </example>

    <para>As you would expect, being an XML construct, a marked
      section starts with <literal>&lt!</literal>.</para>

    <para>The first square bracket begins to delimit the marked
      section.</para>

    <para><replaceable>KEYWORD</replaceable> describes how this marked
      section should be processed by the parser.</para>

    <para>The second square bracket indicates that the content of the
      marked section starts here.</para>

    <para>The marked section is finished by closing the two square
      brackets, and then returning to the document context from the
      XGML context with <literal>&gt;</literal>.</para>

    <sect2>
      <title>Marked Section Keywords</title>

      <sect3>
	<title><literal>CDATA</literal></title>

	<para>These keywords denote the marked sections
	  <emphasis>content model</emphasis>, and allow you to change
	  it from the default.</para>

	<para>When an XML parser is processing a document it keeps
	  track of what is called the <quote>content
	    model</quote>.</para>

	<para>Briefly, the content model describes what sort of
	  content the parser is expecting to see, and what it will do
	  with it when it finds it.</para>

	<para>The content model you will probably find most
	  useful is <literal>CDATA</literal>.</para>

	<para><literal>CDATA</literal> is for <quote>Character
	    Data</quote>. If the parser is in this content model then
	  it is expecting to see characters, and characters only.  In
	  this model the <literal>&lt;</literal> and
	  <literal>&amp;</literal> symbols lose their special status,
	  and will be treated as ordinary characters.</para>

	<note>
	  <para>When you use <literal>CDATA</literal>
	    in examples of text marked up in
	    XML, keep in mind that the content of
	    <literal>CDATA</literal> is not validated.  You have to
	    check the included XML text using other means.  You
	    could, for example, write the example in another document,
	    validate the example code, and then paste it to your
	    <literal>CDATA</literal> content.</para>
	</note>

	<!-- The nesting of CDATA within the next example is disgusting -->
	<example>
	  <title>Using a <literal>CDATA</literal> Marked
	    Section</title>

	  <programlisting>&lt;para>Here is an example of how you would include some text
  that contained many &lt;literal>&amp;lt;&lt;/literal>
  and &lt;literal>&amp;amp;&lt;/literal> symbols.  The sample
  text is a fragment of XHTML.  The surrounding text (&lt;para> and
  &lt;programlisting>) are from DocBook.&lt;/para>

&lt;programlisting>
  &lt;![CDATA[<![CDATA[
    <p>This is a sample that shows you some of the elements within
      XHTML.  Since the angle brackets are used so many times, it is
      simpler to say the whole example is a CDATA marked section
      than to use the entity names for the left and right angle
      brackets throughout.</p>

    <ul>
      <li>This is a listitem</li>
      <li>This is a second listitem</li>
      <li>This is a third listitem</li>
    </ul>

    <p>This is the end of the example.</p>]]>
  ]]&gt;
&lt;/programlisting></programlisting>

	  <para>If you look at the source for this document you will
	    see this technique used throughout.</para>
	</example>
      </sect3>

      <sect3>
	<title><literal>INCLUDE</literal> and
	  <literal>IGNORE</literal></title>

	<para>If the keyword is <literal>INCLUDE</literal> then the
	  contents of the marked section will be processed.  If the
	  keyword is <literal>IGNORE</literal> then the marked section
	  is ignored and will not be processed.  It will not appear in
	  the output.</para>

	<example>
	  <title>Using <literal>INCLUDE</literal> and
	    <literal>IGNORE</literal> in Marked Sections</title>

	  <programlisting>&lt;![INCLUDE[
  This text will be processed and included.
]]&gt;

&lt;![IGNORE[
  This text will not be processed or included.
]]&gt;</programlisting>
	</example>

	<para>By itself, this is not too useful.  If you wanted to
	  remove text from your document you could cut it out, or wrap
	  it in comments.</para>

	<para>It becomes more useful when you realize you can use
	  <link linkend="xml-primer-parameter-entities">parameter
	    entities</link> to control this, yet this usage is limited
	  to entity files.</para>

	<para>For example, suppose that you produced a hard-copy
	  version of some documentation and an electronic version.  In
	  the electronic version you wanted to include some extra
	  content that was not to appear in the hard-copy.</para>

	<para>Create an entity file that defines general entities
	  to include each chapter and guard these definitions with
	  a parameter entity that can be set to either
	  <literal>INCLUDE</literal> or <literal>IGNORE</literal>
	  to control whether the entity is defined.  After these
	  conditional general entity definitions, place one more
	  definition for each general entity to set them to an
	  empty value.  This technique makes use of the fact that
	  entity definitions cannot be overridden but always the
	  first definition takes effect.  So you can control the
	  inclusion of your chapter with the corrsponding parameter
	  entity; if you set it to <literal>INCLUDE</literal>, the
	  first general entity definition will be read and the
	  second one will be ignored but if you set it to
	  <literal>IGNORE</literal>, the first definition will be
	  ignored and the second one will take effect.</para>

	<example>
	  <title>Using A Parameter Entity to Control a Marked
	    Section</title>

	  <programlisting>
&lt;!ENTITY % electronic.copy "INCLUDE">

&lt;![%electronic.copy;[
&lt;!ENTITY chap.preface	SYSTEM "preface.xml"&gt;
]]&gt;

&lt;!ENTITY chap.preface ""&gt;
</programlisting>

	  <para>When producing the hard-copy version, change the
	    parameter entity's definition to:</para>

	  <programlisting>&lt;!ENTITY % electronic.copy "IGNORE"&gt;</programlisting>
	</example>
      </sect3>
    </sect2>

    <sect2>
      <title>For You to Do&hellip;</title>

      <procedure>
	<step>
	  <para>Modify the <filename>entities.ent</filename> file to contain
	    the following:</para>

	  <programlisting>&lt;!ENTITY version "1.1"&gt;
&lt;!ENTITY % conditional.text "IGNORE"&gt;

&lt;![%conditional.text;[
&lt;!ENTITY para1 SYSTEM "para1.xml"&gt;
]]&gt;

&lt;!ENTITY para1 ""&gt;

&lt;!ENTITY para2 SYSTEM "para2.xml"&gt;
&lt;!ENTITY para3 SYSTEM "para3.xml"&gt;</programlisting>
	</step>

	<step>
	  <para>Normalize the <filename>example.xml</filename> file and notice
	    that the conditional text is not present on the output document.
	    Now if you set the parameter entity guard to <literal>INCLUDE</literal>
	    and regenerate the normalized document, it will appear there again.
	    Of course, this method makes more sense if you have more conditional
	    chunks that depend on the same condition, for example, whether you are
	    generating printed or online text.</para>
	</step>
      </procedure>
    </sect2>
  </sect1>

  <sect1 id="xml-primer-conclusion">
    <title>Conclusion</title>

    <para>That is the conclusion of this XML primer.  For reasons of
      space and complexity several things have not been covered in
      depth (or at all).  However, the previous sections cover enough
      XML for you to be able to follow the organization of the FDP
      documentation.</para>
  </sect1>
</chapter>