[RFA]: Improve ld man page generation

[Stephane Carrez <Stephane dot Carrez at worldnet dot fr>]

Hi!

The following patch improves the ld man pages by following
the same rules as GAS .texinfo documentation (see similar patch for GAS).

Can you approve this patch?

Thanks,
	Stephane

2001-11-02  Stephane Carrez  <Stephane.Carrez@worldnet.fr>

	* ld.texinfo: Use @command for commands, @option for options.
	* Makefile.am (POD2MAN): Use 'GNU Development Tools' for
	the page man title.
	* Makefile.in: Rebuild.
Index: Makefile.am
===================================================================
RCS file: /cvs/src/src/ld/Makefile.am,v
retrieving revision 1.73
diff -r1.73 Makefile.am
49c49,50
< POD2MAN = pod2man --center="GNU" --release="binutils-$(VERSION)" --section=1
---
> POD2MAN = pod2man --center="GNU Development Tools" \
> 	--release="binutils-$(VERSION)" --section=1
Index: ld.texinfo
===================================================================
RCS file: /cvs/src/src/ld/ld.texinfo,v
retrieving revision 1.55
diff -r1.55 ld.texinfo
11a12,15
> @macro gcctabopt{body}
> @code{\body\}
> @end macro
> 
165c169
< ld [ options ] objfile...
---
> ld [@b{options}] @var{objfile} @dots{}
177c181
< @code{ld} combines a number of object and archive files, relocates
---
> @command{ld} combines a number of object and archive files, relocates
179c183
< compiling a program is to run @code{ld}.
---
> compiling a program is to run @command{ld}.
181c185
< @code{ld} accepts Linker Command Language files written in
---
> @command{ld} accepts Linker Command Language files written in
188c192
< @code{ld} entry in @code{info}, or the manual
---
> @command{ld} entry in @code{info}, or the manual
194,195c198,199
< This version of @code{ld} uses the general purpose BFD libraries
< to operate on object files. This allows @code{ld} to read, combine, and
---
> This version of @command{ld} uses the general purpose BFD libraries
> to operate on object files. This allows @command{ld} to read, combine, and
204c208
< @code{ld} continues executing, allowing you to identify other errors
---
> @command{ld} continues executing, allowing you to identify other errors
214c218
< The @sc{gnu} linker @code{ld} is meant to cover a broad range of situations,
---
> The @sc{gnu} linker @command{ld} is meant to cover a broad range of situations,
238c242
< For instance, a frequent use of @code{ld} is to link standard Unix
---
> For instance, a frequent use of @command{ld} is to link standard Unix
246c250
< This tells @code{ld} to produce a file called @var{output} as the
---
> This tells @command{ld} to produce a file called @var{output} as the
251c255
< Some of the command-line options to @code{ld} may be specified at any
---
> Some of the command-line options to @command{ld} may be specified at any
320c324
< @table @code
---
> @table @gcctabopt
335,336c339,340
< In the current release of @code{ld}, this option is useful only for the
< Intel 960 family of architectures.  In that @code{ld} configuration, the
---
> In the current release of @command{ld}, this option is useful only for the
> Intel 960 family of architectures.  In that @command{ld} configuration, the
339c343
< archive-library search path.  @xref{i960,,@code{ld} and the Intel 960
---
> archive-library search path.  @xref{i960,,@command{ld} and the Intel 960
342c346
< Future releases of @code{ld} may support similar functionality for
---
> Future releases of @command{ld} may support similar functionality for
354,355c358,359
< @code{ld} may be configured to support more than one kind of object
< file.  If your @code{ld} is configured this way, you can use the
---
> @command{ld} may be configured to support more than one kind of object
> file.  If your @command{ld} is configured this way, you can use the
357c361
< that follow this option on the command line.  Even when @code{ld} is
---
> that follow this option on the command line.  Even when @command{ld} is
359c363
< to specify this, as @code{ld} should be configured to expect as a
---
> to specify this, as @command{ld} should be configured to expect as a
389c393
< For compatibility with linkers produced by MRI, @code{ld} accepts script
---
> For compatibility with linkers produced by MRI, @command{ld} accepts script
399,400c403,404
< scripts written in the general-purpose @code{ld} scripting language.
< If @var{MRI-cmdfile} does not exist, @code{ld} looks for it in the directories
---
> scripts written in the general-purpose @command{ld} scripting language.
> If @var{MRI-cmdfile} does not exist, @command{ld} looks for it in the directories
501c505
< Some older linkers used the @code{-F} option throughout a compilation
---
> Some older linkers used the @option{-F} option throughout a compilation
504c508
< purpose: the @code{-b}, @code{--format}, @code{--oformat} options, the
---
> purpose: the @option{-b}, @option{--format}, @option{--oformat} options, the
506c510
< environment variable.  The @sc{gnu} linker will ignore the @code{-F}
---
> environment variable.  The @sc{gnu} linker will ignore the @option{-F}
561c565
< option may be used any number of times.  @code{ld} will search its
---
> option may be used any number of times.  @command{ld} will search its
565c569
< On systems which support shared libraries, @code{ld} may also search for
---
> On systems which support shared libraries, @command{ld} may also search for
567c571
< and SunOS systems, @code{ld} will search a directory for a library with
---
> and SunOS systems, @command{ld} will search a directory for a library with
579c583
< See the @code{-(} option for a way to force the linker to search
---
> See the @option{-(} option for a way to force the linker to search
586c590
< if you are using @code{ld} on AIX, note that it is different from the
---
> if you are using @command{ld} on AIX, note that it is different from the
595,596c599,600
< Add path @var{searchdir} to the list of paths that @code{ld} will search
< for archive libraries and @code{ld} control scripts.  You may use this
---
> Add path @var{searchdir} to the list of paths that @command{ld} will search
> for archive libraries and @command{ld} control scripts.  You may use this
600c604
< @code{-L} options apply to all @code{-l} options, regardless of the
---
> @option{-L} options apply to all @option{-l} options, regardless of the
605c609
< @samp{-L}) depends on which emulation mode @code{ld} is using, and in
---
> @samp{-L}) depends on which emulation mode @command{ld} is using, and in
667c671
< Use @var{output} as the name for the program produced by @code{ld}; if this
---
> Use @var{output} as the name for the program produced by @command{ld}; if this
674c678
< If @var{level} is a numeric values greater than zero @code{ld} optimizes
---
> If @var{level} is a numeric values greater than zero @command{ld} optimizes
695c699
< turn serve as input to @code{ld}.  This is often called @dfn{partial
---
> turn serve as input to @command{ld}.  This is often called @dfn{partial
699c703
< @c ; see @code{-N}.
---
> @c ; see @option{-N}.
722c726
< For compatibility with other ELF linkers, if the @code{-R} option is
---
> For compatibility with other ELF linkers, if the @option{-R} option is
724c728
< the @code{-rpath} option.
---
> the @option{-rpath} option.
745c749
< Print the names of the input files as @code{ld} processes them.
---
> Print the names of the input files as @command{ld} processes them.
753c757
< @code{ld}'s default linker script (rather than adding to it), so
---
> @command{ld}'s default linker script (rather than adding to it), so
776c780
< turn serve as input to @code{ld}.  When linking C++ programs, @samp{-Ur}
---
> turn serve as input to @command{ld}.  When linking C++ programs, @samp{-Ur}
800c804
< Display the version number for @code{ld}.  The @code{-V} option also
---
> Display the version number for @command{ld}.  The @option{-V} option also
896c900
< @code{-l} options which follow it.
---
> @option{-l} options which follow it.
903c907
< @code{--no-undefined} is implied.  This option is only meaningful on ELF
---
> @option{--no-undefined} is implied.  This option is only meaningful on ELF
918c922
< library searching for @code{-l} options which follow it.
---
> library searching for @option{-l} options which follow it.
1063,1064c1067,1068
< @code{ld} normally optimizes for speed over memory usage by caching the
< symbol tables of input files in memory.  This option tells @code{ld} to
---
> @command{ld} normally optimizes for speed over memory usage by caching the
> symbol tables of input files in memory.  This option tells @command{ld} to
1066c1070
< necessary.  This may be required if @code{ld} runs out of memory space
---
> necessary.  This may be required if @command{ld} runs out of memory space
1092c1096
< Normally @code{ld} will give an error if you try to link together input
---
> Normally @command{ld} will give an error if you try to link together input
1095c1099
< This option tells @code{ld} that it should silently permit such possible
---
> This option tells @command{ld} that it should silently permit such possible
1102c1106
< Turn off the effect of the @code{--whole-archive} option for subsequent
---
> Turn off the effect of the @option{--whole-archive} option for subsequent
1116,1117c1120,1121
< @code{ld} may be configured to support more than one kind of object
< file.  If your @code{ld} is configured this way, you can use the
---
> @command{ld} may be configured to support more than one kind of object
> file.  If your @command{ld} is configured this way, you can use the
1119,1120c1123,1124
< object file.  Even when @code{ld} is configured to support alternative
< object formats, you don't usually need to specify this, as @code{ld}
---
> object file.  Even when @command{ld} is configured to support alternative
> object formats, you don't usually need to specify this, as @command{ld}
1146c1150
< @xref{H8/300,,@code{ld} and the H8/300}.
---
> @xref{H8/300,,@command{ld} and the H8/300}.
1149c1153
< @xref{i960,, @code{ld} and the Intel 960 family}.
---
> @xref{i960,, @command{ld} and the Intel 960 family}.
1194c1198
< linking an ELF executable with shared objects.  All @code{-rpath}
---
> linking an ELF executable with shared objects.  All @option{-rpath}
1196c1200
< them to locate shared objects at runtime.  The @code{-rpath} option is
---
> them to locate shared objects at runtime.  The @option{-rpath} option is
1199c1203
< @code{-rpath-link} option.  If @code{-rpath} is not used when linking an
---
> @option{-rpath-link} option.  If @option{-rpath} is not used when linking an
1203c1207
< The @code{-rpath} option may also be used on SunOS.  By default, on
---
> The @option{-rpath} option may also be used on SunOS.  By default, on
1205,1208c1209,1212
< @code{-L} options it is given.  If a @code{-rpath} option is used, the
< runtime search path will be formed exclusively using the @code{-rpath}
< options, ignoring the @code{-L} options.  This can be useful when using
< gcc, which adds many @code{-L} options which may be on NFS mounted
---
> @option{-L} options it is given.  If a @option{-rpath} option is used, the
> runtime search path will be formed exclusively using the @option{-rpath}
> options, ignoring the @option{-L} options.  This can be useful when using
> gcc, which adds many @option{-L} options which may be on NFS mounted
1211c1215
< For compatibility with other ELF linkers, if the @code{-R} option is
---
> For compatibility with other ELF linkers, if the @option{-R} option is
1213c1217
< the @code{-rpath} option.
---
> the @option{-rpath} option.
1227c1231
< explicitly.  In such a case, the @code{-rpath-link} option
---
> explicitly.  In such a case, the @option{-rpath-link} option
1229c1233
< @code{-rpath-link} option may specify a sequence of directory names
---
> @option{-rpath-link} option may specify a sequence of directory names
1242c1246
< Any directories specified by @code{-rpath-link} options.
---
> Any directories specified by @option{-rpath-link} options.
1244,1247c1248,1251
< Any directories specified by @code{-rpath} options.  The difference
< between @code{-rpath} and @code{-rpath-link} is that directories
< specified by @code{-rpath} options are included in the executable and
< used at runtime, whereas the @code{-rpath-link} option is only effective
---
> Any directories specified by @option{-rpath} options.  The difference
> between @option{-rpath} and @option{-rpath-link} is that directories
> specified by @option{-rpath} options are included in the executable and
> used at runtime, whereas the @option{-rpath-link} option is only effective
1250c1254
< On an ELF system, if the @code{-rpath} and @code{rpath-link} options
---
> On an ELF system, if the @option{-rpath} and @code{rpath-link} options
1254,1255c1258,1259
< On SunOS, if the @code{-rpath} option was not used, search any
< directories specified using @code{-L} options.
---
> On SunOS, if the @option{-rpath} option was not used, search any
> directories specified using @option{-L} options.
1282c1286
< shared library if the @code{-e} option is not used and there are
---
> shared library if the @option{-e} option is not used and there are
1287c1291
< This option tells @code{ld} to sort the common symbols by size when it
---
> This option tells @command{ld} to sort the common symbols by size when it
1295c1299
< Similar to @code{--split-by-reloc} but creates a new output section for
---
> Similar to @option{--split-by-reloc} but creates a new output section for
1320,1321c1324,1325
< For some targets, the output of @code{ld} is different in some ways from
< the output of some existing linker.  This switch requests @code{ld} to
---
> For some targets, the output of @command{ld} is different in some ways from
> the output of some existing linker.  This switch requests @command{ld} to
1325c1329
< For example, on SunOS, @code{ld} combines duplicate entries in the
---
> For example, on SunOS, @command{ld} combines duplicate entries in the
1329c1333
< trouble).  The @samp{--traditional-format} switch tells @code{ld} to not
---
> trouble).  The @samp{--traditional-format} switch tells @command{ld} to not
1361c1365
< Display the version number for @code{ld} and list the linker emulations
---
> Display the version number for @command{ld} and list the linker emulations
1500c1504
< @code{--whole-archive} option, include every object file in the archive
---
> @option{--whole-archive} option, include every object file in the archive
1507,1508c1511,1512
< about this option, so you have to use @code{-Wl,-whole-archive}.
< Second, don't forget to use @code{-Wl,-no-whole-archive} after your
---
> about this option, so you have to use @option{-Wl,-whole-archive}.
> Second, don't forget to use @option{-Wl,-no-whole-archive} after your
1535c1539
< If you link other code with this file using @code{--wrap malloc}, then
---
> If you link other code with this file using @option{--wrap malloc}, then
1541c1545
< links without the @code{--wrap} option will succeed.  If you do this,
---
> links without the @option{--wrap} option will succeed.  If you do this,
1552,1553c1556,1557
< @code{--enable-new-dtags}, the dynamic tags will be created as needed.
< If you specify @code{--disable-new-dtags}, no new dynamic tags will be
---
> @option{--enable-new-dtags}, the dynamic tags will be created as needed.
> If you specify @option{--disable-new-dtags}, no new dynamic tags will be
1565c1569
< The i386 PE linker supports the @code{-shared} option, which causes
---
> The i386 PE linker supports the @option{-shared} option, which causes
1579c1583
< @table @code
---
> @table @gcctabopt
1595c1599
< @code{-shared} or specify a @code{LIBRARY} in a given @code{.def}
---
> @option{-shared} or specify a @code{LIBRARY} in a given @code{.def}
1611c1615
< to be usable.  If you specify @code{--enable-stdcall-fixup}, this
---
> to be usable.  If you specify @option{--enable-stdcall-fixup}, this
1613c1617
< @code{--disable-stdcall-fixup}, this feature is disabled and such
---
> @option{--disable-stdcall-fixup}, this feature is disabled and such
1900c1904
< You can change the behavior of @code{ld} with the environment variables
---
> You can change the behavior of @command{ld} with the environment variables
1908c1912
< @code{GNUTARGET} in the environment, @code{ld} uses the natural format
---
> @code{GNUTARGET} in the environment, @command{ld} uses the natural format
2181c2185
< with the @code{-L} option.  You can nest calls to @code{INCLUDE} up to
---
> with the @option{-L} option.  You can nest calls to @code{INCLUDE} up to
2205c2209
< If you use @samp{INPUT (-l@var{file})}, @code{ld} will transform the
---
> If you use @samp{INPUT (-l@var{file})}, @command{ld} will transform the
2240c2244
< @code{ld} looks for archive libraries.  Using
---
> @command{ld} looks for archive libraries.  Using
2328c2332
< to make @code{ld} assign space to common symbols even if a relocatable
---
> to make @command{ld} assign space to common symbols even if a relocatable
2341c2345
< This command may be used to tell @code{ld} to issue an error about any
---
> This command may be used to tell @command{ld} to issue an error about any
2351c2355
< @code{ld} detects any cross references between the sections, it reports
---
> @command{ld} detects any cross references between the sections, it reports
4254,4255c4258,4259
< @code{ld} has additional features on some platforms; the following
< sections describe them.  Machines where @code{ld} has no additional
---
> @command{ld} has additional features on some platforms; the following
> sections describe them.  Machines where @command{ld} has no additional
4267c4271
< * TI COFF::                     @code{ld} and TI COFF
---
> * TI COFF::                     @command{ld} and TI COFF
4280c4284
< @section @code{ld} and the H8/300
---
> @section @command{ld} and the H8/300
4283c4287
< For the H8/300, @code{ld} can perform these global optimizations when
---
> For the H8/300, @command{ld} can perform these global optimizations when
4289c4293
< @code{ld} finds all @code{jsr} and @code{jmp} instructions whose
---
> @command{ld} finds all @code{jsr} and @code{jmp} instructions whose
4297c4301
< @code{ld} finds all @code{mov.b} instructions which use the
---
> @command{ld} finds all @code{mov.b} instructions which use the
4315c4319
< @chapter @code{ld} and other Hitachi chips
---
> @chapter @command{ld} and other Hitachi chips
4317c4321
< @code{ld} also supports the H8/300H, the H8/500, and the Hitachi SH.  No
---
> @command{ld} also supports the H8/300H, the H8/500, and the Hitachi SH.  No
4329c4333
< @section @code{ld} and the Intel 960 family
---
> @section @command{ld} and the Intel 960 family
4341c4345
< For example, if your @code{ld} command line included @w{@samp{-ACA}} as
---
> For example, if your @command{ld} command line included @w{@samp{-ACA}} as
4364c4368
< @cindex @code{--relax} on i960
---
> @cindex @option{--relax} on i960
4366,4367c4370,4371
< @code{ld} supports the @samp{--relax} option for the i960 family.  If
< you specify @samp{--relax}, @code{ld} finds all @code{balx} and
---
> @command{ld} supports the @samp{--relax} option for the i960 family.  If
> you specify @samp{--relax}, @command{ld} finds all @code{balx} and
4370c4374
< instructions, respectively.  @code{ld} also turns @code{cal}
---
> instructions, respectively.  @command{ld} also turns @code{cal}
4385c4389
< @section @code{ld}'s support for interworking between ARM and Thumb code
---
> @section @command{ld}'s support for interworking between ARM and Thumb code
4389c4393
< For the ARM, @code{ld} will generate code stubs to allow functions calls
---
> For the ARM, @command{ld} will generate code stubs to allow functions calls
4410c4414
< @section @code{ld} and HPPA 32-bit ELF support
---
> @section @command{ld} and HPPA 32-bit ELF support
4413c4417
< When generating a shared library, @code{ld} will by default generate
---
> When generating a shared library, @command{ld} will by default generate
4415c4419
< The @samp{--multi-subspace} switch causes @code{ld} to generate export
---
> The @samp{--multi-subspace} switch causes @command{ld} to generate export
4421c4425
< Long branch stubs and import/export stubs are placed by @code{ld} in
---
> Long branch stubs and import/export stubs are placed by @command{ld} in
4432c4436
< @code{ld} to automatically size input section groups for the branch types
---
> @command{ld} to automatically size input section groups for the branch types
4469c4473
< @section @code{ld}'s support for various TI COFF versions
---
> @section @command{ld}'s support for various TI COFF versions
4475c4479
< format; @code{ld} will read any version or byte order, but the output
---
> format; @command{ld} will read any version or byte order, but the output
4528,4529c4532,4533
< @cindex bugs in @code{ld}
< @cindex reporting bugs in @code{ld}
---
> @cindex bugs in @command{ld}
> @cindex reporting bugs in @command{ld}
4531c4535
< Your bug reports play an essential role in making @code{ld} reliable.
---
> Your bug reports play an essential role in making @command{ld} reliable.
4535c4539
< to help the entire community by making the next version of @code{ld}
---
> to help the entire community by making the next version of @command{ld}
4537c4541
< @code{ld}.
---
> @command{ld}.
4559c4563
< @code{ld} bug.  Reliable linkers never crash.
---
> @command{ld} bug.  Reliable linkers never crash.
4563c4567
< If @code{ld} produces an error message for valid input, that is a bug.
---
> If @command{ld} produces an error message for valid input, that is a bug.
4567c4571
< If @code{ld} does not produce an error message for invalid input, that
---
> If @command{ld} does not produce an error message for invalid input, that
4573c4577
< improvement of @code{ld} are welcome in any case.
---
> improvement of @command{ld} are welcome in any case.
4579c4583
< @cindex @code{ld} bugs, reporting
---
> @cindex @command{ld} bugs, reporting
4582c4586
< products.  If you obtained @code{ld} from a support organization, we
---
> products.  If you obtained @command{ld} from a support organization, we
4589c4593
< Otherwise, send bug reports for @code{ld} to
---
> Otherwise, send bug reports for @command{ld} to
4619c4623
< The version of @code{ld}.  @code{ld} announces it if you start it with
---
> The version of @command{ld}.  @command{ld} announces it if you start it with
4623c4627
< the bug in the current version of @code{ld}.
---
> the bug in the current version of @command{ld}.
4626c4630
< Any patches you may have applied to the @code{ld} source, including any
---
> Any patches you may have applied to the @command{ld} source, including any
4634c4638
< What compiler (and its version) was used to compile @code{ld}---e.g.
---
> What compiler (and its version) was used to compile @command{ld}---e.g.
4663c4667
< Of course, if the bug is that @code{ld} gets a fatal signal, then we
---
> Of course, if the bug is that @command{ld} gets a fatal signal, then we
4670c4674
< copy of @code{ld} is out of synch, or you have encountered a bug in the
---
> copy of @command{ld} is out of synch, or you have encountered a bug in the
4678c4682
< If you wish to suggest changes to the @code{ld} source, send us context
---
> If you wish to suggest changes to the @command{ld} source, send us context
4681c4685
< If you even discuss something in the @code{ld} source, refer to it by
---
> If you even discuss something in the @command{ld} source, refer to it by
4719c4723
< Sometimes with a program as complicated as @code{ld} it is very hard to
---
> Sometimes with a program as complicated as @command{ld} it is very hard to
4739,4740c4743,4744
< To aid users making the transition to @sc{gnu} @code{ld} from the MRI
< linker, @code{ld} can use MRI compatible linker scripts as an
---
> To aid users making the transition to @sc{gnu} @command{ld} from the MRI
> linker, @command{ld} can use MRI compatible linker scripts as an
4744c4748
< @code{ld}.  @sc{gnu} @code{ld} supports the most commonly used MRI
---
> @command{ld}.  @sc{gnu} @command{ld} supports the most commonly used MRI
4757c4761
< MRI-compatible script begins with an unrecognized keyword, @code{ld}
---
> MRI-compatible script begins with an unrecognized keyword, @command{ld}
4770c4774
< Normally, @code{ld} includes in the output file all sections from all
---
> Normally, @command{ld} includes in the output file all sections from all
4825c4829
< @code{ld} command-line option @samp{-M}.
---
> @command{ld} command-line option @samp{-M}.
4834c4838
< same effect as specifying @var{filename} directly on the @code{ld}
---
> same effect as specifying @var{filename} directly on the @command{ld}
4839c4843
< @var{output-name} is the name for the program produced by @code{ld}; the
---
> @var{output-name} is the name for the program produced by @command{ld}; the
4846c4850
< Normally, @code{ld} orders the sections in its output file in the
---
> Normally, @command{ld} orders the sections in its output file in the