LDP
/
LDP
mirror of https://github.com/tLDP/LDP
0
1
Fork 0
Code Releases Activity

This file is replaced by ag-markup.xml

This commit is contained in:
emmajane 2003-12-31 15:58:20 +00:00
parent 5764eb251f
commit 0e70ffde82
1 changed files with 0 additions and 312 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

312
LDP/guide/docbook/LDP-Author-Guide/docbook-xml.xml
View File

@ -1,312 +0,0 @@
<section id="docbook">
<title>DocBook</title>
<para>
To explain what DocBook is, we must first take a look
at what SGML and XML are, and their relationship to DocBook.
</para>
<para>The Standard Generalized Markup Language (SGML) is a
way of embedding information about a document
into the text of the document. SGML is not a markup language
itself, it is a <quote>metalanguage</quote> from which other markup
languages are created (for instance HTML and DocBook). Documents are stored
in SGML format using a specific Document Type Definition or DTD, a
controlled vocabulary. These documents may then be
<quote>transformed</quote> into a variety of other types of documents
such as PDFs, HTML pages, plain text, etc. The advantage of using
SGML means you can use an automated transformation to convert your
document into whatever format you may need.</para>
<para>Instead of defining things like colors, font sizes and other specific
formatting rules you define the structure of the document. This is
done with a series of tags which are wrapped around content.
The controlled vocabulary consists of <quote>elements</quote> which
describes what the content is. This block
of text, for example, is a paragraph. In DocBook notation I have
wrapped the block of text with the start tag &lt;para&gt; and then
the end tag &lt;/para&gt;. In HTML, a sub-set of SGML, this would be
done with the elements &lt;p&gt; and &lt;/p&gt;. Although there are many similarities
between DocBook and HTML, DocBook contains hundreds of elements and
is considered a much more descriptive vocabulary.</para>
<note><title>Example</title><para>Steve
Champeon does a great job of explaining this (from an HTML
perspective but with an example of DocBook markup) in his article
<ulink url="http://hotwired.lycos.com/webmonkey/02/42/index4a.html">The
Secret Life of Markup</ulink></para></note>
<para>There are really three parts to an SGML document:</para>
<itemizedlist>
<listitem><para>
First there is the content. As a TLDP author it is good to remember
that this is the most important piece. Many authors will write the
content first and add their markup later. Content may include both
plain text and graphics. See <xref linkend="write" /> for more information about writing your
content.
</para></listitem>
<listitem><para>
To describe the structure of the content a controlled vocabulary is
added on top of the content. It is used to distinguish different
kinds of content: paragraphs, lists, tables, warnings and so on.
This is also known as document <quote>markup</quote> and is typically
what people are referring to when they talk about SGML, XML and HTML.
</para>
<para>
The rules that
define the structure of a document are known as a Document Type
Definition (DTD). Depending on what kind of document you are writing,
you will use a different set of rules. The rules include the required
elements (tagset) and the order in which they must appear.
This document was written in
DocBook version 4.2 (although that version will likely change over
time).
For more information about marking up your document read <xref linkend="markup" />.
</para></listitem>
<listitem><para>
Finally the document is formatted for display, be it digitally or on paper. This conversion is
controlled through the Document Style Semantics and Specification
Language (DSSSL).
The DSSSL tells the program doing the rendering how to convert
the SGML into something humanly readable. It tells the
renderer to convert a <sgmltag>title</sgmltag> tag into 14 point
bold if it
is going to RTF format, or to turn it into an &lt;h1&gt; tag if
it is going to HTML.
For more information about transforming your document to other
document formats read <xref linkend="transformations" />.
</para></listitem>
</itemizedlist>
<para>
The eXtensible Markup Language (XML) is a sub-set of SGML. Like
SGML it is also a metalanguage and defines the rules of how a
controlled vocabulary (DTD) can be used. Both SGML and XML
documents must point to a DTD for the rules about a document's
structure. DocBook is a DTD which is available in both SGML and XML
formats. Although the element names do not change between the two
there are slight differences. The LDP has chosen
to store its documents in XML format using the DocBook DTD. (Other
markup languages are accepted--this is covered later in the
document.)
</para>
</section>
<section id="whydocbook">
<title>Why DocBook instead of HTML or other formats?</title>
<para>DocBook provides for more than just formatting. You can
automatically build indexes, tables of contents, and links within
the document or to outside references. The Jade and OpenJade packages also
let you transform DocBook to LaTeX,
info, text, HTML, and RTF. From these basic formats you can
then create other formats such as MS Word, PostScript, PDF and
so on. Programs like LyX allow you to write in TeX format, then
export it as DocBook SGML and transform from SGML to whatever you
chose. In
the end, DocBook is more concerned about the way elements work
instead of the way they look.
</para>
<para>
There are other DTDs which could be used for documentation other
than DocBook, but there are a few reasons
not to use them. First, DocBook is the most popular DTD, being
used by more than a dozen major open source projects from GNOME
to Python to FreeBSD. Second, the tools for
DocBook are far more developed than others. DocBook support is
included in most Linux distributions, allowing you to send raw
files to be processed at the receiver's end. And finally,
while DocBook has an extensive set of tags (over 300 in all), the
majority does not need to be used for simple
documentation. Starting with one of the available templates
will allow you to quickly start writing DocBook with minimal
experience. To get started using an LDP template read
<xref linkend="templates"/></para>
</section>
<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 be 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 followed 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 make 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).
<!--I still have this aching feeling that tags should be in lower cases for XML. Look at this entire doc?!? -->
</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 deprecated
tags, changed tags, and new ones. Almost all authors will run
into a changed or deprecated tag when going to DocBook 4.x.
All tags that have been deprecated 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 deprecated 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>