mirror of https://github.com/tLDP/LDP
1531 lines
67 KiB
Plaintext
1531 lines
67 KiB
Plaintext
<!doctype book public "-//OASIS//DTD DocBook V3.1//EN" [
|
|
|
|
<!--
|
|
<!entity header system "header.sgml">
|
|
<!entity docbook system "docbook.sgml">
|
|
-->
|
|
<!entity conventions SYSTEM "conventions.sgml">
|
|
<!entity using-docbook SYSTEM "using-docbook.sgml">
|
|
<!entity doc-index SYSTEM "index.sgml">
|
|
|
|
<!-- Include macros -->
|
|
<!entity conventions SYSTEM "conventions.sgml">
|
|
<!entity example-article SYSTEM "example-article.sgml">
|
|
<!entity example-book SYSTEM "example-book.sgml">
|
|
<!entity example-compile-sgml SYSTEM "compiles-sgml.sgml">
|
|
<!entity example-table SYSTEM "example-table.sgml">
|
|
<!entity dsl-example SYSTEM "dsl-example.sgml">
|
|
<!entity glossary SYSTEM "glossary.sgml">
|
|
<!entity cvs SYSTEM "cvs.sgml">
|
|
<!entity style-guide SYSTEM "style-guide.sgml">
|
|
<!-- Text Macros -->
|
|
<!entity conectivasa '<ulink url="http://www.conectiva.com">Conectiva S.A.</ulink>'>
|
|
<!entity conectiva "Conectiva">
|
|
|
|
]>
|
|
|
|
|
|
<book>
|
|
<bookinfo>
|
|
<title>LDP Author Guide</title>
|
|
<pubdate>v3.5 4 Dec, 2000</pubdate>
|
|
<author>
|
|
<firstname>Mark</firstname>
|
|
<othername>F.</othername>
|
|
<surname>Komarinski</surname>
|
|
<affiliation>
|
|
<orgname>VA Linux Systems</orgname>
|
|
<address><email>markk@linuxdoc.org</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.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 SGML, 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 focues 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 author
|
|
(<email>markk@linuxdoc.org</email>).</para>
|
|
</section>
|
|
|
|
<section id="copyrights">
|
|
<title>Copyrights and Trademarks</title>
|
|
<para>Copyright 1999-2000 Mark F. Komarinski, David C. Merrill, Jorge Godoy</para>
|
|
<para>This manual may be reproduced in whole or in part, without
|
|
fee, subject to the following restrictions:</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>The copyright notice above and this permission notice
|
|
must be preserved complete on all complete or partial copies</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Any translation or derived work must be approved by
|
|
the author in writing before distribution.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>If you distribute this work in part, instructions for
|
|
obtaining the complete version of this manual must be
|
|
included, and a means for obtaining a complete version
|
|
provided.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Small portions may be reproduced as illustrations for
|
|
reviews or quotes in other works without this permission
|
|
notice if proper citation is given. Exceptions to these
|
|
rules may be granted for academic purposes: Write to the
|
|
author and ask. These restrictions are here to protect us as
|
|
authors, not to restrict you as learners and educators. Any
|
|
source code (aside from the SGML this document was written
|
|
in) in this document is placed under the GNU General Public
|
|
License, available via anonymous FTP from the GNU
|
|
archive.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</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 SGML</title>
|
|
|
|
<section id="theldp">
|
|
<title>The LDP</title>
|
|
<para>The Linux Documentation Project (LDP) was started to
|
|
provide new users a way of getting information quickly about a
|
|
particular subject. It not only contains a series of books on
|
|
administration, networking, and programming, but 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 SGML.</para>
|
|
</section>
|
|
|
|
<section id="sgml">
|
|
<title>SGML</title>
|
|
<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 <title> tag into 14 point bold if it
|
|
is going to RTF format, or to turn it into a <h1> tag if
|
|
you're 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 would a graphic
|
|
image, table, numbered list, and so on. Content is surrounded by
|
|
tags to separate out each element.</para>
|
|
</section>
|
|
|
|
<section id="whysgml">
|
|
<title>Why SGML instead of HTML or other formats?</title>
|
|
<para>SGML provides for more than just formatting. You can
|
|
automatically build indexes, table 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) SGML 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 SGML and render from SGML to whatever you chose. In
|
|
the end, SGML 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>
|
|
|
|
<section id="sgmlisnotxml">
|
|
<title>SGML is not XML</title>
|
|
<para>There has been a lot of press recently about XML, and DocBook
|
|
support for XML. DocBook is a collection of markup tags that follow
|
|
a specified hierarchy.
|
|
XML DocBook v4.1.2 is now officially supported by the LDP. If you're
|
|
familiar with SGML and want to convert to XML, please keep the following
|
|
in mind (list borrowed from DocBook: The Definitive Guide):
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>All XML markup is case sensitive. All element, attribute,
|
|
and entity names have to be in lowercase. SGML is not case
|
|
sensitive.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
All attributes have to be quotes using either straight (') or
|
|
double (") quotes.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Empty elements (like xref) have to end with a /: <xref/>.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Tag minimizations (</>) are not supported. The LDP
|
|
discourages their use in SGML as well.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
|
|
<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>
|
|
|
|
<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 "subscribe" to
|
|
<email>discuss-subscribe@linuxdoc.org</email>. To
|
|
unsubscribe, send an e-mail with the subject of
|
|
"unsubscribe" 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>
|
|
</section>
|
|
</chapter>
|
|
|
|
|
|
<chapter id="tools">
|
|
<title>The tools</title>
|
|
<para>In this section, we will cover some of the tools that you'll
|
|
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 Document Style Semantics and Specification Language
|
|
tells jade how to render a SGML document into print or online
|
|
form. The DSSSL is what converts a title tag into an
|
|
<H1> tag in HTML, or bold, 14 point 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 DocBook DTD defines the tags and structure of a
|
|
DocBook SGML document. Modifying the DTD, such as adding a new
|
|
tag, doesn't make it DocBook anymore.</para>
|
|
</section>
|
|
|
|
<section id="jade">
|
|
<title>Jade</title>
|
|
<para>Jade and OpenJade are two of the programs that do most of
|
|
the rendering and validation of code based off 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. It uses the
|
|
DSSSL and DocBook DTD to perform the verification and
|
|
rendering from SGML 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 distribution you're
|
|
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 wame way as for SGML DocBook.
|
|
</para>
|
|
<para>
|
|
After extracting the XML DTD, you may 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 style $_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 style with the style you wish to use. The pointer
|
|
to xml.dcl is requires for jade to work, and it has to be
|
|
listed immediately before the pointer to your XML document.
|
|
</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>
|
|
<xml_dtd_pth>/ent/iso-lat2.ent:119:18:E: "X0176" is not a function name
|
|
<xml_dtd_pth>/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>
|
|
<?xml version='1.0' encoding='ISO-8859-1'?>
|
|
<!DOCTYPE article PUBLIC '-//OASIS//DTD DocBook XML V4.1.2//EN'>
|
|
</screen>
|
|
<para>
|
|
If you have followed LDP guidelines, there should be no
|
|
other changes required to your document.
|
|
</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 officially been 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 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>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>
|
|
<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/">http://www.snee.com/bob/sgmlfree/</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 [
|
|
<!ELEMENT test - - (#PCDATA)>
|
|
]</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 [
|
|
<!ELEMENT test - - (#PCDATA)>
|
|
]</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 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 really in multiple parts. There is
|
|
first the plain vim program, which has compatability 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 highlighed
|
|
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>
|
|
</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="sgedit">
|
|
<title>sgedit</title>
|
|
<para><ulink
|
|
url="http://www.tksgml.de/">http://www.tksgml.de/</ulink></para>
|
|
<para>The sgedit 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. It's a commercial application, but pricing
|
|
has not been set. There will be free licenses for private and
|
|
academic use.</para>
|
|
<para>Along with visual editing, sgedit 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>sgedit 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 sgedit 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>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
|
|
sgedit, 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 start 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 ouput 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. Default spell checkers like 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, 21 April 2000</programlisting>
|
|
</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="nodeptags">
|
|
<title>Depreciated Tags</title>
|
|
<para>Tags listed in <emphasis>DocBook: The Definitive
|
|
Guide</emphasis> as depreciated are discouraged for use in LDP
|
|
documentation. 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 <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, or so you know what files are what. 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. Names 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>
|
|
|
|
<section id="usingldpdsssl">
|
|
<title>Using ldp.dsl</title>
|
|
<para>The LDP uses its own DSSSL file, which adds things like a
|
|
white background and automatic generation of the table of
|
|
contents you see at the beginning of HOWTOs. You can find the
|
|
latest copy of the file at <ulink
|
|
url="http://www.linuxdoc.org/authors/tools/ldp.dsl">http://www.linuxdoc.org/authors/tools/ldp.dsl</ulink>.</para>
|
|
<para>Once you have the file, you may need to do some editing of
|
|
the first few lines based on the location of your DocBook DSSSL
|
|
files. My example uses the Cygnus tool set.</para>
|
|
<para>Place the <filename moreinfo="none">ldp.dsl</filename>
|
|
file in <filename moreinfo="none"
|
|
class="directory">/usr/lib/sgml/stylesheets</filename> and bring
|
|
it up under your favorite text editor.You should see something
|
|
like this:</para>
|
|
|
|
<informalexample>
|
|
<screen format="linespecific">
|
|
<!DOCTYPE style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN" [
|
|
<!ENTITY % html "IGNORE">
|
|
<![%html;[
|
|
<!ENTITY % print "IGNORE">
|
|
<!ENTITY docbook.dsl SYSTEM "docbook.dsl<co id="html">" CDATA dsssl>
|
|
]]>
|
|
<!ENTITY % print "INCLUDE">
|
|
<![%print;[
|
|
<!ENTITY docbook.dsl SYSTEM "docbook.dsl<co id="print">" CDATA dsssl>
|
|
]]>
|
|
]>
|
|
</screen>
|
|
<calloutlist>
|
|
<callout arearefs="html">
|
|
<para>Change the first "docbook.dsl" to read <filename
|
|
moreinfo="none">/usr/lib/sgml/stylesheets/nwalsh-modular/html/docbook.dsl</filename></para>
|
|
</callout>
|
|
<callout arearefs="print">
|
|
<para>Change the second "docbook.dsl" to read <filename
|
|
moreinfo="none">/usr/lib/sgml/stylesheets/nwalsh-modular/print/docbook.dsl</filename></para>
|
|
</callout>
|
|
</calloutlist>
|
|
</informalexample>
|
|
<para>If you're using another DSSSL, point those two files to
|
|
the location of the HTML and print DSSSL files. They're usually
|
|
in directories called html and print.</para>
|
|
<para>With that complete, you can now generate HTML files:</para>
|
|
|
|
<screen format="linespecific">
|
|
<prompt>bash$</prompt> <command>mkdir HOWTO-HOWTO ; cd HOWTO-HOWTO</command>
|
|
<prompt>bash$</prompt> <command> jade -t sgml -i html -d /usr/lib/sgml/stylesheets/ldp.dsl\#html ../HOWTO-HOWTO.sgml</command>
|
|
</screen>
|
|
|
|
<para>The first command creates a new directory to put your
|
|
files into. The second command (the jade one) generates
|
|
individual HTML files for each section of your document. If you
|
|
are going to something like RTF, you can do this:</para>
|
|
|
|
<screen format="linespecific">
|
|
<prompt>bash$</prompt> <command>jade -t rtf -d /usr/lib/sgml/stylesheets/ldp.dsl ../HOWTO-HOWTO.sgml</command>
|
|
</screen>
|
|
</section>
|
|
</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
|
|
comments and factual correctness. 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> Validate your 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>
|
|
|
|
<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 up 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 for 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 Authoring 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 don't 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/COPYRIGHT.html">http://www.linuxdoc.org/COPYRIGHT.html</ulink>.
|
|
Note that this is only a guideline to authors. However, the
|
|
licensing cannot be more restrictive than what is listed in that
|
|
URL. </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 run into
|
|
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>
|
|
|
|
&glossary;
|
|
|
|
&doc-index;
|
|
|
|
</book>
|