Hello,

I wonder whether docbook is still regarded as one of the most
appropriate
tools for authoring software documentation such as user manuals under
Linux
and other operating systems or whether some people have other
preferences.
An up to date docbook manual describing the latest changes of docbook
can
be found at the following site:

http://docbook.org/tdg/en/html/docbook.html

Particularly interesting is the section entitled

II. Reference

which lists all XML elements which may appear inside a DocBook
XML application. Perhaps XML's popularity may even boost usage
of DocBook among users for preparing documentation.

Under Fedora Core 1 (FC1) RedHat Linux using DocBook can be as simple
as:

$ vim manual.xml # vim supports DocBook syntax highlighting
$ cat manual.xml
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<article>
<articleinfo>
<title>User Manual</title>
<author><firstname>Foo</firstname><surname>Bar</surname></author>
</articleinfo>
<para>This manual...</para>
<sect1><title>On the Possibility of Foobaring</title>
<para> ... </para>
</sect1>
</article>
$ xmllint manual.xml --valid --noout # check XML DocBook document
against DTD
$ DBSS=/usr/share/sgml/docbook/xsl-stylesheets # DocBook Style Sheets
$ xsltproc -o manual.xhtml $DBSS/html/docbook.xsl manual.xml
$ mozilla file:`pwd`/manual.xhtml

All in all, the idea behind DocBook seems neat. However, there are
often some
multitude of elements and attributes to choose from, and sometimes it
may not
even be clear what the difference is between one and the other unless
xsltprc
is run on the XML DocBook source file. It would be nice if some text
editor
had the capability of reading a DTD and then allowing the user to
circulate
using the TAB or other key through the list of valid
elements/attributes
that may be nested within some element or for some element, according
to
the given DTD. This would be in addition to providing syntax
hilighting,
at which vim already seems to do a good job. Anyone know of such an
editor or how to enable such a DTD based suggestions feature in an
existing editor by issuing some obscure editor command?

Thanks,

Neil

On 22 Feb 2004 17:58:50 -0800, Neil Zanella <nzanella@cs.mun.ca> wrote:

You might post this on comp.editors

AC

The world rejoiced as Alan Connor <zzzzzz@xxx.yyy> wrote:
Only if you're STUPID. That is a newsgroup for discussions of text
editors, such as vi and Emacs.

comp.text.sgml and comp.text.xml would be vastly more appropriate,
albeit not being newsgroups relevant to Linux usage.

Reality is, of course, that numerous software projects that deploy on
Linux and other operating systems use DocBook either in its XML or
SGML forms. GNOME and KDE use it; OpenOffice.org has an add-on module
for exporting in DocBook form.

Speaking of Linux, itself, its documentation comes in two forms:

- The Documentation tree contains

Yes, DocBook certainly is one of the most suitable formats for
authoring software documentation. There are five other plausible
formats:
1. Man pages (*roff)
2. Raw text
3. HTML
4. Info
5. TeX or LaTeX

DocBook is likely more suitable than any of these...
--
select 'cbbrowne' || '@' || 'cbbrowne.com';
http://www3.sympatico.ca/cbbrowne/docbook.html
"... The book [CLtL1] is about 400 pages of 8.5" by 11" Dover output.
Apparently the publisher and typesetter decided that this made the
lines too wide for easy reading, so they will use a 6" by 9" format.
This will make the shape of the book approximately cubical. Now,
there are 26 chapters counting the index, and a Rubik's cube has 26
exterior cubies. I'll let you individually extrapolate and fantasize
from there." -- GLS

On 23 Feb 2004 03:16:56 GMT, Christopher Browne <cbbrowne@acm.org> wrote:

You've got the score I give ignorant assholes.

The OP should be VERY careful about taking any advice from you.

I don't even read your stupid posts anymore.

Nor am I alone in this.



(the rest deleted unseen)

--
ed(1) Check out the original tutorials by Brian W.
Kernighan at the Ed Home Page http://tinyurl.com/2aa6g

Alan Connor <zzzzzz@xxx.yyy> writes:

Would it be to much to ask that you not reply to them either? Since
you're not reading them and all.

TIA

On Mon, 23 Feb 2004 04:35:04 GMT, Billy O'Connor <billyoc@gnuyork.org> wrote:


Nor will I read this one.

I <heart> ed, eater of trolls...


(the rest deleted unseen)

AC

--
ed(1) Check out the original tutorials by Brian W.
Kernighan at the Ed Home Page http://tinyurl.com/2aa6g

In <c1brb8$1gud48$1@ID-125932.news.uni-berlin.de>, on 02/23/2004
at 03:16 AM, Christopher Browne <cbbrowne@acm.org> said:

Google is your friend, as is your filter. You may as well plonk him
now and not wait for him to plonk you. Suggesting an inappropriate
group is fully in character for him.

--
Shmuel (Seymour J.) Metz, SysProg and JOAT

Unsolicited bulk E-mail will be subject to legal action. I reserve
the right to publicly post or ridicule any abusive E-mail.

Reply to domain Patriot dot net user shmuel+news to contact me. Do
not reply to spamtrap@library.lspace.org