Conditionalizing the GCC documents

Conditionalizing the GCC documents

[Bill Cox]

Hi Folks,

Our company wants to ship GCC docs only for the target
architectures that our customers use.  I'd like to submit
to the gcc/*.texi files to make the specific arch support
conditional like the GAS manual does.

Would such a patch set be welcome for the 3.1 branch?

Thanks in advance!

Re: Conditionalizing the GCC documents

[Stan Shebs]

Bill Cox wrote:
> 
> Our company wants to ship GCC docs only for the target
> architectures that our customers use.  I'd like to submit
> to the gcc/*.texi files to make the specific arch support
> conditional like the GAS manual does.
> 
> Would such a patch set be welcome for the 3.1 branch?

The GDB manual used to try to do this, but we scrubbed it out
a couple years ago.  The problem was not unlike that of that
conditionals in C source - unless you have somebody continually
testing that each combination of ifdefs still works, the
conditionals quickly bitrot and become unusable.  You can also
get into some very twisty situations that are beyond Texinfo's
ability to handle, and you have to replicate sections of text
just to get them to appear in the correct context for each
combination of conditionals.

And after all that, if you're successful, you'll end up with
a manual that purports to be the "GCC Manual", but is actually
a subset that doesn't mention what has been left out.  A subtle
form of censorship, in a way.

So I'd like to put in a vote not to go down that path.  If it's
that important to Wind River, then it should be possible for
you to maintain this as a local patch.

Stan

PS I don't like that the gas manual does it either...

Re: Conditionalizing the GCC documents

[Gerald Pfeifer]

On Tue, 26 Feb 2002, Stan Shebs wrote:
>> Our company wants to ship GCC docs only for the target architectures
>> that our customers use.  I'd like to submit to the gcc/*.texi files to
>> make the specific arch support conditional like the GAS manual does.
> So I'd like to put in a vote not to go down that path.  If it's that
> important to Wind River, then it should be possible for you to maintain
> this as a local patch.

I thought about this, and came to the same conclusion as Stan, so I
believe this should be kept a Window River-local patch.

(The crucial question for me, wearing my GCC maintainer hat, is ``How
does the FSF version of GCC benefit from such a change''?)

Gerald
-- 
Gerald "Jerry" pfeifer@dbai.tuwien.ac.at http://www.dbai.tuwien.ac.at/~pfeifer/

Re: Conditionalizing the GCC documents

[Laurent Guerby]

Gerald Pfeifer wrote:

> (The crucial question for me, wearing my GCC maintainer hat, is ``How
> does the FSF version of GCC benefit from such a change''?)

The ability of someone operating entirely on a GNU system
not to have to store and skip each time he/she is reading the manual all 
the info about
how broken proprietary systems are and what GCC does to
workaround their various problem.

Right now we have no way to produce a GNU documentation that does
not talk all over the place about proprietary systems.
Is it really what we want? As a RTEMS newbie user I might not want
to see piles of stuff about VxWorks just the stuff for my RTEMS target, 
so an option
to remove/select what I want is welcomed.

Also the ability of someone who is dedicating his/her time
to one architecture supported by the GNU system to have a tailored manual.
The GNU as developpers felt this was important,
may be we could follow their choice, or at least ask
their reason, and what were the maintenance costs and issues if any.

Same reasoning to get a readable manual for a limited set of 
architecture (ie
GNU/Linux and BSD on x86 and PowerPC).

It looks like someone is volunteering to provide
some useful work to the GCC project, as long as an easy "include all"
flag is set by default and the conditional system is general enough
and not VxWorks only I don't see on what ground we should reject it.

However, no strong opinions (at work we've been asking our
vendor for a long time to provide one manual with all our
platforms and not a manual per platform with one paragraph
difference amongst 200 pages :).

-- 
Laurent Guerby <guerby@acm.org>

Re: Conditionalizing the GCC documents

[Richard Earnshaw]

> On Tue, 26 Feb 2002, Stan Shebs wrote:
> >> Our company wants to ship GCC docs only for the target architectures
> >> that our customers use.  I'd like to submit to the gcc/*.texi files to
> >> make the specific arch support conditional like the GAS manual does.
> > So I'd like to put in a vote not to go down that path.  If it's that
> > important to Wind River, then it should be possible for you to maintain
> > this as a local patch.
> 
> I thought about this, and came to the same conclusion as Stan, so I
> believe this should be kept a Window River-local patch.
> 
> (The crucial question for me, wearing my GCC maintainer hat, is ``How
> does the FSF version of GCC benefit from such a change''?)

I wouldn't object to it being possible to do this, provided:

1) It was possible to build a manual with all optional sections in it
2) The default was to do that.

That would put the onus on people wanting to make cut-down manuals to keep 
the optional parts consistent.

R.

Re: Conditionalizing the GCC documents

[Stan Shebs]

Richard Earnshaw wrote:
> 
> > On Tue, 26 Feb 2002, Stan Shebs wrote:
> > >> Our company wants to ship GCC docs only for the target architectures
> > >> that our customers use.  I'd like to submit to the gcc/*.texi files to
> > >> make the specific arch support conditional like the GAS manual does.
> > > So I'd like to put in a vote not to go down that path.  If it's that
> > > important to Wind River, then it should be possible for you to maintain
> > > this as a local patch.
> >
> > I thought about this, and came to the same conclusion as Stan, so I
> > believe this should be kept a Window River-local patch.
> >
> > (The crucial question for me, wearing my GCC maintainer hat, is ``How
> > does the FSF version of GCC benefit from such a change''?)
> 
> I wouldn't object to it being possible to do this, provided:
> 
> 1) It was possible to build a manual with all optional sections in it
> 2) The default was to do that.
> 
> That would put the onus on people wanting to make cut-down manuals to keep
> the optional parts consistent.

That was exactly what was done with the GDB manual.  But because
the GCC manual has lots of cross-references, the conditionals would
quickly proliferate, and the people wanting cut-down manuals would
have to be editing it all over the place.  In some cases, the
conditional machinery was inadequate (menus come to mind), and
so for GDB we ended up with multiple copies of things just so that
both arms of a conditional would work right.

Conditionals will add to the maintenance cost for everbody.

Stan