From f69774e6986405862733d6832929aea75b09f2e7 Mon Sep 17 00:00:00 2001 From: markk <> Date: Tue, 6 Jun 2000 13:16:28 +0000 Subject: [PATCH] Brought style guide and tools into their own sections --- .../docbook/HOWTO-HOWTO/HOWTO-HOWTO.sgml | 1358 +++++++++++------ 1 file changed, 924 insertions(+), 434 deletions(-) diff --git a/LDP/howto/docbook/HOWTO-HOWTO/HOWTO-HOWTO.sgml b/LDP/howto/docbook/HOWTO-HOWTO/HOWTO-HOWTO.sgml index d145ab31..c5b31a13 100644 --- a/LDP/howto/docbook/HOWTO-HOWTO/HOWTO-HOWTO.sgml +++ b/LDP/howto/docbook/HOWTO-HOWTO/HOWTO-HOWTO.sgml @@ -2,392 +2,556 @@ [ ]> - -
+ +
HOWTO-HOWTO - v1.10 1 Jun, 2000 + v1.2 6 Jun, 2000 - Mark Komarinski + Mark F. Komarinski List the tools, procedures, and hints to get HOWTO authors up to speed and writing. - - - - - Introduction - - - - History - - - 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. - - - - - New versions - - - 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. - - - - - Comments - - - Comments on this HOWTO may be directed to the author (markk@linuxdoc.org). - - - - - Version History - - - v1.10 (Jun 1, 2000) - - - - - Ditched LinuxDoc informaiton. Everyone should be using DocBook by now. - - - - - Ditched mini-HOWTO information. Everything is now HOWTO format - - - - - - - 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. - - - - - - - Acknowledgements and Thanks - - - Thanks to everyone that gave comments as I was writing this. This includes Deb Richardson, Daniel Barlow, Greg Ferguson, Mark Craig and other members of the ldp-discuss 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. - - - - - - Background on 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, its 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's 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 lets 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. - - - - - The tools - - - In this section, I'll go over 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. - - - - Jade - - - Required unless you use openjade - 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. - - - - - OpenJade - - - Replacement for Jade - http://openjade.sourceforge.net/ - - - An extension of Jade written by the DSSSL community (see below for what a DSSSL is). Some applications require jade, but are being updated to support either software package. - - - - - DSSSL - - - Required - http://nwalsh.com/docbook/dsssl/db152.zip - - - 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 http://nwalsh.com/docbook/dsssl/db152d.zip. 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 that provides for a table of contents. - - - - - 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. - - - - - sgmltools-lite - - - Recommended - 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. - - - - - TeX - - - Optional - - - TeX (rhymes with blech!) is the markup language of choice for many, including those in the mathematics world. I still remember many Calculus exams that were written in TeX. It is also one of the first markup languages that is still around (the other being the *roff formats used in man pages). TeX actually follows some of the same concepts that SGML does. However, TeX renders its files into DVI (Device Independent) that can then be rendered into another format. Unfortunately, DVI can't be easily converted into anything other than printer languages (PostScript, PCL), making it hard to use to generate HTML. TeX is installed or is available with most Linux distributions. TeX is available on almost all distributions as LaTeX or TeTeX. Either should work for you. - - - Some of the tools use TeX to convert into PostScript and PDF, so you may need it installed if you want to render to those formats. You'll probably also need it to install LyX (see below). If you're not using LyX, PostScript, or PDF, you won't need TeX. - - - - - LyX - - - Optional - http://www.lyx.org/ - - - LyX provides the power of writing SGML with the ease-of-use of a regular word processor. It's not a WYSIWYG program, but more WYSIWYM (What You See Is What You Mean) application, since what you see on the screen isn't necessarily what happens after the SGML processor is done with it. The display that LyX provides is similar to, but not exactly like, what the output from jade would look like. However, it's close enough for you to see the flow of the document. Sections and subsections are numbered and put in bold, and different fonts are used to signify things like <code> or <url> tags. Most tags are hidden from the main LyX window while you edit, since LyX writes in TeX, then exports the TeX to SGML. - + + + + + 1.2 + Jun 6, 2000 + mfk + Brought style guide and tools into their own sections + + + + + + +About this HOWTO + + + +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 documentaiton, 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 +stablish 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. + + + + + + +Acknowledgements and Thanks + + +Thanks to everyone that gave comments as I was writing this. This includes Deb Richardson, Daniel Barlow, Greg Ferguson, Mark Craig and other members of the ldp-discuss 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. + + + + + +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, its 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's 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 lets 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'll +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. + + + + + +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/db152.zip + + +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 http://nwalsh.com/docbook/dsssl/db152d.zip. +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 that provides +for a table of contents. + + + + +LDP DSSSL + + +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. + + + + + +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 + + +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. + + + + +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. + + + + + +Editing tools + + +The following tools may be used to create, edit, or validate your HOWTO. + + + +LyX + + +http://www.lyx.org/ + + +LyX provides the power of writing SGML with the ease-of-use of a regular word processor. It's not a WYSIWYG program, but more WYSIWYM (What You See Is What You Mean) application, since what you see on the screen isn't necessarily what happens after the SGML processor is done with it. The display that LyX provides is similar to, but not exactly like, what the output from jade would look like. However, it's close enough for you to see the flow of the document. Sections and subsections are numbered and put in bold, and different fonts are used to signify things like <code> or <url> tags. Most tags are hidden from the main LyX window while you edit, since LyX writes in TeX, then exports the TeX to SGML. +
LyX screen shot - + + + + + +Screen shot of the LyX document processing program +
- - - Emacs (PSGML) - - - Optional - http://www.lysator.liu.se/~lenst/about_psgml/ - - - Emacs has an SGML writing mode called psgml. Anyone with experience writing in this mode is welcome to e-mail the author of this document. psgml is a major mode in Emacs designed for editing SGML and XML documents. It provides "syntax highlighting" or "pretty printing" features that make SGML tag 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. - - - - - WordPerfect 9 (Corel Office 2000) - - - Optional - 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. - - - - - DocBook: The Definitive Guide - - - Optional (but recommended) - 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 at the above URL. - - - - - 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 spellcheck the tags, causing errors at every new tag. - - - - - Cygnus DocBook Tools - - - Optional (may be Red Hat specific) - http://www.redhat.com/ - - - Red Hat distributes three packages, possibly starting with 6.2, that include DocBook support and some tools. They provide for only rendering to HTML and PDF, but they're easily installed if you have Red Hat, allowing you to focus more on writing than wrestling with the tools. TeTex 0.9, Jade, and Jadetex must be installed first. - - - - - - - Getting Started with DocBook - - - This section covers the new method of writing LDP documentation, using the DocBook 3.1 DTD. We'll cover getting, installing, and using tools, along with an introduction to DocBook tags. Since there are over 300 DocBook tags, we won't cover them all here. Really interested readers can go to http://www.docbook.org for more information. - - - - 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. Also note that all HOWTO submissions must be in SGML format using the DocBook 3.1 DTD. Mini-HOWTOs are no longer being accepted, but are being converted into full HOWTOs. - - - - - 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. - - - - - Downloading and installing the tools - - - - Manual using jade/openjade - - - 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 form 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/dssl) - - - - - 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: $ENV{'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. - - - - - - - sgmltools - - - Unlike previous versions of sgmltools, you will require sgmltools version 2.x for use with DocBook. Since the backend programs have all changed, you'll also need to forget the sgml2xxx style of programs (sorry). Since some major distributions ship with sgml 1.x, you'll need to remove the sgml 1.x package and install either a 2.0 version, or a CVS version. To get the latest CVS source code version, you can use the following set of commands: - - + + +Emacs (PSGML) + + +Optional - http://www.lysator.liu.se/~lenst/about_psgml/ + + +Emacs has an SGML writing mode called psgml. Anyone with experience writing in this mode is welcome to e-mail the author of this document. psgml is a major mode in Emacs designed for editing SGML and XML documents. It provides "syntax highlighting" or "pretty printing" features that make SGML tag 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. + + + + +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. + + + + +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. + + + + + +Other/Reference + + +The items in this section are reference books or other utilities that can't +quite be catagorized (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. + + + + +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 spellcheck the tags, causing errors at every new tag. + + + + + + +Getting Started with DocBook + + +This section covers the new method of writing LDP documentation, using the DocBook 3.1 DTD. We'll cover getting, installing, and using tools, along with an introduction to DocBook tags. Since there are over 300 DocBook tags, we won't cover them all here. Really interested readers can go to +http://www.docbook.org for more information. + + + + +Downloading and installing the tools + + + +Manual using jade/openjade + + +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/dssl) + + + + +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. + + + + + + +sgmltools + + +Unlike previous versions of sgmltools, you will require sgmltools version 2.x for use with DocBook. Since the backend programs have all changed, you'll also need to forget the sgml2xxx style of programs (sorry). Since some major distributions ship with sgml 1.x, you'll need to remove the sgml 1.x package and install either a 2.0 version, or a CVS version. To get the latest CVS source code version, you can use the following set of commands: + + bash$ CVSROOT=:pserver:cvs@cvs.sgmltools.org:/home/cvs bash$ export CVSROOT bash$ cvs login bash$ cvs -z6 get sgmltools - - - The CVS password is 'cvs'. Once downloaded, You can just use - - + + +The CVS password is 'cvs'. Once downloaded, You can just use + + bash$ ./compile bash$ make -bash$ make install - - - to install sgmltools. For Red Hat-based systems (using RPM) you can use the rpmfind command to get the latest sgmltools. The rpmfind program is available at http://www.rpmfind.net/. Make sure you get sgmltools and not sgml-tools, as the latter is sgml-tools 1.0.9. For Debian-based systems, apt-get will retrieve the right package for you: +bash# make install + + + to install sgmltools. For Red Hat-based systems (using RPM) you can use the rpmfind command to get the latest sgmltools. The rpmfind program is available at + http://www.rpmfind.net/. Make sure you get sgmltools and not sgml-tools, as the latter is sgml-tools 1.0.9. For Debian-based systems, apt-get will retrieve the right package for you: bash# apt-get install sgmltools @@ -424,7 +588,7 @@ bash# apt-get install sgmltools Red Hat has the latest version on their web site: http://www.redhat.com/support/errata/RHBA-2000022-01.html. - Download/get/sneakernet 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: + Download/get/sneakernet 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 @@ -445,8 +609,22 @@ bash$ db2pdf filename Writing SGML by hand - Must of this is covered by Jorge Godoy's Using DocBook document. Those interested can read it at http://metalab.unc.edu/godoy/using-docbook/using-docbook.html for writing DocBook using your favorite text editor. + Must of this is covered by Jorge Godoy's Using DocBook document. Those +interested can read it at + +http://metalab.unc.edu/godoy/using-docbook/using-docbook.html +for writing DocBook using your favorite text editor. + + If you write SGML by hand + + SGML has over 300 tags, and uses tags much more heavily than HTML. It's +recommended that you use an existing HOWTO as a template and see how +other authors have written. It's also recommended that you use a user-friendly +editor like PSGML or WordPerfect for Windows, as it lists many of the tags +that are available. + + @@ -457,10 +635,25 @@ bash$ db2pdf <emphasis>filename</emphasis> New documents - You can easily start a new HOWTO using LyX. Use the File->New from template... menu command to bring up the template listings. Select Templates on the right side of the screen, then select docbook_template.lyx in the file listing. Select OK, and you'll have a new document. Fill in the items, such as title, abstract, and author name, then start writing. + You can easily start a new HOWTO using LyX. Use the + + File + New From Template... + +menu command to bring up the template listings. Select Templates on the right side of the screen, then select docbook_template.lyx in the file listing. Select OK, and you'll have a new document. Fill in the items, such as title, abstract, and author name, then start writing.
DocBook Template screen from LyX - + + + + + + + + +You can select the docbook_template.lyx here + +
@@ -468,10 +661,30 @@ bash$ db2pdf filename Existing documents - If you have an already-existing LyX, TeX, or text document, you can import it into LyX with the File->import command. Once the file is imported, go to Layout->Document... In the popup window, under Style, select SGML (DocBook Article). You'll be asked if you want to convert all text over, and say Yes. You will need to reapply most tags, but it's a fairly simple matter of selecting text and changing the style. Many LyX functions have a keyboard shortcut to assist you. + If you have an already-existing LyX, TeX, or text document, you can import it into LyX with the + + File + import + + command. Once the file is imported, go to + + Layout + Document... + + In the popup window, under Style, select SGML (DocBook Article). You'll be asked if you want to convert all text over, and say Yes. You will need to reapply most tags, but it's a fairly simple matter of selecting text and changing the style. Many LyX functions have a keyboard shortcut to assist you.
Document Layout screen - + + + + + + + + +Image of the Document Layout Screen from LyX + +
@@ -479,7 +692,13 @@ bash$ db2pdf filename Exporting documents to SGML - Once your document is written or converted, save it in LyX format. This will allow you to edit future versions easily. Then, go to File->Export->as DocBook... and the file will be exported in DocBook. + Once your document is written or converted, save it in LyX format. This will allow you to edit future versions easily. Then, go to + + File + Export + as DocBook... + + and the file will be exported in DocBook. @@ -492,7 +711,15 @@ bash$ db2pdf filename 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-h i m psgml). + 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 + h + +i +m +psgml +). 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/. @@ -515,15 +742,86 @@ 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 sections (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. ;; ******************************************************************* +;; ******************************************************************* +;; 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 @@ -544,7 +842,16 @@ bash$ export SGML_CATALOG_FILES=/usr/lib/sgml/catalog ]]> - Enter C-c C-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: + Enter + + C + c + + + C + 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: ]]> - Enter C-c C-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. + Enter + + C + c + + + C + 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-c C-e RETURN to insert an <article> element and proceed to write your HOWTO. + At this point, enter + + C + c + + + C + e + +RETURN + to insert an <article> element and proceed to write your HOWTO. @@ -583,7 +909,196 @@ bash$ export SGML_CATALOG_FILES=/usr/lib/sgml/catalog - + + + 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. + + + + 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. + + + + + + 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 + + + + +DocBook release + + +The DocBook version used by the LDP is version 3.1. In order for your SGML +to work with the LDP tools, your header must look like this: + + +<!doctype article public "-//OASIS//DTD DocBook V3.1//EN"> + + + + +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><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 +rabitrary 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 +alpha-numeric 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 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 +toolset. + + +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 this to read /usr/lib/sgml/stylesheets/nwalsh-modular/html/docbook.dsl + + + + +Change this 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 -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're going to something like RTF, you can do this: + + +bash$ jade -t rtf -d /usr/lib/sgml/stylesheets/ldp.dsl HOWTO-HOWTO.sgml + + + + CVS @@ -638,10 +1153,10 @@ bash$ export SGML_CATALOG_FILES=/usr/lib/sgml/catalog 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 put_your_password_here | perl -e "print crypt(<>, join '',('.', '/', 0..9, 'A'..'Z', 'a'..'z')[rand 64, rand 64]),\"\n\"" +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 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: + Take the output of this command, and send it with your proposed userid to cvsadmin@cvslist.linuxdoc.org. Your unique CVSROOT 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 @@ -663,9 +1178,6 @@ bash$ cvs get LDP bash$ cvs get howto/YOUR-HOWTO.sgml bash$ cvs get minihowto/YOURDOC.sgml - - Also available is The Commit List, which is an e-mail sent for each change anywhere in the repository. Note that this is a high-volume list. You can subscribe by sending an empty e-mail to commits-subscribe@cvslist.linuxdoc.org. You can unsubscribe by sending an empty e-mail to commits-unsubscribe@cvslist.linuxdoc.org. - @@ -707,17 +1219,17 @@ bash$ cvs -d :pserver:cvs@anoncvs.linuxdoc.org:/cvsroot login Updating files and CVS - CVS has a special tag that you can use to automatically insert the date and version directly into the document. This is called $Id$. 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. + CVS has a special tag that you can use to automatically insert the date and version directly into the document. This is called $Id$. 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. + 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. - + Distributing your documentation @@ -742,7 +1254,7 @@ bash$ cvs -d :pserver:cvs@anoncvs.linuxdoc.org:/cvsroot login Validate your SGML code - Using sgmltools, or really the nsgmls command, you can validate your .sgml code against the DTD to make sure there aren't any errors. + 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 @@ -765,52 +1277,19 @@ bash$ nsgmls -s HOWTO-HOWTO.sgml Submission to LDP - Once your LDP document has been reviewed by a few people and you took into account their comments, 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. + Once your LDP document has been reviewed by a few people and you took into account their comments, 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. - - - - 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. - - - - Date formats - - - The <date> tag in your header should be in the following format: - - -v1.0, 21 April 2000 - - - - - 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 - - + +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. + - + FAQs about the LDP @@ -835,7 +1314,18 @@ tcsh# setenv DISPLAY :0.0 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.organd mention the problem and how you think it needs to be fixed. + Contact the author of the document, or the LDP coordinator at ldp-discuss@lists.linuxdoc.organd 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.