Re: More (sigh) questions: applet docs

[gnome-doc-list rascal org]

I think the first question about using sections has been covered pretty well,
it leaves three interesting points.

On Fri, Jan 28, 2000 at 01:26:09PM +0000, Telsa Gwynne wrote:
<SNIP>
> 
> <!ENTITY ch01 SYSTEM "ch01.sgm">
> <!ENTITY ch02 SYSTEM "ch02.sgm">
> <book>
> &ch01;
> &ch02;
> </book>       
> 
> But is that the intention here? Then how do I decide what to call
> the chapter? Just the name of the applet? In that case, will the
> same file do for the help in the applet itself, or does that have
> to have enough surrounding it for it to parse properly even in
> the absence of the other chapters? I would guess the latter.
> 

Whomever takes control of the 'applets' doc will have to make a Makefile with
some shell script to whack them all together.  If you look at the desktop docs
this it does something along these lines.  

More interesting is the possibility of dynamic help files depending on what
the user has installed since you would have to find the original sgml files
and then convert them.  I guess the app could tell the system what the name of
the helpfile/location was: you could register the names as part of the install
in some /etc file: or you could make a fixed path/namespace for the help file
names.  Anyway, I'll leave all that to the whomever is doing it though it is
an interesting idea!


> I do read stuff and try things, honestly, but I'm beginning to
> think it's just too complicated for me. 

Well I don't think anyone's worried and you're already pretty close to having
a release: like any development it's that old saw about the last 5% taking 50%
of the time :)

> 
> I was really looking forward to the documentation workshop at
> GUADEC to help me sort some of this out, but apparently that workshop
> is not happening now :(
> 

So was I: it's a pity so few external people were interested but hardly
suprising as docs has a bad name as being difficult to do and boring. We seem
to have more active documenters than a few months ago but need more, learning
more about how it all works sounded darned good to me.  

Hopefully a few people from the GDP and Translations will be at GUADEC, I
hope to be.  Perhaps we can have an informal meet to discuss docs and GNOME
while the developers hack??  Who else is going to be there?  Perhaps we can
grab whomever is going to develop the help browser to give us an idea about
it's capabilities so we'll be prepared, whose doing it anyway?

Steve 'blah' George