Re: New `gnucc.info' doc patch for gcc 2.95

[Jeffrey A Law <law at cygnus dot com>]

  In message <19990713185551.3292.qmail@deer>you write:
  > >Well, longer term we should be working towards a model where we do not
  > >have separate doc kits for each of the projects we've integrated.  ie,
  > >there should be a single doc kit for the project as a whole rather
  > >than a doc kit for gcc, g++, g77, libstdc++, cpp etc etc etc.
  > >
  > >At least that's where I think we should be going.
  > 
  > Hmm, it's certainly on one extreme end of the range of possible approaches.
  > It has the advantage of resulting in the smallest amount of *total*
  > documentation.
  > 
  > The downside is that it means it's much harder to design the document
  > structure so users can quickly and easily find the information they
  > want, e.g. if they're just g77 users.  And printing the manual can
  > become infeasible, especially as an official "book", if the size gets
  > sufficiently large.
But the opposite case -- separate doc sets with no consistent format, 
duplicated
or contradictory information, no good way to navigate between info
for the various projects, etc etc sucks in a major way.  I would claim 
finding information right now is nearly impossible to the novice user because
the basic information is scattered through 6 different manuals (gcc, g77, cpp,
chill, g++, libstdc++).    Even if you just think about options one can pass
to the compiler we've got 3 manuals! (gcc, g77, chill)  That's 100% braindead.


Remember what we've done, we've taken multiple projects and merged them
together from a technical standpoint, but we've done nothing to merge the
documentation presented to users, developers or installers.

If we do our job right, I don't think we're going to run into problems 
printing manual.  The first thing to remember is we want to organize docs
based on audience -- ie, the poor bastard installing the system, the guy
who uses it daily for development and the weirdos that actually hack the
internals.  Those should be three separate books/kits (if we really must,
we could find a way to bind them all together for bulk printing, but I think
that's a step in the wrong direction).


  > Indeed.  The current approach is probably best described as throwing all
  > the info we have into the new document, worrying about just how and where
  > to sort it all out later, on the theory that more, even disorganized,
  > information is better than not having the information at all.
I'm not sure I totally agree.  In many ways, we're taking a problem and making
it worse by adding yet another place one might need to go to find info.

  > >Good question.  I think the answer depends on how we plan to build the
  > >project's documentation long term.  Will we have a toplevel doc kit
  > >which includes .texi files from the subdirs, or will we move all doc stuff
  > >into the toplevel doc directory?
  > 
  > One thing to keep in mind is that some .texi's are derived from *source
  > code* of the components.  g77's intdoc.texi is an example of this.
Good point.

  > I suspect it'll be best, overall, to make the doc-building infrastructure
  > parallel whatever the front-end/library infrastructure looks like for
  > adding/deleting components, automatically configuring and building them,
  > etc.
That argues that we keep the bulk of the info in their current locations.
Probably the only thing that needs to break out from that model would be
the installation instructions.


  > One that comes to mind is "if Fortran is disabled, should the documentation
  > contain the Fortran information anyway?".  (The question pertains to
  > what *should* happen, not what is convenient, what will, what we as
  > developers want, but what we think the *field* wants, first and foremost.)
  > Another is "is the ability to selectively disable/enable components
  > in the *docs*, independently of the corresponding configure/build decisions
  > important?"
If a language is disabled (or not available), docs for that front-end and its
associated runtime should not be included.  Remember, some folks just pick up
a subset of the languages and the doc build procedure needs to gracefully
handle that.

This structure also argues that the bulk of the doc info stay within the
language subdirectories, probably in texinfo source files that can be
conditionally included.

I do not think we need/want the ability to selectively disable/enable doc
sets independently of the languages we select.


  > Agreed.  For now, though, it might be helpful to readers to provide at
  > least basic @xref's in each of the existing manuals to the new one, as
  > a sort of "in the meantime, here's some extra info on the overall GCC
  > project you might find useful".  It could go into, e.g., g77's
  > "What is GNU Fortran?" node, or "Invoking g77", or something like that,
  > for each document in GCC.
I've got no problem with that.  I just wanted to make sure we didn't get 
carried away until we had a clue about the overall structure we want.



jeff