Documenting assembler target options

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

(This message is Bcc:ed to the listed binutils maintainers for relevant 
target architectures, per Nick Clifton's request in 
<http://sourceware.org/ml/binutils/2010-11/msg00360.html>.  If you're a 
maintainer but only get it via the list, check your email address in 
binutils/MAINTAINERS is up to date, though I may also have missed some 
people out by accident.)

Assembler target maintainers should note that there is now a method in
use of putting documentation of target-specific command-line options
in the assembler manpage without duplicating descriptions of those
options in both as.texinfo and c-$target.texi.

Each option in general needs entries in two places: the "Overview" in
as.texinfo that appears as SYNOPSIS in the manpage, just listing what
the options are, and in c-$target.texi.  Formerly, for there to be any
documentation of the option in the main OPTIONS section of the manpage
it would need directly documenting in as.texinfo as well.

Alpha and C6X provide examples of how to do things in the new scheme.
The text in as.texinfo should look something like that for C6X:

@ifset TIC6X

@ifclear man
@xref{TIC6X Options}, for the options available when @value{AS} is configured
for a TMS320C6000 processor.
@end ifclear

@ifset man
@c man begin OPTIONS
The following options are available when @value{AS} is configured for a
TMS320C6000 processor.
@c man end
@c man begin INCLUDE
@include c-tic6x.texi
@c ended inside the included file
@end ifset

@end ifset

In addition, *before* this text there should be "@c man end", if the
target before does not yet use this scheme, and *after* it should be
"@c man begin OPTIONS", if the target after does not yet use this
scheme.  The c-$target.texi file should have "@c man end" before any
non-comment text; then, the actual table of options should be
surrounded by "@c man begin OPTIONS" and "@c man end", and the table
itself should start "@table @gcctabopt".

I've gone through the supported targets (tc-*.c files) to identify the
state of each target regarding target options and their
documentation.  In what follows, "None" means there are no target
options in md_longopts or md_shortopts, "Done" means the new scheme is
now in use, and otherwise a sequence of letters indicates where
documentation is present: "S" for the synopsis having documentation,
"s" for it being missing, "O" for the OPTIONS section in as.texinfo
having documentation, "(O)" for it just having a cross-reference to
c-$target.texi and "o" for nothing there, "T" for c-$target.texi
having documentation and "t" for nothing there.  I have not checked
whether the full set of options for any particular target is
documented in either place, and where both "O" and "T" are shown care
will be needed in merging the two sets of documentation, each of which
could have improvements not present in the other.

alpha      Done
arc        SOT
arm        SOT
avr        soT
bfin       SOT
cr16       None
cris       S(O)T
crx        None
d10v       SOT
d30v       SOT
dlx        None
fr30       None
frv        sot
h8300      SoT
hppa       sot
           (the manual claims no options for this target, but that appears
            to be wrong)
i370       sot
           (the manual claims no options for this target, but that appears
            to be wrong)
i386       SoT
i860       soT
i960       SOT
ia64       SoT
ip2k       SOT
iq2000     None
lm32       soT
m32c       SOT
m32r       SOT
m68hc11    SOT
m68k       SOT
mcore      SOt
mep        sot
microblaze None
mips       SOT
mmix       S(O)T
mn10200    None
mn10300    None
moxie      None
msp430     soT
mt         soT
           (there is documentation in c-mt.texi, but that file is
            never actually @included anywhere in the manual)
ns32k      soT
           (c-ns32k.texi is included but marked @ignore)
openrisc   sot
or32       None
pdp11      S(O)T
pj         SOT
ppc        SoT
rx         S(O)T
s390       SOT
score      SoT
sh         soT
sparc      SOT
spu        sot
tic30      None
tic4x      sot
tic54x     SOT
tic6x      Done
v850       soT
vax        soT
xc16x      None
xstormy16  None
xtensa     SOT
z80        SOT
z8k        soT

-- 
Joseph S. Myers
joseph@codesourcery.com