Re: Proposal for GNOME Developers' Guide

[John R Sheets <dusk smsi-roman com>]

Federico Mena Quintero wrote:

> As people have already said, the front
> end/back end division for gnome-libs is not very clear, but that is
> not an issue.

Agreed.  I've already changed it.

> I am a bit confused about your "Inside GNOME Applications" book.  Is
> it intended to contain documentation on each program's internals and
> how to extend them using the Baboon components they define?  I.e. if
> Gnumeric provides a spreadsheet component, would the book describe how
> to use it?

Well, I'm the first (or apparently the second) to admit that my ideas for
the Applications book are still a little hazy.  Your questions give a
pretty clear account of the scope I was intending.  Each App book should
describe the internal structure & mechanisms used by the application, and
any specialized usage of common libraries (e.g. how the word processor
uses special features of gnome-xml to store its data).  After reading an
App book (plus any other applicable GNOME books), a developer should be
able to leap right into the app and help intelligently to co-develop it.
It's a quick ramp up.

And yes, any Baboon components created with/for the app should be included
here, too.  Common Baboon components used by a number of applications
should probably be described in the main GNOME docs (i.e. not repeated in
a number of App books).

> If that is the case, I would prefer to have a separate book for each
> application -- this is just an organizational issue.

Agreed.  I can't think of a single case where you'd want to combine apps
together in the same grouping unit (whether it's by chapter or by book).
Making each app a separate book would also give us more flexibility within
DocBook.  Should we consider making the Application Books a separate Set
from the GNOME Developers' Guide (GDG)?  Perhaps a GNOME Applications
Developers' Guide(GADG).

But then, I don't know how hard it would be to connect two book-sets
together.  Mark G, do you have any thoughts here?  The Set is the highest
DocBook tag level, right?  Is it possible to directly reference or include
things across Sets?  Would we even _need_ to link these two (GDG to
GADG)?  If we wanted to render them both as a single ps file (ack!) or
HTML site (eh, maybe), they would probably have to be under the same Set.
Right?  Any other reasons, or am I totally off my whack?

> I would appreciate it if you could look into how to make it easy to
> integrate all the documentation together, as far as the different
> modules are concerned.  The way I am imagining it is that a toplevel
> developer's documentation module would contain the basic bookset
> information (the "set" tag).  However, I have no idea of how to plug
> in the different parts of the documentation if they come from
> different cvs modules.  I.e., how would Gnumeric or Gnomecal integrate
> their own developer's docs into the main framework?  I don't know what
> is the usual practice for dealing with this in DocBook.

As I understand it, as long as you have a path to the sgml file, you can
reference it as an external entity.  As long as all the SGML doc files get
installed into a sane tree, we should be okay here.  (I'm guessing...)

A quick install-related question: When does db2html usually get run (errr,
does it?)?  Before or after 'make install'?  If it's before, then we may
have a problem.  We can't guarantee that the developer/administrator is
going to compile every package in the same directory tree.  This means we
may not be able to find, e.g. gnumeric's docs if they compile it in
~/gnome/apps/ instead of ~/gnome/ where they compiled the rest.  But if
the stylesheets aren't run until after the files are installed in a common
place, we can probably count on them being there.  Or am I, once again,
totally off whack?

John

P.S.--I apologize for all the babbling.  My babble ratio is inversely
proportionate to my understanding of a given problem.  (c: