LDP/LDP/guide/docbook/LDP-Author-Guide/docbook-xml.xml

  <section id="docbookxml">
    <title>Writing in DocBook XML</title>
    <para>
      While tools for writing XML are not as developed as those
      for SGML, there are a few reasons why you may want to start
      writing in XML: 
    </para> 

    <orderedlist inheritnum="ignore" continuation="restarts">
      <listitem>
        <para>
          Libraries for handling XML files are developing at
          a rapid pace.  These utilities may make it easier
          for new authoring tools to become available.
        </para>
      </listitem>
      <listitem>
        <para> 
          Many popular word processing programs are now creating
          XML output.  While it may not DocBook XML, this does make
          it easier for application writers to either add DocBook XML
          support, or provide some method of translating between
          their format and DocBook XML.
        </para>
      </listitem>
      <listitem>
        <para>
          Everyone else is doing it.  While this might not be a real
          reason, it allows the LDP to keep up-to-date with similar
          projects.  Tools, procedures, and issues can be worked out
          in a common framework.
        </para>
      </listitem>
    </orderedlist>

    <para>
      The real intent of this section is to get you familiar with the changes
      between writing in previous versions of DocBook SGML and DocBook XML.
      Since the LDP supports DocBook SGML 3.1 (which much of this Guide
      is written against) and up, and DocBook XML 4.1 and up, there will be
      a few differences.
    </para>

    <para>
      In the following sections, if you see DocBook follwed by XML or SGML,
      it refers to the XML or SGML version of DocBook.  If DocBook is
      followed by a version number, it refers to both the XML and SGML
      versions of DocBook.
    </para>

    <section id="xmldifferences">
      <title>Differences between XML and SGML</title>
      <para>
        There are a few changes between writing XML and SGML.  Handling
        these differences should be relatively easy for most small documents,
        and many authors will not need to maky any changes except
        for the XML declaration and DocBook declaration at the start
        of their document.
      </para>

      <para>
        For others, here is a list of what you should keep in mind
        when writing.
      </para>

      <itemizedlist>
        <listitem>
          <para>
            Most tags are case-dependent, or at least should have
            the same case.  That is, you do not want to have code
            like this:
          </para>
<screen>
&lt;para&gt;This part will fail XML validation&lt;/PARA&gt;
</screen>
        </listitem>

        <listitem>
          <para>
            The above being said, most XML-specific tags (like entity)
            have to be in all capital letters (ENTITY).
          </para>
        </listitem>


        <listitem>
          <para>
            All arguments to a tag have to be in quotes.  This can
            be either single (') or double (") quotes, but no
            reverse (`) or smart quotes are allowed.
          </para>
        </listitem>

        <listitem>
          <para>
            Tags that have no close (like <sgmltag>xref</sgmltag>) have to have
            a trailing / as part of the tag. (&lt;xref/&gt;)
          </para>
        </listitem>

        <listitem>
          <para>
            Processing instructions that get sent to the DSSSL (like
            &lt;?dbhtml&gt;) have to have a question mark at the
            end of the tag.  The new tag would look like this:
          </para>
<screen>
&lt;?dbhtml filename="foo"?&gt;
</screen>
        </listitem>

        <listitem>
          <para>
            If you're converting to XML, be sure file names refer
            to .xml files instead of .sgml.  Some tools may get
            confused if a .sgml file contains XML.
          </para>
        </listitem>

        <listitem>
          <para>
            Tag minimizations (<sgmltag class="endtag"></sgmltag>)
            are not supported.  Their use is discouraged in DocBook SGML.
          </para>
        </listitem>

      </itemizedlist>
    </section>

    <section id="differences3040">
      <title>Differences between DocBook 3.x and DocBook 4.x</title>
      <para>
        The big changes between DocBook 3.x and 4.x involve depreciated
        tags, changed tags, and new ones.  Almost all authors will run
        into a changed or depreciated tag when going to DocBook 4.x.
        All tags that have been depreciated or changed for 4.x are listed
        in DocBook:  The definitive guide, published by O'Reilly and
        Associates.
      </para>
      <itemizedlist>

        <listitem>
          <para>
            The <sgmltag>artheader</sgmltag> tag has been changed
            to <sgmltag>articleinfo</sgmltag>;.
            Most other header tags have been renamed to info.
          </para>
        </listitem>

        <listitem>
          <para>
            The <sgmltag>graphic</sgmltag> tag is being depreciated in
            DocBook 5.x.  To prepare for this, you can instead use the
            <sgmltag>mediaobject</sgmltag>
            tag.  You can find out using <sgmltag>mediaobject</sgmltag> at 
            <xref linkend="images"/>.
          </para>
        </listitem>

        <listitem>
          <para>
            The file format for <sgmltag>imagedata</sgmltag> has to be in
            capital letters.  If you use lowercase or mixed-case spellings
            for your file formats, it will fail.
          </para>
          <para>
            Valid:
          </para>
<screen>
&lt;imagedata format="EPS" fileref="foo.eps"&gt;
</screen>
          <para>
            Invalid:
          </para>
<screen>
&lt;imagedata format="eps" fileref="foo.eps"&gt;
</screen>
        </listitem>

      </itemizedlist>

    </section>
  </section>