Re: Documenting assembler target options

["H.J. Lu" <hjl dot tools at gmail dot com>]

On Mon, Nov 22, 2010 at 4:58 PM, Joseph S. Myers
<joseph@codesourcery.com> wrote:
> (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 am checking in this patch.


H.J.
diff --git a/gas/doc/as.texinfo b/gas/doc/as.texinfo
index 45dcb30..bddd93c 100644
--- a/gas/doc/as.texinfo
+++ b/gas/doc/as.texinfo
@@ -812,7 +812,28 @@ Warn when nops are generated.
 Warn when a nop after a 32-bit multiply instruction is generated.
 @end table
 @end ifset
+@c man end
+
+@ifset I80386
+
+@ifclear man
+@xref{i386-Options}, for the options available when @value{AS} is
+configured for an i386 processor.
+@end ifclear
+
+@ifset man
+@c man begin OPTIONS
+The following options are available when @value{AS} is configured for
+an i386 processor.
+@c man end
+@c man begin INCLUDE
+@include c-i386.texi
+@c ended inside the included file
+@end ifset
+
+@end ifset

+@c man begin OPTIONS
 @ifset I960
 The following options are available when @value{AS} is configured for the
 Intel 80960 processor.
diff --git a/gas/doc/c-i386.texi b/gas/doc/c-i386.texi
index d0a47de..1c6175b 100644
--- a/gas/doc/c-i386.texi
+++ b/gas/doc/c-i386.texi
@@ -3,6 +3,8 @@
 @c Free Software Foundation, Inc.
 @c This is part of the GAS manual.
 @c For copying conditions, see the file as.texinfo.
+@c man end
+
 @ifset GENERIC
 @page
 @node i386-Dependent
@@ -50,7 +52,8 @@ extending the Intel architecture to 64-bits.
 The i386 version of @code{@value{AS}} has a few machine
 dependent options:

-@table @code
+@c man begin OPTIONS
+@table @gcctabopt
 @cindex @samp{--32} option, i386
 @cindex @samp{--32} option, x86-64
 @cindex @samp{--64} option, i386
@@ -226,6 +229,7 @@ This opetion specifies that registers don't
require a @samp{%} prefix.
 The @code{.att_syntax} and @code{.intel_syntax} directives will take precedent.

 @end table
+@c man end

 @node i386-Directives
 @section x86 specific Directives