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