LDP Author Guide
Mark F. Komarinski
markk@linuxdoc.org
Jorge Godoy
[1]Conectiva S.A.
Publishing Department
godoy@conectiva.com
godoy@metalab.unc.edu
List the tools, procedures, and hints to get LDP authors up to speed
and writing.
_________________________________________________________________
Table of Contents
1. [2]About this Guide
1.1. [3]Purpose / Scope of this Guide
1.2. [4]About the LDP
1.3. [5]Feedback
1.4. [6]Copyrights and Trademarks
1.5. [7]Acknowledgments and Thanks
1.6. [8]Documents
2. [9]Introduction to the LDP and SGML
2.1. [10]The LDP
2.2. [11]SGML
2.3. [12]Why SGML instead of HTML or other formats?
2.4. [13]SGML is not XML
2.5. [14]For New Authors
2.6. [15]Mailing Lists
3. [16]The tools
3.1. [17]DSSSL
3.2. [18]DocBook DTD (version 3.1)
3.3. [19]Jade
3.4. [20]Jade wrappers
3.5. [21]Editing tools
3.6. [22]CVS
3.7. [23]Other/Reference
4. [24]Using DocBook Tags
4.1. [25]Introduction
4.2. [26]Configuration needed
4.3. [27]Creating and modifying catalogues
4.4. [28]Writing with DocBook elements
4.5. [29]Encoding Indexes
4.6. [30]Inserting Pictures
4.7. [31]Tables
4.8. [32]Listings and program codes
4.9. [33]Tools & Hints
4.10. [34]Document samples
5. [35]Style guides
5.1. [36]Date formats
5.2. [37]Graphics formats
5.3. [38]DocBook Versions
5.4. [39]Depreciated Tags
5.5. [40]Tag Minimization
5.6. [41]Conventions
6. [42]Tips and Tricks with DocBook
6.1. [43]Including Images
6.2. [44]Naming separate HTML files
6.3. [45]Using ldp.dsl
7. [46]Distributing your documentation
7.1. [47]Before you distribute
7.2. [48]Copyright and Licensing issues
7.3. [49]Submission to LDP
7.4. [50]HOWTO maintenance
8. [51]FAQs about the LDP
[52]Glossary
_________________________________________________________________
Chapter 1. About this Guide
1.1. Purpose / Scope of this Guide
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.
The newest version of this can be found on my homepage
[53]http://www.cgipc.com/~markk in its SGML source. Other versions may
be found in different formats at the LDP homepage
[54]http://www.linuxdoc.org.
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.
_________________________________________________________________
1.2. About the LDP
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.
--LDP Manifesto located at [55]http://www.linuxdoc.org/manifesto.html
You can find out more about the Linux Documentation Project at
[56]http://www.linuxdoc.org
_________________________________________________________________
1.3. Feedback
Comments on this Guide may be directed to the author
(<[57]markk@linuxdoc.org>).
_________________________________________________________________
1.4. Copyrights and Trademarks
(c) 1999-2000 Mark F. Komarinski
This manual may be reproduced in whole or in part, without fee,
subject to the following restrictions:
* The copyright notice above and this permission notice must be
preserved complete on all complete or partial copies
* Any translation or derived work must be approved by the author in
writing before distribution.
* 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.
* 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.
_________________________________________________________________
1.5. Acknowledgments and Thanks
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
<[58]ldp-discuss@lists.linuxdoc.org> list. Some sections I got from
the [59]HOWTO Index and the sgmltools documentation. The sections on
network access to CVS was partially written by Serek
(<[60]ser@serek.arch.pwr.wroc.pl>). Sections on DocBook were written
by Jorge Godoy (<[61]godoy@conectiva.com>). A great deal of thanks to
both of them for their help.
_________________________________________________________________
1.6. Documents
This document uses the following conventions[62][1]:
Descriptions Appearance
Warnings
Caution
Warnings.
Hint
Tip: Hint.
Notes
Note: Note.
Information requiring special attention
Warning
Warning.
File Names file.extension
Directory Names directory
Commands to be typed command
Applications Names application
Prompt of users command under bash shell bash$
Prompt of root users command under bash shell bash#
Prompt of user command under tcsh shell tcsh$
Environment Variables VARIABLE
Emphasized work word
Code Example
Beginning and end of paragraph
_________________________________________________________________
Chapter 2. Introduction to the LDP and SGML
2.1. The LDP
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 [63]Printing HOWTO. If you want to do find
out if your Ethernet card works with Linux, grab the [64]Ethernet
HOWTO, 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.
_________________________________________________________________
2.2. SGML
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
tag into 14 point
bold if it is going to RTF format, or to turn it into a
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.
_________________________________________________________________
2.3. Why SGML instead of HTML or other formats?
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.
_________________________________________________________________
2.4. SGML is not XML
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 tools for authors are not quite as far
advanced as their SGML counterparts, so the LDP is refraining from
using XML markups. At this time, only SGML is accepted by the LDP.
_________________________________________________________________
2.5. For New Authors
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
<[65]ldp-discuss@lists.linuxdoc.org>. This is to make sure the HOWTO
coordinator can know who is working on what documentation.
Once that part is complete, you may write your documentation in the
format of your choice and submit a draft to
<[66]ldp-submit@lists.linuxdoc.org> 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.
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.
If you choose to start your document off in DocBook, there are plenty
of templates to get you started:
* [67]http://www.nyx.net/~sgjoen/template.sgml - This template is
written by Stein Gojen and is based off the LinuxDoc template.
* [68]http://www.linuxdoc.org/authors/template/big-howto-template.sg
ml - This template is based on Stein's work, but is much larger
and complicated than the above. It uses more features of DocBook.
_________________________________________________________________
2.6. Mailing Lists
There are a few mailing lists to subscribe to so you can take part in
how the LDP works. First is <[69]ldp-discuss@lists.linuxdoc.org>,
which is the main discussion group of the LDP. To subscribe, send a
message with the subject reading "subscribe" to
<[70]ldp-discuss-request@lists.linuxdoc.org>. To unsubscribe, send an
e-mail with the subject of "unsubscribe" to
<[71]ldp-discuss-request@lists.linuxdoc.org>.
Another list is the <[72]ldp-docbook@lists.linuxdoc.org> 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 <[73]ldp-docbook-request@lists.linuxdoc.org>.
_________________________________________________________________
Chapter 3. The tools
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.
_________________________________________________________________
3.1. DSSSL
The Normal Walsh version is required, the LDP is optional.
_________________________________________________________________
3.1.1. Norman Walsh DSSSL
[74]http://nwalsh.com/docbook/dsssl/
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
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).
_________________________________________________________________
3.1.2. LDP DSSSL
[75]http://metalab.unc.edu/gferg/ldp/ldp.dsl
The LDP DSSSL requires the Norman Walsh version (see above) but is a
slightly modified DSSSL to provide things like a table of contents.
_________________________________________________________________
3.2. DocBook DTD (version 3.1)
Required - [76]http://www.oasis-open.org/docbook/sgml/3.1/docbk31.zip
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.
_________________________________________________________________
3.3. Jade
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.
_________________________________________________________________
3.3.1. Jade
[77]ftp://ftp.jclark.com/pub/jade/jade-1.2.1.tar.gz
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.
_________________________________________________________________
3.3.1.1. Using Jade
This is the quick and dirty way that should work for all
distributions, no matter what distribution you're using.
1. Create a base directory to store everything such as
/usr/local/sgml/. We'll call this $_toolroot from here on.
2. Install Jade, DocBook DTD, and DSSSL such that the base of each is
under $_toolroot, creating:
+ $_toolroot/jade-1.2.1
+ $_toolroot/dtd
+ $_toolroot/dsssl
3. You'll need to set the SGML_CATALOG_FILES environment variable to
the catalogs that you have under$_toolroot. You can do this with
the command:
bash$ export SGML_CATALOG_FILES=$_toolroot/dtd/docbook.cat:\
$_toolroot/dsssl/docbook/catalog:$_toolroot/jade-1.2.1/dsssl/catalog
4. Now you can start using Jade. To create individual HTML files:
$_toolroot/jade-1.2.1/jade/jade -t sgml -i html \
-d $_toolroot/dsssl/docbook/html/docbook.dsl howto.sgml
5. To create one large HTML file, add -V nochunks to the jade
command.
_________________________________________________________________
3.3.2. OpenJade
[78]http://openjade.sourceforge.net/
An extension of Jade written by the DSSSL community. Some applications
require jade, but are being updated to support either software
package.
_________________________________________________________________
3.4. Jade wrappers
These tools are optional and may be installed after Jade, the DSSSL,
and DTD have been installed.
_________________________________________________________________
3.4.1. sgmltools-lite
[79]http://sgmltools-lite.sourceforge.net/
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.
_________________________________________________________________
3.4.2. Cygnus DocBook Tools
May be Red Hat specific - [80]http://www.redhat.com/
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.
_________________________________________________________________
3.4.2.1. Using the Cygnus Tools
These tools are provided with Red Hat 6.2. Make sure the following
packages are installed:
* sgml-common-0.1-8.noarch
* docbook-3.1-4.noarch
* stylesheets-1.54.13rh-1.noarch
Red Hat has the latest version on their web site:
[81]http://www.redhat.com/support/errata/RHBA-2000022-01.html.
Download/get/sneaker-net the RPMs to your machine and install in the
usual manner (become root, then rpm -Uvh filename). Once the RPMs are
installed, you can use the following commands to render DocBook:
bash$ db2html filename
Renders DocBook into HTML. A subdirectory with the filename (minus the
.sgml extension) is created and the HTML files are placed there.
bash$ db2pdf filename
Renders DocBook into a PDF file. Note that there is currently a
problem with db2pdf, and pd2ps caused by JadeTeX. This has been
[82]registered as a bug with RedHat.
_________________________________________________________________
3.5. Editing tools
The following tools may be used to create, edit, or validate your
HOWTO.
_________________________________________________________________
3.5.1. Emacs (PSGML)
Optional - [83]http://www.lysator.liu.se/~lenst/about_psgml/
Emacs has an SGML writing mode called psgml that is a major mode
designed for editing SGML and XML documents. It provides "syntax
highlighting" or "pretty printing" 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.
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.
_________________________________________________________________
3.5.1.1. Writing SGML using PSGML
3.5.1.1.1. Introduction
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 (C-himpsgml).
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:
[84]http://www.snee.com/bob/sgmlfree/.
_________________________________________________________________
3.5.1.1.2. Updating your .emacs to use PSGML
If you want GNU Emacs to enter PSGML mode when you open a .sgml 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).
For example:
bash$ export SGML_CATALOG_FILES=/usr/lib/sgml/catalog
Then add something like the following to your .emacs file:
;; *******************************************************************
;; 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.
;; *******************************************************************
Then restart Emacs
_________________________________________________________________
3.5.1.1.3. SGML Smoke Test
Try the following smoke test. Start a new file, /tmp/test.sgml for
example, and enter the following:
]>
Enter C-cC-p. If Emacs manages to parse your DTD, you will see Parsing
prolog...done in the minibuffer. Try C-c C-e RETURN to insert a
element. If things are working correctly, you should see the following
in Emacs:
]>
_________________________________________________________________
3.5.1.1.4. Writing a New HOWTO in DocBook
Start a new file for your HOWTO and enter the following:
Enter C-cC-p and hold your breath. If everything goes as planned, you
will see Emacs chewing for a few seconds and then Parsing
prolog...done in the minibuffer.
At this point, enter C-cC-eRETURN to insert an element and
proceed to write your HOWTO.
_________________________________________________________________
3.5.1.1.5. Quick Reference for Emacs with PSGML
See Nik Clayton's primer for FreeBSD documentation:
[85]http://www.freebsd.org/tutorials/docproj-primer/psgml-mode.html
_________________________________________________________________
3.5.2. VIM
[86]http://www.vim.org
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.
_________________________________________________________________
3.5.2.1. Getting Started
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 vim, 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 gvim.
_________________________________________________________________
3.5.2.2. Loading or starting new documents
In both vim and gvim modes, .sgml files will be automatically
recognized and enter into "sgml mode". A series of known DocBook tags
have been entered into vim 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 vi commands to navigate and edit.
_________________________________________________________________
3.5.3. WordPerfect 9 (Corel Office 2000)
[87]http://www.corel.com/
WordPerfect 9 for the MS Windows platform has support for SGML and
DocBook 3.0. WordPerfect 9 for Linux has no SGML capabilities.
This is the least expensive of the commercial applications that
support SGML.
_________________________________________________________________
3.5.4. sgedit
[88]http://www.tksgml.de/
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.
Along with visual editing, sgedit will also validate documents on
loading, and on demand by using the Document->Validate command.
Figure 3-1. sgedit screen shot
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.
_________________________________________________________________
3.5.5. nedit
[89]http://nedit.org
To be fair, 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 nsgmls to validate the SGML and aspell to do my spell checking.
Figure 3-2. nedit screen shot
The nedit program can provide line numbers across the left side of the
screen, handy for when nsgmls complains of errors
_________________________________________________________________
3.5.5.1. Using nedit
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 Preferences->Language Mode->SGML HTML
command.
_________________________________________________________________
3.5.5.2. Tips and tricks with nedit
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 nsgmls.
Select Preferences->Default Settings->Customize Menus->Shell Menu....
This will bring up the Shell Command dialog box, with all the shell
commands nedit has listed under the Shell menu. Under Menu Entry,
enter "SGML Validate". This will be the entry you'll see on the
screen. Under Accelerator, press Alt-S. Once this menu item is set up,
you can press Alt-S 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 nsgmls has to be
in your PATH for this to work properly.
Figure 3-3. Adding shell commands to nedit
[neditshellcommand.jpg]
Click OK and you'll now be back at the main nedit screen. Load up an
SGML file, and select Shell->SGML Validate or press Alt-S. The nedit
program will fire up and check the contents of the window. The reason
for using -sv is that the -v tells nsgmls to output the version of the
program, so you'll always get ouput and know that nsgmls 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
Preferences->Show Line Numbers) then finding the errors is much
simpler, as nsgmls will list errors by their line number.
Figure 3-4. nsgmls output on success
If nsgmls reports success, it merely reports the version of nsgmls
_________________________________________________________________
3.6. CVS
The LDP is in the process of providing CVS access to authors. There
are a few good reasons for this:
1. CVS will keep an off-site backup of your documents. In the event
that you hand over a document to another author, they can just
retrieve the document from CVS and continue on. In the event you
need to go back to a previous version of a document, you can
retrieve it as well.
2. It's great if you have many people working on the same document.
You can have CVS tell you what changes were made while you were
editing your copy by another author, and integrate those changes
in.
3. Keeps a log of what changes were made. These logs (and a date
stamp) can be placed automatically inside the document when you
use some special tags that get processed before the SGML
processor.
4. Can provide for a way for a program to automatically update the
LDP web site with new documentation as it's written and submitted.
This is not in place yet, but is a potential goal. Currently, CVS
updates signal the HOWTO coordinator to update the LDP web page,
meaning that if you use CVS, you're not required to e-mail your
SGML code.
If you're completely new to CVS, there are a few web pages you may
want to look at which can help you out:
* [90]http://www.sourcegear.com/CVS/Docs/blandy
* [91]https://wroclaw.art.pl/~ser/docs/cvs.html
_________________________________________________________________
3.6.1. Getting a CVS account
First you'll need to get an account at the LDP's CVS Repository. This
is pretty much the root directory that is used by CVS, with various
projects (HOWTOs, mini HOWTOs, etc.) created as subdirectories of
that.
You will need to create a hashed password and userid for your account.
The hashed password allows you to send an encrypted password to the
CVS group without them needing to know your password. You can do this
with the following command, from bash (or sh):
bash$ echo your_password | perl -e "print crypt(<>,\
join '',('.', '/', 0..9, 'A'..'Z', 'a'..'z')[rand 64, rand 64]),\"\n\""
Take the output of this command, and send it with your proposed userid
to <[92]cvsadmin@cvslist.linuxdoc.org>. Your unique CVSROOT directory
will be created and you'll get an e-mail with a response. When you get
your response, log into your CVSROOT and make sure everything is set
up properly:
bash$ export CVSROOT=:pserver:your_userid@cvs.linuxdoc.org:/cvsroot
bash$ cvs -d $CVSROOT login
(Replace the your_userid with what you were sent in the response
e-mail).
You will be asked for your password, and then given access to the CVS
Repository in read-write mode. Once you've used cvs login once and
have been given access to the system, your password is stored in
.cvspass and you will not have to use cvs login again. Just set the
CVSROOT and continue on. You can get the entire LinuxDoc repository
with this command:
bash$ cvs get LDP
Or you can get the SGML source for your own document with these
commands:
bash$ cvs get howto/YOUR-HOWTO.sgml
bash$ cvs get
minihowto/YOURDOC.sgml
_________________________________________________________________
3.6.2. Other CVS repository notes
3.6.2.1. Anonymous CVS access
Anonymous CVS access is available for those who do not require an
account (such as those wishing to publish LDP documents). This
repository is read-only:
bash$ cvs -d :pserver:cvs@anoncvs.linuxdoc.org:/cvsroot login
As a password, use cvs. You can then get LinuxDoc modules as above.
Note that changes to the anoncvs site may be a half an hour behind the
main site.
_________________________________________________________________
3.6.2.2. CVS Files via web
You can access the CVS repository via the web at
[93]http://cvsweb.linuxdoc.org/index.cgi/linuxdoc.
_________________________________________________________________
3.6.2.3. Graphical access to CVS
There are graphical interfaces to CVS, and you can get a list of them
at [94]http://freshmeat.net/appindex. Search for CVS.
_________________________________________________________________
3.6.3. Updating files and CVS
CVS has a special tag, $Id, that you can use to automatically insert
the date and version directly into the document. After committing, CVS
will turn this tag into $Id: HOWTO-HOWTO.sgml,v 1.4 2000/06/12
20:49:54 markk Exp $. By including this tag in your document, you can
have that automatically change each time you change the file, allowing
the revision mark to increment each time.
When you're ready to upload changes to the CVS server, use the command
cvs ci -m "comment" YOUR-HOWTO.sgml. The -m "comment" isn't necessary,
but if you don't include it, you'll be brought into the editor
(usually vi, or whatever your EDITOR environment variable is) and be
given the chance to add a comment about the changes.
You can follow more of the CVS discussion on the ldp-discuss list. For
the time being, LDP submissions should still be sent to
<[95]ldp-submit@lists.linuxdoc.org>.
_________________________________________________________________
3.7. Other/Reference
The items in this section are reference books or other utilities that
can't quite be categorized (yet).
_________________________________________________________________
3.7.1. DocBook: The Definitive Guide
[96]http://www.docbook.org/
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.
_________________________________________________________________
3.7.2. SGML templates
Optional - [97]http://www.linuxdoc.org/authors/index.html#resources
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.
_________________________________________________________________
3.7.3. Aspell
Optional - [98]http://aspell.sourceforge.net/
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.
_________________________________________________________________
3.7.4. ispell
Optional - [99]http://www.cs.hmc.edu/~geoff/ispell.html
The ispell program is distributed with RedHat (and possibly other
distros) and also ignores markup tags.
_________________________________________________________________
Chapter 4. Using DocBook Tags
4.1. Introduction
DocBook defines a set of markup elements useful for marking up text so
that the text can then be transformed into several different formats.
It's possible to create documents in different formats HTML, XML, RTF,
TeX, and others.
The idea is to write just once and reach the largest possible number
of people with the information.
Digital information not stored properly tends to get lost. Due to the
fact that not containing uncommon characters (such as binary formats)
it's possible to index and search directly on the documents written on
SGML and consequently on DocBook.
The SGML systems use markups to make their description. DocBook holds
over 300 markup elements each one with several attributes which can
assume several values, these can be fixed or defined by the document /
style that the author has used.
Just to remind if any changes are made on the DocBook's definitions
DTD, it's no longer DocBook.
_________________________________________________________________
4.2. Configuration needed
The identifier systems used by the SGML and by some tools are based on
catalogues which perform the translation of these identifiers over to
files holding the necessary definitions.
The section on tailoring a catalogue (see [100]Section 4.3) will give
more details about these files.
For such tools to be able to find the necessary catalogue(s) the value
of the environment variable SGML_CATALOG_FILES should be configured,
as shown in the following example:
$ export SGML_CATALOG_FILES="/usr/lib/sgml/catalog"
This is the only necessary additional configuration for the DocBook,
tools and the like to work correctly on your platform.
_________________________________________________________________
4.3. Creating and modifying catalogues
A catalogue is a text file containing the translation rules of the
public identifier to system's files.
They make easy to use the DocBook, for they allow each user to have
their files installed in a different place (e.g. your home directory,
/usr/local/sgml or in any other place) though no other change on the
document is necessary to be processed and "compiled".
Example 4-1. Example of catalogue
-- Catalogue for the Conectiva Styles -- (1)
OVERRIDE YES
PUBLIC "-//Conectiva SA//DTD DocBook Conectiva variant V1.0//EN" (2)
"/home/ldp/styles/books.dtd"
DELEGATE "-//OASIS"
"/home/ldp/SGML/dtds/catalog.dtd"
DOCTYPE BOOK /home/ldp/SGML/dtds/docbook/db31/docbook.dtd (3)
-- EOF --
[101](1)
Comment. Comments start with "--" and follow to the end of the
line.
[102](2)
The public type association "-//Conectiva SA//DTD books
V1.0//EN" with the file books.dtd on the directory
/home/ldp/styles.
[103](3)
Comment informing the end of the file.
As in the example above, to associate an identifier to a file just
follow the sequence shown:
1. Copy the identifier PUBLIC
2. Type the identifying text
3. Indicate the path to the associated file
_________________________________________________________________
4.3.1. Explaining the terminology system
Notice the identifier
"-//Conectiva SA//DTD books V1.0//EN"
Its formation is not random and follows some pre-defined conditions.
The token "-" indicates that the used identfier isn't a registered
type. Only a few identifiers are registered and those usualy belong to
entities like ISO, IEEE, and others.
The second part of the identfier defines the name of the organization
that created it. On the example above, Conectiva S.A.
The one before the last defines the contents (in this case a
DTD[104][2]) and the name of the identified text.
The last element indicates the language in which the document was
written. Since DocBook is a DTD written in English, the language is
EN. The two letter code recommended is the ISO identification of the
language.
More information can be obtained at [105]OASIS Technical Resolution
9401:1997 (Amendment 2 to TR 9401).
_________________________________________________________________
4.3.2. Useful command for catalogues
The most common commands to be used on catalogues are:
PUBLIC
The keyword PUBLIC maps public identifiers for identifiers on
the system.
SYSTEM
The keywordSYSTEM maps system identifiers for files on the
system.
SYSTEM "http://nexus.conectiva/utilidades/publicacoes/livros.dtd"
"publicacoes/livros.dtd"
SGMLDECL
The keyword SGMLDECL designates the system identifier of the
SGML statement that should be used.
SGMLDECL "publishings/books.dcl"
DTDDECL
Similar to the SGMLDECL the keyword DTDDECL identifies the SGML
statement that should be used. DTDDECL makes the association of
the statement with a public identifier to a DTD. Unfortunately
this association isn't supported by the charge free tools
available. The benefits of this statement can be achieved
somehow with multiple catalogue files.
DTDDECL "-//Conectiva SA//DTD livros V1.0//EN"
"publicacoes/livros.dcl"
CATALOG
The keyword CATALOG allows a catalogue to be included inside
another. This is a way to make use of several different
catalogues without the need to alter them.
OVERRIDE
The keyword OVERRIDE informs whether an identifier has priority
over a system identifier. The standard on most systems is that
the system identifier has priority over the public one.
DELEGATE
The keyword DELEGATE allows the association of a catalogue to a
specific type of public identifier. The clause DELEGATE is very
similar to the CATALOG, except by the fact that it doesn't do
anything until a specific pattern is specified.
DOCTYPE
In case of a document starts with a type of document, but has
no public identifier and no system identifier the clause
DOCTYPE makes the association of this document with an specific
DTD.
_________________________________________________________________
4.4. Writing with DocBook elements
An editor capable of inserting an element according with DTD analisys
helps a lot since it can allow or not the element to be used at the
position where the cursor is in. This way you can be sure that no
invalid element was added anywhere in your document.
In order to ensure future changes are as easy as possible, authors
should try to keep as much compatibility as possible with theXML
version of the DocBook DTD. This means keeping element names in upper
case, using double quotes in all attributes, not using "markup
minimizations" (explained below), and not omitting end tags. Most
tools that automatically insert elements (like psgml+emacs) follow
these rules automatically or with some fine tuning.
There are several forms of markup minimization. These include empty
tags. One example of tag minimization is that instead of typing the
end tag you simply type >. Another example, as said before, is
ommiting tags. You can see both examples below:
I'm using here>, normal text here,
and <>here> I emphasized the text again, with empty tags.
Each type of document created has a specific structure and example of
documents can found afterwards on this document. (see [106]Section
4.10).
Considering the explanation above we can proceed to instructions on
how to write a document using DocBook.
_________________________________________________________________
4.4.1. Useful commands
The [107]Table 4-1 shows some commands which are useful to generate
generic documents. Remember that some elements are valide only on some
contexts.
Tip: Sometimes the appearance of a particular tag changes from one
format to another. As a beginner in DocBook writing, you ay wish to
see how your document looks in several formats before you publish
them.
Note: Since the formatting depends on the output style chosen, it's
recommended to use as much markup as possible. Even if the
appearance of the output doesn't seem to change with the standard
output style, there may be specific output formats that will make
these tags stand out.
Table 4-1. Useful commands
Description Command Result
E-mail address address@domain <[108]address@domain>
About the author ... (see example below)
Author's name
First_NameMiddle_NameSurname
First Name Middle Name Surname
Keys' name (printings on the keyboard) F1 F1
Symbol represented by the keys KEY_F1 KEY_F1
Key's code 0x3B 0x3B
Combinations or sequences of keys
CtrlS
Ctrl-S
Programs Menu File File
Menu Items Salvar Save
Menu Sequences
CtrlSArquivoSalvar
File->Save (Ctrl-S)
Mouse Button left left
Command Names comando command
Application Names application application
Text Bibliographical Reference reference
[reference]
Quote
Text AuthorQuote Text.
Quote Text.
--Text Author
Index (NA) See [109]Section 4.5.
File Names
file
file
Directories
directory
directory/
Emphasize Text[110][a]
text
text
Footnotes
Footnote text
(See note at the end of this table)
URLs
123456ABCDEF
1 2 3
4 5 6
A, B, C, D, E, F
Pictures (NA) See [112]Section 4.6
Table (NA) See [113]Section 4.7
Programs List (NA) See [114]Section 4.8
Glossary
TermDefinition
(See the glossary at the end of this document)
Crossed References
...
...
Please, see for more information.
(NA)
Notes:
a. The text can be enphasized in a few ways. The most common ways are
italics and bold. DocBook, however, supports only italics. The use of
bold requires additional settings on the stylesheet used.
_________________________________________________________________
4.5. Encoding Indexes
The generation of indexes depends on the markups inserted in the text.
Such markups will be processed afterwards by an external tool and will
generate the index. An example of such a tool is the collateindex.pl
script (see [115]Section 4.9.1). Details about the process used to
generate these indexes are shown in [116]Section 4.9.3.
The indexes have nesting levels. The markup of an index is done by the
code [117]Example 4-2.
Example 4-2. Code for the generation of an index
Main levelSecond levelThird level
It's possible to refer to chapters, sections and other parts of the
document using the attribute zone.
Example 4-3. Use of the attributte zone
Encoding IndexeseditionindexThe generation of indexes depend on the inserted markups on the text.
The [118]Example 4-3 has the code used to generate the entry of this
edition on the index. In fact, since the attribute zone is used, the
index statement could be located anywhere in the document or even in a
separate file.
However, to facilitate maintenance the entries for the index were all
placed after the text to which it refers.
Example 4-4. Usage of values startofrangeand endofrange on the
attributeclass
Typing the text normally sometimes there's the need of
examplesindex
mark large amounts of text.Keep inserting the paragraphs normally.Until the end of the section intended
to be indexed.
.
_________________________________________________________________
4.6. Inserting Pictures
It's necessary to insert pictures for all types of media on which the
document will be published.
If you use the TeX format you'll need the images as a PostScript file.
For online publishing you can use any kind of common image file, such
as JPG, GIF or PNG.
The easiest way to insert pictures is the use of the attribute
fileref. Usually pictures are generated in JPG and in PostScript (PS
or EPS).
Example 4-5. Inserting a picture
Replacing
by eliminates the need to insert a
title for the picture.
There's still the float attribute on which the value 0 indicates that
the picture should be placed exactly where the text flux appears. The
value 1 allows the picture to be moved to a more convenient location
(this location can be described on the style sheet used or even can be
controlled by the application being used).
_________________________________________________________________
4.6.1. Alternative Methods
The first alternative to [119]Example 4-5 is the elimination of
elements
or .
Another interesting alternative when it's the decision to publish the
text on media and pictures aren't accepted, is the use of a wrapper
.
Example 4-6. Using
Files on the following formats are available BMP, CGM-BINARY,
CGM-CHAR, CGM-CLEAR, DITROFF, DVI, EPS, EQN, FAX, GIF, GIF87A, GIF89A,
IGES, JPEG, JPG, LINESPECIFIC, PCX, PIC, PS, SGML, TBL, TEX, TIFF,
WMF, WPG.
This method presents an advantage: a better control of the
application. The elements are consecutively tested until
one of them is accepted. In case of the output format doesn't support
images the element will be used. However, the biggest
advantage in usage of the format [120]Example 4-6 is that on the
release 5.0 of the DocBook the element will cease to exist.
As a disadvantage there's the need for more than one representation
code of the same information. It's up to the author to decide which
method he will implement illustrations and pictures on his or hers
document, but for compatibility reasons with future versions I
recommend the use of this method for pictures and graphics.
_________________________________________________________________
4.7. Tables
Many information are best represented when formatted as tables.
A primitive way to create tables was already presented on the
[121]Table 4-1 with the use of , however, the DocBook has
more sophisticated methods to deal with this information.
Example 4-7. Inserting tables
Table 4-2. Example Table
Horizontal Span Heading 2 Heading 3 Heading 4
Data11 Data12 Data13 Data14 Data15
Data21 Data22 Data23 Data24 Vertical Span
Data31 Double Span Data34
Data41 Data44 Data45
Footing 1 Footing 2 Footing 3 Footing 4 Footing 5
_________________________________________________________________
4.8. Listings and program codes
An interesting feature is to show parts of code and the possibility to
comment on them. The DocBook allows the insertion of the program code
and also callouts to specific lines of this code.
Such a feature was used, for example, to demonstrate how a catalogue
file is configured (see [122]Section 4.3).
The used code was demonstrated below. In case the callout feature
isn't desired, it's possible to eliminate the areas between
and .
Catalog Sample
-- Catalogues for the Conectiva S.A. Style --
OVERRIDE YES
PUBLIC "-//Conectiva SA//DTD books V1.0//EN" "/home/ldp/estilos/livros.dtd"
DELEGATE "-//OASIS" "/home/ldp/SGML/dtds/catalog.dtd"
DOCTYPE BOOK /home/ldp/SGML/dtds/docbook/db31/docbook.dtd
-- EOF --
Comment. Comments begin with --
and follows to the end of the line. The public type association
"-//Conectiva SA//DTD books V1.0//EN"
with the file books.dtd on the directory
/home/ldp/estilos.
Comment informing the end of the file.
The listings can be directly inserted on the document's body without
the need of the element or .
The calling coordinates specifications are done with reference to the
code line which will be commented.
_________________________________________________________________
4.9. Tools & Hints
The process of producing output and generating indexes is repetitive
and error prone. To make things easier some scripts are included here
to facilitate this work. Customize and use them at will.
_________________________________________________________________
4.9.1. Compiling the sources
The script compiles-sgml is a set of grouped commands. As parameters
the name of the document should be passed SGML and the output format
expected.
The script version included below supports the formats XML, HTML, TeX,
RTF, PS, DVI and mirrored PS, ideal for the creation of
photolithographs.
The generation of the indices is made automatically by the script
collateindex.pl[123][4], which should be installed in your system.
Besides the commands below which generate the outputs in different
formats, there are other tools fromCygnus(TM) making the direct
conversion. Such tools can be obtained in [124]here.
The list below is available [125]here.
Here is also available a version of [126]collateindex.pl.
Example 4-8. Script compiles-sgml
#!/bin/bash
#
# Compile DocBook documents into several output formats.
#
# Godoy.
# 19991230 - Initial release.
# 20000117 - Placed the options using "case" and parameters passed
# via command line. The pages on the Zope are already updated.
# --- Removed to public version (/home/ldp).
# 20000120 - Placed the call to use the books.dtd.
# 20000126 - Placed the commands for the index generation.
#
# If the jade is already installed, disconsider the line bellow.
JADE=/usr/bin/jade
# If the jade package is already installed, disconsider the line bellow.
# JADE=/usr/bin/openjade
DOCUMENT=$1
shift 1
TYPE=$1
. ~/.bash_profile
. ~/.bashrc
case $TYPE in
html)
rm -f *.htm
rm -f *.html
perl /home/ldp/SGML/style/dsssl/docbook/bin/collateindex.pl -N -o index.
sgml
jade -t sgml -V html-index -d /home/ldp/SGML/style/dsssl/docbook/html/do
cbook.dsl $DOCUMENT.sgml
perl /home/ldp/SGML/style/dsssl/docbook/bin/collateindex.pl -o index.sgm
l HTML.index
$JADE -t sgml -i html -d /home/ldp/SGML/style/dsssl/docbook/html/docbook
.dsl -d /home/ldp/SGML/conectiva/livros.dsl#html $DOCUMENT.sgml
;;
rtf)
rm -f $DOCUMENT.rtf
perl /home/ldp/SGML/style/dsssl/docbook/bin/collateindex.pl -N -o index.
sgml
jade -t sgml -V html-index -d /home/ldp/SGML/style/dsssl/docbook/html/do
cbook.dsl $DOCUMENT.sgml
perl /home/ldp/SGML/style/dsssl/docbook/bin/collateindex.pl -o indice.sg
ml HTML.index
$JADE -t rtf -V rtf-backend -d /home/ldp/SGML/style/dsssl/docbook/print/
docbook.dsl -d /home/ldp/SGML/conectiva/books.dsl#print $DOCUMENT.sgml
;;
xml)
rm -f $DOCUMENT.xml
perl /home/ldp/SGML/style/dsssl/docbook/bin/collateindex.pl -N -o index.
sgml
jade -t sgml -V html-index -d /home/ldp/SGML/style/dsssl/docbook/html/do
cbook.dsl $DOCUMENT.sgml
perl /home/ldp/SGML/style/dsssl/docbook/bin/collateindex.pl -o indice.sg
ml HTML.index
$JADE -t sgml -i xml -d /home/ldp/SGML/style/xsl/docbook/html/docbook.xs
l $DOCUMENT.sgml
;;
tex)
rm -f $DOCUMENT.tex
perl /home/ldp/SGML/style/dsssl/docbook/bin/collateindex.pl -N -o indice
.sgml
jade -t sgml -V html-index -d /home/ldp/SGML/style/dsssl/docbook/html/do
cbook.dsl $DOCUMENT.sgml
perl /home/ldp/SGML/style/dsssl/docbook/bin/collateindex.pl -o indice.sg
ml HTML.index
$JADE -t tex -V tex-backend -d /home/ldp/SGML/style/dsssl/docbook/print/
docbook.dsl -d /home/ldp/SGML/conectiva/livros.dsl#print $DOCUMENT.sgml
;;
dvi)
rm -f $DOCUMENT.tex
rm -f $DOCUMENT.dvi
perl /home/ldp/SGML/style/dsssl/docbook/bin/collateindex.pl -N -o indice
.sgml
jade -t sgml -V html-index -d /home/ldp/SGML/style/dsssl/docbook/html/do
cbook.dsl $DOCUMENT.sgml
perl /home/ldp/SGML/style/dsssl/docbook/bin/collateindex.pl -o indice.sg
ml HTML.index
$JADE -t tex -V tex-backend -d /home/ldp/SGML/style/dsssl/docbook/print/
docbook.dsl -d /home/ldp/SGML/conectiva/livros.dsl#print $DOCUMENT.sgml
jadetex $DOCUMENT.tex
;;
mirror)
rm -f $DOCUMENT.tex
rm -f $DOCUMENT.dvi
rm -f $DOCUMENT.mirror.ps
perl /home/ldp/SGML/style/dsssl/docbook/bin/collateindex.pl -N -o indice
.sgml
jade -t sgml -V html-index -d /home/ldp/SGML/style/dsssl/docbook/html/do
cbook.dsl $DOCUMENT.sgml
perl /home/ldp/SGML/style/dsssl/docbook/bin/collateindex.pl -o indice.sg
ml HTML.index
$JADE -t tex -V tex-backend -d /home/ldp/SGML/style/dsssl/docbook/print/
docbook.dsl -d /home/ldp/SGML/conectiva/livros.dsl#print $DOCUMENT.sgml
jadetex $DOCUMENT.tex
dvips -h /home/ldp/estilos/skel/mirr.hd -O 1.5cm,3cm -f $DOCUMENT.dvi -o
$DOCUMENT.mirror.ps
;;
ps)
rm -f $DOCUMENT.tex
rm -f $DOCUMENT.dvi
rm -f $DOCUMENT.ps
perl /home/ldp/SGML/style/dsssl/docbook/bin/collateindex.pl -N -o indice
.sgml
jade -t sgml -V html-index -d /home/ldp/SGML/style/dsssl/docbook/html/do
cbook.dsl $DOCUMENT.sgml
perl /home/ldp/SGML/style/dsssl/docbook/bin/collateindex.pl -o indice.sg
ml HTML.index
$JADE -t tex -V tex-backend -d /home/ldp/SGML/style/dsssl/docbook/print/
docbook.dsl -d /home/ldp/SGML/conectiva/livros.dsl#print $DOCUMENT.sgml
jadetex $DOCUMENT.tex
dvips -The 1.5cm,3cm -f $DOCUMENT.dvi -o $DOCUMENT.ps
;;
*)
echo "How to use: $0 file {html|tex|rtf|xml|ps|dvi|mirror}"
exit 1
esac
exit 0
Obviously such script can be modified forming a Makefile, optimizing
some functions.
_________________________________________________________________
4.9.2. Inserting a summary on the initial articles page
A feature that might be interesting in some cases is the insertion of
a summary on the initial page of an article. The DocBook articles does
not include it as a standard feature.
To enable this it's necessary to make a modification on the stylesheet
file used.
The example below describes the process and it's use is shown in
[127]Example 4-8.
Example 4-9. Stylesheet to insert summaries in articles
]>
; Includes a summary at the beginning of an item.
(define %generate-article-toc% #t)
; Includes a summary at the beginning of an item.
(define %generate-article-toc% #t)
_________________________________________________________________
4.9.3. Inserting indexes automatically
Although DocBook has markups for the composition of indexes, these are
not generated automatically. The tool [128]collateindex.pl allows the
indexes to be generated automatically.
The way to use this script is described bellow and a practical example
can be seen previously in this document (see [129]Example 4-8).
1. Process the document with jade using the style to HTML with the
option -V html-index.
$ jade -t sgml -d html/docbook.dsl -V html-index document.sgml
2. Generate the document index.sgml with [130]collateindex.pl.
$ perl collateindex.pl -o index.sgml HTML.index
For the above example to work, it's necessary to define an external
entity by calling the file index.sgml.
Example 4-10. Configuring an external entity to include the index
]>
See also [131]Section 4.5 for information on how to insert necessary
information on the text.
Note: Remember that if you're trying to get Table of Contents or
Indexes on PS or PDF output you'll need to run jadetex or
pdfjadetex at least three times. This is a TeX requirement and not
a DocBook or related application one.
_________________________________________________________________
4.9.4. Making notes on the text while it's being written
An interesting feature while writing a text is to be able to check if
such text will be presentable or not on the final draft. It's common
to have several parts of the text marked as drafts, especially when
we're updating an already existent document.
DocBook allows along with an entity of parameters to include or not
the insertions of specific parts of text in several places on the
document based on the context. Sometimes for an upgrading we need to
see how the document looks like or just have sketches of a new session
or chapter, but we don't want this sketch to appear on the final
draft.
With the use of parameter entities we can include or eliminate these
drafts altering only one line at the beginning of a document.
Example 4-11. Use of parameter entities
...
This paragrph will be included on the draft when the entity
"review" is defined with the value "INCLUDE".
]]>
The entity review might have several texts defined as in [132]Example
4-11. When the changes on the text are considered final, it's
necessary just to remove parts of the text relative to the 3rd. and
6th. lines.
To keep the draft definitions and don't show the text on the final
draft, just alter de specification of the entity from INCLUDE to
IGNORE.
_________________________________________________________________
4.9.5. Re-using parts of documents
An important characteristic about the external entities is about the
re-using issue of text and documents.
With those characteristics it's possible to create files with text
used several times (e.g. licenses and company policies) and simply
include those files in the appropriate place.
An example and application of this characteistic was found previously
in [133]Example 4-10. Another example is the SGML code of this HOWTO.
_________________________________________________________________
4.10. Document samples
As stated before each type of document has a particular heading and
valid commands structure. The following sub-sections will provide
heading and valid commands structures on articles and books.
These examples do not cover all possibilities and they are available
here only with the intention to serve as generic guides for what it's
possible to do.
_________________________________________________________________
4.10.1. Article example
Como-Fazer DocBookJorgeLuizGodoyFilhoConectiva S.A.
orgname>
Publishing Departmentt;/orgdiv>
godoy@conectiva.com1.027 de janeiro de 2000godoyVersão inicial.This document can be freely translated and distributed. It's releas
ed
under the LDP License.SGMLDocBookDTDXMLcatalogsdocumentsPublishingdlt;/keyword>
ConectivaconfigurationusetoolsHOWTO
_________________________________________________________________
4.10.2. Book Example
_________________________________________________________________
Chapter 5. Style guides
This section contains notes on conventions that the LDP has agreed to
in order to give all LDP documents a similar look and feel. You should
keep these guides in mind when writing.
_________________________________________________________________
5.1. Date formats
The tag in your header should be in the following format:
v1.0, 21 April 2000
_________________________________________________________________
5.2. Graphics formats
When submitting graphics to the LDP, please submit one set of graphics
in .eps, and another in either .gif or .jpg. Be aware of the patent
issues with .gif, but it makes slightly better pictures than .jpg.
_________________________________________________________________
5.3. DocBook Versions
Only DocBook 3.1 is supported by the LDP at this time. DocBook 4.0 is
under consideration. Many 3.1 documents can be converted to 4.0 easily
by avoiding the use of depreciated tags.
When writing your DocBook header, it should look like this:
_________________________________________________________________
5.4. Depreciated Tags
Tags listed in DocBook: The Definitive Guide as depreciated are
discouraged for use in LDP documentation. Some ways to use newer tags
are listed in the tip and tricks section.
_________________________________________________________________
5.5. Tag Minimization
Tag minimization is using > instead of the full end of a tag (such
as . 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.
_________________________________________________________________
5.6. Conventions
Conventions for different kinds of text is as follows:
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.
A command would then look like this:
bash$ command "run as a normal user"
bash# command "run as a root user"
tcsh# setenv DISPLAY :0.0
_________________________________________________________________
Chapter 6. Tips and Tricks with DocBook
This section covers a few quirks of DocBook that you may run into when
writing your documents.
_________________________________________________________________
6.1. Including Images
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:
This is a better way than using for two reasons. First,
will be removed in DocBook 5.0 in favor of the
tag. So you may as well get started with the right way now. Second,
allows for different kinds of media based on what the
output is. In this example, the first is an encapsulated
PostScript(eps) file for use with formats derived from TeX such as
DVI, PS, and PDF. The second is a JPEG image for visual
display, mostly for HTML output. The is presented if the
output doesn't support graphics (TXT). Think of it as an tag.
_________________________________________________________________
6.2. Naming separate HTML files
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:
In your first tag (which should be the only one) include an
id parameter and call it index. This will make your tag look like
this:
On the first tag, do not modify it, as it's usually an
introduction and you want that on the first page. For each other
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.
_________________________________________________________________
6.3. Using ldp.dsl
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 [134]http://metalab.unc.edu/gferg/ldp/ldp.dsl.
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.
Place the ldp.dsl file in /usr/lib/sgml/stylesheets and bring it up
under your favorite text editor.You should see something like this:
]]>
]]>
]>
[135](1)
Change the first "docbook.dsl" to read
/usr/lib/sgml/stylesheets/nwalsh-modular/html/docbook.dsl
[136](2)
Change the second "docbook.dsl" to read
/usr/lib/sgml/stylesheets/nwalsh-modular/print/docbook.dsl
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.
With that complete, you can now generate HTML files:
bash$ mkdir HOWTO-HOWTO ; cd HOWTO-HOWTO
bash$ jade -t sgml -i html -d /usr/lib/sgml/stylesheets/ldp.dsl\#html ../HOWTO
-HOWTO.sgml
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:
bash$ jade -t rtf -d /usr/lib/sgml/stylesheets/ldp.dsl ../HOWTO-HOWTO.sgml
_________________________________________________________________
Chapter 7. Distributing your documentation
7.1. Before you distribute
Before you distribute your code to millions of potential readers there
are a few things you should do.
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.
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.
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.
_________________________________________________________________
7.1.1. Validate your SGML code
Using jade, or really the nsgmls command, you can validate your .sgml
code against the DTD to make sure there aren't any errors.
bash$ nsgmls -s HOWTO-HOWTO.sgml
If there are no issues, you'll just get your command prompt back.
_________________________________________________________________
7.2. Copyright and Licensing issues
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 [137]http://www.linuxdoc.org/manifesto.html. As
an author, you may retain the copyright and add other restrictions
(for example, you must approve any translations or derivative works).
A sample license is available in the Manifesto or at
[138]http://www.linuxdoc.org/COPYRIGHT.html. If you choose to use the
boilerplate copyright, simply copy it into your source code under a
section called "Copyright and Licenses" 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.
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.
_________________________________________________________________
7.3. Submission to LDP
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
<[139]ldp-submit@lists.linuxdoc.org>.
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 7 calendar days, please follow up with an e-mail to
make sure things are still in process.
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.
_________________________________________________________________
7.4. HOWTO maintenance
Now that you're a HOWTO author, you should maintain the document and
update it when new versions of software are released. You should also
respond to reasonable comments and questions from your readers. You
don't have to help them all, especially if their question is already
answered in your HOWTO. However, a good experience with the LDP from
readers is one of our goals and a great way of increasing the
popularity of Linux
_________________________________________________________________
Chapter 8. FAQs about the LDP
Q: [140]I want to help the LDP. How can I do this?
Q: [141]I want to publish a collection of LDP documents in a book. How
is the LDP content licensed?
Q: [142]I found an error in an LDP document. Can I fix it?
Q: [143]But I don't know SGML/Can't get the tools working/Don't like
SGML
Q: I want to help the LDP. How can I do this?
A: 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.
Q: I want to publish a collection of LDP documents in a book. How is
the LDP content licensed?
A: Please see [144]http://www.linuxdoc.org/COPYRIGHT.html. Note that
this is only a guideline to authors. However, the licensing cannot be
more restrictive than what is listed in that URL.
Q: I found an error in an LDP document. Can I fix it?
A: Contact the author of the document, or the LDP coordinator at
<[145]ldp-discuss@lists.linuxdoc.org> and mention the problem and how
you think it needs to be fixed.
Q: But I don't know SGML/Can't get the tools working/Don't like SGML
A: 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
<[146]ldp-docbook@lists.linuxdoc.org>.
Glossary
attribute
One attributte makes available extra information regarding the
element on which it appears. The attributes always appear as a
name-value pair on the initialization pointers. Example of an
attribute is id="identification", which gives to the attribute
id the value identification.
Document Type Definition (DTD)
Group of statements that define element names and their
attributes specifying the rules for combinations and sequences.
It's the DTD that define which elements can or cannot be
inserted in the context on which the cursor is in.
DSSSL
DSSSL stands for Document Style Semantics and Specification
Language. It's an ISO standard (ISO/IEC 10179:1996). The DSSSL
standard is internationally used as a language for documents
stylesheets pages for SGML.
element
The elements define the hierarchical structure of a document.
The majority of elements have opening and closing pointers.
Among these pointers, pieces of text or even the whole document
being written can be found. There are empty elements which
contains only opening pointers without any content.
entity
Entity is a name designated for some part of data so that it
can be referenced by a name. These designations are made by a
statement and the stored data might hold from simple characters
to chapters or set of statements of a DTD. There are parameter
entities generic, external, internal and of data on theSGML.
external entity
An external entity points to an external document. External
entities are used to include texts on certain locations of a
SGML document. Suggestions for its use includes sample screens,
legal notes and chapters.
generic entities
An entity referenced by a name which starts with "&" and ends
with semicolon is a generic entity. Most of the time these type
of entities are used on the document and not on the DTD. There
are two types of entities: external and internal which refers
either to special characters or to text objects such as
repeated sentences, names or chapters.
internal entity
An internal entity refers to part of the text and is often used
as a schortcut for portions of a text frequently repeated.
paremeter entity
An entity often used on the DTD. The entity's name starts with
a percent sign (%) and it ends with a semicolon.
float
Objects such as side bars, pictures, tables and charts are
called floats when they don't have a fixed placement on the
text. For a printed text, the chart can appear either at the
top or at the bottom of the page. It can also be placed on the
next page if that's too large.
processing instruction
A processing instruction is a command passed to the document
formatting tool. It starts with "". A sample of instruction
is used on this document for the generated file's choice when
the file is converted to HTML:
SGML
Standard Generalized Markup Language. It's also an
international standard (ISO8879) which specifies rules for the
creation of electronic documents in markup systems regardless
the work platform used.
tag
An SGML element bounded by the marks "<" and ">". Tags are used
to mark the semantic or the structure of a document. A sample
is the tag to mark the beginning of a title.
XML
eXtensible Markup Language. A subproduct of SGML created
specifically for Internet use.
XSL
XML Style Language. XSL is to a XML document what a DSSSL style
is for a SGML document. In fact, the style is a document XML.
Notes
[147][1]
Please, take a look at the [148]source to see how to get similar
results on your documents. You should also remember that the way this
appears to you depends on the format you're reading this document:
online appearance is slightly different from the PostScript or PDF
ones.
[149][2]
Here are valid: DTD, DOCUMENT, ELEMENTS, ENTITIES and NONSGML.
[150][4]
More information about indexes are available at [151]the page about
index of Norman Walsh.
References
1. http://www.conectiva.com/
2. file://localhost/export/sunsite/users/gferg/guides/LAG/LDP-Author-Guide.html#ABOUTTHISGUIDE
3. file://localhost/export/sunsite/users/gferg/guides/LAG/LDP-Author-Guide.html#PURPOSE
4. file://localhost/export/sunsite/users/gferg/guides/LAG/LDP-Author-Guide.html#ABOUTLDP
5. file://localhost/export/sunsite/users/gferg/guides/LAG/LDP-Author-Guide.html#FEEDBACK
6. file://localhost/export/sunsite/users/gferg/guides/LAG/LDP-Author-Guide.html#COPYRIGHTS
7. file://localhost/export/sunsite/users/gferg/guides/LAG/LDP-Author-Guide.html#ACKNOWLEDGEMENTS
8. file://localhost/export/sunsite/users/gferg/guides/LAG/LDP-Author-Guide.html#CONVENTIONS
9. file://localhost/export/sunsite/users/gferg/guides/LAG/LDP-Author-Guide.html#INTRODUCTION
10. file://localhost/export/sunsite/users/gferg/guides/LAG/LDP-Author-Guide.html#THELDP
11. file://localhost/export/sunsite/users/gferg/guides/LAG/LDP-Author-Guide.html#SGML
12. file://localhost/export/sunsite/users/gferg/guides/LAG/LDP-Author-Guide.html#WHYSGML
13. file://localhost/export/sunsite/users/gferg/guides/LAG/LDP-Author-Guide.html#SGMLISNOTXML
14. file://localhost/export/sunsite/users/gferg/guides/LAG/LDP-Author-Guide.html#NEWAUTHORS
15. file://localhost/export/sunsite/users/gferg/guides/LAG/LDP-Author-Guide.html#MAILINGLISTS
16. file://localhost/export/sunsite/users/gferg/guides/LAG/LDP-Author-Guide.html#TOOLS
17. file://localhost/export/sunsite/users/gferg/guides/LAG/LDP-Author-Guide.html#DSSSL
18. file://localhost/export/sunsite/users/gferg/guides/LAG/LDP-Author-Guide.html#DTD
19. file://localhost/export/sunsite/users/gferg/guides/LAG/LDP-Author-Guide.html#JADE
20. file://localhost/export/sunsite/users/gferg/guides/LAG/LDP-Author-Guide.html#JADEWRAPPERS
21. file://localhost/export/sunsite/users/gferg/guides/LAG/LDP-Author-Guide.html#EDITING
22. file://localhost/export/sunsite/users/gferg/guides/LAG/LDP-Author-Guide.html#CVS
23. file://localhost/export/sunsite/users/gferg/guides/LAG/LDP-Author-Guide.html#OTHER
24. file://localhost/export/sunsite/users/gferg/guides/LAG/LDP-Author-Guide.html#AEN614
25. file://localhost/export/sunsite/users/gferg/guides/LAG/LDP-Author-Guide.html#DOCBOOKINTRO
26. file://localhost/export/sunsite/users/gferg/guides/LAG/LDP-Author-Guide.html#CONFIGURATIONS
27. file://localhost/export/sunsite/users/gferg/guides/LAG/LDP-Author-Guide.html#MAKING-CATALOGUES
28. file://localhost/export/sunsite/users/gferg/guides/LAG/LDP-Author-Guide.html#WRITING-DOCBOOK
29. file://localhost/export/sunsite/users/gferg/guides/LAG/LDP-Author-Guide.html#ENCODING-INDEX
30. file://localhost/export/sunsite/users/gferg/guides/LAG/LDP-Author-Guide.html#INSERTING-PICTURES
31. file://localhost/export/sunsite/users/gferg/guides/LAG/LDP-Author-Guide.html#TABLES
32. file://localhost/export/sunsite/users/gferg/guides/LAG/LDP-Author-Guide.html#LISTINGS
33. file://localhost/export/sunsite/users/gferg/guides/LAG/LDP-Author-Guide.html#TOOLS-HINTS
34. file://localhost/export/sunsite/users/gferg/guides/LAG/LDP-Author-Guide.html#EXAMPLES-DOCUMENTS
35. file://localhost/export/sunsite/users/gferg/guides/LAG/LDP-Author-Guide.html#STYLE
36. file://localhost/export/sunsite/users/gferg/guides/LAG/LDP-Author-Guide.html#ACCEPTEDDATES
37. file://localhost/export/sunsite/users/gferg/guides/LAG/LDP-Author-Guide.html#ACCEPTEDGFX
38. file://localhost/export/sunsite/users/gferg/guides/LAG/LDP-Author-Guide.html#ACCEPTEDVERSION
39. file://localhost/export/sunsite/users/gferg/guides/LAG/LDP-Author-Guide.html#NODEPTAGS
40. file://localhost/export/sunsite/users/gferg/guides/LAG/LDP-Author-Guide.html#NOTAGMIN
41. file://localhost/export/sunsite/users/gferg/guides/LAG/LDP-Author-Guide.html#USINGCONVENTIONS
42. file://localhost/export/sunsite/users/gferg/guides/LAG/LDP-Author-Guide.html#TIPS
43. file://localhost/export/sunsite/users/gferg/guides/LAG/LDP-Author-Guide.html#IMAGES
44. file://localhost/export/sunsite/users/gferg/guides/LAG/LDP-Author-Guide.html#NAMEDFILES
45. file://localhost/export/sunsite/users/gferg/guides/LAG/LDP-Author-Guide.html#USINGLDPDSSSL
46. file://localhost/export/sunsite/users/gferg/guides/LAG/LDP-Author-Guide.html#DISTRIBUTION
47. file://localhost/export/sunsite/users/gferg/guides/LAG/LDP-Author-Guide.html#BEFOREYOUDISTRIBUTE
48. file://localhost/export/sunsite/users/gferg/guides/LAG/LDP-Author-Guide.html#MAKINGCOPYRIGHT
49. file://localhost/export/sunsite/users/gferg/guides/LAG/LDP-Author-Guide.html#SUBMISSION
50. file://localhost/export/sunsite/users/gferg/guides/LAG/LDP-Author-Guide.html#MAINTENTANCE
51. file://localhost/export/sunsite/users/gferg/guides/LAG/LDP-Author-Guide.html#FAQ
52. file://localhost/export/sunsite/users/gferg/guides/LAG/LDP-Author-Guide.html#GLOSSARY
53. http://www.cgipc.com/~markk
54. http://www.linuxdoc.org/
55. http://www.linuxdoc.org/manifesto.html
56. http://www.linuxdoc.org/
57. mailto:markk@linuxdoc.org
58. mailto:ldp-discuss@lists.linuxdoc.org
59. http://www.linuxdoc.org/HOWTO/
60. mailto:ser@serek.arch.pwr.wroc.pl
61. mailto:godoy@conectiva.com
62. file://localhost/export/sunsite/users/gferg/guides/LAG/LDP-Author-Guide.html#FTN.AEN92
63. http://www.linuxdoc.org/HOWTO/Printing-HOWTO.html
64. http://www.linuxdoc.org/HOWTO/Ethernet-HOWTO.html
65. mailto:ldp-discuss@lists.linuxdoc.org
66. mailto:ldp-submit@lists.linuxdoc.org
67. http://www.nyx.net/~sgjoen/template.sgml
68. http://www.linuxdoc.org/authors/template/big-howto-template.sgml
69. mailto:ldp-discuss@lists.linuxdoc.org
70. mailto:ldp-discuss-request@lists.linuxdoc.org
71. mailto:ldp-discuss-request@lists.linuxdoc.org
72. mailto:ldp-docbook@lists.linuxdoc.org
73. mailto:ldp-docbook-request@lists.linuxdoc.org
74. http://nwalsh.com/docbook/dsssl/
75. http://metalab.unc.edu/gferg/ldp/ldp.dsl
76. http://www.oasis-open.org/docbook/sgml/3.1/docbk31.zip
77. ftp://ftp.jclark.com/pub/jade/jade-1.2.1.tar.gz
78. http://openjade.sourceforge.net/
79. http://sgmltools-lite.sourceforge.net/
80. http://www.redhat.com/
81. http://www.redhat.com/support/errata/RHBA-2000022-01.html
82. http://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=9670
83. http://www.lysator.liu.se/~lenst/about_psgml/
84. http://www.snee.com/bob/sgmlfree/
85. http://www.freebsd.org/tutorials/docproj-primer/psgml-mode.html
86. http://www.vim.org/
87. http://www.corel.com/
88. http://www.tksgml.de/
89. http://nedit.org/
90. http://www.sourcegear.com/CVS/Docs/blandy
91. https://wroclaw.art.pl/~ser/docs/cvs.html
92. mailto:cvsadmin@cvslist.linuxdoc.org
93. http://cvsweb.linuxdoc.org/index.cgi/linuxdoc
94. http://freshmeat.net/appindex
95. mailto:ldp-submit@lists.linuxdoc.org
96. http://www.docbook.org/
97. http://www.linuxdoc.org/authors/index.html#resources
98. http://aspell.sourceforge.net/
99. http://www.cs.hmc.edu/~geoff/ispell.html
100. file://localhost/export/sunsite/users/gferg/guides/LAG/LDP-Author-Guide.html#MAKING-CATALOGUES
101. file://localhost/export/sunsite/users/gferg/guides/LAG/LDP-Author-Guide.html#EX.CATALOGUE.COMMENT
102. file://localhost/export/sunsite/users/gferg/guides/LAG/LDP-Author-Guide.html#EX.CATALOGUE.DEFINITION
103. file://localhost/export/sunsite/users/gferg/guides/LAG/LDP-Author-Guide.html#EX.CATALOGUE.EOF
104. file://localhost/export/sunsite/users/gferg/guides/LAG/LDP-Author-Guide.html#FTN.AEN718
105. http://www.oasis-open.org/html/a401.htm
106. file://localhost/export/sunsite/users/gferg/guides/LAG/LDP-Author-Guide.html#EXAMPLES-DOCUMENTS
107. file://localhost/export/sunsite/users/gferg/guides/LAG/LDP-Author-Guide.html#TABLE-USEFUL-COMMANDS
108. mailto:address@domain
109. file://localhost/export/sunsite/users/gferg/guides/LAG/LDP-Author-Guide.html#ENCODING-INDEX
110. file://localhost/export/sunsite/users/gferg/guides/LAG/LDP-Author-Guide.html#FTN.AEN1002
111. http://www.conectiva.com/
112. file://localhost/export/sunsite/users/gferg/guides/LAG/LDP-Author-Guide.html#INSERTING-PICTURES
113. file://localhost/export/sunsite/users/gferg/guides/LAG/LDP-Author-Guide.html#TABLES
114. file://localhost/export/sunsite/users/gferg/guides/LAG/LDP-Author-Guide.html#LISTINGS
115. file://localhost/export/sunsite/users/gferg/guides/LAG/LDP-Author-Guide.html#TOOLS-COMPILE
116. file://localhost/export/sunsite/users/gferg/guides/LAG/LDP-Author-Guide.html#AUTOMATIC-INDEXES
117. file://localhost/export/sunsite/users/gferg/guides/LAG/LDP-Author-Guide.html#EXAMPLE-CODE-INDEX
118. file://localhost/export/sunsite/users/gferg/guides/LAG/LDP-Author-Guide.html#INDEX-ZONE
119. file://localhost/export/sunsite/users/gferg/guides/LAG/LDP-Author-Guide.html#EX-PICTURE-FILEREF
120. file://localhost/export/sunsite/users/gferg/guides/LAG/LDP-Author-Guide.html#FORMER-FIGURE-IMAGEOBJECT
121. file://localhost/export/sunsite/users/gferg/guides/LAG/LDP-Author-Guide.html#TABLE-USEFUL-COMMANDS
122. file://localhost/export/sunsite/users/gferg/guides/LAG/LDP-Author-Guide.html#MAKING-CATALOGUES
123. file://localhost/export/sunsite/users/gferg/guides/LAG/LDP-Author-Guide.html#FTN.AEN1505
124. http://sourceware.cygnus.com/docbook-tools/
125. file://localhost/export/sunsite/users/gferg/guides/LAG/compiles-sgml
126. file://localhost/export/sunsite/users/gferg/guides/LAG/collateindex.pl
127. file://localhost/export/sunsite/users/gferg/guides/LAG/LDP-Author-Guide.html#LISTING-COMPILE-SGML
128. file://localhost/export/sunsite/users/gferg/guides/LAG/collateindex.pl
129. file://localhost/export/sunsite/users/gferg/guides/LAG/LDP-Author-Guide.html#LISTING-COMPILE-SGML
130. file://localhost/export/sunsite/users/gferg/guides/LAG/collateindex.pl
131. file://localhost/export/sunsite/users/gferg/guides/LAG/LDP-Author-Guide.html#ENCODING-INDEX
132. file://localhost/export/sunsite/users/gferg/guides/LAG/LDP-Author-Guide.html#EX-ENTITY-PARAMETERS
133. file://localhost/export/sunsite/users/gferg/guides/LAG/LDP-Author-Guide.html#EX-ENTITY-EXTERNAL-INDEX
134. http://metalab.unc.edu/gferg/ldp/ldp.dsl
135. file://localhost/export/sunsite/users/gferg/guides/LAG/LDP-Author-Guide.html#HTML
136. file://localhost/export/sunsite/users/gferg/guides/LAG/LDP-Author-Guide.html#PRINT
137. http://www.linuxdoc.org/manifesto.html
138. http://www.linuxdoc.org/COPYRIGHT.html
139. mailto:ldp-submit@lists.linuxdoc.org
140. file://localhost/export/sunsite/users/gferg/guides/LAG/LDP-Author-Guide.html#AEN2107
141. file://localhost/export/sunsite/users/gferg/guides/LAG/LDP-Author-Guide.html#AEN2112
142. file://localhost/export/sunsite/users/gferg/guides/LAG/LDP-Author-Guide.html#AEN2118
143. file://localhost/export/sunsite/users/gferg/guides/LAG/LDP-Author-Guide.html#AEN2124
144. http://www.linuxdoc.org/COPYRIGHT.html
145. mailto:ldp-discuss@lists.linuxdoc.org
146. mailto:ldp-docbook@lists.linuxdoc.org
147. file://localhost/export/sunsite/users/gferg/guides/LAG/LDP-Author-Guide.html#AEN92
148. file://localhost/export/sunsite/users/gferg/guides/LAG/sgml/conventions.sgml
149. file://localhost/export/sunsite/users/gferg/guides/LAG/LDP-Author-Guide.html#AEN718
150. file://localhost/export/sunsite/users/gferg/guides/LAG/LDP-Author-Guide.html#AEN1505
151. http://nwalsh.com/docbook/dsssl/doc/indexing.html