Re: gnome-libs man pages.

[Telsa Gwynne <hobbit aloss ukuu org uk>]

On Thu, Jul 06, 2000 at 12:20:53PM -0700 or thereabouts, Derek Simkowiak wrote:
> -> But totally obsolete. Use DocBook.
> 
> 	Unfortunately, there aren't any easy-to-use, GUI-like DocBook
> creation tools available (that I'm aware of).  The author needs to know
> the tags, when and where to use them, and all the issues around SGML (or
> now, XML) document creation.  Then, you need a full-fledged development
> environment built around jade that will 'compile' it into HTML before you
> can even see whether or not it looks any good.

Hey, I'm a user, not a developer, and I can write DocBook with the 'joe'
editor :)

Braindump: 

I will totally agree that DocBook has a steep learning curve. I thought
hackers _liked_ that kind of thing and liked showing off how they could
just inhale new concepts: I was disgusted when it took me some months
to learn DocBook and it took a hacker I knew two days of poking at it
to learn it, write in it, and find and partially fix a jade problem. 
I hate hackers at times, I do...

The most promising GUI thing for DocBook stuff I saw was Conglomerate,
which appears to be on the backburner for a bit and is certainly not
in a state where you could use it to create DocBook files yet. Pah.
(Sorry, Joakim!)

On the other hand, in the making-hackers'-lives-easier-if-it-gets-docs
stakes, I will cheerfully attempt (attempt) to mark up docs which are 
provided in ASCII or something else I can read. I can do user-level
docs, and I have marked up a couple of more technical things in the
past: I had a hand in polishing some of the DocBook things in the more
recent Linux kernels, which use such esoteric-to-me tags as (gasp) 
<function>, <structname> and other such scary concepts, and no-one
has complained yet.

But I will be slow: I am horribly busy. I have to tidy up some old
docs, mark up some others I promised to turn into DocBook, finish
some docs I promised other people and projects, and write an article
about an introduction to DocBook so that everyone else can do it
instead :) Also, we're moving house and I'm going to be away from
the keyboard a lot in the near future as a result. I need to unblock
some drains...

Other people will also mark up docs: the Open Source Writers' Group
has a list of volunteers and a specific category in that list is
"mark-up specialists". It's quite long :) You might even find the
other Gnome Documentation Project folks haven't enough to do (says
she, fearlessly volunteering other people before vanishing).

And once you've seen the before and after of plain ASCII to DocBook,
it becomes a lot clearer. Honestly. 

	http://www.oswg.org 
		...is the OSWG.
	http://www.oswg.org/oswg/query/view_markers 
		...is the list of people who have offered to mark things up. 
	http://www.gnome.org/gdp/ 
		...is the GDP.

> intelligently.  So all the docs need to be converted to HTML before
> they're really usable in an app anyhow.

This gets done in several of the gnome packages as part of the
"turning CVS into a tarball for release" package. Jacob Berkman
appears to have this kind of thing worked out neatly: he had very 
definite opinions on where docs should be in CVS that made such 
building a lot easier on the packager. I recall this well :)

> it's very difficult for the beginner (read: endusers who are willing to
> document software) to get started.

Agreed. We have _tried_ to address that with the GDP Handbook, which is
a start at "how to get and install the packages and what to do with them
next" and a collection of sample templates (take 'em, alter titles to
your preference, insert text :)). http://www.gnome.org/gdp/ -- feedback
is very very welcome. 

And I know I am not the only person who is contemplating Yet Another
Intro To DocBook article. (Be afraid.)

> 	It would be nice if there were something like Netscape Composer
> that produced immediate visual results, along with a selectable library of
> tags to choose from...

If you're an EMACS user, half of this is addressed by the PSGML mode,
which will give you a choice of what tags are permissible at different
stages in the doc. It's tempting me to learn the editor just to use the
mode :) That helps with learning which tags live inside which other
tags. I suspect, however, that's not quite what you meant. Sorry.

One remarkable fact about the DocBook tools: I rarely break them.
Given my track record in breaking things (today's victim was the Gimp,
a stable version of which I can now crash at will), this is not too
bad :)

I haven't used it yet, but there is supposed to be a DocBook->man 
converter: there are certainly tags designed specifically for man
page output. So it does at least address the original question, if
I remember what you wanted in the first place.

Telsa