misc updates:

(1) show `-y SYMBOL' with space
(2) weaken multi-target stuff, to avoid false expectations now that
linker now often config'd with only one target
(3) describe -relax support on i960
(4) correct description of hyphen chars in symbols
(5) describe CONSTRUCTORS linker script cmd

1 files changed, 94 insertions, 46 deletions

diff --git a/ld/ld.texinfo b/ld/ld.texinfo
index 8081322..78d4580 100644
--- a/ld/ld.texinfo
+++ b/ld/ld.texinfo
@@ -5,7 +5,6 @@
 @c (configdoc.texi is generated by the Makefile)
 
 @c @smallbook
-@c @cropmarks
 
 @ifinfo
 @format
@@ -177,7 +176,7 @@ ld [ -o @var{output} ]  @var{objfile}@dots{}
   [ -T @var{commandfile} ]
   [ -Ttext @var{org} ]  [ -Tdata @var{org} ]
   [ -Tbss @var{org} ]  [ -t ]  [ -u @var{symbol}]  [-V]  [-v]  [ --version ]
-  [ -warn-common ]  [ -y@var{symbol} ]  [ -X ]  [-x ]
+  [ -warn-common ]  [ -y @var{symbol} ]  [ -X ]  [-x ]
 @end smallexample
 
 This plethora of command-line options may seem intimidating, but in
@@ -250,14 +249,18 @@ other architecture families.
 @cindex input format
 @item -b @var{input-format}
 @cindex input format
-Specify the binary format for input object files that follow this option
-on the command line.  You don't usually need to specify this, as
-@code{ld} is configured to expect as a default input format the most
-usual format on each machine.  @var{input-format} is a text string, the
-name of a particular format supported by the BFD libraries.
-(You can list the available binary formats with @samp{objdump -i}.)
-@w{@samp{-format @var{input-format}}} has the same effect, as does the
-script command @code{TARGET}.  @xref{BFD}.
+@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
+@samp{-b} option to specify the binary format for input object files
+that follow this option on the command line.  Even when @code{ld} is
+configured to support alternative object formats, you don't usually need
+to specify this, as @code{ld} should be configured to expect as a
+default input format the most usual format on each machine.
+@var{input-format} is a text string, the name of a particular format
+supported by the BFD libraries.  (You can list the available binary
+formats with @samp{objdump -i}.)  @w{@samp{-format @var{input-format}}}
+has the same effect, as does the script command @code{TARGET}.
+@xref{BFD}.
 
 You may want to use this option if you are linking files with an unusual
 binary format.  You can also use @samp{-b} to switch formats explicitly (when
@@ -416,7 +419,7 @@ common storage allocation.
 @itemx -m @var{emulation}
 Emulate the @var{emulation} linker.  You can list the available
 emulations with the @samp{-V} option.  The
-default is the system for which you configured @code{ld}.
+default depends on how your @code{ld} was configured.
 
 @kindex -N
 @cindex read/write from cmd line
@@ -451,14 +454,17 @@ script command @code{OUTPUT} can also specify the output file name.
 @ifclear SingleFormat
 @kindex -oformat
 @item -oformat @var{output-format}
-Specify the binary format for the output object file.  You don't usually
-need to specify this, as @code{ld} is configured to produce as a default
-output format the most usual format on each machine.
-@var{output-format} is a text string, the name of a particular format
-supported by the BFD libraries.  (You can list the available binary
-formats with @samp{objdump -i}.)  The script command
-@code{OUTPUT_FORMAT} can also specify the output format, but this option
-overrides it.  @xref{BFD}.
+@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
+@samp{-oformat} option to specify the binary format for the output
+object file.  Even when @code{ld} is configured to support alternative
+object formats, you don't usually need to specify this, as @code{ld}
+should be configured to produce as a default output format the most
+usual format on each machine.  @var{output-format} is a text string, the
+name of a particular format supported by the BFD libraries.  (You can
+list the available binary formats with @samp{objdump -i}.)  The script
+command @code{OUTPUT_FORMAT} can also specify the output format, but
+this option overrides it.  @xref{BFD}.
 @end ifclear
 
 @item -R @var{filename}
@@ -473,19 +479,26 @@ programs.
 @kindex -relax
 @cindex synthesizing linker
 @cindex relaxing addressing modes
-An option with machine dependent effects.  Currently this option is only
-supported on the H8/300.
+An option with machine dependent effects.  
+@ifset GENERIC
+Currently this option is only supported on the H8/300 and the Intel 960.
+@end ifset
 @ifset H8300
 @xref{H8/300,,@code{ld} and the H8/300}.
 @end ifset
+@ifset I960
+@xref{i960,, @code{ld} and the Intel 960 family}.
+@end ifset
 
-On some platforms, use option performs global optimizations that
+On some platforms, the @samp{-relax} option performs global optimizations that
 become possible when the linker resolves addressing in the program, such
 as relaxing address modes and synthesizing new instructions in the
 output object file.  
 
+@ifset GENERIC
 On platforms where this is not supported, @samp{-relax} is accepted, but
 ignored.
+@end ifset
 
 @item -r 
 @cindex partial link
@@ -570,17 +583,17 @@ arguments to enter additional undefined symbols.
 For anything other than C++ programs, this option is equivalent to
 @samp{-r}: it generates relocatable output---i.e., an output file that can in
 turn serve as input to @code{ld}.  When linking C++ programs, @samp{-Ur}
-@emph{will} resolve references to constructors, unlike @samp{-r}.
+@emph{does} resolve references to constructors, unlike @samp{-r}.
 It does not work to use @samp{-Ur} on files that were themselves linked
-with @samp{-Ur}; once the constructor table has been built, it can not
+with @samp{-Ur}; once the constructor table has been built, it cannot
 be added to.  Use @samp{-Ur} only for the last partial link, and
 @samp{-r} for the others.
 
 @item -V
 @kindex -V
 @cindex version
-Display the version number for @code{ld} and list the supported emulations.
-Display which input files can and can not be opened.
+Display the version number for @code{ld} and list the linker emulations
+supported.  Display which input files can and cannot be opened.
 
 @item -v
 @kindex -v
@@ -689,8 +702,8 @@ beginning with @samp{L}.
 If @samp{-s} or @samp{-S} is also specified, delete all local symbols,
 not just those beginning with @samp{L}.
 
-@item -y@var{symbol}
-@kindex -y@var{symbol}
+@item -y @var{symbol}
+@kindex -y @var{symbol}
 @cindex symbol tracing
 Print the name of each linked file in which @var{symbol} appears.  This
 option may be given any number of times.  On many systems it is necessary
@@ -878,9 +891,9 @@ respectively. For example, the following all refer to the same quantity:
 @cindex names
 @cindex quoted symbol names
 @kindex "
-Unless quoted, symbol names start with a letter, underscore, point or
-hyphen and may include any letters, underscores, digits, points,
-and minus signs.  Unquoted symbol names must not conflict with any
+Unless quoted, symbol names start with a letter, underscore, or point
+and may include any letters, underscores, digits, points,
+and hyphens.  Unquoted symbol names must not conflict with any
 keywords.  You can specify a symbol which contains odd characters or has
 the same name as a keyword, by surrounding the symbol name in double quotes:
 @example
@@ -888,6 +901,10 @@ the same name as a keyword, by surrounding the symbol name in double quotes:
         "with a space" = "also with a space" + 10;
 @end example
 
+Since symbols can contain many non-alphabetic characters, it is safest
+to delimit symbols with spaces.  For example, @samp{A-B} is one symbol,
+whereas @samp{A - B} is an expression involving subtraction.
+
 @node Location Counter
 @subsection The Location Counter
 @kindex .
@@ -1839,10 +1856,27 @@ use for specialized purposes.  They are similar in purpose to
 command-line options.
 
 @table @code
-@item FLOAT
+@kindex CONSTRUCTORS
+@cindex C++ constructors, arranging in link
+@cindex constructors, arranging in link
+@item CONSTRUCTORS
+This command ties up C++ style constructor and destructor records.  The
+details of the constructor representation vary from one object format to
+another, but usually lists of constructors and destructors appear as
+special sections.  The @code{CONSTRUCTORS} command specifies where the
+linker is to place the data from these sections, relative to the rest of
+the linked output.  Constructor data is marked by the symbol
+@w{@code{__CTOR_LIST__}} at the start, and @w{@code{__CTOR_LIST_END}} at
+the end; destructor data is bracketed similarly, between
+@w{@code{__DTOR_LIST__}} and @w{@code{__DTOR_LIST_END}}.  (The compiler
+must arrange to actually run this code; GNU C++ calls constructors from
+a subroutine @code{__main}, which it inserts automatically into the
+startup code for @code{main}, and destructors from @code{_exit}.)
+
 @kindex FLOAT
-@itemx NOFLOAT
 @kindex NOFLOAT
+@item FLOAT
+@itemx NOFLOAT
 These keywords were used in some older linkers to request a particular
 math subroutine library.  @code{ld} doesn't use the keywords, assuming
 instead that any necessary subroutines are in libraries specified using
@@ -1850,17 +1884,17 @@ the general mechanisms for linking to archives; but to permit the use of
 scripts that were written for the older linkers, the keywords
 @code{FLOAT} and @code{NOFLOAT} are accepted and ignored.
 
-@item FORCE_COMMON_ALLOCATION
 @kindex FORCE_COMMON_ALLOCATION
 @cindex common allocation
+@item FORCE_COMMON_ALLOCATION
 This command has the same effect as the @samp{-d} command-line option:
 to make @code{ld} assign space to common symbols even if a relocatable
 output file is specified (@samp{-r}).
 
-@item INPUT ( @var{file}, @var{file}, @dots{} )
 @kindex INPUT ( @var{files} )
-@itemx INPUT ( @var{file} @var{file} @dots{} )
 @cindex binary input files
+@item INPUT ( @var{file}, @var{file}, @dots{} )
+@itemx INPUT ( @var{file} @var{file} @dots{} )
 Use this command to include binary input files in the link, without
 including them in a particular section definition.  
 Specify the full name for each @var{file}, including @samp{.a} if
@@ -1900,10 +1934,11 @@ command.
 @item OUTPUT_FORMAT ( @var{bfdname} )
 @kindex OUTPUT_FORMAT ( @var{bfdname} )
 @cindex format, output file
-Specify a particular output format, with one of the names used by the
-BFD back-end routines (@pxref{BFD}).  The effect is identical to the
-effect of the @samp{-oformat} command-line option.
-This selection will only affect
+When @code{ld} is configured to support multiple object code formats,
+you can use this command to specify a particular output format.
+@var{bfdname} is one of the names used by the BFD back-end routines
+(@pxref{BFD}).  The effect is identical to the effect of the
+@samp{-oformat} command-line option.  This selection affects only
 the output file; the related command @code{TARGET} affects primarily
 input files.
 @end ifclear
@@ -1926,12 +1961,13 @@ process.
 @item TARGET ( @var{format} )
 @cindex input file format
 @kindex TARGET ( @var{format} )
-Change the input-file object code format (like the command-line option
-@samp{-b} or its synonym @samp{-format}).  The argument @var{format} is
-one of the strings used by BFD to name binary formats.  If @code{TARGET}
-is specified but @code{OUTPUT_FORMAT} is not, the last @code{TARGET}
-argument is also used as the default format for the @code{ld} output
-file.  @xref{BFD}.
+When @code{ld} is configured to support multiple object code formats,
+you can use this command to change the input-file object code format
+(like the command-line option @samp{-b} or its synonym @samp{-format}).
+The argument @var{format} is one of the strings used by BFD to name
+binary formats.  If @code{TARGET} is specified but @code{OUTPUT_FORMAT}
+is not, the last @code{TARGET} argument is also used as the default
+format for the @code{ld} output file.  @xref{BFD}.
 
 @kindex GNUTARGET
 If you don't use the @code{TARGET} command, @code{ld} uses the value of
@@ -2029,6 +2065,18 @@ You can meaningfully use @samp{-A} more than once on a command line, since
 the 960 architecture family allows combination of target architectures; each
 use will add another pair of name variants to search for when @w{@samp{-l}}
 specifies a library.
+
+@cindex @code{-relax} on i960
+@cindex relaxing on i960
+@code{ld} supports the @samp{-relax} option for the i960 family.  If you
+specify @samp{-relax}, @code{ld} finds all @code{balx} and @code{calx}
+instructions whose targets are within 24 bits, and turns them into
+24-bit program-counter relative @code{bal} and @code{cal}
+instructions, respectively.  @code{ld} also turns @code{cal}
+instructions into @code{bal} instructions when it determines that the
+target subroutine is a leaf routine (that is, the target subroutine does
+not itself call any subroutines).
+
 @ifclear GENERIC
 @lowersections
 @end ifclear