Purpose / Scope of this HOWTO

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 http://www.cgipc.com/~markk in its SGML source. Other versions may be found in different formats at the LDP homepage 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 HOWTO is designed to help you get familiar with how the LDP works, and what tools you'll need to write your own HOWTO.

About the LDP

The following is an excerpt from the LDP Manifesto (http://www.linuxdoc.org/manifesto.html)

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.

You can find out more about the Linux Documentation Project at http://www.linuxdoc.org

Feedback

Comments on this HOWTO may be directed to the author (<markk@linuxdoc.org>).

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.

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 <ldp-discuss@lists.linuxdoc.org> list. Some sections I got from the HOWTO Index (available at many LDP locations) and the sgmltools documentation. The sections on network access to CVS was partially written by Serek (<ser@serek.arch.pwr.wroc.pl>). Sections on DocBook were written by Jorge Godoy (<godoy@conectiva.com.br>). A great deal of thanks to both of them for their help.

Conventions

Commands that are listed have the following format. Commands are prefaced with the name of the current shell running. This is followed by a $ for commands that should be run as a normal (non-root) user. Shells followed by a # are commands that should be run as a root user.

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 Printing HOWTO. If you want to do find out if your Ethernet card works with Linux, grab the 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.

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. 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 <table> 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.

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.

For New Authors

If you are a new to the LDP and want to pick up an unmaintained HOWTO or write a new HOWTO or mini-HOWTO document, contact the HOWTO coordinator at <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 <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.

Mailing Lists

There are a few mailing lists to subscribe to so you can take part in how the LDP works. First is <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 <ldp-discuss-request@lists.linuxdoc.org>. To unsubscribe, send an e-mail with the subject of "unsubscribe" to <ldp-discuss-request@lists.linuxdoc.org>.

Another list is the <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 <ldp-docbook-request@lists.linuxdoc.org>.

DSSSL

The Normal Walsh version is required, the LDP is optional.

DocBook DTD (version 3.1)

Required - 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.

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.

Jade wrappers

These tools are optional and may be installed after Jade, the DSSSL, and DTD have been installed.

Editing tools

The following tools may be used to create, edit, or validate your HOWTO.

Other/Reference

The items in this section are reference books or other utilities that can't quite be categorized (yet).

Downloading and installing the tools

bash$ CVSROOT=:pserver:cvs@cvs.sgmltools.org:/home/cvs
bash$ export CVSROOT
bash$ cvs login
bash$ cvs -z6 get sgmltools

bash$ ./compile
bash$ make
bash# make install

bash# apt-get install sgmltools-2   

bash$ db2html filename   

bash$ db2pdf filename   

Writing SGML by hand

Most of this is covered by Jorge Godoy's Using DocBook document. Those interested can read it athttp://metalab.unc.edu/godoy/using-docbook/using-docbook.htmlfor writing DocBook using your favorite text editor.

Writing SGML using LyX

Writing SGML using PSGML

bash$ export SGML_CATALOG_FILES=/usr/lib/sgml/catalog

;; *******************************************************************
;; 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.
;; *******************************************************************

<!DOCTYPE test [
<!ELEMENT test - - (#PCDATA)>
]>

<!DOCTYPE test [
<!ELEMENT test - - (#PCDATA)>
]>
<test></test>

<!DOCTYPE ARTICLE PUBLIC "-//OASIS//DTD DocBook V3.1//EN">

Date formats

The <pubdate> tag in your header should be in the following format:

v1.0, 21 April 2000

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 then .jpg.

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:

<!doctype article public "-//OASIS//DTD DocBook V3.1//EN">

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.

Tag Minimization

Tag minimization is using </> instead of the full end of a tag (such as </para>. 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.

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

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:

<figure>
<title>LyX screen shot</title>
<mediaobject>
<imageobject><imagedata fileref="lyx_screenshot.eps" format="eps"></imageobject>
<imageobject><imagedata fileref="lyx_screenshot.jpg" format="jpg"></imageobject>
<textobject><phrase>Screen shot of the LyX document processing program</phrase></textobject>
</mediaobject>
</figure>

This is a better way than using <graphic> for two reasons. First, <graphic> will be removed in DocBook 5.0 in favor of the <mediaobject> tag. So you may as well get started with the right way now. Second, <mediaobject> allows for different kinds of media based on what the output is. In this example, the first <imageobject> is an encapsulated PostScript(eps) file for use with formats derived from TeX such as DVI, PS, and PDF. The second <imageobject> is a JPEG image for visual display, mostly for HTML output. The <textobject> is presented if the output doesn't support graphics (TXT). Think of it as an <alt> tag.

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 <article> tag (which should be the only one) include an id parameter and call it index. This will make your tag look like this:

<article id="index">

On the first <sect1> tag, do not modify it, as it's usually an introduction and you want that on the first page. For each other <sect> 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.

<sect1 id="tips">

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 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:

<!DOCTYPE style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN" [
<!ENTITY % html "IGNORE">
<![%html;[
<!ENTITY % print "IGNORE">
<!ENTITY docbook.dsl SYSTEM "docbook.dsl" CDATA dsssl>
]]>
<!ENTITY % print "INCLUDE">
<![%print;[
<!ENTITY docbook.dsl SYSTEM "docbook.dsl" CDATA dsssl>
]]>
]>

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 -ihtml -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

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 <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 .cvsroot 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  

Other CVS repository notes

bash$ cvs -d :pserver:cvs@anoncvs.linuxdoc.org:/cvsroot login    

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 <ldp-submit@lists.linuxdoc.org>.

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.

bash$ nsgmls -s HOWTO-HOWTO.sgml   

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 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 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 HOWTO-HOWTO requires notification to the author of any derivative works or translations. I also explicitly place any source code (aside from the SGML the HOWTO 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.

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 <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.

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

I want to help the LDP. How can I do this?

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.

I want to publish a collection of LDP documents in a book. How is the LDP content licensed?

Please see 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.

I found an error in an LDP document. Can I fix it?

Contact the author of the document, or the LDP coordinator at <ldp-discuss@lists.linuxdoc.org>and mention the problem and how you think it needs to be fixed.

But I don't know SGML/Can't get the tools working/Don't like SGML

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<ldp-docbook@lists.linuxdoc.org>.