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

[craig at jcb-sc 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.

Oh, indeed.  At first, while writing my email, I thought you were talking
about a *single* document for the entire project, but I've since realized
you probably meant a single document for each type of user *activity*
(developing/porting vs. installing vs. using; not sure where ABI, multlib,
and similar issues fit in offhand, but that's in the details).

I agree, a single document on, say, *using* all of GCC wouldn't be a bad
approach, given its advantages.

Something to keep in mind, though, is that if you're thinking this gives
the user *one* document he needs for his *work*, drop that idea right
away!

Think about it.  To *use* gcc, say, the user must not only read *that*
manual, he must read manuals on using the shell, using make, interfacing
to all those other libraries, and so on.

So while I agree the navigation issue is important, let's make sure
we keep our focus on fitting it into the overall issue of navigating
between documents that are, *appropriately*, made and maintained
separately.  If GNU's Info format, for example, isn't up to that task,
we have *no* choice but to fix *that*, since we'll never be able to
offer a single manual that covers what a gcc, or g77, user really needs.

Further, I think it's important to design into this document architecture
an allowance for each front end's *language reference* manual to be
a separate document.  These manuals *should*, ideally, change less often,
and sometimes according to a very different schedule, than documentation
on how the *compiler* works.  And they *should* grow to a much larger
size over time (certainly true of g77's anyway, which has only the most
sketchy information on what "GNU Fortran" actually is).

Again, that indicates a need to solve the navigation problem.

However, I suspect the navigation problem you see isn't intrinsic to
GNU Info, just to how GCC itself happens to put together (or, "not" ;-)
the doc formats in its current form.

I think it's *very* tempting to at least put all the command-line-option
information together, as an example.  On a case-by-case basis, I suspect
we could agree that most such aspects of the docs would, by being grouped
together into a GCC-wide document, offer far more advantages than
disadvantages.

So, though I can think of an exception or two (language-reference
info) that might not fit quite so easily into this mold, and would
thus suggest nobody get *too* excited about "One True GCC Manual" as
a worthwhile goal, I *do* think that, after a reasonably thorough
analysis of the audience, plus editorial and maintenance issues,
we'll have a fairly clear picture as to what a "master GCC manual"
should contain.

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

Well, yes, but that avoided the problem of figuring out where the information
belong in the gcc, g77, and other manuals (at least one front end doesn't
*have* a manual!), then reproducing it in each of those.

And, conceptually at least, this *new* place is worth considering as the
"launching-point" into those several GCC-wide manuals you're thinking
about, so while it represents "yet another place" to find info, it
could end up being *the* place to start for *all* GCC info.

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

By "bulk of the info", I assume you mean ".texi files and related stuff",
rather than .info files -- for a GCC-wide manual that covers all the
front ends and libraries, the .info files need to be in a single location.
(Just as the worker-bee executables like cc1, cc1plus, f771, etc., end
up in a single location, prior to install.)

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

I'd tend to agree.

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

Yup.

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

Ditto.

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

Oh, I definitely agree.  Are you think of adding the bare-bones @xref's
in the context of 2.95?  I mean, thinking of someone like *me* adding
them, in which case I'd be glad to help?

        tq vm, (burley)