mirror of https://github.com/tLDP/LDP
225 lines
8.5 KiB
XML
225 lines
8.5 KiB
XML
<!--
|
|
<!DOCTYPE book PUBLIC '-//OASIS//DTD DocBook XML V4.2//EN'>
|
|
-->
|
|
|
|
<chapter id="ag-markup">
|
|
<title>Markup</title>
|
|
|
|
<section id="markup">
|
|
<title>Markup: A General Overview</title>
|
|
<para>
|
|
A markup language is a system for marking or tagging a document to
|
|
define the structure of the document. You may add tags to your document
|
|
to define which parts of your document are paragraphs, titles,
|
|
sections, glossary items (the list goes on!).
|
|
There are many markup languages in use today. XHTML and HTML will be
|
|
familiar to those who author web documents. The LDP uses a markup
|
|
language known as DocBook. Each of these markup languages uses its own
|
|
<quote>controlled vocabulary</quote> to describe documents. For
|
|
example: in XHTML a paragraph would be marked up with the tagset
|
|
<p></p> while in DocBook a paragraph would be marked up
|
|
with <sgmltag class="starttag">para</sgmltag><sgmltag
|
|
class="endtag">para</sgmltag>. The tagsets are defined in a quasi
|
|
dictionary known as a Document Type Definition (DTD).
|
|
</para>
|
|
|
|
<para>
|
|
Markup languages also follow a set of rules on how a document
|
|
can be assembled. The rules are either SGML (Standard Generalized
|
|
Markup Language) or XML (eXtensible Markup Language). These rules are
|
|
essentially the <quote>grammar</quote> of a document's markup. SGML and
|
|
XML are very similiar. XML is a sub-set of SGML, but XML requires more
|
|
precise use of the tags when marking up a document.
|
|
The LDP accepts both SGML and XML documents, but prefers XML.
|
|
</para>
|
|
|
|
<para>There are three components to an XML/SGML document which is read by a
|
|
person.</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<formalpara><title>Content</title><para>
|
|
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. This is the only part that
|
|
is required of LDP authors!
|
|
</para></formalpara>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<formalpara><title>Markup</title><para>
|
|
To describe the structure of a document 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). The markup must also conform to
|
|
either SGML or XML rules. If you are not comfortable
|
|
adding markup to your document, a TLDP volunteer will do it for you.
|
|
</para>
|
|
</formalpara>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<formalpara><title>Transformation</title><para>
|
|
Finally the document is transformed from DocBook to PDF, HTML,
|
|
PostScript for display in digital or paper form. This transformation is controlled
|
|
through the Document Style Semantics and Specification
|
|
Language (DSSSL).
|
|
The DSSSL tells the program doing the transformation how to
|
|
convert the raw markup into something that a human can read.
|
|
The LDP uses a series of scripts to automate these transformations.
|
|
You are not required to transform your own documents.
|
|
</para></formalpara>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<note><title>Content, markup and transformations</title>
|
|
<para>Steve Champeon does a great job of
|
|
explaining how content, markup languages, and transformations all fit
|
|
together in his article <ulink
|
|
url="http://hotwired.lycos.com/webmonkey/02/42/index4a.html">The
|
|
Secret Life of Markup</ulink>. Although he is writing from an HTML
|
|
perspective, the ideas are relevant and there is an example of DocBook markup.</para></note>
|
|
|
|
</section>
|
|
|
|
<section id="docbook-why">
|
|
<title>DocBook: What it is and why we use it</title>
|
|
|
|
<para>
|
|
According to the official DocBook web site,
|
|
<blockquote>
|
|
<attribution>DocBook.org</attribution>
|
|
<para>
|
|
DocBook is a general purpose XML and SGML document type particularly well
|
|
suited to books and papers about computer hardware and software (though
|
|
it is by no means limited to these applications).
|
|
</para></blockquote>
|
|
</para>
|
|
|
|
<tip><title>For the impatient</title><para>
|
|
In the next sections we will be explaining about the theoretical side of DocBook, its origins, development, advantages and disadvantages. If you just want the practical side, check out these sections for an overview of HOWTO DocBook:
|
|
<xref linkend="ref-docbook" />,
|
|
<xref linkend="using-docbook" />,
|
|
and <xref linkend="x2docbook" />
|
|
from this guide.
|
|
</para></tip>
|
|
|
|
<caution><title>For the beginner</title>
|
|
<para>We wish to stress again the fact that any open document format will
|
|
be accepted. If you feel more comfortable with plain text, OpenOffice or
|
|
HTML, that is fine with us. If you do not look forward to learning
|
|
DocBook, LDP volunteerd will convert your document to DocBook XML. To us, the most important task for our authors is the actual writing, not the formatting, keep that in mind!</para>
|
|
<para>From the point of submission onwards, however, you will have to maintain
|
|
your document in this XML format, but that's a piece of cake. Promised.</para>
|
|
</caution>
|
|
|
|
<para>
|
|
Although there are other DTDs used to write documentation,
|
|
there are a few reasons not to use them.
|
|
</para>
|
|
|
|
<itemizedlist> <listitem><para> DocBook is the most
|
|
popular DTD, being
|
|
used by more than a dozen major open source projects from
|
|
GNOME to Python to FreeBSD.
|
|
</para></listitem> <listitem><para> The tools for DocBook
|
|
are 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.
|
|
</para></listitem> <listitem><para> And finally, DocBook
|
|
has an extensive set of tags (over 300 in all) which is
|
|
very useful when you are trying to describe the content
|
|
of a document. Fortunately for new authors the majority
|
|
of them do not need to be used for simple documentation.
|
|
</para></listitem> </itemizedlist>
|
|
|
|
<para>Still not convinced? Eric
|
|
Raymond has written a <ulink
|
|
url="http://en.tldp.org/HOWTO/DocBook-Demystification-HOWTO/">DocBook
|
|
Demystification HOWTO</ulink> which may help. </para>
|
|
|
|
<para>
|
|
Convinced, but still not comfortable with the thought of
|
|
working with DocBook? Give David Lawyer's <ulink
|
|
url="http://tldp.org/HOWTO/Howtos-with-LinuxDoc.html">Howtos-with-LinuxDoc-mini-HOWTO</ulink>
|
|
a try.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="docbookxml">
|
|
<title>XML and SGML: Why we use XML</title>
|
|
<para>
|
|
DocBook comes in a couple of different flavors--including both
|
|
XML and SGML formats. This means that you may use either the SGML
|
|
grammar/rules when adding markup, or you may use the XML grammar/rules.
|
|
Either way you may only use one set of rules throughout your document,
|
|
and you must define which one you are using at the top of your document.
|
|
</para>
|
|
|
|
<para>
|
|
The LDP prefers the XML flavor of DocBook. There are a number of
|
|
reasons for this including the following:
|
|
</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>
|
|
Still not convinced? Fortunately the LDP does
|
|
accept a number of other file formats for input. The list of accepted markup
|
|
languages can be found in <xref linkend="acceptedversions"/>
|
|
</para>
|
|
</section>
|
|
|
|
<section id="acceptedversions">
|
|
<title>Markup Languages Accepted by TLDP</title>
|
|
&ldp-markup;
|
|
</section>
|
|
<!--
|
|
<section id="doctype">
|
|
<title>DocBook Documents: Inserting a DOCTYPE</title>
|
|
|
|
<para>When writing your DocBook header, it should look like
|
|
this:</para>
|
|
|
|
<screen>
|
|
<sgmltag class="starttag">!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"</sgmltag>
|
|
</screen>
|
|
|
|
<section id="html2db">
|
|
<title>HTML to DocBook</title>
|
|
<para>
|
|
If your document is already written in HTML, you may want to try
|
|
<application>html2db</application> to convert your document.
|
|
More information is available from <ulink
|
|
url="http://www.cise.ufl.edu/~ppadala/tidy/" />.
|
|
</para>
|
|
</section>
|
|
-->
|
|
|
|
</chapter>
|