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

Added "linuxdoc" as one of the accepted markup languages. Need to go 

back and double check that Linuxdoc is sufficiently referred to in
this section.
This commit is contained in:
emmajane 2003-12-07 21:12:04 +00:00
parent 4c499b1165
commit 20c2c7e128
1 changed files with 197 additions and 191 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

388
LDP/guide/docbook/LDP-Author-Guide/ag-markup.xml
View File

@ -1,263 +1,269 @@
<!--
<!DOCTYPE book PUBLIC '-//OASIS//DTD DocBook XML V4.2//EN'>
-->
<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 (e.g. HTML and DocBook). Documents are stored
in SGML format using a specific Document Type Definition--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>
<section id="markup">
<title>Markup</title>
<note><para>
As of this writing the LDP accepts documents in the following
markup languages: Linuxdoc SGML; DocBook
SGML v4.2, v4.1 or v3.x; and DocBook XML
v4.2 or v4.1.2. DocBook XML 4.2 is
<quote>preferred</quote> to DocBook SGML.
</para></note>
<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 element &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><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
<para>
To explain what markup is, we must first take a look at
what SGML, XML and Linuxdoc and DocBook are.
</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
(e.g. HTML and DocBook). Documents are stored in SGML
format using a specific Document Type Definition--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 element &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><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. For more information about writing your
content read: FIXME
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. For more
information about writing your content read: FIXME
</para></listitem>
<listitem><para>
To describe the structure of the content a controlled vocabulary
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
<listitem><para>
To describe the structure of the content a controlled
vocabulary 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: FIXME
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: FIXME
</para></listitem>
<listitem><para>
<listitem><para>
Finally the document is transformed to another type of
document and formatted for displayed. This is
controlled through the Document Style Semantics and Specification
document and formatted for displayed. This 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 DSSSL tells the program doing the transformation how to
convert the raw markup into something that a human can read.
</para>
<para>For example: The DSSSL instructions may specify
that an RTF document should have all
<sgmltag>title</sgmltag>s transformed into 14 point
<para>For example: The DSSSL instructions may specify that
an RTF document should have all <sgmltag>title</sgmltag>s
transformed into 14 point
bold type; however, the instructions for an HTML
document may convert that same <sgmltag>title</sgmltag>
into an &lt;h1&gt; HTML element.</para>
<para>
For more information about transforming your document to other
into an &lt;h1&gt; HTML element.</para> <para> For more
information about transforming your document to other
document formats read <xref linkend="transformations"/>.
</para>
</listitem>
</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 in how the markup is
applied. The LDP has chosen
to store its documents in XML format using the DocBook DTD.
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 in how
the markup is applied. The LDP has chosen to store
its documents in XML format using the DocBook DTD.
(Other markup languages are accepted by the LDP. See
<xref linkend="templates"/> for more information.)
</para>
</section>
<section id="whydocbook">
<title>Why DocBook?</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. You can also transform
your DocBook document into a variety of
formats including: 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. If you prefer to work in Lyx you can write in
Tex format, export to DocBook and then transform to
any of the formats mentioned above.
<section id="docbook">
<title>Why DocBook?</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. You can also transform
your DocBook document into a variety of formats including:
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. If you prefer to work in Lyx you can write in
Tex format, export to DocBook and then transform to any
of the formats mentioned above.
DocBook, unlike other formats, is more concerned about
describing a document's structure than detailing how
it will be displayed.
describing a document's structure than detailing how it
will be displayed.
</para>
<para>
Although there are other DTDs used to write documentation,
<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>
<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>
</section>
<section id="docbookxml">
<title>Why XML?</title>
<para>
<title>Why 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>
writing in XML:
</para>
<orderedlist inheritnum="ignore" continuation="restarts">
<listitem>
<para>
<para>
It's the format preferred by The LDP.
</para>
</listitem>
<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>
<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. Lists of formats that
the LDP accepts is listed in <xref linkend="templates"/>
Still not convinced? Fortunately the LDP does
accept a number of other file formats. Lists of
formats that
the LDP accepts is listed in <xref linkend="templates"/>
</para>
</section>
<section id="docbookintro">
<title>Introduction</title>
<para>DocBook defines a set of markup elements useful for marking
up text so that the text can then be transformed into several
different formats:
<acronym>HTML</acronym>, <acronym>XML</acronym>, <acronym>RTF</acronym>,
TeX, and others.</para>
<para>DocBook defines a set of markup elements useful for
marking up text so that the text can then be transformed
into several different formats: <acronym>HTML</acronym>,
<acronym>XML</acronym>, <acronym>RTF</acronym>, TeX, and
others.</para>
<para>The idea is to write just once and reach the largest possible number
of people with the information.</para>
<para>The idea is to write just once and reach the largest
possible number of people with the information.</para>
<para>Digital information not stored properly tends to get lost.
Because DocBook uses standard <acronym>ASCII</acronym> characters,
it is easy to index and search DocBook document directly.
Because DocBook uses standard <acronym>ASCII</acronym>
characters, it is easy to index and search DocBook document
directly.
</para>
<para>The <acronym>SGML</acronym> systems use markups to describe their
data. DocBook holds over 300 markup elements each one with several
attributes which can assume several values; these can be fixed or defined
by the document / style that the author has used.</para>
<para>The <acronym>SGML</acronym> systems use markups to describe
their data. DocBook holds over 300 markup elements each one
with several attributes which can assume several values; these
can be fixed or defined by the document / style that the author
has used.</para>
<para>Just to remind you, if any changes are made to DocBook's
<acronym>DTD</acronym>, it's no longer DocBook.</para>
<acronym>DTD</acronym>, it's no longer DocBook.</para>
</section>
<section id="acceptedversions">
<title>DocBook Versions</title>
<para>
The LDP supports and accepts documentation in the following formats:
</para>
<itemizedlist>
<listitem>
<para>
XML DocBook version 4.1.2
</para>
</listitem>
<listitem>
<para>
SGML DocBook versions 4.x and 3.1
</para>
</listitem>
<listitem>
<para>
SGML LinuxDoc
</para>
</listitem>
<title>DocBook Versions</title> <para>
The LDP supports and accepts documentation in the following
formats:
</para> <itemizedlist>
<listitem>
<para>
XML DocBook version 4.1.2
</para>
</listitem> <listitem>
<para>
SGML DocBook versions 4.x and 3.1
</para>
</listitem> <listitem>
<para>
SGML LinuxDoc
</para>
</listitem>
</itemizedlist>
</section>
<section id="doctype">
<para>When writing your DocBook header, it should look like
this:</para>
<programlisting format="linespecific">
<sgmltag class="starttag">!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.1//EN"</sgmltag>
</programlisting>
this:</para> <programlisting format="linespecific">
<sgmltag class="starttag">!DOCTYPE article PUBLIC "-//OASIS//DTD
DocBook V4.1//EN"</sgmltag> </programlisting>
<!-- add different doctypes for articles, books, etc -->
<!-- explain what Doctypes are all about - check the catalog
section, I think for more pre-written work. -->
<!-- add different doctypes for articles, books, etc --> <!--
explain what Doctypes are all about - check the catalog section,
I think for more pre-written work. -->
</section>