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

[craig at jcb-sc dot com]

>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.

>What is not clear to me is what audience you intend this multilib information
>for.  Users shouldn't much care about this stuff except at a very high
>level -- they need to know that they should be using gcc/g++/g77 to link
>their programs and that they should pass any -m arguments that they used
>during the compilation to the link step too so that they will pick up any
>libraries specific to that -m option.

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.

>Also note that multilibs have been around for years.  What is different is
>libf2c, libobjc & libchill are multilibbed.  In the past only libgcc, libstdc++
>and newlib/libgloss were multilibbed.

Yep, I've certainly been unaware (in many important ways) of multilibs
having been around for so long.

>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.

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.

But the most important issues need to be figured out, then addressed, first.
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?"

>I would suggest against adding lots of xrefs at this time since I expect
>we'll want separate manuals based on the target audience.  Installation,
>user and developer guides.  We don't want to have a lot of xrefs to chase
>down betweeen the separate manuals.

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.

        tq vm, (burley)