LDP
/
LDP
mirror of https://github.com/tLDP/LDP
0
1
Fork 0
Code Releases Activity
LDP/LDP/guide/docbook/LDP-Author-Guide/LDP-Author-Guide.xml

1590 lines
69 KiB
XML
Raw Blame History

<?xml version='1.0' encoding='ISO-8859-1'?>
<!DOCTYPE book PUBLIC '-//OASIS//DTD DocBook XML V4.1.2//EN'
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
<!--
<!entity header system "header.sgml">
<!entity docbook system "docbook.sgml">
-->
<!ENTITY conventions SYSTEM "conventions.xml">
<!ENTITY using-docbook SYSTEM "using-docbook.xml">
<!ENTITY doc-index SYSTEM "index.xml">
<!ENTITY gfdl SYSTEM "fdl-appendix.xml">
<!-- Include macros -->
<!ENTITY conventions SYSTEM "conventions.xml">
<!ENTITY example-article SYSTEM "example-article.xml">
<!ENTITY example-book SYSTEM "example-book.xml">
<!ENTITY example-compile-sgml SYSTEM "compiles-sgml.xml">
<!ENTITY example-table SYSTEM "example-table.xml">
<!ENTITY dsl-example SYSTEM "dsl-example.xml">
<!ENTITY glossary SYSTEM "glossary.xml">
<!ENTITY cvs SYSTEM "cvs.xml">
<!ENTITY xml SYSTEM "docbook-xml.xml">
<!ENTITY style-guide SYSTEM "style-guide.xml">
<!ENTITY using-ldp-dsssl SYSTEM "using-ldp-dsssl.xml">
<!ENTITY using-ldp-xsl SYSTEM "using-ldp-xsl.xml">
<!-- Text Macros -->
<!ENTITY conectivasa '<ulink url="http://www.conectiva.com">Conectiva S.A.</ulink>'>
<!ENTITY conectiva "Conectiva">
]>
<book id="index">
<bookinfo>
<title>LDP Author Guide</title>
<pubdate>v3.7 2001/06/20</pubdate>
<author>
<firstname>Mark</firstname>
<othername>F.</othername>
<surname>Komarinski</surname>
<affiliation>
<orgname>VA Linux Systems</orgname>
<address><email>markk@wayga.net</email></address>
</affiliation>
</author>
<author>
<firstname>Jorge</firstname>
<surname>Godoy</surname>
<affiliation>
<orgname>&conectivasa;</orgname>
<orgdiv>Publishing Department</orgdiv>
<address><email>godoy@conectiva.com</email></address>
<address><email>godoy@metalab.unc.edu</email></address>
</affiliation>
</author>
<author>
<firstname>David</firstname>
<othername>C.</othername>
<surname>Merrill</surname>
<affiliation>
<address><email>dcmerrill@mindspring.com</email></address>
</affiliation>
</author>
<abstract>
<para>List the tools, procedures, and hints to get LDP authors
up to speed and writing. </para>
</abstract>
<revhistory>
<revision>
<revnumber>3.9</revnumber>
<date>2001-11-27</date>
<authorinitials>sp</authorinitials>
<revremark>
Updated CVS information.
</revremark>
</revision>
<revision>
<revnumber>3.8</revnumber>
<date>2001-09-25</date>
<authorinitials>dy</authorinitials>
<revremark>
XML/XSLT information.
</revremark>
</revision>
<revision>
<revnumber>3.7</revnumber>
<date>2001-06-20</date>
<authorinitials>mfk</authorinitials>
<revremark>
Now under the GFDL.
</revremark>
</revision>
<revision>
<revnumber>3.62</revnumber>
<date>2001-03-13</date>
<authorinitials>mfk</authorinitials>
<revremark>
Spelling and grammar changes from Dave Edwards (amoamasam@sympatico.ca).
Also performed some housecleaning from comments of discuss@linuxdoc.org.
</revremark>
</revision>
<revision>
<revnumber>3.6</revnumber>
<date>2001-01-10</date>
<authorinitials>mfk</authorinitials>
<revremark>
First revision in DocBook XML. Added section covering writing
in DB XML, since first rev is 4.1.
</revremark>
</revision>
<revision>
<revnumber>3.51</revnumber>
<date>2001-01-05</date>
<authorinitials>mfk</authorinitials>
<revremark>sgedit (now tksgml) is not free, included link for pricing, more XML info</revremark>
</revision>
<revision>
<revnumber>3.5</revnumber>
<date>Dec 4, 2000</date>
<authorinitials>mfk</authorinitials>
<revremark>Changed mailing list pointers to new lists.</revremark>
</revision>
<revision>
<revnumber>3.4</revnumber>
<date>Dec 1, 2000</date>
<authorinitials>dcm</authorinitials>
<revremark>Added Crediting Translators and Converters</revremark>
</revision>
<revision>
<revnumber>3.3</revnumber>
<date>Nov 11, 2000</date>
<authorinitials>mfk</authorinitials>
<revremark>Added links to SGML GPL and FDL</revremark>
</revision>
<revision>
<revnumber>3.1</revnumber>
<date>Oct 10, 2000</date>
<authorinitials>mfk</authorinitials>
<revremark>Spelling changes, changed list of LDP policies to now
accept DocBook XML. More information about how to use *jade
with XML will follow.
</revremark>
</revision>
<revision>
<revnumber>3.0</revnumber>
<date>Aug 24, 2000</date>
<authorinitials>gjf</authorinitials>
<revremark>Integrated David Merrill's style guide document. Further clean-up and additions.</revremark>
</revision>
<revision>
<revnumber>2.0</revnumber>
<date>Jul 13, 2000</date>
<authorinitials>mfk</authorinitials>
<revremark>Cleaned up using-docbook a bit. Moved some chapters</revremark>
</revision>
<revision>
<revnumber>1.9</revnumber>
<date>Jun 26, 2000</date>
<authorinitials>mfk</authorinitials>
<revremark>Integrated Jorge's using-docbook document.</revremark>
</revision>
<revision>
<revnumber>1.5</revnumber>
<date>Jun 14, 2000</date>
<authorinitials>mfk</authorinitials>
<revremark>Documented sgedit</revremark>
</revision>
<revision>
<revnumber>1.4</revnumber>
<date>Jun 12, 2000</date>
<authorinitials>mfk</authorinitials>
<revremark>Documented vim and sgedit. Spelling and other
changes from ldp list. Also added LDP guidelines under style
guide.</revremark>
</revision>
</revhistory>
</bookinfo>
<chapter id="aboutthisguide">
<title>About this Guide</title>
<section id="purpose">
<title>Purpose / Scope of this Guide</title>
<para>This document was started on Aug 26, 1999 by Mark
F. Komarinski after two day's worth of frustration getting tools
to work. If even one LDP author is helped by this, then I did my
job.</para>
<para>
The newest version of this document can be found at the LDP
homepage
<ulink url="http://www.linuxdoc.org/">http://www.linuxdoc.org</ulink>.
The original DocBook, HTML, and other formats can be found there.
</para>
<para>There are many ways to contribute to the Linux movement
without actually writing code. One of the most important is
writing documentation, allowing each person to share their
knowledge with thousands of others around the world. This Guide
is designed to help you get familiar with how the LDP works, and
what tools you'll need to write your own HOWTO.</para>
</section>
<section id="aboutldp">
<title>About the LDP</title>
<blockquote>
<attribution>LDP Manifesto located at <ulink
url="http://www.linuxdoc.org/manifesto.html">http://www.linuxdoc.org/manifesto.html</ulink></attribution>
<para>The Linux Documentation Project (LDP) is working on
developing free, high-quality documentation for the GNU/Linux
operating system. The overall goal of the LDP is to
collaborate in all of the issues of Linux documentation. This
includes the creation of "HOWTOs" and "Guides". We hope to
establish a system of documentation for Linux that will be
easy to use and search. This includes the integration of the
manual pages, info docs, HOWTOs, and other documents.</para>
</blockquote>
<para>
The human readable version goes more like this: The LDP consists
of a large group of volunteers that are working on documentation
for the Linux OS. The most visible documentation are the HOWTOs
located at <ulink url="http://www.linuxdoc.org/">http://www.linuxdoc.org/"</ulink>.
This Guide focuses primarily on how to write your own HOWTOs for
submission to the LDP.
</para>
</section>
<section id="feedback">
<title>Feedback</title>
<para>Comments on this Guide may be directed to the LAG coordinator
(<email>markk@wayga.net</email>).</para>
</section>
<section id="copyrights">
<title>Copyrights and Trademarks</title>
<para>Copyright 1999-2001 Mark F. Komarinski, David C. Merrill, Jorge Godoy</para>
<para>
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
Texts. A copy of the license is included in the appendix entitled "GNU
Free Documentation License".
</para>
</section>
<section id="acknowledgements">
<title>Acknowledgments and Thanks</title>
<para>Thanks to everyone that gave comments as I was writing
this. This includes David Lawyer, Deb Richardson, Daniel Barlow,
Greg Ferguson, Mark Craig and other members of the
<email>discuss@linuxdoc.org</email> list. Some
sections I got from the <ulink
url="http://www.linuxdoc.org/HOWTO/">HOWTO Index</ulink> and the
sgmltools documentation. The sections on network access to CVS
was partially written by Serek
(<email>ser@serek.arch.pwr.wroc.pl</email>). Sections on DocBook
were written by Jorge Godoy
(<email>godoy@conectiva.com</email>). A great deal of thanks
to both of them for their help.</para>
</section>
&conventions;
</chapter>
<chapter id="introduction">
<title>Introduction to the LDP and DocBook</title>
<section id="theldp">
<title>The LDP</title>
<para>The Linux Documentation Project (LDP) was started to
provide new users a way of quickly getting information about a
particular subject. It not only contains a series of books on
administration, networking, and programming, but also has a large
number of smaller works on individual subjects, written by those
who have used it. If you want to find out about printing, you
get the <ulink
url="http://www.linuxdoc.org/HOWTO/Printing-HOWTO.html">Printing
HOWTO</ulink>. If you want to do find out if your Ethernet card
works with Linux, grab the <ulink
url="http://www.linuxdoc.org/HOWTO/Ethernet-HOWTO.html">Ethernet
HOWTO</ulink>, and so on. At first, many of these works were in
text or HTML. As time went on, there had to be a better way of
managing these documents. One that would let you read it from a
web page, a text file on a CD-ROM, or even your hand-held
PDA. The answer, as it turns out, is DocBook.</para>
</section>
<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
language that is based on embedding codes within a document. In
this way, it is similar to HTML, but there is where any
similarities end. The power of SGML is that unlike WYSIWYG (What
You See Is What You Get), you don't define things like colors,
or font sizes, or even some kinds of formatting. Instead, you
define elements (paragraph, section, numbered list) and let the
SGML processor and the end program worry about placement,
colors, fonts, and so on. HTML does the same thing, and is
actually a subset of SGML. SGML has really three parts that make
it up. First is the Structure, which is what is commonly called
the DTD, or Document Type Definition. The DTD defines the
relationship between each of the elements (or tags). The DocBook
DTD, used to create this document, is an example of this. The
DTD lists the rules that the content must follow. Second is the
DSSSL or Document Style Semantics and Specification Language.
The DSSSL tells the program doing the rendering how to convert
the SGML into something that a human can read. 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 a &lt;h1&gt; tag if
it is going to HTML. Finally there is the Content, which is
what gets rendered by the SGML processor and is eventually seen
by the user. This paragraph is content, but so is a graphic
image, a table, a numbered list, and so on. Content is surrounded by
tags to separate each element.</para>
<para>
The Extensible Markup Language (XML) has all the advantages
of SGML, but is getting much more press and development time.
For the purposes of writing documentation, the differences
are minimal.
</para>
<para>
This brings us back to DocBook, which is a DTD available for
both SGML and XML. Since the tags themselves do not change
when moving from DocBook XML to DocBook SGML, much of this
guide will apply to both versions of the DTD.
</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. The Jade and OpenJade packages also
let you export (I'll call it render from here on) 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 render from SGML to whatever you
chose. In
the end, DocBook is more concerned about the way elements work
instead of the way they look. A big distinction,and one that
will let you write faster, since you don't have to worry about
placement of paragraphs, font sizes, font types, and so
on.</para>
</section>
&xml;
<section id="newauthors">
<title>For New Authors</title>
<para>If you are a new to the LDP and want to pick up an
unmaintained HOWTO or write a new HOWTO document, contact the
HOWTO coordinator at
<email>discuss@linuxdoc.org</email>. This is to make
sure the HOWTO coordinator can know who is working on what
documentation.</para>
<para>Once that part is complete, you may write your
documentation in the format of your choice and submit a draft to
<email>submit@linuxdoc.org</email> and the draft will
be reviewed by an LDP volunteer. In a few short days you will
get the draft and comments from the volunteer. After applying
the comments, you may send this version to the ldp-submit list
again for final submission into the LDP.</para>
<para>At this point, another LDP volunteer will translate your
document into DocBook and send you the finished DocBook
document. From here on, all submissions to the LDP has to be in
DocBook format. If you have markup questions, you may ask the
volunteer who assisted you, or ask the LDP DocBook list.</para>
<para>If you choose to start your document off in DocBook, there
are plenty of templates to get you started:</para>
<itemizedlist>
<listitem><para>
<ulink url="http://www.linuxdoc.org/authors/template-ld/big-howto-template-ld.sgml">http://www.linuxdoc.org/authors/template-ld/big-howto-template-ld.sgml</ulink> -
This template is written by Stein Gojen
and is based off the LinuxDoc template.</para>
</listitem>
<listitem><para><ulink url="http://www.linuxdoc.org/authors/template/big-howto-template.sgml">http://www.linuxdoc.org/authors/template/big-howto-template.sgml</ulink> - This template is based on Stein's work, but is much larger
and complicated than the above. It uses more features of DocBook.</para>
</listitem>
</itemizedlist>
<section id="newauthorresources">
<title>Resources for New Authors</title>
<para>
This section contains a list of web sites and books
that may be useful to new readers. If you have never used
DocBook before, or have never written technical documentation
before, please take a look at these.
</para>
<itemizedlist>
<listitem>
<para>
<ulink url="http://lwn.net/2000/features/DocBook/">http://lwn.net/2000/features/DocBook/</ulink> - DocBook tutorial from Linux Weekly News
</para>
</listitem>
<listitem>
<para>
<ulink url="http://docbook.org/tdg/html/quickref.html">http://docbook.org/tdg/html/quickref.html</ulink> - Quick Reference Guide to DocBook v3.1 tags.
</para>
</listitem>
</itemizedlist>
</section> <!-- newauthorresources -->
</section> <!-- newauthor -->
<section id="mailinglists">
<title>Mailing Lists</title>
<para>There are a few mailing lists to subscribe to so you can
take part in how the LDP works. First is
<email>discuss@linuxdoc.org</email>, which is the main
discussion group of the LDP. To subscribe, send a message with
the subject reading &quot;subscribe&quot; to
<email>discuss-subscribe@linuxdoc.org</email>. To
unsubscribe, send an e-mail with the subject of
&quot;unsubscribe&quot; to
<email>discuss-unsubscribe@linuxdoc.org</email>.</para>
<para>Another list is the
<email>docbook@linuxdoc.org</email> list, which is for
markup or other questions about DocBook itself. If you run into
trouble with a particular markup tag, you can send your question
here for answers. You can subscribe to the DocBook list by
sending a "subscribe" message to
<email>docbook-subscribe@linuxdoc.org</email>.</para>
<para>
There is also a mailing list run by OASIS that can also
answer DocBook questions. Please see <ulink url="http://docbook.org/mailinglist/index.html">http://docbook.org/mailinglist/index.html</ulink>
for more information about the mailing lists. The LDP prefers
our own list, but only because the LDP list focuses more on tag usage
than other questions such as formatting.
</para>
</section>
</chapter>
<chapter id="tools">
<title>The tools</title>
<para>In this section, we will cover some of the tools that you will
need or want to use to create your own LDP documentation. I'll
describe them here, and better define them later on, along with
how to install them. If you use some other tool to assist in
writing LDP, please let me know and I'll add a blurb here for
it.</para>
<section id="dsssl">
<title>DSSSL</title>
<para>The Normal Walsh version is required, the LDP is
optional.</para>
<section id="nwdsssl">
<title>Norman Walsh DSSSL</title>
<para><ulink
url="http://nwalsh.com/docbook/dsssl/">http://nwalsh.com/docbook/dsssl/</ulink></para>
<para>The <indexterm><primary>DSSSL</primary></indexterm>
Document Style Semantics and Specification Language
tells jade (see <xref linkend="jade"/>) how to render a DocBook document
into print or online
form. The DSSSL is what converts a title tag into an
&lt;H1&gt; tag in HTML, or to 14 point bold Times Roman for RTF,
for example. Documentation for DSSSL is located at the same
site. Note that modifying the DSSSL doesn't modify DocBook
itself. It merely changes the way the rendered text looks. The
LDP uses a modified DSSSL (see below).</para>
</section>
<section id="ldpdsssl">
<title>LDP DSSSL</title>
<para><ulink
url="http://www.linuxdoc.org/authors/tools/ldp.dsl">http://www.linuxdoc.org/authors/tools/ldp.dsl</ulink></para>
<para>The LDP DSSSL requires the Norman Walsh version (see
above) but is a slightly modified DSSSL to provide things like
a table of contents.</para>
</section>
</section>
<section id="dtd">
<title>DocBook DTD (version 4.1 or 3.1)</title>
<para>Required - <ulink
url="http://www.oasis-open.org/docbook/sgml/4.1/docbk41.zip">http://www.oasis-open.org/docbook/sgml/4.1/docbk41.zip</ulink> or <ulink
url="http://www.oasis-open.org/docbook/sgml/3.1/docbk31.zip">http://www.oasis-open.org/docbook/sgml/3.1/docbk31.zip</ulink></para>
<para>The XML DTD is available from <ulink url="http://www.oasis-open.org/docbook/xml/4.1.2">http://www.oasis-open.org/xml/4.1.2/</ulink>.
</para>
<para>
The <indexterm><primary>DocBook DTD</primary></indexterm>
DocBook DTD defines the tags and structure of a
DocBook document. Modifying the DTD, such as adding a new
tag, means that this DTD is no longer DocBook.
</para>
</section>
<section id="jade">
<title>Jade</title>
<para>
<indexterm><primary>jade</primary></indexterm>
Jade and OpenJade are two of the programs that do most of
the rendering and validation of code based on the DTD and
DSSSL. One of the following is required and should be installed
after the DTD and DSSSL have been installed.
</para>
<section>
<title>Jade</title>
<para><ulink
url="ftp://ftp.jclark.com/pub/jade/jade-1.2.1.tar.gz">ftp://ftp.jclark.com/pub/jade/jade-1.2.1.tar.gz</ulink></para>
<para>Jade is the front-end processor for SGML and XML. It uses the
DSSSL and DocBook DTD to perform the verification and
rendering from SGML and XML into the target format.</para>
<section id="usingjade">
<title>Using Jade</title>
<para>This is the quick and dirty way that should work for all
distributions, no matter what one you are using.
</para>
<orderedlist inheritnum="ignore" continuation="restarts">
<listitem>
<para>Create a base directory to store everything such as
<filename moreinfo="none"
class="directory">/usr/local/sgml/</filename>. We'll call
this <envar>$_toolroot</envar> from here on.</para>
</listitem>
<listitem>
<para>Install Jade, DocBook DTD, and DSSSL such that the
base of each is under <envar>$_toolroot</envar>, creating:
</para>
<itemizedlist>
<listitem>
<para><filename class="directory">$_toolroot/jade-1.2.1</filename>
</para>
</listitem>
<listitem>
<para><filename class="directory">$_toolroot/dtd</filename>
</para>
</listitem>
<listitem>
<para><filename class="directory">$_toolroot/dsssl</filename>
</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>You'll need to set the
<envar>SGML_CATALOG_FILES</envar> environment variable to
the catalogs that you have under<filename moreinfo="none"
class="directory">$_toolroot</filename>. You can do this
with the command:
<screen format="linespecific">
<prompt moreinfo="none">bash$</prompt> <command moreinfo="none">export SGML_CATALOG_FILES=$_toolroot/dtd/docbook.cat:\
$_toolroot/dsssl/docbook/catalog:$_toolroot/jade-1.2.1/dsssl/catalog</command>
</screen>
</para>
</listitem>
<listitem>
<para>Now you can start using Jade. To create individual
HTML files: </para>
<screen format="linespecific">
<command moreinfo="none">$_toolroot/jade-1.2.1/jade/jade -t sgml -i html \
-d $_toolroot/dsssl/docbook/html/docbook.dsl howto.sgml</command>
</screen>
</listitem>
<listitem>
<para>To create one large HTML file, add <emphasis>-V
nochunks</emphasis> to the jade command.</para>
</listitem>
</orderedlist>
</section>
<section id="jadexml">
<title>Jade in XML mode</title>
<para>
Once configured for XML, jade and openjade will work
the same way as for SGML DocBook.
</para>
<para>
After extracting the XML DTD, you will want to make
a symlink from the docbook.cat file to "catalog", the
default filename for jade/openjade catalogs. Replace
$_xml_root with the location of your XML DTD.
</para>
<informalexample>
<screen format="linespecific">
<prompt moreinfo="none">bash$</prompt> <command>cd $_xml_root</command>
<prompt moreinfo="none">bash$</prompt> <command>ln -s docbook.cat catalog</command>
<prompt moreinfo="none">bash$</prompt> <command>export SGML_CATALOG_FILES=$_xml_root/catalog:$_toolroot/dsssl/catalog:\
$_toolroot/dtd/docbook/catalog</command> <co id="export"/>
<prompt moreinfo="none">bash$</prompt> <command>jade -t sgml -i html -d <replaceable>style</replaceable> $_jade_path/pubtext/xml.dcl foo.xml</command> <co id="jadexmlcmd"/>
</screen>
<calloutlist>
<callout arearefs="export">
<para>
You'll need the catalogs for XML, the DSSSL, and DocBook,
respectively. $_toolroot was defined above.
</para>
</callout>
<callout arearefs="jadexmlcmd">
<para>
Replace <replaceable>style</replaceable> with the DSSSL
(ldp.dsl) you wish to use. The pointer to xml.dcl is
required for jade to work, and it has to be listed
immediately before the pointer to your XML document.
This file may be in a different directory.
Check your distribution.
</para>
<para>
You may get the following warnings when processing XML
documents. They don't impact the output, and the cause
is being looked into.
</para>
<screen>
&lt;xml_dtd_pth&gt;/ent/iso-lat2.ent:119:18:E: "X0176" is not a function name
&lt;xml_dtd_pth&gt;/ent/iso-lat2.ent:120:17:E: "X0178" is not a function name
</screen>
</callout>
</calloutlist>
</informalexample>
<para>
If you want to convert your existing SGML DocBook into
XML docbook, use this as your declaration (the lines at the
very start of your document).
</para>
<screen>
&lt;?xml version='1.0' encoding='ISO-8859-1'?&gt;
&lt;!DOCTYPE article PUBLIC '-//OASIS//DTD DocBook XML V4.1.2//EN'&gt;
</screen>
<para>
If you have followed LDP guidelines, there should be no
other changes required to your document. Note that there
are changes between DocBook 3.x and 4.x that you may
also have to take into account. You can get more information
at this in <xref linkend="differences3040"/>.
</para>
</section>
</section>
<section id="openjade">
<title>OpenJade</title>
<para><ulink
url="http://openjade.sourceforge.net/">http://openjade.sourceforge.net/</ulink></para>
<para>An extension of Jade written by the DSSSL
community. Some applications require jade, but are being
updated to support either software package.</para>
</section>
</section>
<section id="jadewrappers">
<title>Jade wrappers</title>
<para>These tools are optional and may be installed after Jade,
the DSSSL, and DTD have been installed.</para>
<section id="sgmltools-lite">
<title>sgmltools-lite</title>
<para><ulink
url="http://sgmltools-lite.sourceforge.net/">http://sgmltools-lite.sourceforge.net/</ulink></para>
<para>This is the successor to the sgmltools project, which
has been officially disbanded for over a year. Since then,
Cees de Groot has created a slightly different project, which
acts as a wrapper to the jade SGML processor. It hides much of
the ugliness of the syntax. This author was able to install the
old sgmltools package followed by the sgmltools-lite and could
format this document quite easily. There's even a man page for
sgmltools showing syntax.</para>
</section>
<section id="cygnus">
<title>Cygnus DocBook Tools</title>
<para>May be Red Hat specific - <ulink
url="http://www.redhat.com/">http://www.redhat.com/</ulink></para>
<para>
<indexterm><primary>Cygnus Tools</primary></indexterm>
Red Hat distributes three packages, starting with the
6.2 release, that include DocBook support and some tools. The
tools are easily installed, allowing you to focus more on
writing than wrestling with the tools. TeTex, Jade, and
JadeTeX must be installed first. All three of these packages
are available on the installation CD.
</para>
<section id="usingcygnus">
<title>Using the Cygnus Tools</title>
<para> These tools are provided with Red Hat 6.2. Make sure
the following packages are installed: </para>
<itemizedlist>
<listitem><para> sgml-common-0.1-8.noarch </para></listitem>
<listitem><para> docbook-3.1-4.noarch </para></listitem>
<listitem><para> stylesheets-1.54.13rh-1.noarch </para></listitem>
</itemizedlist>
<para> Red Hat has the latest version on their web site:
<ulink
url="http://www.redhat.com/support/errata/RHBA-2000022-01.html">http://www.redhat.com/support/errata/RHBA-2000022-01.html</ulink>.</para>
<para>Download/get/sneaker-net the RPMs to your machine and
install in the usual manner (become root, then <command
moreinfo="none">rpm -Uvh filename</command>). Once the RPMs
are installed, you can use the following commands to render
DocBook: </para>
<screen>
<prompt>bash$</prompt> <command>db2html</command> <option>filename</option>
</screen>
<para> Renders DocBook into HTML. A subdirectory with the
filename (minus the .sgml extension) is created and the HTML
files are placed there. </para>
<screen>
<prompt>bash$</prompt> <command>db2pdf</command> <option>filename</option>
</screen>
<para>Renders DocBook into a PDF file. Note that there is currently a
problem with db2pdf, and pd2ps caused by JadeTeX. This has been
<ulink url="http://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=9670">
registered as a bug with RedHat</ulink>.</para>
</section>
</section>
</section>
<section id="editing">
<title>Editing tools</title>
<para>The following tools may be used to create, edit, or
validate your HOWTO.</para>
<section id="psgml">
<title>Emacs (PSGML)</title>
<para>Optional - <ulink
url="http://www.lysator.liu.se/~lenst/about_psgml/">http://www.lysator.liu.se/~lenst/about_psgml/</ulink></para>
<indexterm>
<primary>Emacs</primary>
</indexterm>
<indexterm>
<primary>Editors</primary>
<secondary>emacs</secondary>
</indexterm>
<para>Emacs has an SGML writing mode called psgml that is a
major mode designed for editing SGML and XML documents. It
provides <quote>syntax highlighting</quote> or <quote>pretty
printing</quote> features that make SGML tags stand out, a way
to insert tags other than typing them by hand, and the ability
to validate your document while writing.</para>
<para>For users of Emacs, it's a great way to go, and many
believe it to allow more versatility than any other SGML
documentation tool. It works with DocBook, LinuxDoc and other
DTDs equally well.</para>
<section>
<title> Writing SGML using PSGML </title>
<section><title> Introduction </title>
<para> If you have installed a recent distribution, you may
already have PSGML installed for use with Emacs. To check,
start Emacs and look for the PSGML documentation (<keycombo
moreinfo="none"><keycap moreinfo="none">C</keycap><keycap
moreinfo="none">h</keycap></keycombo><keycap
moreinfo="none">i</keycap><keycap
moreinfo="none">m</keycap><keycap
moreinfo="none">psgml</keycap>).</para>
<para> From here on, we assume you have PSGML installed for
use with a recent version of GNU Emacs. If that all went by
too fast for you, see the free chapter from Bob Ducharme's
SGML CD book: <ulink
url="http://www.snee.com/bob/sgmlfree/psgmqref.html">http://www.snee.com/bob/sgmlfree/psgmqref.html</ulink>.</para>
</section>
<section>
<title> Updating your .emacs to use PSGML </title>
<para> If you want GNU Emacs to enter PSGML mode when you open
a <emphasis>.sgml</emphasis> file and be ready for SGML
editing, make sure PSGML can find the DocBook DTD. If your
distribution already had PSGML set up for use with GNU Emacs,
you probably do not have to do anything to get this to
work. Otherwise, you may need to set an environment variable
that tells PSGML where to look for the SGML catalog (the list
of DTDs). </para>
<para> For example: </para>
<screen format="linespecific">
<prompt>bash$</prompt> <command>export SGML_CATALOG_FILES=/usr/lib/sgml/catalog</command>
</screen>
<para> Then add something like the following to your .emacs
file: </para>
<programlisting>
;; *******************************************************************
;; set up psgml mode...
;; use psgml-mode instead of emacs native sgml-mode
;;
(autoload 'sgml-mode "psgml" "Major mode to edit SGML files." t )
(setq auto-mode-alist
(append
(list
'("\\.sgm$" . sgml-mode)
'("\\.sgml$" . sgml-mode)
)
auto-mode-alist))
;; set some psgml variables
(setq sgml-auto-activate-dtd t)
(setq sgml-omittag-transparent t)
(setq sgml-balanced-tag-edit t)
(setq sgml-auto-insert-required-elements t)
(setq sgml-live-element-indicator t)
(setq sgml-indent-step nil)
;; create faces to assign to markup categories
(make-face 'sgml-comment-face)
(make-face 'sgml-start-tag-face)
(make-face 'sgml-end-tag-face)
(make-face 'sgml-entity-face)
(make-face 'sgml-doctype-face) ; DOCTYPE data
(make-face 'sgml-ignored-face) ; data ignored by PSGML
(make-face 'sgml-ms-start-face) ; marked sections start
(make-face 'sgml-ms-end-face) ; end of marked section
(make-face 'sgml-pi-face) ; processing instructions
(make-face 'sgml-sgml-face) ; the SGML declaration
(make-face 'sgml-shortref-face) ; short references
;; view a list of available colors with the emacs-lisp command:
;;
;; list-colors-display
;;
;; please assign your own groovy colors, because these are pretty bad
(set-face-foreground 'sgml-comment-face "coral")
;(set-face-background 'sgml-comment-face "cornflowerblue")
(set-face-foreground 'sgml-start-tag-face "slateblue")
;(set-face-background 'sgml-start-tag-face "cornflowerblue")
(set-face-foreground 'sgml-end-tag-face "slateblue")
;(set-face-background 'sgml-end-tag-face "cornflowerblue")
(set-face-foreground 'sgml-entity-face "lavender")
;(set-face-background 'sgml-entity-face "cornflowerblue")
(set-face-foreground 'sgml-doctype-face "lavender")
;(set-face-background 'sgml-doctype-face "cornflowerblue")
(set-face-foreground 'sgml-ignored-face "cornflowerblue")
;(set-face-background 'sgml-ignored-face "cornflowerblue")
(set-face-foreground 'sgml-ms-start-face "coral")
;(set-face-background 'sgml-ms-start-face "cornflowerblue")
(set-face-foreground 'sgml-ms-end-face "coral")
;(set-face-background 'sgml-ms-end-face "cornflowerblue")
(set-face-foreground 'sgml-pi-face "coral")
;(set-face-background 'sgml-pi-face "cornflowerblue")
(set-face-foreground 'sgml-sgml-face "coral")
;(set-face-background 'sgml-sgml-face "cornflowerblue")
(set-face-foreground 'sgml-shortref-face "coral")
;(set-face-background 'sgml-shortref-face "cornflowerblue")
;; assign faces to markup categories
(setq sgml-markup-faces '
(
(comment . sgml-comment-face)
(start-tag . sgml-start-tag-face)
(end-tag . sgml-end-tag-face)
(entity . sgml-entity-face)
(doctype . sgml-doctype-face)
(ignored . sgml-ignored-face)
(ms-start . sgml-ms-start-face)
(ms-end . sgml-ms-end-face)
(pi . sgml-pi-face)
(sgml . sgml-sgml-face)
(shortref . sgml-shortref-face)
))
;; tell PSGML to pay attention to face settings
(setq sgml-set-face t)
;; ...done setting up psgml-mode.
;; *******************************************************************
</programlisting>
<para> Then restart Emacs </para>
</section>
<section>
<title> SGML Smoke Test </title>
<para> Try the following smoke test. Start a new file,
<filename moreinfo="none">/tmp/test.sgml</filename> for
example, and enter the following: </para>
<programlisting format="linespecific">
<sgmltag class="starttag">!DOCTYPE test [
&lt;!ELEMENT test - - (#PCDATA)&gt;
]</sgmltag>
</programlisting>
<para> Enter <keycombo moreinfo="none"><keycap
moreinfo="none">C</keycap> <keycap
moreinfo="none">c</keycap></keycombo><keycombo
moreinfo="none"><keycap moreinfo="none">C</keycap>
<keycap moreinfo="none">p</keycap></keycombo>. If Emacs
manages to parse your DTD, you will see <emphasis>Parsing
prolog...done</emphasis> in the minibuffer. Try
<emphasis>C-c C-e RETURN</emphasis> to insert a
<emphasis><sgmltag
class="starttag">test</sgmltag></emphasis> element. If
things are working correctly, you should see the following
in Emacs: </para>
<programlisting format="linespecific">
<sgmltag class="starttag">!DOCTYPE test [
&lt;!ELEMENT test - - (#PCDATA)&gt;
]</sgmltag>
<sgmltag class="starttag">test</sgmltag><sgmltag class="endtag">test</sgmltag>
</programlisting>
</section>
<section>
<title> Writing a New HOWTO in DocBook </title>
<para> Start a new file for your HOWTO and enter the
following: </para>
<programlisting format="linespecific">
<sgmltag class="starttag">!DOCTYPE ARTICLE PUBLIC "-//OASIS//DTD DocBook V3.1//EN"</sgmltag>
</programlisting>
<para> Enter <keycombo moreinfo="none"><keycap
moreinfo="none">C</keycap><keycap
moreinfo="none">c</keycap></keycombo><keycombo
moreinfo="none"><keycap moreinfo="none">C</keycap>
<keycap moreinfo="none">p</keycap></keycombo> and hold
your breath. If everything goes as planned, you will see
Emacs chewing for a few seconds and then <emphasis>Parsing
prolog...done</emphasis> in the minibuffer. </para>
<para> At this point, enter <keycombo moreinfo="none"><keycap
moreinfo="none">C</keycap> <keycap
moreinfo="none">c</keycap></keycombo><keycombo
moreinfo="none"><keycap moreinfo="none">C</keycap><keycap
moreinfo="none">e</keycap></keycombo><keycap
moreinfo="none">RETURN</keycap> to insert an
<emphasis><sgmltag
class="starttag">article</sgmltag></emphasis> element and
proceed to write your HOWTO. </para>
</section>
<section>
<title> Quick Reference for Emacs with PSGML </title>
<para> See Nik Clayton's primer for FreeBSD documentation:
<ulink
url="http://www.freebsd.org/tutorials/docproj-primer/psgml-mode.html">http://www.freebsd.org/tutorials/docproj-primer/psgml-mode.html</ulink>
</para>
</section>
</section>
</section>
<section id="vim">
<title>VIM</title>
<para><ulink
url="http://www.vim.org">http://www.vim.org</ulink></para>
<para>No mention of Emacs is complete without talking about
vi. The <indexterm><primary>vim</primary></indexterm>
<indexterm>
<primary>Editors</primary>
<secondary>vim</secondary>
</indexterm>
VIM (Vi IMproved) editor has the functionality of
regular vi, but also has an SGML mode that will
color-coordinate your screen to show where tags are.</para>
<section id="usingvim">
<title>Getting Started</title>
<para>The vim program comes in many parts. There is
the plain vim program, which is compatibile with the
vi program and its commands. Red Hat users will want the vim-common
and vim-minimal packages. Next is the enhanced
<command>vim</command>, which includes the highlighting and other
features of vim over regular vi. Red Hat
users will want vim-enhanced. Last, but certainly not least, is the
X interface, which gives a graphical interface, menus, and mouse
control. To separate this from vim or vi, the command for graphical
access is called <command>gvim</command>.</para>
</section>
<section>
<title>Loading or starting new documents</title>
<para>In both <command>vim</command> and <command>gvim</command> modes,
<filename>.sgml</filename> files will be automatically recognized and
enter into <quote>sgml mode</quote>. A series of known DocBook tags
have been entered into <command>vim</command> and will he highlighted
in brown if a tag is known. If it isn't, it will appear in light blue.
attributes to known tags are in light blue, and values for the
attributes are in pink. From here on, you can use regular <command>vi</command>
commands to navigate and edit.</para>
<para>
While VIM has an XML mode, this mode will not highlight known
and unknown DocBook tags. You can still force VIM into
SGML mode if you like using the <command>:set ft=sgml</command>
command. Note that this will not have any affect on the file
or its contents, only the highlighting within VIM.
</para>
</section>
</section>
<section id="wordperfect">
<title>WordPerfect 9 (Corel Office 2000)</title>
<para><ulink
url="http://www.corel.com/">http://www.corel.com/</ulink></para>
<para>WordPerfect 9 for the MS Windows platform has support
for SGML and DocBook 3.0. WordPerfect 9 for Linux has no SGML
capabilities.</para>
<para>This is the least expensive of the commercial
applications that support SGML.</para>
</section>
<section id="epcEdit">
<title>epcEdit</title>
<para><ulink
url="http://www.tksgml.de/">http://www.tksgml.de/</ulink></para>
<para>The <indexterm><primary>epcEdit</primary></indexterm>
<indexterm>
<primary>Editors</primary>
<secondary>epcEdit</secondary>
</indexterm>
epcEdit program allows you to visually edit SGML
files. It has the advantages of not needing to know Emacs or
vi before starting, and is cross-platform, working in both
Windows and Linux. This is a commercial application, and
pricing can be found at
<ulink url="http://www.tksgml.de/pricing.html">http://www.tksgml.de/pricing.html</ulink>
</para>
<para>Along with visual editing, epcEdit will also validate
documents on loading, and on demand by using the <menuchoice
moreinfo="none"><guimenu
moreinfo="none">Document</guimenu><guimenuitem
moreinfo="none">Validate</guimenuitem></menuchoice>
command.</para>
<figure>
<title>epcEdit screen shot</title>
<mediaobject>
<imageobject>
<imagedata format="EPS" fileref="sgeditscreenshot.eps"/>
</imageobject>
<imageobject>
<imagedata format="JPG" fileref="sgeditscreenshot.jpg"/>
</imageobject>
<textobject>
<phrase>The screen shot of the epcEdit program shows a
tree on the left side that has the SGML document in a
hierarchy, while the right side shows the document.
Tags are shown with a grey background.</phrase>
</textobject>
</mediaobject>
</figure>
</section>
<section id="nedit">
<title>nedit</title>
<para><ulink
url="http://nedit.org">http://nedit.org</ulink></para>
<para>To be fair,
<indexterm><primary>nedit</primary></indexterm>
<indexterm>
<primary>Editors</primary>
<secondary>nedit</secondary>
</indexterm>
nedit is more
for programmers, so it might seem a bit of overkill for new
users and especially non-programmers. All that aside, it's
extremely powerful, allowing for color coding of tags. Unlike
epcEdit, nedit doesn't allow you to automatically insert tags
or automatically validate your code. However, it does allow
for shell commands to be run against the contents of the
window (as opposed to saving the file, then checking). In a
few minutes, I was able to set up <command>nsgmls</command> to
validate the SGML and <command>aspell</command> to do my spell
checking.
<figure>
<title>nedit screen shot</title>
<mediaobject>
<imageobject>
<imagedata fileref="neditscreenshot.eps" format="EPS"/>
</imageobject>
<imageobject>
<imagedata fileref="neditscreenshot.jpg" format="JPG"/>
</imageobject>
<textobject>
<phrase>The nedit program can provide line numbers
across the left side of the screen, handy for when
<command>nsgmls</command> complains of errors</phrase>
</textobject>
</mediaobject>
</figure>
</para>
<section id="usingnedit">
<title>Using nedit</title>
<para>For writing new documentation, it is recommended that
you download and use the LDP DocBook template. Once you have
the file, you can start up nedit and begin editing. If the
file is saved with a .sgml extension, nedit will load the file
up with SGML/HTML tags enabled. You can turn this on
explicitly using the
<menuchoice><guimenu>Preferences</guimenu><guimenuitem>Language
Mode</guimenuitem><guimenuitem>SGML
HTML</guimenuitem></menuchoice> command. </para>
</section> <!-- New Documents -->
<section id="tipsandtricksnedit">
<title>Tips and tricks with nedit</title>
<para>Since you can feed the contents of your window to
outside programs, you can easily extend nedit to perform
repetitive functions. The example you'll see here is to
validate the SGML code using <command>nsgmls</command>.</para>
<para> Select
<menuchoice><guimenu>Preferences</guimenu><guimenuitem>Default
Settings</guimenuitem><guimenuitem>Customize
Menus</guimenuitem><guimenuitem>Shell
Menu...</guimenuitem></menuchoice>. This will bring up the
Shell Command dialog box, with all the shell commands nedit
has listed under the
<menuchoice><guimenu>Shell</guimenu></menuchoice> menu. Under
Menu Entry, enter "SGML Validate". This will be the entry
you'll see on the screen. Under Accelerator, press
<keycombo><keycap>Alt</keycap><keycap>S</keycap></keycombo>.
Once this menu item is set up, you can press
<keycombo><keycap>Alt</keycap><keycap>S</keycap></keycombo>
to have the SGML Validate automatically run. Under Command
Input, select window, and under Command Output, select
dialog. Under Command to Execute, enter nsgmls -sv. Note
that <command>nsgmls</command> has to be in your
<envar>PATH</envar> for this to work properly. </para>
<figure>
<title>Adding shell commands to nedit</title>
<mediaobject>
<imageobject>
<imagedata fileref="neditshellcommand.eps" format="EPS"/>
</imageobject>
<imageobject>
<imagedata fileref="neditshellcommand.jpg" format="JPG"/>
</imageobject>
</mediaobject>
</figure>
<para> Click <guibutton>OK</guibutton> and you'll now be back
at the main nedit screen. Load up an SGML file, and select
<menuchoice><guimenu>Shell</guimenu><guimenuitem>SGML
Validate</guimenuitem></menuchoice> or press
<keycombo><keycap>Alt</keycap><keycap>S</keycap></keycombo>.
The <command>nedit</command> program will fire up and check
the contents of the window. The reason for using -sv is that
the -v tells <command>nsgmls</command> to output the version
of the program, so you'll always get output and know that
<command>nsgmls</command> has run. If all you get is a
version number, then there are no errors with the document.
If there are errors, then they'll be listed in the separate
window for you to see. If you have line numbers turned on
(using
<menuchoice><guimenu>Preferences</guimenu><guimenuitem>Show
Line Numbers</guimenuitem></menuchoice>) then finding the
errors is much simpler, as <command>nsgmls</command> will list
errors by their line number.</para>
<figure>
<title>nsgmls output on success</title>
<mediaobject>
<imageobject>
<imagedata fileref="neditsuccess.eps" format="EPS"/>
</imageobject>
<imageobject>
<imagedata fileref="neditsuccess.jpg" format="JPG"/>
</imageobject>
<textobject>
<phrase>If nsgmls reports success, it merely reports the version of nsgmls</phrase>
</textobject>
</mediaobject>
</figure>
</section>
</section>
</section>
&cvs;
<section id="other">
<title>Other/Reference</title>
<para>The items in this section are reference books or other
utilities that can't quite be categorized (yet).</para>
<section id="docbooktdg">
<title>DocBook: The Definitive Guide</title>
<para><ulink
url="http://www.docbook.org/">http://www.docbook.org/</ulink></para>
<para>This book was released by O'Reilly in October 1999, and
is a great reference to DocBook. I have not found it to be a
great practical book, and much of the emphasis is on XML, but
the DocBook tags for version 3.1 are all listed in a handy
format. You can pick it up at the book vendor of choice. The
entire book is also available online (in HTML and SGML
formats) at the above URL. </para>
</section>
<section id="templates">
<title>SGML templates</title>
<para>Optional - <ulink url="http://www.linuxdoc.org/authors/index.html#resources">http://www.linuxdoc.org/authors/index.html#resources</ulink></para>
<para>Contains links to SGML templates and their resulting HTML output
to help you see what your document will look like. Many of the tags
just need to be replaced with information unique to your HOWTO.
</para>
</section>
<section id="aspell">
<title>Aspell</title>
<para>Optional - <ulink
url="http://aspell.sourceforge.net/">http://aspell.sourceforge.net/</ulink></para>
<para>This spell checking application can work around SGML
tags, and only spell check the content within the
tags. Older version of ispell will try to spell
check the tags, causing errors at every new tag.</para>
</section>
<section id="ispell">
<title>ispell</title>
<para>Optional - <ulink url="http://www.cs.hmc.edu/~geoff/ispell.html">http://www.cs.hmc.edu/~geoff/ispell.html</ulink></para>
<para>The ispell program is distributed with RedHat (and possibly other
distros) and also ignores markup tags.</para>
</section>
</section>
</chapter>
&using-docbook;
&style-guide;
<chapter id="other-style">
<title> Additional Style-related Items</title>
<para> This section contains additional style-oriented topics to
consider when preparing your document. </para>
<section id="accepteddates">
<title> Date formats </title>
<para> The <sgmltag class="starttag">pubdate</sgmltag> tag in
your header should be in the following format: </para>
<programlisting format="linespecific">v1.0, 2000/04/10</programlisting>
<para>
The date is in the format YYYY/MM/DD, which is an ISO standard
for representing dates. For you Yanks out there (me too),
think of it as going from the largest unit of time to
the smallest.
</para>
</section>
<section id="acceptedgfx">
<title>Graphics formats</title>
<para> When submitting graphics to the LDP, please submit one
set of graphics in <filename>.eps</filename>, and another in
either <filename moreinfo="none">.gif</filename> or <filename
moreinfo="none">.jpg</filename>. Be aware of the patent issues
with <filename moreinfo="none">.gif</filename>, but it makes
slightly better pictures than <filename>.jpg</filename>. </para>
</section>
<section id="acceptedversions">
<title>DocBook Versions</title>
<para>
The LDP supports and accepts documentation in the following formats:
</para>
<itemizedlist>
<listitem>
<para>
SGML DocBook versions 4.x and 3.1
</para>
</listitem>
<listitem>
<para>
SGML LinuxDoc
</para>
</listitem>
<listitem>
<para>
XML DocBook version 4.1.2
</para>
</listitem>
</itemizedlist>
<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>
</section>
<section id="nooldtags">
<title>Obsolete Tags</title>
<para>Some tags listed in <emphasis>DocBook: The Definitive
Guide</emphasis> may be listed as being discarded in future
revisions of DocBook. To maintain future compatability, the
LDP recommends against using tags that will be discarded in
the future. Some ways to use newer tags are listed in the
tip and tricks section.</para>
</section>
<section id="notagmin">
<title>Tag Minimization</title>
<para>Tag minimization is using <sgmltag
class="endtag"></sgmltag> instead of the full end of a tag (such
as <sgmltag class="endtag">para</sgmltag>. Since this makes the
document more confusing for future authors and LDP members, and
is not allowed in XML DocBook, please refrain from this
practice.</para>
</section>
<section id="usingconventions">
<title>Conventions</title>
<para>Conventions for different kinds of text is as
follows:</para>
<para>If you're going to show the use of a command, format the
command so it looks like a user's command line. The prompt must
contain the shell type (bash, tcsh, zsh, etc) followed by a $
for commands to be run as a normal (non-root) user or a # for a
root user.</para>
<para> A command would then look like this: </para>
<screen format="linespecific">
<prompt>bash$</prompt> <command>command "run as a normal user"</command>
<prompt>bash#</prompt> <command>command "run as a root user"</command>
<prompt>tcsh#</prompt> <command>setenv DISPLAY :0.0</command>
</screen>
</section>
</chapter>
<chapter id="tips">
<title>Tips and Tricks with DocBook</title>
<para>This section covers a few quirks of DocBook that you may run
into when writing your documents.</para>
<section id="images">
<title>Including Images</title>
<para>If you plan on including images in your HOWTOs, you can
now do this, as LinuxDoc didn't support images. Here's a sample
way of including an image in your HOWTOS:</para>
<programlisting format="linespecific">
<sgmltag class="starttag">figure</sgmltag>
<sgmltag class="starttag">title</sgmltag>LyX screen shot<sgmltag class="endtag">title</sgmltag>
<sgmltag class="starttag">mediaobject</sgmltag>
<sgmltag class="starttag">imageobject</sgmltag>
<sgmltag class="starttag">imagedata fileref="lyx_screenshot.eps" format="eps"</sgmltag>
<sgmltag class="endtag">imageobject</sgmltag>
<sgmltag class="starttag">imageobject</sgmltag>
<sgmltag class="starttag">imagedata fileref="lyx_screenshot.jpg" format="jpg"</sgmltag>
<sgmltag class="endtag">imageobject</sgmltag>
<sgmltag class="starttag">textobject</sgmltag>
<sgmltag class="starttag">phrase</sgmltag>Screen shot of the LyX document processing program<sgmltag class="endtag">phrase</sgmltag>
<sgmltag class="endtag">textobject</sgmltag>
<sgmltag class="endtag">mediaobject</sgmltag>
<sgmltag class="endtag">figure</sgmltag>
</programlisting>
<para>This is a better way than using <sgmltag
class="starttag">graphic</sgmltag> for two reasons. First,
<sgmltag class="starttag">graphic</sgmltag> will be removed in
DocBook 5.0 in favor of the <sgmltag
class="starttag">mediaobject</sgmltag> tag. So you may as well
get started with the right way now. Second, <sgmltag
class="starttag">mediaobject</sgmltag> allows for different kinds
of media based on what the output is. In this example, the first
<sgmltag class="starttag">imageobject</sgmltag> is an encapsulated
PostScript(eps) file for use with formats derived from TeX such as
DVI, PS, and PDF. The second <sgmltag
class="starttag">imageobject</sgmltag> is a JPEG image for visual
display, mostly for HTML output. The <sgmltag
class="starttag">textobject</sgmltag> is presented if the output
doesn't support graphics (TXT). Think of it as an HTML <sgmltag
class="starttag">alt</sgmltag> tag.</para>
</section>
<section id="namedfiles">
<title>Naming separate HTML files</title>
<para>By default, when separate HTML files are made, the SGML
processor will assign arbitrary names to the resulting files.
This can be confusing to readers who may bookmark a page only to
have it change. Whatever
your reasoning, here's how to make separate files named the way
you want:</para>
<para>In your first <sgmltag class="starttag">article</sgmltag>
tag (which should be the only one) include an id parameter and
call it index. This will make your tag look like this:</para>
<programlisting format="linespecific">
<sgmltag class="starttag">article id="index"</sgmltag>
</programlisting>
<para>On the first <sgmltag class="starttag">chapter</sgmltag>
tag, do not modify it, as it's usually an introduction and you
want that on the first page. For each other <sgmltag
class="starttag">section</sgmltag> tag, include the id parameter
and name it. A name should include only alphanumeric characters,
and it should be short enough to understand what it is.</para>
<programlisting format="linespecific">
<sgmltag class="starttag">chapter id="tips"</sgmltag>
</programlisting>
</section>
&using-ldp-dsssl;
&using-ldp-xsl;
</chapter>
<chapter id="distribution">
<title> Distributing your documentation </title>
<section id="beforeyoudistribute">
<title> Before you distribute </title>
<para> Before you distribute your code to millions of potential
readers there are a few things you should do. </para>
<para> First, be sure to spell-check your document. Most
utilities that you would use to write SGML have plug-ins to
perform a spell check. If not, there's always the aspell
program. </para>
<para> Second, get someone to review your documentation for
factual correctness. You can also ask for general
comments. The documentation that is
published by the LDP needs to be as factually correct as
possible, as there are millions of Linux users that may be
reading it. If you're part of a larger mailing list talking
about the subject, ask others from the list to help you
out. </para>
<para> Third, create a web site where you can distribute your
documentation. This isn't required, but is helpful for people to
find the original location of your document. </para>
<section id="validatecode">
<title>Validating SGML code </title>
<para> Using jade, or really the nsgmls command, you can
validate your .sgml code against the DTD to make sure there
aren't any errors. </para>
<screen>
<prompt>bash$</prompt> <command>nsgmls -s HOWTO-HOWTO.sgml</command>
</screen>
<para> If there are no issues, you'll just get your command
prompt back. </para>
</section>
<section id="validatexml">
<title>Validating XML code</title>
<para>Validating XML is a touch harder than validating SGML
code, but it can be done. You will need to have XML DocBook
installed, and then set the <envar>SGML_CATALOG_FILES</envar>
to the location of xml.soc (included with jade) and to
the location of the DocBook XML catalog file.
</para>
<screen>
<prompt>bash$</prompt> <command>export <envar>SGML_CATALOG_FILES</envar>=/usr/lib/sgml/declaration/xml.soc:/usr/lib/xml/catalog</command>
<prompt>bash$</prompt> <command>nsgmls -s HOWTO-HOWTO.xml</command>
</screen>
</section>
</section>
<section id="makingcopyright">
<title> Copyright and Licensing issues </title>
<para> In order for an LDP document to be accepted by the LDP,
it must be licensed to conform to the "LICENSE REQUIREMENTS"
section of the LDP Manifesto located at <ulink
url="http://www.linuxdoc.org/manifesto.html">http://www.linuxdoc.org/manifesto.html</ulink>.
As an author, you may retain the copyright and add other
restrictions (for example, you must approve any translations or
derivative works). </para>
<para> We recommend using the <ulink
url="http://www.gnu.org/copyleft/fdl.html">GNU Free Documentation
License (GFDL)</ulink> or the <ulink
url="http://opencontent.org/openpub/">Open Publication License
(OPL)</ulink> <emphasis>without</emphasis> options A and B. If
you choose, you can get DocBook markups of both the GNU GPL
and the GNU FDL from <ulink url="http://developer.gnome.org/projects/gdp/licenses.html">
the GNOME Documentation Project</ulink>. You can then merely
include the license in its entirety in your document. Due
to its length, you may just want to provide a link
to the source.</para>
<para>If you choose to use a boilerplate copyright, simply copy it
into your source code under a section called <quote>Copyright
and Licenses</quote> or similar. Also include a copyright
statement of your own (since you still own it). If you are a new
maintainer of an already-existing HOWTO, you must include the
previous copyright statements of the previous author(s) and the
dates they maintained that document. </para>
<para>You'll note that the licensing for the LDP Author Guide
requires notification to the author of any derivative works or
translations. I also explicitly place any source code (aside
from the SGML the Guide was written in) under the GPL. If your
HOWTO includes bits of source code that you want others to use,
you may do the same.</para>
</section>
<section id="submission">
<title> Submission to LDP </title>
<para> Once your LDP document has been carefully reviewed, you
can release your document to the LDP. Send an e-mail with the
SGML source code as an attachment (you may gzip it if you like)
to <email>submit@linuxdoc.org</email>. </para>
<para> Be sure to include the name of your HOWTO in the subject
line, and use the body to outline changes you've made and attach
your HOWTO. This allows the maintainers to do their jobs faster,
so you will not have to wait for your HOWTO to be updated on the
LDP web site. If you don't hear anything in 5 calendar days,
please follow up with an e-mail to make sure things are still in
process. </para>
<para>If your HOWTO contains extras, such as graphics or a
special catalog, create a.tar.gz file with all the files in it
including the .sgml source code and mail it as an attachment to
the ldp-submit list.</para>
<para>If you are using the LDP CVS tree while developing
your document, the LDP will still need to be notified when your
document is ready to be published. E-mail should be sent to
<email>submit@linuxdoc.org</email>. Indicate
the title of your document and the relative path to the
file(s) in the LDP CVS tree within your message. </para>
</section>
<section id="maintentance">
<title>Maintaining Your HOWTO</title>
<para>
Just because your HOWTO has now been published doesn't mean your
job is done. HOWTOs need regular maintenance, to make sure they
are up to date, and to improve them in response to readers' ideas
and suggestions. A HOWTO is a living, growing body of knowledge,
not just a publish-and-forget-it static document.
</para>
<para>
You put your email address in the HOWTO, and politely requested
feedback from your readers, right? Once you are officially published,
you will begin to receive notes with suggestions. Some will be
very valuable; others will request personal assistance. You should
feel free to decline personal assistance if you cannot spare the
time. Writing a HOWTO for the LDP doesn't commit you to a lifetime
of free support for anyone on the net. It is polite to refer
questioners to another resource, if you can. And, if you see a
pattern in the questions you receive, it might indicate a topic
you should add to your HOWTO.
</para>
</section>
</chapter>
<chapter id="faq">
<title> FAQs about the LDP </title>
<qandaset defaultlabel="qanda">
<qandaentry>
<question>
<para>I want to help the LDP. How can I do this?</para>
</question>
<answer>
<para> The easiest way is to find something and document
it. Also check the unmaintained HOWTOs and see if there is a
subject there that you know about and can continue
documenting. </para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para> I want to publish a collection of LDP documents in a
book. How is the LDP content licensed? </para>
</question>
<answer>
<para> Please see <ulink
url="http://www.linuxdoc.org/manifesto.html#pub">http://www.linuxdoc.org/manifesto.html#pub</ulink> for more information about publishing LDP documents.
</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para> I found an error in an LDP document. Can I fix it? </para>
</question>
<answer>
<para> Contact the author of the document, or the LDP
coordinator at <email>discuss@linuxdoc.org</email> and
mention the problem and how you think it needs to be
fixed. </para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>But I don't know SGML/Can't get the tools working/Don't
like SGML</para>
</question>
<answer>
<para> That's okay. You have the option of writing your first
draft of the HOWTO in the format of your choice, then submit
that to the LDP. An LDP volunteer will review the document,
then convert it into DocBook for you. Once that's done,it will
be easier for you to maintain the HOWTO. If you have
questions, you can always drop a line to the LDP volunteer or the
LDP Docbook list
at <email>docbook@linuxdoc.org</email>.</para>
</answer>
</qandaentry>
</qandaset>
</chapter>
&gfdl;
&glossary;
&doc-index;
</book>
View Git Blame Copy Permalink