Avoiding duplication in assembler manual

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

In <http://sourceware.org/ml/binutils/2010-03/msg00146.html>, I
commented on the problems with documentation of assembler options
being duplicated and commonly only one copy being updated when someone
adds a new target-specific option.

I proposed at the time that the duplication should be reduced by
avoiding as.texinfo duplicating target option documentation while
ensuring the documentation in c-$target.texi goes in the generated
manpage.  This patch provides a proof-of-concept implementation of
this.

No changes to texi2pod.pl are needed.  Instead, appropriate markup is
added in the list of target options in as.texinfo, that for manpage
generation includes c-$target.texi and in other cases has a Texinfo
internal link to the relevant section.  The markup in c-$target.texi
is also adjusted to cause the right parts to go in the manpage.  The
ugliest part is that the "@c man begin INCLUDE" (required for
texi2pod.pl to process the @include directive) has the corresponding
"@c man end" inside the included c-$target.texi (it needs to go before
the "@c man begin OPTIONS" there).

As an illustration of the concept this patch makes the changes for
Alpha, which had no details at all in the manpage apart from the
initial list of options, and C6X, where I had kept the descriptions of
individual options in sync in the two places.  While the updates for
targets like Alpha, or those where the manpage just refers to the info
manual, are easy, updates for targets with lists of options in both
places are more involved as they require working out if anything in
the list in as.texinfo should be merged into c-$target.texi.  My
inclination is that such updates are best done by the relevant target
maintainers.

I have not attempted to go through the supported targets and work out
which have target options, and, of those, in what subset of the three
places (option list in as.texinfo, option details in as.texinfo,
option details in c-$target.texi) those options are documented.

Similar issues of duplication also apply to target-independent options
- each is documented twice in the info manual (plus the summary list
of options) with only the first (shorter) documentation going in the
manpage.  In practice I don't think trying to maintain documentation
at two different levels of detail is useful and it would be better for
the manpage and info manual just to have the main detailed
documentation.  I don't plan to do anything about this; certainly I
think target-specific options are rather more frequently added in
development and so the value of avoiding the duplication for them is
greater.

OK to commit?

2010-11-11  Joseph Myers  <joseph@codesourcery.com>

	* doc/as.texinfo: Refer to or include c-alpha.texi for Alpha
	options.  Refer to or include c-tic6x.texi for C6X options instead
	of duplicating documentation here.
	* doc/c-alpha.texi, doc/c-tic6x.texi: Add markup for use in
	manpage generation.

Index: doc/as.texinfo
===================================================================
RCS file: /cvs/src/src/gas/doc/as.texinfo,v
retrieving revision 1.225
diff -u -r1.225 as.texinfo
--- doc/as.texinfo	2 Nov 2010 14:36:36 -0000	1.225
+++ doc/as.texinfo	11 Nov 2010 17:52:47 -0000
@@ -702,7 +702,28 @@
 Standard input, or source files to assemble.
 
 @end table
+@c man end
+
+@ifset ALPHA
+
+@ifclear man
+@xref{Alpha Options}, for the options available when @value{AS} is configured
+for an Alpha processor.
+@end ifclear
+
+@ifset man
+@c man begin OPTIONS
+The following options are available when @value{AS} is configured for an Alpha
+processor.
+@c man end
+@c man begin INCLUDE
+@include c-alpha.texi
+@c ended inside the included file
+@end ifset
+
+@end ifset
 
+@c man begin OPTIONS
 @ifset ARC
 The following options are available when @value{AS} is configured for
 an ARC processor.
@@ -1261,71 +1282,28 @@
 but evaluates to zero.
 @end table
 @end ifset
+@c man end
 
 @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.
