513 lines
9.0 KiB
HTML
513 lines
9.0 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
|
|
<HTML
|
|
><HEAD
|
|
><TITLE
|
|
>DocBook to DocBook Transformations</TITLE
|
|
><META
|
|
NAME="GENERATOR"
|
|
CONTENT="Modular DocBook HTML Stylesheet Version 1.7"><LINK
|
|
REL="HOME"
|
|
TITLE="LDP Author Guide"
|
|
HREF="index.html"><LINK
|
|
REL="UP"
|
|
TITLE="Converting Documents to DocBook XML"
|
|
HREF="x2docbook.html"><LINK
|
|
REL="PREVIOUS"
|
|
TITLE="LyX to DocBook"
|
|
HREF="lyx2docbook.html"><LINK
|
|
REL="NEXT"
|
|
TITLE="Glossary"
|
|
HREF="glossary.html"></HEAD
|
|
><BODY
|
|
CLASS="section"
|
|
BGCOLOR="#FFFFFF"
|
|
TEXT="#000000"
|
|
LINK="#0000FF"
|
|
VLINK="#840084"
|
|
ALINK="#0000FF"
|
|
><DIV
|
|
CLASS="NAVHEADER"
|
|
><TABLE
|
|
SUMMARY="Header navigation table"
|
|
WIDTH="100%"
|
|
BORDER="0"
|
|
CELLPADDING="0"
|
|
CELLSPACING="0"
|
|
><TR
|
|
><TH
|
|
COLSPAN="3"
|
|
ALIGN="center"
|
|
>LDP Author Guide</TH
|
|
></TR
|
|
><TR
|
|
><TD
|
|
WIDTH="10%"
|
|
ALIGN="left"
|
|
VALIGN="bottom"
|
|
><A
|
|
HREF="lyx2docbook.html"
|
|
ACCESSKEY="P"
|
|
>Prev</A
|
|
></TD
|
|
><TD
|
|
WIDTH="80%"
|
|
ALIGN="center"
|
|
VALIGN="bottom"
|
|
>Appendix E. Converting Documents to DocBook XML</TD
|
|
><TD
|
|
WIDTH="10%"
|
|
ALIGN="right"
|
|
VALIGN="bottom"
|
|
><A
|
|
HREF="glossary.html"
|
|
ACCESSKEY="N"
|
|
>Next</A
|
|
></TD
|
|
></TR
|
|
></TABLE
|
|
><HR
|
|
ALIGN="LEFT"
|
|
WIDTH="100%"></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><H1
|
|
CLASS="section"
|
|
><A
|
|
NAME="docbook2docbook"
|
|
></A
|
|
>E.6. DocBook to DocBook Transformations</H1
|
|
><DIV
|
|
CLASS="section"
|
|
><H2
|
|
CLASS="section"
|
|
><A
|
|
NAME="xmldifferences"
|
|
></A
|
|
>E.6.1. XML and SGML DocBook</H2
|
|
><P
|
|
> There are a few changes between DocBook XML and SGML. Handling
|
|
these differences should be relatively easy for most small documents,
|
|
and many authors will not need to make any changes
|
|
to convert their documents other than the XML and DocBook
|
|
declarations at the start of their document.
|
|
</P
|
|
><P
|
|
> For others, here is a list of what you should keep in mind
|
|
when converting your documents from SGML to XML.
|
|
</P
|
|
><DIV
|
|
CLASS="note"
|
|
><P
|
|
></P
|
|
><TABLE
|
|
CLASS="note"
|
|
WIDTH="100%"
|
|
BORDER="0"
|
|
><TR
|
|
><TD
|
|
WIDTH="25"
|
|
ALIGN="CENTER"
|
|
VALIGN="TOP"
|
|
><IMG
|
|
SRC="../images/note.gif"
|
|
HSPACE="5"
|
|
ALT="Note"></TD
|
|
><TH
|
|
ALIGN="LEFT"
|
|
VALIGN="CENTER"
|
|
><B
|
|
>Differences between XML and SGML elements</B
|
|
></TH
|
|
></TR
|
|
><TR
|
|
><TD
|
|
> </TD
|
|
><TD
|
|
ALIGN="LEFT"
|
|
VALIGN="TOP"
|
|
><P
|
|
> An XML element typically has three parts: the start tag,
|
|
the content (your words) and the end tag. Qualifiers
|
|
are added in the start tag and are known as
|
|
attributes. They will always have a name and a
|
|
quoted value.</P
|
|
><TABLE
|
|
BORDER="0"
|
|
BGCOLOR="#E0E0E0"
|
|
WIDTH="100%"
|
|
><TR
|
|
><TD
|
|
><FONT
|
|
COLOR="#000000"
|
|
><PRE
|
|
CLASS="screen"
|
|
> <filename class="directory">/usr/local<filename>
|
|
</PRE
|
|
></FONT
|
|
></TD
|
|
></TR
|
|
></TABLE
|
|
><P
|
|
> The start tag contains one attribute (class)
|
|
with a value of <SPAN
|
|
CLASS="QUOTE"
|
|
>"directory"</SPAN
|
|
>. The end tag (also filename)
|
|
must not contain any attributes.
|
|
</P
|
|
></TD
|
|
></TR
|
|
></TABLE
|
|
></DIV
|
|
><P
|
|
></P
|
|
><UL
|
|
><LI
|
|
><P
|
|
> Element names (tags) and their attributes are
|
|
case-dependent--typically lowercase.
|
|
The following will not validate because the end tag
|
|
<PARA> is uppercase:
|
|
</P
|
|
><TABLE
|
|
BORDER="0"
|
|
BGCOLOR="#E0E0E0"
|
|
WIDTH="100%"
|
|
><TR
|
|
><TD
|
|
><FONT
|
|
COLOR="#000000"
|
|
><PRE
|
|
CLASS="screen"
|
|
> <para>This part will fail XML validation</PARA>
|
|
</PRE
|
|
></FONT
|
|
></TD
|
|
></TR
|
|
></TABLE
|
|
></LI
|
|
><LI
|
|
><P
|
|
> All attributes in the start tag must be
|
|
"quoted". This can
|
|
be either single (') or double (") quotes, but
|
|
not
|
|
reverse (`) or <SPAN
|
|
CLASS="QUOTE"
|
|
>"smart quotes"</SPAN
|
|
>.
|
|
The quote used to start a name="value"
|
|
pair must be the same quote used at the end of
|
|
the value. In other words: "this" would
|
|
validate, but 'that" would not.
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> Tags that have a start tag, but no end tag are
|
|
referred to as <SPAN
|
|
CLASS="QUOTE"
|
|
>"empty"</SPAN
|
|
> because they do
|
|
not contain (wrap around) anything. These tags must still be
|
|
closed with a trailing slash (/). For example:
|
|
<TT
|
|
CLASS="sgmltag"
|
|
>xref</TT
|
|
> must be written as
|
|
<xref linkend="software"/>. You may not
|
|
have any spaces between the / and >.
|
|
(Although you may have a space after the final
|
|
attribute: <xref linkend="foo" />.)
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> Processing instructions that get sent to the transformation
|
|
engine (DSSSL or XSLT) and must have a question mark at the
|
|
end of the tag. All processing instructions are removed from
|
|
the output stream. The XML version of this tag
|
|
would look like this:
|
|
</P
|
|
><TABLE
|
|
BORDER="0"
|
|
BGCOLOR="#E0E0E0"
|
|
WIDTH="100%"
|
|
><TR
|
|
><TD
|
|
><FONT
|
|
COLOR="#000000"
|
|
><PRE
|
|
CLASS="screen"
|
|
> <?dbhtml filename="foo"?>
|
|
</PRE
|
|
></FONT
|
|
></TD
|
|
></TR
|
|
></TABLE
|
|
></LI
|
|
><LI
|
|
><P
|
|
> If you're converting from SGML to XML, be sure
|
|
file names refer to .xml files instead of .sgml.
|
|
Some tools may get confused if a .sgml file contains XML.
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> Tag minimizations were used in SGML instead of
|
|
writing out the element name in the end tag.
|
|
Example: <TT
|
|
CLASS="sgmltag"
|
|
><para></TT
|
|
>This is foo.<TT
|
|
CLASS="sgmltag"
|
|
></></TT
|
|
> Tag minimizations are
|
|
not supported in XML and their use is
|
|
discouraged in DocBook.
|
|
</P
|
|
></LI
|
|
></UL
|
|
></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><H2
|
|
CLASS="section"
|
|
><A
|
|
NAME="differences"
|
|
></A
|
|
>E.6.2. Changing DTDs</H2
|
|
><P
|
|
> The significant changes between version changes in the DTD
|
|
involve changes to the elements (tags). Elements may be:
|
|
deprecated (which means they will be removed in
|
|
future versions); removed; modified; or added.
|
|
Almost all authors will run into a changed or
|
|
deprecated tag when going from a lower version
|
|
of DocBook to a higher version.
|
|
</P
|
|
><P
|
|
> <I
|
|
CLASS="citetitle"
|
|
>DocBook: The Definitive Guide</I
|
|
> does
|
|
an excellent job of showing you how elements fit
|
|
together. For each element it tells you what an
|
|
element must contain (its content model) and what is
|
|
may be contained in (who its parents are). For
|
|
example: a <TT
|
|
CLASS="sgmltag"
|
|
>note</TT
|
|
> must contain a
|
|
<TT
|
|
CLASS="sgmltag"
|
|
>para</TT
|
|
>. If you try to write
|
|
<note>Content in a
|
|
note</note> your document will not validate.
|
|
Learning how elements are assembled will make it a
|
|
lot easier to understand any validation errors that
|
|
are thrown at you. If you get truly stuck you can
|
|
also email the LDP's docbook mailing list for extra
|
|
hints. Information on subscribing is available from
|
|
<A
|
|
HREF="mailinglists.html"
|
|
>Section 2.2</A
|
|
>
|
|
</P
|
|
><P
|
|
> All tags that have been deprecated or changed for 4.x are listed
|
|
in <I
|
|
CLASS="citetitle"
|
|
>DocBook: The definitive guide</I
|
|
>,
|
|
published by O'Reilly and Associates. This book is
|
|
also available on-line from <A
|
|
HREF="http://www.docbook.org"
|
|
TARGET="_top"
|
|
>http://www.docbook.org</A
|
|
>.
|
|
</P
|
|
><DIV
|
|
CLASS="section"
|
|
><H3
|
|
CLASS="section"
|
|
><A
|
|
NAME="differences3040"
|
|
></A
|
|
>E.6.2.1. Differences between version 3.x and 4.x</H3
|
|
><P
|
|
> Here are a few elements that are of particular
|
|
relevance to LDP authors:
|
|
</P
|
|
><P
|
|
></P
|
|
><UL
|
|
><LI
|
|
><DIV
|
|
CLASS="formalpara"
|
|
><P
|
|
><B
|
|
><TT
|
|
CLASS="sgmltag"
|
|
>artheader</TT
|
|
>. </B
|
|
>has been changed to
|
|
<TT
|
|
CLASS="sgmltag"
|
|
>articleinfo</TT
|
|
>.
|
|
Most other header elements have been renamed to info.
|
|
</P
|
|
></DIV
|
|
></LI
|
|
><LI
|
|
><DIV
|
|
CLASS="formalpara"
|
|
><P
|
|
><B
|
|
><TT
|
|
CLASS="sgmltag"
|
|
>graphic</TT
|
|
>. </B
|
|
>has been deprecated and will be removed as of DocBook 5.x.
|
|
To prepare for this, start using
|
|
<TT
|
|
CLASS="sgmltag"
|
|
>mediaobject</TT
|
|
>. There is more
|
|
information about <TT
|
|
CLASS="sgmltag"
|
|
>mediaobject</TT
|
|
>
|
|
in <A
|
|
HREF="inserting-pictures.html"
|
|
>Section D.5</A
|
|
>.
|
|
</P
|
|
></DIV
|
|
></LI
|
|
><LI
|
|
><DIV
|
|
CLASS="formalpara"
|
|
><P
|
|
><B
|
|
><TT
|
|
CLASS="sgmltag"
|
|
>imagedata</TT
|
|
>. </B
|
|
>file formats
|
|
must now be written in UPPERCASE letters. If you
|
|
use lowercase or mixed-case spellings
|
|
for your file formats, it will fail.
|
|
</P
|
|
></DIV
|
|
><P
|
|
> Valid:
|
|
</P
|
|
><TABLE
|
|
BORDER="0"
|
|
BGCOLOR="#E0E0E0"
|
|
WIDTH="100%"
|
|
><TR
|
|
><TD
|
|
><FONT
|
|
COLOR="#000000"
|
|
><PRE
|
|
CLASS="screen"
|
|
> <imagedata format="EPS" fileref="foo.eps">
|
|
</PRE
|
|
></FONT
|
|
></TD
|
|
></TR
|
|
></TABLE
|
|
><P
|
|
> Invalid:
|
|
</P
|
|
><TABLE
|
|
BORDER="0"
|
|
BGCOLOR="#E0E0E0"
|
|
WIDTH="100%"
|
|
><TR
|
|
><TD
|
|
><FONT
|
|
COLOR="#000000"
|
|
><PRE
|
|
CLASS="screen"
|
|
> <imagedata format="eps" fileref="foo.eps">
|
|
</PRE
|
|
></FONT
|
|
></TD
|
|
></TR
|
|
></TABLE
|
|
></LI
|
|
></UL
|
|
></DIV
|
|
></DIV
|
|
></DIV
|
|
><DIV
|
|
CLASS="NAVFOOTER"
|
|
><HR
|
|
ALIGN="LEFT"
|
|
WIDTH="100%"><TABLE
|
|
SUMMARY="Footer navigation table"
|
|
WIDTH="100%"
|
|
BORDER="0"
|
|
CELLPADDING="0"
|
|
CELLSPACING="0"
|
|
><TR
|
|
><TD
|
|
WIDTH="33%"
|
|
ALIGN="left"
|
|
VALIGN="top"
|
|
><A
|
|
HREF="lyx2docbook.html"
|
|
ACCESSKEY="P"
|
|
>Prev</A
|
|
></TD
|
|
><TD
|
|
WIDTH="34%"
|
|
ALIGN="center"
|
|
VALIGN="top"
|
|
><A
|
|
HREF="index.html"
|
|
ACCESSKEY="H"
|
|
>Home</A
|
|
></TD
|
|
><TD
|
|
WIDTH="33%"
|
|
ALIGN="right"
|
|
VALIGN="top"
|
|
><A
|
|
HREF="glossary.html"
|
|
ACCESSKEY="N"
|
|
>Next</A
|
|
></TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
WIDTH="33%"
|
|
ALIGN="left"
|
|
VALIGN="top"
|
|
>LyX to DocBook</TD
|
|
><TD
|
|
WIDTH="34%"
|
|
ALIGN="center"
|
|
VALIGN="top"
|
|
><A
|
|
HREF="x2docbook.html"
|
|
ACCESSKEY="U"
|
|
>Up</A
|
|
></TD
|
|
><TD
|
|
WIDTH="33%"
|
|
ALIGN="right"
|
|
VALIGN="top"
|
|
>Glossary</TD
|
|
></TR
|
|
></TABLE
|
|
></DIV
|
|
></BODY
|
|
></HTML
|
|
> |