Re: [patch] document Blackfin-specific gas options

["Joseph S. Myers" <joseph at codesourcery dot com>]

On Tue, 9 Mar 2010, Mike Frysinger wrote:

> 	* doc/as.texinfo: Add Blackfin options.
> 	* doc/c-bfin.texi: Document -mfdpic, -mno-fdpic and -mnopic.

This is only changing two of the three places that list options for each 
target.  You're changing the summary, and the documentation in 
c-$target.texi.  But there's also documentation of the options for many 
targets in as.texinfo, and only that documentation of the individual 
options, and not that in c-$target.texi, ends up in the manpage.  (Some 
targets do e.g.

@ifset CRIS
See the info pages for documentation of the CRIS-specific options.
@end ifset

in as.texinfo, avoiding some duplication but resulting in a less helpful 
manpage.)

This duplication does have the unfortunate effect of options only being 
documented in some of the three places (for example, the ARM -mimplicit-it 
option is only documented in c-arm.texi, although ARM has documentation in 
all three places).  It might be nice to reduce them to two places by 
eliminating the text in as.texinfo that effectively duplicates 
c-$target.texi (while ensuring that any places where that text is better 
than c-$target.texi are merged into c-$target.texi), while arranging for 
the option information from c-$target.texi to end up in the manpage.  But 
until anyone does that, you should probably at least put something like 
the CRIS text in the text that ends up in the manpage, if not a copy of 
the documentation of individual options.

-- 
Joseph S. Myers
joseph@codesourcery.com