Conectiva S.A.'> ]> 2002-04-25 Mark F. Komarinski

mkomarinski@wayga.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. 4.0 2003-08-13 ejh Revised the structure of the document and shuffled elements into place. 3.15 2002-12-16 gjf Contribution by Jaime Irving Davila regarding ldp.dsl usage. 3.14 2002-05-16 mfk Added information about LDP Reviewer HOWTO. New reviewers are asked to read this document. 3.14 2002-04-25 gf Update meta-data information, resources; add articleinfo content &aboutthisguide; &authoring-overview; &authoring-proposal; &authoring-writing; &tools;

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

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.

Optional - http://www.tldp.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. Also contains links to tools and other useful information.

Optional - http://aspell.sourceforge.net/ This spell checking application can work around SGML tags, and only spell check the content within the tags. Older version of ispell will try to spell check the tags, causing errors at every new tag.

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; This section contains additional style-oriented topics to consider when preparing your document.

The pubdate tag in your header should list the publication date of this particular version of the document (coincide with the revision date). It should be in the following format: pubdate2002-04-25pubdate The date is in the format YYYY-MM-DD, which is one of the ISO 8601 standard formats for representing dates. For you Yanks out there (me too), think of it as going from the largest unit of time to the smallest.

The revhistory tag should be used to denote the various revisions of the document. Specify the date, revision number and comments regarding what has changed. Revisions should be listed with the most-recent version at the top (list in descending order).

Here is a sample of a complete DocBook (SGML or XML) articleinfo element which contains some of the items and constructs previously described. <articleinfo> <!-- Use "HOWTO", "mini HOWTO", "FAQ" in title, if appropriate --> <title>Sample HOWTO</title> <author> <firstname>your_firstname</firstname> <surname>your_surname</surname> <affiliation> <!-- Valid email...spamblock/scramble if so desired --> <address><email>xxx (at) xxx.xxx</email></address> </affiliation> </author> <pubdate>2002-04-25</pubdate> <revhistory> <revision> <revnumber>1.0</revnumber> <date>2002-04-25</date> <authorinitials>xx</authorinitials> <revremark>first official release</revremark> </revision> <revision> <revnumber>0.9</revnumber> <date>2002-04-15</date> <authorinitials>xx</authorinitials> <revremark>first draft</revremark> </revision> </revhistory> <!-- Provide a good abstract; a couple of sentences is sufficient --> <abstract> <para> This is a sample DocBook (SGML or XML) HOWTO which has been constructed to serve as a template. </para> </abstract> </articleinfo>

When submitting graphics to the LDP, please submit one set of graphics in .eps, and another in .gif, .jpg or .png. The preferred format is .png or .jpg due to patent problems with .gif. You can use .jpg file for continuous-tone images such as photos or images with gradual changes in color. Use .png for simple images like diagrams, some screen shots, and images with a low number of colors.

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"

Some tags listed in DocBook: The Definitive Guide may be listed as being discarded in future revisions of DocBook. To maintain future compatability, the LDP recommends against using tags that will be discarded in the future. Some ways to use newer tags are listed in the tip and tricks section.

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

This section covers a few quirks of DocBook that you may run into when writing your documents.

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 HTML alt tag.

By default, when separate HTML files are made, the SGML processor will assign arbitrary names to the resulting files. This can be confusing to readers who may bookmark a page only to have it change. Whatever your reasoning, here's how to make separate files named the way you want: 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. A name should include only alphanumeric characters, and it should be short enough to understand what it is. chapter id="tips"

&using-ldp-dsssl; &using-ldp-xsl;

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 factual correctness. You can also ask for general comments. The documentation that is published by the LDP needs to be as factually correct as possible, as there are millions of Linux users that may be reading it. If you're part of a larger mailing list talking about the subject, ask others from the list to help you out. 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.

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.

Validating XML is a touch harder than validating SGML code, but it can be done. You will need to have XML DocBook installed, and then set the SGML_CATALOG_FILES to the location of xml.soc (included with jade) and to the location of the DocBook XML catalog file. bash$ export SGML_CATALOG_FILES=/usr/lib/sgml/declaration/xml.soc:/usr/lib/xml/catalog bash$ nsgmls -s HOWTO-HOWTO.xml

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.tldp.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 of 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 of 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 Author Guide requires notification to the author of any derivative works or translations. I also explicitly place any source code (aside from the SGML the Guide was written in) under the GPL. If your HOWTO includes bits of source code that you want others to use, you may do the same.

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@en.tldp.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 will not have to wait for your HOWTO to be updated on the LDP web site. If you don't hear anything in 5 calendar days, please follow up with an e-mail to make sure things are still in process. 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@en.tldp.org. Indicate the title of your document and the relative path to the file(s) in the LDP CVS tree within your message.

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.

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.tldp.org/manifesto.html#pub for more information about publishing LDP documents. I found an error in an LDP document. Can I fix it? Contact the author of the document, or the LDP coordinator at feedback@en.tldp.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 have questions, you can always drop a line to the LDP volunteer or the LDP Docbook list at docbook@en.tldp.org. &gfdl; &glossary; &doc-index;