docbook: Re: How to create a HOWTO on Red Hat Linux 9?
Subject:
Re: How to create a HOWTO on Red Hat Linux 9?
From:
Tabatha Marshall ####@####.####
Date:
20 Oct 2003 21:38:13 -0000
Message-Id: <1066686098.6956.54.camel@mysticchild>
On Sun, 2003-10-19 at 18:54, Rodolfo J. Paiz wrote:
> Should I somehow switch this thing to Linuxdoc, or where can I find a
> Docbook quick-reference guide or tutorial that will get me off the ground?
> Between Linuxdoc and Docbook, is there a "better" choice for me? For
> documents which could eventually be submitted to the LDP for inclusion? For
> Linux documentation in general? I want to write nice, clean, clear,
> well-documented code with no bugs... but I don't have much (or any) real
> experience at this and I guess I need a little primer or help to get started.
>
> Comments on the errors? Choice of Linuxdoc/Docbook? Anything?
Hi Rodolfo,
I know how frustrating it can be to figure all this out. Let me start
by saying there are some widely differing opinions on which flavor of
markup to use. Linuxdoc has benefits in that it's easy to learn,
doesn't require strict usage (such as closing tags) that DocBook does.
On the other hand, DocBook has a larger variety of tags to choose from
and inserts images well. Many say DocBook is bloated with tags, but I
consider it variety.
THE definitive guide on DocBook is at:
http://www.docbook.org/tdg/en/html/docbook.html
This lists all the tags and their usage. Now when I was new at this,
that list was all fine and dandy, but I was still a little lost. I run
RH8, and the authoring tools were already installed. Since you're
running RH9, the tools are most definitely there. Which means that you
have Emacs and Xemacs, and you probably have the PSGML plugin installed
as well. The Xemacs editor is the one I like to use, and with the psgml
plugin, you get additional menus to work with the markup. It can
highlight them, and though it has a validator (which I find to be
gimpy), there's this nifty menu command called "Find next trouble spot,"
which automatically moves to an error in markup syntax. You can even
find out which tags are valid from anywhere in your document with one
drop-down menu command (list valid tags).
Now, all of this of course means DocBook. But there are still 2 flavors
of DocBook to consider: SGML and XML. I prefer XML, because it's
everything that SGML is, but with one extra line at the top. You can
take a look at the source for any recent HOWTO written in XML and see
how simple it is. XML is supposedly the hot thing right now, which is
why I use it instead. The Openjade tools are great for processing with
dsl files, and the xslt tools are good for using xsl files (those are
the stylesheets - dsl for SGML, and xsl for XML).
The LDP supports all of them: Linuxdoc, DocBook SGML and XML. I like to
see new docs come in as XML, and some of us are even willing to
volunteer our time to help you convert your text to XML if you need
help, but it sounds like you want to give this a try on your own, and I
think that's a good idea. Then it will take out the mystery for you.
If you don't think you need everything DocBook offers, we have
documentation at the LDP for working in Linuxdoc too (see link below).
The LDP has many guides on the subject of authoring tools, if I haven't
already got that covered for you. Try this link for a full list of what
we've got: http://www.tldp.org/HOWTO/HOWTO-INDEX/misc.html#MISCAUTHOR
I'll leave you with all that to chew on, and if you have any other
questions, feel free to contact me off-list.
Tab
--
Tabatha Marshall
Web: www.merlinmonroe.com
Linux Documentation Project Review Coordinator (http://www.tldp.org)
Linux Counter Area Manager US:wa (http://counter.li.org)
