--> Conectiva S.A.'> ]> LDP Author Guide v3.5 4 Dec, 2000 Mark F. Komarinski VA Linux Systems
markk@linuxdoc.org
 Jorge Godoy &conectivasa; Publishing Department
godoy@conectiva.com
godoy@metalab.unc.edu
 David C. Merrill
dcmerrill@mindspring.com
 List the tools, procedures, and hints to get LDP authors up to speed and writing. 3.5 Dec 4, 2000 mfk Changed mailing list pointers to new lists. 3.4 Dec 1, 2000 dcm Added Crediting Translators and Converters 3.3 Nov 11, 2000 mfk Added links to SGML GPL and FDL 3.1 Oct 10, 2000 mfk Spelling changes, changed list of LDP policies to now accept DocBook XML. More information about how to use *jade with XML will follow. 3.0 Aug 24, 2000 gjf Integrated David Merrill's style guide document. Further clean-up and additions. 2.0 Jul 13, 2000 mfk Cleaned up using-docbook a bit. Moved some chapters 1.9 Jun 26, 2000 mfk Integrated Jorge's using-docbook document. 1.5 Jun 14, 2000 mfk Documented sgedit 1.4 Jun 12, 2000 mfk Documented vim and sgedit. Spelling and other changes from ldp list. Also added LDP guidelines under style guide. About this Guide
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 document can be found at the LDP homepage http://www.linuxdoc.org. The original DocBook SGML, HTML, and other formats can be found there. 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.
About the LDP
LDP Manifesto located at 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.
The human readable version goes more like this: The LDP consists of a large group of volunteers that are working on documentation for the Linux OS. The most visible documentation are the HOWTOs located at http://www.linuxdoc.org/". This Guide focues primarily on how to write your own HOWTOs for submission to the LDP.
Feedback Comments on this Guide may be directed to the author (markk@linuxdoc.org).
Copyrights and Trademarks Copyright 1999-2000 Mark F. Komarinski, David C. Merrill, Jorge Godoy 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 discuss@linuxdoc.org list. Some sections I got from the HOWTO Index 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). A great deal of thanks to both of them for their help.
&conventions; Introduction to the LDP and SGML
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 (or tags). The DocBook DTD, used to create this document, is an example of this. The DTD lists the rules that the content must follow. Second is the DSSSL or Document Style Semantics and Specification Language. The DSSSL tells the program doing the rendering how to convert the SGML into something that a human can read. It tells the renderer to convert a <title> tag into 14 point bold if it is going to RTF format, or to turn it into a <h1> tag if you're going to HTML. Finally there is the Content, which is what gets rendered by the SGML processor and is eventually seen by the user. This paragraph is content, but so would a graphic image, table, numbered list, and so on. Content is surrounded by tags to separate out each element.
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.
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 DocBook v4.1.2 is now officially supported by the LDP. If you're familiar with SGML and want to convert to XML, please keep the following in mind (list borrowed from DocBook: The Definitive Guide): All XML markup is case sensitive. All element, attribute, and entity names have to be in lowercase. SGML is not case sensitive. All attributes have to be quotes using either straight (') or double (") quotes. Empty elements (like xref) have to end with a /: <xref/>. Tag minimizations (</>) are not supported. The LDP discourages their use in SGML as well.
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 discuss@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 submit@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: http://www.linuxdoc.org/authors/template-ld/big-howto-template-ld.sgml - This template is written by Stein Gojen and is based off the LinuxDoc template. http://www.linuxdoc.org/authors/template/big-howto-template.sgml - This template is based on Stein's work, but is much larger and complicated than the above. It uses more features of DocBook.
Mailing Lists There are a few mailing lists to subscribe to so you can take part in how the LDP works. First is discuss@linuxdoc.org, which is the main discussion group of the LDP. To subscribe, send a message with the subject reading "subscribe" to discuss-subscribe@linuxdoc.org. To unsubscribe, send an e-mail with the subject of "unsubscribe" to discuss-unsubscribe@linuxdoc.org. Another list is the docbook@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 docbook-subscribe@linuxdoc.org.
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.
DSSSL The Normal Walsh version is required, the LDP is optional.
Norman Walsh DSSSL 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 <H1> tag in HTML, or bold, 14 point Times Roman for RTF, for example. Documentation for DSSSL is located at the same site. Note that modifying the DSSSL doesn't modify DocBook itself. It merely changes the way the rendered text looks. The LDP uses a modified DSSSL (see below).
LDP DSSSL http://www.linuxdoc.org/authors/tools/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.
DocBook DTD (version 4.1 or 3.1) Required - http://www.oasis-open.org/docbook/sgml/4.1/docbk41.zip or http://www.oasis-open.org/docbook/sgml/3.1/docbk31.zip The XML DTD is available from http://www.oasis-open.org/xml/4.1.2/. 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 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.
Using Jade This is the quick and dirty way that should work for all distributions, no matter what distribution you're using. Create a base directory to store everything such as /usr/local/sgml/. We'll call this $_toolroot from here on. 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 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 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 To create one large HTML file, add -V nochunks to the jade command.
Jade in XML mode Once configured for XML, jade and openjade will work the wame way as for SGML DocBook. After extracting the XML DTD, you may want to make a symlink from the docbook.cat file to "catalog", the default filename for jade/openjade catalogs. Replace $_xml_root with the location of your XML DTD. bash$ cd $_xml_root bash$ ln -s docbook.cat catalog bash$ export SGML_CATALOG_FILES=$_xml_root/catalog:$_toolroot/dsssl/catalog:\ $_toolroot/dtd/docbook/catalog bash$ jade -t sgml -i html -d style $_jade_path/pubtext/xml.dcl foo.xml You'll need the catalogs for XML, the DSSSL, and DocBook, respectively. $_toolroot was defined above. Replace style with the style you wish to use. The pointer to xml.dcl is requires for jade to work, and it has to be listed immediately before the pointer to your XML document. You may get the following warnings when processing XML documents. They don't impact the output, and the cause is being looked into. <xml_dtd_pth>/ent/iso-lat2.ent:119:18:E: "X0176" is not a function name <xml_dtd_pth>/ent/iso-lat2.ent:120:17:E: "X0178" is not a function name If you want to convert your existing SGML DocBook into XML docbook, use this as your declaration (the lines at the very start of your document). <?xml version='1.0' encoding='ISO-8859-1'?> <!DOCTYPE article PUBLIC '-//OASIS//DTD DocBook XML V4.1.2//EN'> If you have followed LDP guidelines, there should be no other changes required to your document.
OpenJade 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.
Jade wrappers These tools are optional and may be installed after Jade, the DSSSL, and DTD have been installed.
sgmltools-lite 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.
Cygnus DocBook Tools May be Red Hat specific - 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.
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: 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 Renders DocBook into HTML. A subdirectory with the filename (minus the .sgml extension) is created and the HTML files are placed there. bash$ db2pdf Renders DocBook into a PDF file. Note that there is currently a problem with db2pdf, and pd2ps caused by JadeTeX. This has been registered as a bug with RedHat.
Editing tools The following tools may be used to create, edit, or validate your HOWTO.
Emacs (PSGML) Optional - 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.
Writing SGML using PSGML
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 (Chimpsgml). 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: http://www.snee.com/bob/sgmlfree/.
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
SGML Smoke Test Try the following smoke test. Start a new file, /tmp/test.sgml for example, and enter the following: !DOCTYPE test [ <!ELEMENT test - - (#PCDATA)> ] 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 test element. If things are working correctly, you should see the following in Emacs: !DOCTYPE test [ <!ELEMENT test - - (#PCDATA)> ] testtest
Writing a New HOWTO in DocBook Start a new file for your HOWTO and enter the following: !DOCTYPE ARTICLE PUBLIC "-//OASIS//DTD DocBook V3.1//EN" Enter CcC 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 cCeRETURN to insert an article element and proceed to write your HOWTO.
Quick Reference for Emacs with PSGML See Nik Clayton's primer for FreeBSD documentation: http://www.freebsd.org/tutorials/docproj-primer/psgml-mode.html
VIM 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.
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.
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.
WordPerfect 9 (Corel Office 2000) 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.
sgedit 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 DocumentValidate command.
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.
nedit http://nedit.org To be fair, neditnedit 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.
nedit screen shot The nedit program can provide line numbers across the left side of the screen, handy for when nsgmls complains of errors
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 PreferencesLanguage ModeSGML HTML command.
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 PreferencesDefault SettingsCustomize MenusShell 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 AltS. Once this menu item is set up, you can press AltS 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.
Adding shell commands to nedit
Click OK and you'll now be back at the main nedit screen. Load up an SGML file, and select ShellSGML Validate or press AltS. 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 PreferencesShow Line Numbers) then finding the errors is much simpler, as nsgmls will list errors by their line number.
nsgmls output on success If nsgmls reports success, it merely reports the version of nsgmls
&cvs;
Other/Reference The items in this section are reference books or other utilities that can't quite be categorized (yet).
DocBook: The Definitive Guide 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.
SGML templates Optional - 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.
Aspell Optional - 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.
ispell Optional - http://www.cs.hmc.edu/~geoff/ispell.html The ispell program is distributed with RedHat (and possibly other distros) and also ignores markup tags.
&using-docbook; &style-guide; Additional Style-related Items This section contains additional style-oriented topics to consider when preparing your document.
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 than .jpg.
DocBook Versions The LDP supports and accepts documentation in the following formats: SGML DocBook versions 4.x and 3.1 SGML LinuxDoc XML DocBook version 4.1.2 When writing your DocBook header, it should look like this: !doctype article public "-//OASIS//DTD DocBook V4.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
Tips and Tricks with DocBook This section covers a few quirks of DocBook that you may run into when writing your documents.
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 titleLyX screen shottitle mediaobject imageobject imagedata fileref="lyx_screenshot.eps" format="eps" imageobject imageobject imagedata fileref="lyx_screenshot.jpg" format="jpg" imageobject textobject phraseScreen shot of the LyX document processing programphrase 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 chapter tag, do not modify it, as it's usually an introduction and you want that on the first page. For each other section 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. chapter 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://www.linuxdoc.org/authors/tools/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> ]]> ]> Change the first "docbook.dsl" to read /usr/lib/sgml/stylesheets/nwalsh-modular/html/docbook.dsl 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
Distributing your documentation
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.
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.
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). We recommend using the GNU Free Documentation License (GFDL) or the Open Publication License (OPL) without options A and B. If you choose, you can get DocBook markups up both the GNU GPL and the GNU FDL from the GNOME Documentation Project. You can then merely include the license in its entirety in your document. Due to its length, you may just want to provide a link to the source. If you choose to use a 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.
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 submit@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 5 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. If you are using the LDP CVS tree while developing your document, the LDP will still need to be notified when your document is ready to be published. E-mail should be sent to submit@linuxdoc.org. Indicate the title of your document and the relative path to the file(s) in the LDP CVS tree within your message.
Maintaining Your HOWTO Just because your HOWTO has now been published doesn't mean your job is done. HOWTOs need regular maintenance, to make sure they are up to date, and to improve them in response to readers' ideas and suggestions. A HOWTO is a living, growing body of knowledge, not just a publish-and-forget-it static document. You put your email address in the HOWTO, and politely requested feedback from your readers, right? Once you are officially published, you will begin to receive notes with suggestions. Some will be very valuable; others will request personal assistance. You should feel free to decline personal assistance if you cannot spare the time. Writing a HOWTO for the LDP doesn't commit you to a lifetime of free support for anyone on the net. It is polite to refer questioners to another resource, if you can. And, if you see a pattern in the questions you receive, it might indicate a topic you should add to your HOWTO.
FAQs about the LDP 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 discuss@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 docbook@linuxdoc.org. &glossary; &doc-index;