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

Simplified the language in ag-markup.xml

This commit is contained in:
emmajane 2003-12-21 23:20:11 +00:00
parent c8f9e080ea
commit e3affe9e6e
2 changed files with 129 additions and 147 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -158,6 +158,21 @@ what's on the LDP web site as I'm currently *gasp* offline. -->
</abstract>
<revhistory>
<revision>
<revnumber>4.0.6</revnumber>
<date>2003-12-22</date>
<authorinitials>ejh</authorinitials>
<revremark>Simplified the language in the markup section (main
guide, not appendix).</revremark>
</revision>
<revision>
<revnumber>4.0.5</revnumber>
<date>2003-12-22</date>
<authorinitials>ejh</authorinitials>
<revremark>Incorporation of Machtelt Garrel (Tille)'s review.</revremark>
</revision>
<revision>
<revnumber>4.0.4</revnumber>
<date>2003-12-11</date>

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

@ -2,141 +2,113 @@
<!DOCTYPE book PUBLIC '-//OASIS//DTD DocBook XML V4.2//EN'>
-->
<chapter id="ag-markup">
<title>Markup</title>
<chapter id="ag-markup">
<title>Markup</title>
<section id="markup">
<title>Markup: A General Overview</title>
<para>
To explain what markup is, we must first take a look at
what SGML, XML, 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>meta-language</quote>
from which other markup languages are created
(such as 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
and more. 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: 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
&lt;p&gt;&lt;/p&gt; 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>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
describe 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 than HTML, which generally focused on display rather than content.</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>
<note><para>Steve Champeon does a great job of
explaining this in his article 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>
<para>There are really three parts to an SGML document:</para>
<para>There are three components to an XML/SGML document which is read by a
person.</para>
<itemizedlist>
<listitem><para>
First there is the content. As a TLDP author it is good
to remember
<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.
</para></listitem>
may include both plain text and graphics. This is the only part that
is required of LDP authors!
</para></formalpara>
</listitem>
<listitem><para>
To describe the structure of the content a controlled
<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). 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>
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>
<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.
</para></listitem>
<listitem><para>
<listitem>
<formalpara><title>Transformation</title><para>
Finally the document is transformed to another type of
document and formatted for display. 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.
</para>
<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
document formats read <xref linkend="transformations"/>.
</para>
convert the raw markup into something that a human can read. A
document may be transformed from DocBook to PDF, HTML, RTF, or any
other number of formats. 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><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>
<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.
(Other markup languages are accepted by the LDP. See
<xref linkend="templates"/> for more information.)
</para>
</section>
</section>
<section id="docbook-why">
<title>DocBook: What it is and why we use it</title>
<para>DocBook is a <emphasis>name space</emphasis> of XML.
You can think of this as a dialect of XML and thus of SGML. Even more
simplified, DocBook is a DTD for rendering XML source files. On first
sight, it is a means of arranging output in a nice way.
</para>
<para>But DocBook provides for more
than just formatting. You can automatically build indexes,
tables of contents and links within the document or to
outside references. You can also use it to 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.
</para>
<section id="docbook-why">
<title>DocBook: What it is why we use it</title>
<para> Although there are other DTDs used to write
documentation,
there are a few reasons not to use them.</para>
<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><para>
For an overview of HOWTO DocBook check out:
<xref linkend="ref-docbook" />,
<xref linkend="using-docbook" />,
and <xref linkend="x2docbook" />
from this guide.
</para></tip>
<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
@ -164,29 +136,32 @@
url="http://tldp.org/HOWTO/Howtos-with-LinuxDoc.html">Howtos-with-LinuxDoc-mini-HOWTO</ulink>
a try.
</para>
</section>
</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>
<section id="docbookxml">
<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>
<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>
It's the format preferred by The LDP.
</para>
</listitem>
<listitem>
<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>
</listitem>
<listitem>
<para>
Many popular word processing programs are now creating
XML output. While it may not be DocBook XML, this does
@ -194,36 +169,28 @@
DocBook XML support, or provide some method of translating
between their format and DocBook XML.
</para>
</listitem> <listitem>
</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>
</listitem>
</orderedlist>
<para>
<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>
<section id="acceptedversions">
<title>DocBook Versions</title>
<section id="acceptedversions">
<title>Markup Languages Accepted by TLDP</title>
&ldp-markup;
<para>
For an overview of HOWTO DocBook check out:
<xref linkend="ref-docbook" />,
<xref linkend="using-docbook" />,
and <xref linkend="x2docbook" />
from this guide.
</para>
</section>
</section>
<!--
<section id="doctype">
<title>DocBook Documents: Inserting a DOCTYPE</title>