move specs documentation to internals manual?

move specs documentation to internals manual?

[Geoffrey Keating]

"Joseph S. Myers" <joseph@codesourcery.com> writes:

> On Fri, 7 Jul 2005, Ian Lance Taylor wrote:
> 
> > gkeating@apple.com (Geoffrey Keating) writes:
> > 
> > > 	* gcc.c: Include xregex.h.
> > > 	(version_compare_spec_function): New.
> > > 	(spec_function): Add version-compare.
> > > 	(replace_outfile_spec_function): Reformat comment.
> > > 	(compare_version_strings): New.
> > 
> > I think version-compare should be documented in the specs file section
> > of invoke.texi.
> 
> I think having this documentation in invoke.texi is a mistake - specs are 
> internals rather than something for users to use.  The documentation 
> should either be in the internals manual or be in comments in gcc.c, not 
> both and not the user manual.

I agree with both comments here: it's lame that we have duplicated
documentation (and explains why I didn't realise that I had to change
two places), and I don't think that we should be considering specs to
be an user-level interface to GCC.

So, what do people think about (a) deleting the big comment in gcc.c
that tries to explain specs (leaving a pointer to the manual), and (b)
moving the specs documentation to the internals manual?

Re: move specs documentation to internals manual?

[Daniel Jacobowitz]

On Fri, Jul 08, 2005 at 04:29:49PM -0700, Geoffrey Keating wrote:
> I agree with both comments here: it's lame that we have duplicated
> documentation (and explains why I didn't realise that I had to change
> two places), and I don't think that we should be considering specs to
> be an user-level interface to GCC.
> 
> So, what do people think about (a) deleting the big comment in gcc.c
> that tries to explain specs (leaving a pointer to the manual), and (b)
> moving the specs documentation to the internals manual?

I think it's a good idea - but someone should compare the two existing
bits of documentation first, since IIRC I've seen people add to one but
not the other.

-- 
Daniel Jacobowitz
CodeSourcery, LLC

Re: move specs documentation to internals manual?

[Joseph S. Myers]

On Fri, 8 Jul 2005, Daniel Jacobowitz wrote:

> > So, what do people think about (a) deleting the big comment in gcc.c
> > that tries to explain specs (leaving a pointer to the manual), and (b)
> > moving the specs documentation to the internals manual?
> 
> I think it's a good idea - but someone should compare the two existing
> bits of documentation first, since IIRC I've seen people add to one but
> not the other.

Agreed.  The documentation of -dumpspecs and -specs= should point to the 
internals manual information on specs, but that should be the only 
reference needed in the user manual.

-- 
Joseph S. Myers               http://www.srcf.ucam.org/~jsm28/gcc/
    jsm@polyomino.org.uk (personal mail)
    joseph@codesourcery.com (CodeSourcery mail)
    jsm28@gcc.gnu.org (Bugzilla assignments and CCs)

Re: move specs documentation to internals manual?

[Joel Sherrill <joel@OARcorp.com>]

Geoffrey Keating wrote:
> "Joseph S. Myers" <joseph@codesourcery.com> writes:
> 
> 
>>On Fri, 7 Jul 2005, Ian Lance Taylor wrote:
>>
>>
>>>gkeating@apple.com (Geoffrey Keating) writes:
>>>
>>>
>>>>	* gcc.c: Include xregex.h.
>>>>	(version_compare_spec_function): New.
>>>>	(spec_function): Add version-compare.
>>>>	(replace_outfile_spec_function): Reformat comment.
>>>>	(compare_version_strings): New.
>>>
>>>I think version-compare should be documented in the specs file section
>>>of invoke.texi.
>>
>>I think having this documentation in invoke.texi is a mistake - specs are 
>>internals rather than something for users to use.  The documentation 
>>should either be in the internals manual or be in comments in gcc.c, not 
>>both and not the user manual.
> 
> 
> I agree with both comments here: it's lame that we have duplicated
> documentation (and explains why I didn't realise that I had to change
> two places), and I don't think that we should be considering specs to
> be an user-level interface to GCC.
> 
> So, what do people think about (a) deleting the big comment in gcc.c
> that tries to explain specs (leaving a pointer to the manual), and (b)
> moving the specs documentation to the internals manual?

I think it is definitely appropriate to fix gcc.c to point to any
manual.

Which manual is another question.  RTEMS uses the specs to specify
board specific linking issues so to us, it is at least something the
user is aware of even if there is only one per board generated which
applies to all code linked for that board.  So it is more a user level
feature to us than a gcc internal one.

It should only be documented in one place though.

--joel


-- 
Joel Sherrill, Ph.D.             Director of Research & Development
joel@OARcorp.com                 On-Line Applications Research
Ask me about RTEMS: a free RTOS  Huntsville AL 35805
    Support Available             (256) 722-9985