-
-@table @gcctabopt
-@item -march=@var{arch}
-Enable (only) instructions from architecture @var{arch}.  By default,
-all instructions are permitted.
-
-The following values of @var{arch} are accepted: @code{c62x},
-@code{c64x}, @code{c64x+}, @code{c67x}, @code{c67x+}, @code{c674x}.
-
-@item -matomic
-@itemx -mno-atomic
-Enable or disable the optional C64x+ atomic operation instructions.
-By default, they are enabled if no @option{-march} option is given, or
-if an architecture is specified with @option{-march} that implies
-these instructions are present (currently, there are no such
-architectures); they are disabled if an architecture is specified with
-@option{-march} on which the instructions are optional or not
-present.  This option overrides such a default from the architecture,
-independent of the order in which the @option{-march} or
-@option{-matomic} or @option{-mno-atomic} options are passed.
-
-@item -mdsbt
-@itemx -mno-dsbt
-The @option{-mdsbt} option causes the assembler to generate the
-@code{Tag_ABI_DSBT} attribute with a value of 1, indicating that the
-code is using DSBT addressing.  The @option{-mno-dsbt} option, the
-default, causes the tag to have a value of 0, indicating that the code
-does not use DSBT addressing.  The linker will emit a warning if
-objects of different type (DSBT and non-DSBT) are linked together.
-
-@item -mpid=no
-@itemx -mpid=near
-@itemx -mpid=far
-The @option{-mpid=} option causes the assembler to generate the
-@code{Tag_ABI_PID} attribute with a value indicating the form of data
-addressing used by the code.  @option{-mpid=no}, the default,
-indicates position-dependent data addressing, @option{-mpid=near}
-indicates position-independent addressing with GOT accesses using near
-DP addressing, and @option{-mpid=far} indicates position-independent
-addressing with GOT accesses using far DP addressing.  The linker will
-emit a warning if objects built with different settings of this option
-are linked together.
-
-@item -mpic
-@itemx -mno-pic
-The @option{-mpic} option causes the assembler to generate the
-@code{Tag_ABI_PIC} attribute with a value of 1, indicating that the
-code is using position-independent code addressing,  The
-@code{-mno-pic} option, the default, causes the tag to have a value of
-0, indicating position-dependent code addressing.  The linker will
-emit a warning if objects of different type (position-dependent and
-position-independent) are linked together.
-
-@item -mbig-endian
-@itemx -mlittle-endian
-Generate code for the specified endianness.  The default is
-little-endian.
-@end table
+@c man end
+@c man begin INCLUDE
+@include c-tic6x.texi
+@c ended inside the included file
+@end ifset
 
 @end ifset
 
+@c man begin OPTIONS
 @ifset XTENSA
 The following options are available when @value{AS} is configured for
 an Xtensa processor.
Index: doc/c-alpha.texi
===================================================================
RCS file: /cvs/src/src/gas/doc/c-alpha.texi,v
retrieving revision 1.11
diff -u -r1.11 c-alpha.texi
--- doc/c-alpha.texi	21 Jun 2010 10:49:41 -0000	1.11
+++ doc/c-alpha.texi	11 Nov 2010 17:52:47 -0000
@@ -2,6 +2,7 @@
 @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
@@ -38,7 +39,8 @@
 @cindex Alpha options
 @cindex options for Alpha
 
-@table @option
+@c man begin OPTIONS
+@table @gcctabopt
 @cindex @code{-m@var{cpu}} command line option, Alpha
 @item -m@var{cpu}
 This option specifies the target processor.  If an attempt is made to
@@ -117,6 +119,7 @@
 @itemx -32addr
 These options are ignored for backward compatibility.
 @end table
+@c man end
 
 @cindex Alpha Syntax
 @node Alpha Syntax
Index: doc/c-tic6x.texi
===================================================================
RCS file: /cvs/src/src/gas/doc/c-tic6x.texi,v
retrieving revision 1.6
diff -u -r1.6 c-tic6x.texi
--- doc/c-tic6x.texi	2 Nov 2010 14:36:36 -0000	1.6
+++ doc/c-tic6x.texi	11 Nov 2010 17:52:47 -0000
@@ -1,6 +1,7 @@
 @c Copyright 2010 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 TIC6X-Dependent
@@ -24,7 +25,8 @@
 @cindex TIC6X options
 @cindex options for TIC6X
 
-@table @code
+@c man begin OPTIONS
+@table @gcctabopt
 
 @cindex @code{-march=} command line option, TIC6X
 @item -march=@var{arch}
@@ -95,6 +97,7 @@
 little-endian.
 
 @end table
+@c man end
 
 @node TIC6X Syntax
 @section TIC6X Syntax

-- 
Joseph S. Myers
joseph@codesourcery.com