* move specs documentation to internals manual?
[not found] ` <Pine.LNX.4.61.0507081217260.14395@digraph.polyomino.org.uk>
@ 2005-07-08 23:29 ` Geoffrey Keating
2005-07-09 0:23 ` Daniel Jacobowitz
2005-07-09 0:32 ` Joel Sherrill <joel@OARcorp.com>
0 siblings, 2 replies; 4+ messages in thread
From: Geoffrey Keating @ 2005-07-08 23:29 UTC (permalink / raw)
To: Joseph S. Myers; +Cc: Geoffrey Keating, gcc
"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?
^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: move specs documentation to internals manual?
2005-07-08 23:29 ` move specs documentation to internals manual? Geoffrey Keating
@ 2005-07-09 0:23 ` Daniel Jacobowitz
2005-07-09 0:32 ` Joseph S. Myers
2005-07-09 0:32 ` Joel Sherrill <joel@OARcorp.com>
1 sibling, 1 reply; 4+ messages in thread
From: Daniel Jacobowitz @ 2005-07-09 0:23 UTC (permalink / raw)
To: Geoffrey Keating; +Cc: Joseph S. Myers, Geoffrey Keating, gcc
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
^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: move specs documentation to internals manual?
2005-07-09 0:23 ` Daniel Jacobowitz
@ 2005-07-09 0:32 ` Joseph S. Myers
0 siblings, 0 replies; 4+ messages in thread
From: Joseph S. Myers @ 2005-07-09 0:32 UTC (permalink / raw)
To: Daniel Jacobowitz; +Cc: Geoffrey Keating, Geoffrey Keating, gcc
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)
^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: move specs documentation to internals manual?
2005-07-08 23:29 ` move specs documentation to internals manual? Geoffrey Keating
2005-07-09 0:23 ` Daniel Jacobowitz
@ 2005-07-09 0:32 ` Joel Sherrill <joel@OARcorp.com>
1 sibling, 0 replies; 4+ messages in thread
From: Joel Sherrill <joel@OARcorp.com> @ 2005-07-09 0:32 UTC (permalink / raw)
To: Geoffrey Keating; +Cc: Joseph S. Myers, Geoffrey Keating, gcc
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
^ permalink raw reply [flat|nested] 4+ messages in thread
end of thread, other threads:[~2005-07-09 0:32 UTC | newest]
Thread overview: 4+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
[not found] <20050708054604.67D4A15D66FE@geoffk5.apple.com>
[not found] ` <m3vf3lvld8.fsf@gossamer.airs.com>
[not found] ` <Pine.LNX.4.61.0507081217260.14395@digraph.polyomino.org.uk>
2005-07-08 23:29 ` move specs documentation to internals manual? Geoffrey Keating
2005-07-09 0:23 ` Daniel Jacobowitz
2005-07-09 0:32 ` Joseph S. Myers
2005-07-09 0:32 ` Joel Sherrill <joel@OARcorp.com>
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).