Fixed info-markup bugs; makeinfo now succeeds with no complaints.

1 files changed, 1167 insertions, 495 deletions

diff --git a/ld/ld.texinfo b/ld/ld.texinfo
index 5bdbc53..6b37185 100644
--- a/ld/ld.texinfo
+++ b/ld/ld.texinfo
@@ -31,6 +31,8 @@ except that the section entitled ``GNU General Public License'' may be
 included in a translation approved by the author instead of in the
 original English.
 @end ifinfo
+@iftex
+@finalout
 @setchapternewpage odd
 @settitle GLD, the GNU linker
 @titlepage
@@ -39,7 +41,7 @@ original English.
 @sp 1
 @subtitle Second Edition---@code{gld} version 2.0
 @subtitle April 1991
-@author {Steve Chamberlain, Roland Pesch}
+@author {Steve Chamberlain and Roland Pesch}
 @author {Cygnus Support}
 @page
 
@@ -48,9 +50,9 @@ original English.
 \xdef\manvers{\$Revision$}  % For use in headers, footers too
 {\parskip=0pt
 \hfill Cygnus Support\par
+\hfill steve\@cygnus.com, pesch\@cygnus.com\par
 \hfill {\it GLD, the GNU linker}, \manvers\par
 \hfill \TeX{}info \texinfoversion\par
-\hfill steve\@cygnus.com, pesch\@cygnus.com\par
 }
 \global\parindent=0pt % Steve likes it this way.
 @end tex
@@ -70,59 +72,129 @@ permission notice identical to this one.
 Permission is granted to copy and distribute translations of this manual
 into another language, under the above conditions for modified versions.
 @end titlepage
+@end iftex
 @c FIXME: Talk about importance of *order* of args, cmds to linker!
 
-@node Top,,,
+@node Top, Overview, (dir), (dir)
 @ifinfo
 This file documents the GNU linker gld.
 @end ifinfo
 
-@node Overview,,,
+@menu
+* Overview::			Overview
+* Invocation::			Invocation
+* Commands::			Command Language
+* BFD::				BFD
+* Index::			Index
+
+ --- The Detailed Node Listing ---
+
+Invocation
+
+* Options::			Command Line Options
+* Environment::			Environment Variables
+
+Command Language
+
+* Scripts::			Linker Scripts
+* Expressions::			Expressions
+* MEMORY::			MEMORY Command
+* SECTIONS::			SECTIONS Command
+* Entry Point::			The Entry Point
+* Other Commands::		Other Commands
+
+Expressions
+
+* Integers::			Integers
+* Symbols::			Symbol Names
+* Location Counter::		The Location Counter
+* Operators::			Operators
+* Evaluation::			Evaluation
+* Assignment::			Assignment: Defining Symbols
+* Built-ins::			Built-In Functions
+
+SECTIONS Command
+
+* Section Definition::		Section Definitions
+* Section Contents::		Section Contents
+* Section Options::		Optional Section Attributes
+
+BFD
+
+* BFD outline::			How it works: an outline of BFD
+* BFD information loss::	Information Loss
+* Mechanism::			Mechanism 
+@end menu
+
+@node Overview, Invocation, Top, Top
 @chapter Overview
 
+@cindex GNU linker
+@cindex what is this?
 @code{gld} combines a number of object and archive files, relocates
 their data and ties up symbol references. Often the last step in
 building a new compiled program to run is a call to @code{gld}.
 
 @code{gld} accepts Linker Command Language files written in
-a superset of AT@&T's Link Editor Command Language syntax,
+a superset of AT&T's Link Editor Command Language syntax,
 to provide explicit and total control over the linking process.
 
-This version of @code{gld} uses the general purpose @code{bfd} libraries
+This version of @code{gld} uses the general purpose BFD libraries
 to operate on object files. This allows @code{gld} to read, combine, and
 write object files in many different formats---for example, COFF or
 @code{a.out}.  Different formats may be linked together to produce any
 available kind of object file.  @xref{BFD} for a list of formats
 supported on various architectures.
 
-When linking formats with equivalent representations of debugging
-information (typically variations on one format), @code{gld} maintains
-all debugging information.
+Aside from its flexibility, the GNU linker is more helpful than other
+linkers in providing diagnostic information.  Many linkers abandon
+execution immediately upon encountering an error; whenever possible,
+@code{gld} continues executing, allowing you to identify other errors
+(or, in some cases, to get an output file in spite of the error).
+
+@node Invocation, Commands, Overview, Top
+@chapter Invocation
+
+The GNU linker @code{gld} is meant to cover a broad range of situations,
+and to be as compatible as possible with other linkers.  As a result,
+you have many choices to control its behavior through the command line,
+and through environment variables.
+
+@menu
+* Options::			Command Line Options
+* Environment::			Environment Variables
+@end menu
 
-@node Invocation,,,
-@chapter Command line options
+@node Options, Environment, Invocation, Invocation
+@section Command Line Options
+
+@cindex command line
+@cindex options
+Here is a sketch of the options you can use on the @code{gld} command
+line:
 
-@c FIXME: -D, -N, -z, -f from older GNU linker, but not currently in new;
-@c FIXME...steve is currently thinking about whether to add them.  Maybe
-@c FIXME...remove from document.
 @example
 gld [-o @var{output} ] @var{objfiles}@dots{}
-    [ -A@var{architecture} ]  [ -b @var{output-format} ]  [ -Bstatic ]  
-    [ -c @var{commandfile} ]  [ -D @var{datasize} ]  
-    [ -d | -dc | -dp ]  [ -defsym @var{symbol} = @var{expression} ]
-    [ -e @var{entry} ]  [ -f @var{fill} ]  [ -F ]  [ -F @var{format} ]
-    [ -format @var{output-format} ]  [ -g ]  [ -i ]
+    [ -A@var{architecture} ]  [ -b @var{input-format} ]  [ -Bstatic ]  
+    [ -c @var{commandfile} ]  [ -d | -dc | -dp ]  
+    [ -defsym @var{symbol} = @var{expression} ]
+    [ -e @var{entry} ]  [ -F ]  [ -F @var{format} ]
+@c -f was in old GNU linker, not currently in new
+@c   [ -f @var{fill} ]
+    [ -format @var{input-format} ]  [ -g ]  [ -i ]
     [ -l@var{ar} ]  [ -L@var{searchdir} ]  [ -M | -m ]  
-    [ -N | -n | -z ]  [ -noinhibit-exec ]  [ -R @var{filename} ]
-    [ -r | -Ur ]  [ -S ]  [ -s ]  
-    [ SCRIPT  @dots{}  ENDSCRIPT ]  [ SCRIPT  @dots{}  @@ ]
-    [ -T @var{commandfile} ]  
+    [ -n ]  [ -noinhibit-exec ]  [ -R @var{filename} ]
+@c -N and -z were alternatives to -n in old GNU linker, not curr in new
+@c    [ -N | -n | -z ]  [ -noinhibit-exec ]  [ -R @var{filename} ]
+    [ -r | -Ur ]  [ -S ]  [ -s ]  [ -T @var{commandfile} ]  
     [ -Ttext @var{textorg} ]  [ -Tdata @var{dataorg} ]  [ -Tbss @var{bssorg} ]
     [ -t ]  [ -u @var{sym}]  [-v]  [ -X ]  [ -x ] 
+    [ @{ @var{script} @} ] 
 @end example
 
 This plethora of command-line options may seem intimidating, but in
 actual practice few of them are used in any particular context.
+@cindex standard Unix system
 For instance, a frequent use of @code{gld} is to link standard Unix
 object files on a standard, supported Unix system.  On such a system, to
 link a file @code{hello.o}:
@@ -140,300 +212,560 @@ different argument will either have no further effect, or override prior
 occurrences (those further to the left on the command line) of an
 option.  
 
-The exceptions---which may meaningfully be used more than once---
-are @code{-L}, @code{-l}, and @code{-u}.
-@c FIXME: probably some new opts can be repeated meaningfully too.
+The exceptions---which may meaningfully be used more than once---are
+@code{-A}, @code{-b} (or its synonym @code{-format}), @code{-defsym},
+@code{-L}, @code{-l}, @code{-R}, and @code{-u}.
 
+@cindex object files
 The list of object files to be linked together, shown as @var{objfiles},
 may follow, precede, or be mixed in with command-line options; save that
 an @var{objfiles} argument may not be placed between an option flag and
 its argument.
 
-Option arguments must follow the option letter without intervening
+Usually the linker is invoked with at least one object file, but other
+forms of binary input files can also be specified with @code{-l},
+@code{-R}, and the script command language.  If @emph{no} binary input
+files at all are specified, the linker does not produce any output, and
+issues the message @samp{No input files}.
+
+Option arguments must either follow the option letter without intervening
 whitespace, or be given as separate arguments immediately following the
 option that requires them.
 
 @table @code
 @item @var{objfiles}@dots{}
-The object files @var{objfiles} to be linked; at least one must be specified.
+The object files @var{objfiles} to be linked.
 
+@cindex architectures
+@kindex -A@var{arch}
 @item -A@var{architecture}
 In the current release of @code{gld}, this option is useful only for the
-Intel 960 family of architectures.  In that context, the
+Intel 960 family of architectures.  In that @code{gld} configuration, the
 @var{architecture} argument is one of the two-letter names identifying
 members of the 960 family; the option specifies the desired output
 target, and warns of any incompatible instructions in the input files.
-It also selects archive libraries supporting the particular
-architecture; its effect in this regard is similar to that of @code{-l}, save
-that @code{-A}@var{architecture} triggers a two-level search; first for a
-library with exactly the name you specify as @var{architecture}, and if
-that fails, for a library named with the @code{-l} convention---i.e.,
-@samp{lib@var{architecture}.a}.   
+It also modifies the linker's search strategy for archive libraries, to
+support the use of libraries specific to each particular
+architecture, by including in the search loop names suffixed with the
+string identifying the architecture.
+
+For example, if your @code{gld} command line included @w{@samp{-ACA}} as
+well as @w{@samp{-ltry}}, the linker would look (in its built-in search
+paths, and in any paths you specify with @code{-L}) for a library with
+the names
+@example
+try
+libtry.a
+tryca
+libtryca.a
+@end example
+@noindent
+The first two possibilities would be considered in any event; the last
+two are due to the use of @w{@samp{-ACA}}.
 
 Future releases of @code{gld} may support similar functionality for
 other architecture families.
 
-@item -b @var{output-format}
-Specify the desired output-file binary format.  You don't usually need
-to specify this.  @code{gld} can determine
-the format of @emph{input} files by inspection, and---in the most frequent
-case, when all input files have the same format, @code{gld} selects the
-same format for output files by default.  
-
-You can use this option if you need to link a variety of object formats
-together, or if you wish to force a different output format even though
-you have homogeneous input files.
-
-@var{output-format} is a text string, the name of a particular format
-supported by the BFD libraries.  @xref{BFD}.
-
-@code{-format @var{output-format}} has the same effect.
-
+You can meaningfully use @code{-A} more than once on a command line, if
+an architecture family allows combination of target architectures; each
+use will add another pair of name variants to search for when @w{@code{-l}}
+specifies a library.
+
+@cindex binary input format
+@kindex -b @var{format}
+@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{gld} 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.  @xref{BFD}.
+@code{-format @var{input-format}} has the same effect.@refill
+
+You may want to use this option if you are linking files with an unusual
+binary format.  You can also use @code{-b} to switch formats explicitly (when
+linking object files of different formats), by including
+@code{-b @var{input-format}} before each group of object files in a
+particular format.  
+
+The default format is taken from the environment variable
+@code{GNUTARGET}.  @xref{Environment}.  You can also define the input
+format from a script, using the command @code{TARGET}.
+
+@kindex -Bstatic
 @item -Bstatic 
 This flag is accepted for command-line compatibility with the SunOS linker,
 but has no effect on @code{gld}.
 
+@kindex -c @var{cmdfile}
+@cindex script files
 @item -c @var{commandfile}
 Directs @code{gld} to read link commands from the file
-@var{commandfile}.  These commands will override @code{gld}'s
-default link format in its entirety; @var{commandfile} must specify
-everything necessary to specify the target format.  @xref{Commands}.
+@var{commandfile}.  These commands will completely override @code{gld}'s
+default link format (rather than adding to it); @var{commandfile} must
+specify everything necessary to describe the target format.
+@xref{Commands}.
 
 You may also include a script of link commands directly in the command
-line by using the @code{SCRIPT} @dots{} @code{ENDSCRIPT} keywords.
-
-@c FIXME: -D in older GNU linker, not necessarily in new
-@item -D @var{datasize}
-Use this option to specify a target size for the @code{data} segment of
-your linked program.  The option is only obeyed if @var{datasize} is
-larger than the natural size of the program's @code{data} segment.
-
-@var{datasize} must be an integer specified in hexadecimal.
-
-@code{ld} will simply increase the size of the @code{data} segment,
-padding the created gap with zeros (or a fill pattern specified with
-@samp{-f}, or using the command language), and reduce the size of the
-@code{bss} segment by the same amount.
-@c FIXME: double-check this w/Steve.  Open questions: order? Does it
-@c FIXME...matter whether -f before or after -D?  What about -c relative
-@c FIXME...position? fill cmd in default script? Apparently
-@c FIXME...can have multiple fill patterns; which used here?
-
+line by bracketing it between @samp{@{} and @samp{@}} characters.
 
+@cindex common allocation
+@kindex -d
 @item -d 
+@kindex -dc
 @itemx -dc
+@kindex -dp
 @itemx -dp
 These three options are equivalent; multiple forms are supported for
-compatibility with other linkers.  Any of them options will force
-@code{ld} to assign space to common symbols even if a relocatable output
-file is specified (@code{-r}).
+compatibility with other linkers.  Use any of them to make @code{ld}
+assign space to common symbols even if a relocatable output file is
+specified (@code{-r}).  The script command
+@code{FORCE_COMMON_ALLOCATION} has the same effect.
 
+@cindex symbols, from command line
+@kindex -defsym @var{symbol}=@var{exp}
 @item -defsym @var{symbol} = @var{expression}
-Create a global symbol, in the output file, set to the absolute address
-given by @var{expression}.  A limited form of arithmetic is supported
-for the @var{expression} in this context: you may give a hexadecimal
-constant, or use @code{+} and @code{-} to add or subtract hexacedimal
-constants.  If you need more elaborate expressions, consider using the
-linker command language from a script.
-
+Create a global symbol in the output file, containing the absolute
+address given by @var{expression}.  You may use this option as many
+times as necessary to define multiple symbols in the command line.  A
+limited form of arithmetic is supported for the @var{expression} in this
+context: you may give a hexadecimal constant or the name of an existing
+symbol, or use @code{+} and @code{-} to add or subtract hexadecimal
+constants or symbols.  If you need more elaborate expressions, consider
+using the linker command language from a script.
+
+@cindex entry point, from command line
+@kindex -e @var{entry}
 @item -e @var{entry} 
 Use @var{entry} as the explicit symbol for beginning execution of your
 program, rather than the default entry point. @xref{Entry Point}, for a
 discussion of defaults and other ways of specifying the
 entry point.
 
-@c FIXME: -f in older GNU linker, not necessarily in new
+@ignore
+@cindex fill, from command line
+@kindex -f @var{fill}
+@c -f in older GNU linker, not in new
 @item -f @var{fill}
 Sets the default fill pattern for ``holes'' in the output file to
-the lowest two bytes of the expression specified.
+the lowest two bytes of the expression specified.  Holes are created
+when you advance the location counter (@xref{Location Counter}), or when
+there is a gap between explicitly specified section addresses
+(@xref{Section Options}).
+@end ignore
 
+@kindex -F
 @item -F
-@itemx -F{format}
-Some older linkers required the specification of object-file format,
-even when all input files were homogeneous, and used this option for
-that purpose.  @code{gld} doesn't usually require this information---it
-automatically recognizes input-file object format---but it accepts the
-option flag for compatibility with old scripts.  
-
-@item -format @var{output-format}
-Synonym for @code{-b} @var{output-format}.
-
+@itemx -F@var{format}
+Some older linkers used this option throughout a compilation toolchain
+for specifying object-file format for both input and output object
+files.  @code{gld}'s mechanisms (the @code{-b} or @code{-format} options
+for input files, the @code{TARGET} command in linker scripts for output
+files, the @code{GNUTARGET} environment variable) are more flexible, but
+but it accepts (and ignores) the @code{-F} option flag for compatibility
+with scripts written to call the old linker.
+
+@kindex -format
+@item -format @var{input-format}
+Synonym for @code{-b} @var{input-format}.
+
+@kindex -g
 @item -g
 Accepted, but ignored; provided for compatibility with other tools.
 
+@kindex -i
+@cindex incremental link
 @item -i
-Produce an incremental link (same as option @code{-r}).
+Perform an incremental link (same as option @code{-r}).
 
+@cindex archive files, from cmd line
+@kindex -l@var{ar}
 @item -l@var{ar} 
 Add an archive file @var{ar} to the list of files to link.  This 
 option may be used any number of times.  @code{ld} will search its
 path-list for occurrences of @code{lib@var{ar}.a} for every @var{ar}
 specified.
 
-@c FIXME: -l also has a side effect of using the "c++ demangler" if we happen
-@c FIXME...to specify -llibg++.  Document?  pesch@@cygnus.com, 24jan91
-
+@cindex search directory, from cmd line
+@kindex -L@var{dir}
 @item -L@var{searchdir} 
 This command adds path @var{searchdir} to the list of paths that
 @code{gld} will search for archive libraries.  You may use this option
 any number of times.
 
-@c Should we make any attempt to list the standard paths searched
-@c without listing?  When hacking on a new system I often want to know
-@c this, but this may not be the place... it's not constant across
-@c systems, of course, which is what makes it interesting.
-@c pesch@@cygnus.com, 24jan91.
+The default set of paths searched (without being specified with
+@code{-L}) depends on what emulation mode @code{gld} is using, and in
+some cases also on how it was configured.  @xref{Environment}.  The
+paths can also be specified in a link script with the @code{SEARCH_DIR}
+command.
 
+@cindex link map
+@kindex -M
 @item -M 
+@kindex -m
 @itemx -m
 Print (to the standard output file) a link map---diagnostic information
 about where symbols are mapped by @code{ld}, and information on global
 common storage allocation.
 
-@c FIXME: -N in older GNU linker, not necessarily in new
+@ignore
+@c -N in older GNU linker, not in new
+@kindex -N
+@cindex read/write from cmd line
+@kindex OMAGIC
 @item -N 
 specifies readable and writable @code{text} and @code{data} sections. If
 the output format supports Unix style magic numbers, the output is
 marked as @code{OMAGIC}.
+@end ignore
 
 @item -n 
+@kindex -n
+@cindex read-only text
+@kindex NMAGIC
 sets the text segment to be read only, and @code{NMAGIC} is written
 if possible.
 
 @item -noinhibit-exec
+@cindex output file after errors
+@kindex -noinhibit-exec
 Normally, the linker will not produce an output file if it encounters
 errors during the link process.  With this flag, you can specify that
-you wish the output file retained for even after non-fatal errors.
+you wish the output file retained even after non-fatal errors.
 
 @item -o @var{output}
+@kindex -o @var{output}
+@cindex naming the output file
 @var{output} is a name for the program produced by @code{ld}; if this
-option is not specified, the name @samp{a.out} is used by default.
+option is not specified, the name @samp{a.out} is used by default.  The
+script command @code{OUTPUT} can also specify the output file name.
 
 @item -R @var{filename}
+@kindex -R @var{file}
+@cindex symbol-only input
 Read symbol names and their addresses from @var{filename}, but do not
 relocate it or include it in the output.  This allows your output file
 to refer symbolically to absolute locations of memory defined in other
 programs.
-@c FIXME: -R accurate?  Motivation?  Kernel memory, shared mem?
 
 @item -r 
 @cindex partial link
+@cindex relocatable output
+@kindex -r
 Generates relocatable output---i.e., generate an output file that can in
 turn serve as input to @code{gld}.  This is often called @dfn{partial
-linking}.  As a side effect, this option also sets the output file's
-magic number to @code{OMAGIC}; see @samp{-N}. If this option is not
-specified, an absolute file is produced.  When linking C++ programs,
-this option @emph{will not} resolve references to constructors;
-@samp{-Ur} is an alternative.
+linking}.  As a side effect, in environments that support standard Unix
+magic numbers, this option also sets the output file's magic number to
+@code{OMAGIC}.
+@c ; see @code{-N}. 
+If this option is not specified, an absolute file is produced.  When
+linking C++ programs, this option @emph{will not} resolve references to
+constructors; @code{-Ur} is an alternative. @refill
+
+This option does the same as @code{-i}.
 
 @item -S 
+@kindex -S
+@cindex strip debugger symbols
 Omits debugger symbol information (but not all symbols) from the output file.
 
 @item -s 
+@kindex -s
+@cindex strip all symbols
 Omits all symbol information from the output file.
 
-@item SCRIPT  @dots  @@
-@itemx SCRIPT  @dots  ENDSCRIPT
+@item @{ @var{script} @}
+@kindex @{ @var{script} @}
+@cindex scripts on command line
 You can, if you wish, include a script of linker commands directly in
 the command line instead of referring to it via an input file.  When the
-keyword @code{SCRIPT} occurs on the command line, the linker switches to
+character @samp{@{} occurs on the command line, the linker switches to
 interpreting the command language until the end of the list of commands
-is reached---flagged with either an at sign @samp{@@} or with the
-keyword @code{ENDSCRIPT}.  Other command-line options will not be
-recognized while parsing the script.  @xref{Commands} for a description
-of the command language.
-
-@item -Tbss @var{bssorg}
-@itemx -Tdata @var{dataorg}
-@itemx -Ttext @var{textorg}
-Use @var{textorg} as the starting address for---respectively---the
+is reached---flagged with a closing brace @samp{@}}.  Other command-line
+options will not be recognized while parsing the script.
+@xref{Commands} for a description of the command language.
+
+@item -Tbss @var{org}
+@kindex -Tbss @var{org}
+@itemx -Tdata @var{org}
+@kindex -Tdata @var{org}
+@itemx -Ttext @var{org}
+@kindex -Ttext @var{org}
+@cindex segment origins, cmd line
+Use @var{org} as the starting address for---respectively---the
 @code{bss}, @code{data}, or the @code{text} segment of the output file.
 @var{textorg} must be a hexadecimal integer.
 
 @item -T @var{commandfile}
 @itemx -T@var{commandfile}
+@kindex -T @var{script}
 Equivalent to @code{-c @var{commandfile}}; supported for compatibility with
 other tools.  
 
 @item -t 
+@kindex -t
+@cindex verbose
+@cindex input files, displaying
 Prints names of input files as @code{ld} processes them.
 
 @item -u @var{sym}
+@kindex -u @var{sym}
+@cindex undefined symbol
 Forces @var{sym} to be entered in the output file as an undefined symbol.
 This may, for example, trigger linking of additional modules from
 standard libraries.  @code{-u} may be repeated with different option
-arguments to enter additional undefined symbols. This option is equivalent
-to the @code{EXTERN} linker command.
+arguments to enter additional undefined symbols.
+@c Nice idea, but no such command: This option is equivalent
+@c to the @code{EXTERN} linker command.
 
 @item -Ur 
+@kindex -Ur
 @cindex constructors
 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{gld}.  When linking C++ programs, @samp{-Ur}
-@emph{will} resolve references to constructors, unlike @samp{-r}.
+@code{-r}: it generates relocatable output---i.e., an output file that can in
+turn serve as input to @code{gld}.  When linking C++ programs, @code{-Ur}
+@emph{will} resolve references to constructors, unlike @code{-r}.
 
 @item -v
+@kindex -v
 @cindex version
-@cindex verbose
-``Verbose'' switch: display informative messages, including the version
-numbers for @code{gld} and BFD, information on files opened, and BFD
-subroutine calls.
+Display the version number for @code{gld}.
 
 @item -X 
+@kindex -X
+@cindex local symbols, deleting
+@cindex L, deleting symbols beginning
 If @code{-s} or @code{-S} is also specified, delete only local symbols
 beginning with @samp{L}.
 
 @item -x
+@kindex -x
+@cindex deleting local symbols
 If @code{-s} or @code{-S} is also specified, delete all local symbols,
 not just those beginning with @samp{L}.
 
-@c FIXME: -z in older GNU linker, not necessarily in new
+@ignore
+@c  -z in older GNU linker, not in new
 @item -z
+@kindex -z
+@cindex read-only text
 Specifies a read-only, demand pageable, and shared @code{text} segment.
 If the output format supports Unix-style magic numbers, @code{-z} also
 marks the output as @code{ZMAGIC}, the default.
 
-@c FIXME: why is following here?.  Is it useful to say '-z -r' for
-@c FIXME...instance, or is this just a ref to other ways of setting
-@c FIXME...magic no?
+@c why was following here?.  Is it useful to say '-z -r' for
+@c instance, or is this just a ref to other ways of setting
+@c magic no?
 Specifying a relocatable output file (@code{-r}) will also set the magic
 number to @code{OMAGIC}.
 
-See description of @samp{-N}.
+See description of @code{-N}.
+@end ignore
 
 @end table
 
-@node Commands,,,
-@chapter Command Language
-@c FIXME: is this a good place to talk about LDEMULATION env var?
-@c FIXME...Apparently some commands "subtly different" depending on
-@c FIXME...whether this set to eg "link960", "gld960", "gld".  What is
-@c FIXME...full set of possibilities, what is default?  Config-dep?
+@node Environment,  , Options, Invocation
+@section Environment Variables
+
+@code{gld} always consults two environment variables: @code{GNUTARGET}
+and @code{LDEMULATION}.  Depending on the setting of the latter, other
+environment variables may be used as well.
+
+@kindex GNUTARGET
+@cindex default input format
+@code{GNUTARGET} determines the input-file object format if you don't
+use @code{-b} (or its synonym @code{-format}).  Its value should be one
+of the BFD names for an input format (@pxref{BFD}).  If there is no
+@code{GNUTARGET} in the environment, @code{gld} uses the natural format
+of the host. If @code{GNUTARGET} is set to @code{default} then BFD attempts to discover the
+input format by examining binary input files; this method often
+succeeds, but there are potential ambiguities, since there is no method
+of ensuring that the magic number used to flag object-file formats is
+unique.  However, the configuration procedure for BFD on each system
+places the conventional format for that system first in the search-list,
+so ambiguities are resolved in favor of convention.
+
+@kindex LDEMULATION
+@cindex emulation
+@cindex environment vars
+@code{LDEMULATION} controls some aspects of @code{gld}'s dominant
+personality.  Although @code{gld} is flexible enough to permit its use
+in many contexts regardless of configuration, you can use this variable
+to make it act more like one or another older linker by default.
+
+@cindex defaults
+@cindex library paths, default
+In particular, the value of @code{LDEMULATION} controls what default
+linker script is used (thereby controlling the default input and output
+formats; @pxref{BFD}); what default paths are searched for
+archive libraries; and in some cases whether additional linker script
+commands are available.
+
+Here is the current set of emulations available:
+@table @code
+
+@item LDEMULATION=gld
+@kindex gld
+@cindex emulating old GNU linker
+Emulate the older GNU linker.  When this emulation is selected, the
+default library search paths are
+@example
+/lib
+/usr/lib
+/usr/local/lib/lib
+@end example
+@noindent
+The default output format is set to @code{a.out-generic-big}, and the
+default machine is the system's configured BFD default.
+
+@item LDEMULATION=gld68k
+@kindex gld68k
+@cindex m68k
+A variant of the @code{gld} emulation; only differs in specifically
+setting the default BFD machine as @code{m68k}.
+
+@item LDEMULATION=gld960
+@kindex gld960
+@kindex G960LIB
+@kindex G960BASE
+@cindex i960
+Emulate the Intel port of the older @code{gld} for the i960
+architectures.  The default library search paths are taken from two
+other environment variables, @code{G960LIB} and @code{G960BASE}.  The
+default architecture is @code{i960}.  The default output format is set
+to @code{b.out.big}, and in fact the default output file name (if
+@code{-o} is not specified) is @code{b.out}, to reflect this variant
+format, for this emulation.
+
+@kindex GNU960
+This emulation can behave slightly differently depending on the setting
+of the @code{gld} compile-time switch @code{GNU960}.  If @code{gld} is
+compiled with @code{GNU960} defined, then an additional environment
+variable---@code{GNUTARGET}---is available; its value, if available,
+specifies some other default output format than @code{b.out.big}.
+
+@item LDEMULATION=gldm88kbcs
+@kindex gldm88kbcs
+@cindex m88k
+Sets the output format to @code{m88kbcs} and the architecture to
+@code{m88k}.  Default library search paths are
+@example
+/lib
+/usr/lib
+/usr/local/lib
+@end example
 
+@item LDEMULATION=lnk960
+@kindex lnk960
+@cindex i960
+@cindex Architectures, i960 family
+Emulate the Intel linker @code{lnk960}.  The default output format is
+@code{coff-Intel-big}.  With this emulation, @code{gld}
+supports the additional script commands @code{HLL} and @code{SYSLIB} for
+specification of library archives.  This is the only emulation with
+extensive support for the @code{-A} (architecture) command-line option.
+By default, the architecture @code{CORE} is assumed, but you can choose
+additional features from the i960 architecture family by using one of
+the following with @code{-A} (or by using the @code{OUTPUT_ARCH} command
+from a script):
+@example
+CORE
+KB
+SB
+MC
+XA
+CA
+KA
+SA
+@end example
+
+The default libraries are chosen with some attention to the architecture
+selected; the core library @file{cg} is always included, but the library
+@code{fpg} is also used if you've specified any of the architectures
+@code{KA}, @code{SA}, or @code{CA}.
+
+@kindex GNU960
+Like @code{gld960}, this emulation uses additional environment variables
+to set the default library search paths.  Also like @code{gld960}, the
+behavior of this emulation is slightly different depending on whether
+@code{gld} itself was compiled with @code{GNU960} defined.
+
+@kindex G960BASE
+@kindex G960LIB
+@kindex I960BASE
+If your @code{gld} was compiled with @code{GNU960} defined, the default
+paths are taken from all three of @code{G960LIB}, @code{G960BASE}, and
+@code{I960BASE}.  For the first two, paths you supply are automatically
+suffixed with @samp{/lib/libcoff}; for the last, your path is
+automatically suffixed with @samp{/lib}.
+
+If your @code{gld} was @emph{not} compiled with @code{GNU960} defined,
+the default paths are taken from @code{I960BASE}, and @code{G960BASE} is
+only consulted if @code{I960BASE} is undefined.  In this case
+@code{G960LIB} is not used at all.
+
+@item LDEMULATION=vanilla
+@kindex vanilla
+@cindex emulation, disabling
+@cindex disabling emulation
+This is the least specific setting for @code{gld}.  You can set
+@code{LDEMULATION=vanilla} to disable emulation of other linkers.  This
+setting makes @code{gld} take the default machine from the BFD
+configuration on your system; @code{a.out-generic-big} is the default
+target.  No other defaults are specified.
+
+@end table
+
+@node Commands, BFD, Invocation, Top
+@chapter Command Language
 
+@cindex command files
 The command language allows explicit control over the link process,
 allowing complete specification of the mapping between the linker's
 input files and its output.  This includes:
 @itemize @bullet
-@item input files 
-@item file formats
-@item output file format
-@item addresses of sections
-@item placement of common blocks
+@item 
+input files 
+@item 
+file formats
+@item 
+output file format
+@item 
+addresses of sections
+@item 
+placement of common blocks
 @end itemize
 
-A command file may be supplied to the linker, either explicitly through
-the @code{-c} option, or implicitly as an ordinary file. If the linker
-opens a file which it cannot recognize as a supported object or archive
-format, it tries to interpret the file as a command file.
-
-@node Scripts,,,
+You may supply a command file (also known as a link script) to the
+linker either explicitly through the @code{-c} option, or implicitly as
+an ordinary file. If the linker opens a file which it cannot recognize
+as a supported object or archive format, it tries to interpret the file
+as a command file.
+
+You can also include a script directly on the @code{gld} command line,
+delimited by the characters @samp{@{} and @samp{@}}.
+
+@menu
+* Scripts::			Linker Scripts
+* Expressions::			Expressions
+* MEMORY::			MEMORY Command
+* SECTIONS::			SECTIONS Command
+* Entry Point::			The Entry Point
+* Other Commands::		Other Commands
+@end menu
+
+@node Scripts, Expressions, Commands, Commands
 @section Linker Scripts
 The @code{gld} command language is a collection of statements; some are
 simple keywords setting a particular flag, some are used to select and
 group input files or name output files; and two particular statement
 types have a fundamental and pervasive impact on the linking process.
 
+@cindex fundamental script commands
+@cindex commands, fundamental
+@cindex output file layout
+@cindex layout of output file
 The most fundamental command of the @code{gld} command language is the
 @code{SECTIONS} command (@pxref{SECTIONS}).  Every meaningful command
 script must have a @code{SECTIONS} command: it specifies a
@@ -441,50 +773,84 @@ script must have a @code{SECTIONS} command: it specifies a
 No other command is required in all cases.
 
 The @code{MEMORY} command complements @code{SECTIONS} by describing the
-available memory in the target architecture; if it is not present,
-sufficient memory is assumed to be available in a contiguous block for
-all output.  @xref{MEMORY}.
+available memory in the target architecture.  This command is optional;
+if you don't use a @code{MEMORY} command, @code{gld} assumes sufficient
+memory is available in a contiguous block for all output.
+@xref{MEMORY}.
 
-@node Expressions,,,
+@cindex comments
+You may include comments in linker scripts just as in C: delimited
+by @samp{/*} and @samp{*/}.  As in C, comments are syntactically
+equivalent to whitespace.
+
+@node Expressions, MEMORY, Scripts, Commands
 @section Expressions
+@cindex expression syntax
+@cindex arithmetic
 Many useful commands involve arithmetic expressions.  The syntax for
 expressions in the command language is identical to that of C
 expressions, with the following features:
 @itemize @bullet
-@item All expressions evaluated as integers and
+@item 
+All expressions evaluated as integers and
 are of ``long'' or ``unsigned long'' type.
-@item All constants are integers.
-@item All of the C arithmetic operators are provided.
-@item Global variables may be referenced, defined and created.
-@item Built in functions may be called.
+@item 
+All constants are integers.
+@item 
+All of the C arithmetic operators are provided.
+@item 
+You may reference, define, and create global variables.
+@item 
+You may call special purpose built-in functions.
 @end itemize
 
-@node Integers,,,
+@menu
+* Integers::			Integers
+* Symbols::			Symbol Names
+* Location Counter::		The Location Counter
+* Operators::			Operators
+* Evaluation::			Evaluation
+* Assignment::			Assignment: Defining Symbols
+* Built-ins::			Built-In Functions
+@end menu
+
+@node Integers, Symbols, Expressions, Expressions
 @subsection Integers
+@cindex integer notation
+@cindex octal integers
 An octal integer is @samp{0} followed by zero or more of the octal
 digits (@samp{01234567}).
 @example
+_as_octal = 0157255;
 @end example
 
+@cindex decimal integers
 A decimal integer starts with a non-zero digit followed by zero or
 more digits (@samp{0123456789}).
 @example
-_as_octal = 0157255;
+_as_decimal = 57005;
 @end example
 
+@cindex hexadecimal integers
+@kindex 0x
 A hexadecimal integer is @samp{0x} or @samp{0X} followed by one or
 more hexadecimal digits chosen from @samp{0123456789abcdefABCDEF}.
 @example
 _as_hex = 0xdead;
 @end example
 
-Decimal integers have the usual values.  To denote a negative integer, use
+@cindex negative integers
+Decimal integers have the usual values.  To write a negative integer, use
 the prefix operator @samp{-}; @pxref{Operators}.
 @example
-_as_decimal = 57005;
 _as_neg = -57005;
 @end example
 
+@cindex scaled integers
+@cindex K and M integer suffixes
+@cindex M and K integer suffixes
+@cindex suffixes for integers
+@cindex integer suffixes
 Additionally the suffixes @code{K} and @code{M} may be used to scale a
 constant by 
 @tex
@@ -496,15 +862,19 @@ ${\rm 1024}$ or ${\rm 1024}^2$
 respectively. For example, the following all refer to the same quantity:@refill
 
 @example
-        _4k_1 = 4K;
-        _4k_2 = 4096;
-        _4k_3 = 0x1000;
+        _fourk_1 = 4K;
+        _fourk_2 = 4096;
+        _fourk_3 = 0x1000;
 @end example
 
-@node Symbols,,,
+@node Symbols, Location Counter, Integers, Expressions
 @subsection Symbol Names
+@cindex symbol names
+@cindex names
+@cindex quoted symbol names
+@kindex "
 Unless quoted, symbol names start with a letter, underscore, point or
-minus sign and may include any letters, underscores, digits, points,
+hyphen and may include any letters, underscores, digits, points,
 and minus signs.  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:
@@ -513,7 +883,12 @@ the same name as a keyword, by surrounding the symbol name in double quotes:
         "with a space" = "also with a space" + 10;
 @end example
 
+@node Location Counter, Operators, Symbols, Expressions
 @subsection The Location Counter
+@kindex .
+@cindex dot
+@cindex location counter
+@cindex current output location
 The special linker variable @dfn{dot} @samp{.} always contains the
 current output location counter. Since the @code{.} always refers to
 a location in an output section, it must always appear in an
@@ -521,41 +896,41 @@ expression within a @code{SECTIONS} command. The @code{.} symbol
 may appear anywhere that an ordinary symbol is allowed in an
 expression, but its assignments have a side effect. Assigning a value
 to the @code{.} symbol will cause the location counter to be moved.
+@cindex holes
 This may be used to create holes in the output section.  The location
 counter may never be moved backwards.
 @example
-        SECTIONS
+SECTIONS
+@{
+        output :
         @{
-                output :
-                @{
-                file1(.text)
-                . = . + 1000;
-                file2(.text)
-                . += 1000;
-                file3(.text)
-                . -= 32;
-                file4(.text)
-                @} = 0x1234;
-        @}
+        file1(.text)
+        . = . + 1000;
+        file2(.text)
+        . += 1000;
+        file3(.text)
+        @} = 0x1234;
+@}
 @end example
-In the previous example, @code{file1} is located at the beginning of
-the output section, then there is a 1000 byte gap, filled with 0x1234.
-Then @code{file2} appears, also with a 1000 byte gap following before
-@code{file3} is loaded. Then the first 32 bytes of @code{file4} are
-placed over the last 32 bytes of @code{file3}.
+@noindent
+In the previous example, @code{file1} is located at the beginning of the
+output section, then there is a 1000 byte gap.  Then @code{file2}
+appears, also with a 1000 byte gap following before @code{file3} is
+loaded.  The notation @samp{= 0x1234} specifies what data to write in
+the gaps (@pxref{Section Options}).
 
-@node Operators,,,
+@node Operators, Evaluation, Location Counter, Expressions
 @subsection Operators
+@cindex Operators for arithmetic
+@cindex arithmetic operators
+@cindex precedence in expressions
 The linker recognizes  the standard C set of arithmetic operators, with
 the standard bindings and precedence levels:
-@c FIXME: distinguish somehow between prefix, infix in operator table!
-@c FIXME: is it fair to include assignments below?  Don't they
-@c FIXME...require trailing ; when no other exprs do?
 @ifinfo
 @example
-precedence	associativity	Operators
+precedence	associativity	Operators                Notes
 (highest)
-1		left		!  -  ~
+1		left		!  -  ~                  (1)
 2		left		*  /  %
 3		left		+  -
 4		left		>>  <<
@@ -565,52 +940,55 @@ precedence	associativity	Operators
 8		left		&&
 9		left		||
 10		right		? :
-11		right		&=  +=  -=  *=  /=
+11		right		&=  +=  -=  *=  /=       (2)
 (lowest)
 @end example
+Notes:
+(1) Prefix operators 
+(2) @xref{Assignment}
 @end ifinfo
-@c FIXME: simplify, debug TeX form of this table!
 @tex
-
-\vbox{\offinterlineskip
+\vskip \baselineskip
+%"lispnarrowing" is the extra indent used generally for @example
+\hskip\lispnarrowing\vbox{\offinterlineskip
 \hrule
 \halign
-{\vrule#&\hfil#\hfil&\vrule#&\hfil#\hfil&\vrule#&\hfil#\hfil&\vrule#\cr
-height2pt&&&&&\cr
-&Level&&  associativity  &&Operators&\cr
-height2pt&&&&&\cr
+{\vrule#&\strut\hfil\ #\ \hfil&\vrule#&\strut\hfil\ #\ \hfil&\vrule#&\strut\hfil\ {\tt #}\ \hfil&\vrule#\cr
+height2pt&\omit&&\omit&&\omit&\cr
+&Precedence&&  Associativity  &&{\rm Operators}&\cr
+height2pt&\omit&&\omit&&\omit&\cr
 \noalign{\hrule}
-height2pt&&&&&\cr
+height2pt&\omit&&\omit&&\omit&\cr
 &highest&&&&&\cr
-&1&&left&&$ ! -         ~$&\cr
-height2pt&&&&&\cr
-&2&&left&&*        /        \%&\cr
-height2pt&&&&&\cr
-&3&&left&&+        -&\cr
-height2pt&&&&&\cr
-&4&&left&&$>> <<$&\cr
-height2pt&&&&&\cr
-&5&&left&&$==        !=        > < <= >=$&\cr
-height2pt&&&&&\cr
+% '176 is tilde, '~' in tt font
+&1&&left&&\qquad-          \char'176\      !\qquad\dag&\cr 
+&2&&left&&*          /        \%&\cr
+&3&&left&&+          -&\cr
+&4&&left&&>>         <<&\cr
+&5&&left&&==         !=       >      <      <=      >=&\cr
 &6&&left&&\&&\cr
-height2pt&&&&&\cr
 &7&&left&&|&\cr
-height2pt&&&&&\cr
 &8&&left&&{\&\&}&\cr
-height2pt&&&&&\cr
 &9&&left&&||&\cr
-height2pt&&&&&\cr
-&10&&right&&? :&\cr
-height2pt&&&&&\cr
-&11&&right&&$${\&=        +=        -=        *=        /=}&\cr
+&10&&right&&?        :&\cr
+&11&&right&&\qquad\&=      +=       -=     *=     /=\qquad\ddag&\cr
 &lowest&&&&&\cr
-height2pt&&&&&\cr}
+height2pt&\omit&&\omit&&\omit&\cr}
 \hrule}
 @end tex
+@iftex
+{
+@obeylines@parskip=0pt@parindent=0pt
+@dag@quad Prefix operators.
+@ddag@quad @xref{Assignment}.
+}
+@end iftex
 
-@node Evaluation,,,
+@node Evaluation, Assignment, Operators, Expressions
 @subsection Evaluation
 
+@cindex lazy evaluation
+@cindex expression evaluation order
 The linker uses ``lazy evaluation'' for expressions; it only calculates
 an expression when absolutely necessary.  The linker needs the value of
 the start address, and the lengths of memory regions, in order to do any
@@ -621,14 +999,17 @@ values are evaluated later, when other information (such as the sizes of
 output sections) is available for use in the symbol assignment
 expression.
 
-@node Assignment,,,
+@node Assignment, Built-ins, Evaluation, Expressions
 @subsection Assignment: Defining Symbols
-
+@cindex assignment in scripts
+@cindex symbol definition, scripts
+@cindex variables, defining
 You may create global symbols, and assign values (addresses) to global
 symbols, using any of the C assignment operators:
 
 @table @code
 @item @var{symbol}  = @var{expression} ;
+@itemx @var{symbol} &= @var{expression} ;
 @itemx @var{symbol} += @var{expression} ;
 @itemx @var{symbol} -= @var{expression} ;
 @itemx @var{symbol} *= @var{expression} ;
@@ -638,17 +1019,25 @@ symbols, using any of the C assignment operators:
 Two things distinguish assignment from other operators in @code{gld}
 expressions.
 @itemize @bullet
-@item Assignment may only be used at the root of an expression;
+@item 
+Assignment may only be used at the root of an expression;
 @samp{a=b+3;} is allowed, but @samp{a+b=3;} is an error.
-@item A trailing semicolon is required at the end of an assignment
+
+@kindex ;
+@cindex semicolon
+@item 
+A trailing semicolon is required at the end of an assignment
 statement. 
 @end itemize
 
 Assignment statements may appear:
 @itemize @bullet
-@item as commands in their own right in a @code{gld} script; or
-@item as independent statements within a @code{SECTIONS} command; or
-@item as part of the contents of a section definition in a
+@item 
+as commands in their own right in a @code{gld} script; or
+@item 
+as independent statements within a @code{SECTIONS} command; or
+@item 
+as part of the contents of a section definition in a
 @code{SECTIONS} command.
 @end itemize
 
@@ -656,117 +1045,183 @@ The first two cases are equivalent in effect---both define a symbol with
 an absolute address; the last case defines a symbol whose address is
 relative to a particular section (@pxref{SECTIONS}).
 
-When a linker expression is evaluated and assigned to a variable it is given
-either an absolute or a relocatable type. An absolute expression type
-is one in which the symbol contains the value that it will have in the
-output file, a relocateable expression type is one in which the value
-is expressed as a fixed offset from the base of a section.
+@cindex absolute and relocatable symbols
+@cindex relocatable and absolute symbols
+@cindex symbols, relocatable and absolute
+When a linker expression is evaluated and assigned to a variable, it is
+given either an absolute or a relocatable type. An absolute expression
+type is one in which the symbol contains the value that it will have in
+the output file, a relocateable expression type is one in which the
+value is expressed as a fixed offset from the base of a section.
 
 The type of the expression is controlled by its position in the script
-file. A symbol assigned within a @code{SECTION} specification is
-created relative to the base of the section, a symbol assigned in any
-other place is created as an absolute symbol. Since a symbol created
-within a @code{SECTION} specification is relative to the base of the
-section it will remain relocatable if relocatable output is requested.
-A symbol may be created with an absolute value even when assigned to
-within a @code{SECTION} specification by using the absolute assignment
-function @code{ABSOLUTE} For example, to create an absolute symbol
-whose address is the last byte of the output section @code{.data}:
+file.  A symbol assigned within a section definition is created relative
+to the base of the section; a symbol assigned in any other place is
+created as an absolute symbol. Since a symbol created within a
+section definition is relative to the base of the section, it
+will remain relocatable if relocatable output is requested.  A symbol
+may be created with an absolute value even when assigned to within a
+section definition by using the absolute assignment function
+@code{ABSOLUTE}.  For example, to create an absolute symbol whose address
+is the last byte of an output section named @code{.data}:
 @example
+SECTIONS@{ @dots{}
 .data : 
         @{
                 *(.data)
                 _edata = ABSOLUTE(.) ;
         @} 
+@dots{} @}
 @end example
 
-The linker tries to put off the evaluation of an assignment until
-all the terms in the source expression are known (@pxref{Evaluation}).
-For instance the sizes of sections cannot be known until after
-allocation, so assignments dependent upon these are not performed until
-after allocation. Some expressions, such as those depending upon the
-location counter @dfn{dot}, @samp{.} must be evaluated during
-allocation. If the result of an expression is required, but the value is
-not available, then an error results.  For example, attempting to use a
-script like the following
+The linker tries to put off the evaluation of an assignment until all
+the terms in the source expression are known (@pxref{Evaluation}).  For
+instance the sizes of sections cannot be known until after allocation,
+so assignments dependent upon these are not performed until after
+allocation. Some expressions, such as those depending upon the location
+counter @dfn{dot}, @samp{.} must be evaluated during allocation. If the
+result of an expression is required, but the value is not available,
+then an error results.  For example, a script like the following
 @example
-SECTIONS @{
+SECTIONS @{ @dots{}
       text 9+this_isnt_constant: 
                 @{ @dots{}
                 @}
-        @}
+@dots{} @}
 @end example
-will get the error message ``@code{Non constant expression for initial
+@kindex Non constant expression
+@noindent
+will cause the error message ``@code{Non constant expression for initial
 address}''. 
 
-@node Builtins,,,
-@subsection Built in Functions
-The command language provides built in functions for use in
-expressions in link scripts.
-@itemize @bullet 
-@item @code{ALIGN(@var{exp})}
-returns the result of the current location counter (@code{.}) aligned to
-the next @var{exp} boundary.  @var{exp} must be an expression whose
-value is a power of two.  This is equivalent to @samp{(. + @var{exp} -1)
-& ~(@var{exp}-1)}.  As an example, to align the output @code{.data}
-section to the next 0x2000 byte boundary after the preceding section and
-to set a variable within the section to the next 0x8000 boundary after
-the input sections:
-@example
-        .data ALIGN(0x2000) :@{
-                *(.data)
-                variable = ALIGN(0x8000);
-        @}
-@end example
-
-@item @code{ADDR(@var{section name})}
-returns the absolute address of the named section.  Your script must
+@node Built-ins,  , Assignment, Expressions
+@subsection Built-In Functions
+@cindex functions in expression language
+The command language includes a number of special purpose built-in
+functions for use in link script expressions.
+@table @code
+@item ABSOLUTE(@var{exp})
+@kindex ABSOLUTE(@var{exp})
+@cindex expression, absolute
+returns the absolute value of the expression @var{exp}.  Primarily
+useful to assign an absolute value to a symbol within a section
+definition, where symbol values are normally section-relative.
+
+@item ADDR(@var{section})
+@kindex ADDR(@var{section})
+@cindex section address
+returns the absolute address of the named @var{section}.  Your script must
 previously have defined the location of that section. In the following
 example the @code{symbol_1} and @code{symbol_2} are assigned identical
 values:
 @example
+SECTIONS@{ @dots{}
         .output1:
                 @{ 
-                start_of_output_1 $= .;
-                ... 
+                start_of_output_1 = ABSOLUTE(.);
+                @dots{}
                 @}
         .output:
                 @{
                 symbol_1 = ADDR(.output1);
                 symbol_2 = start_of_output_1;
                 @}
+@dots{} @}
+@end example
+
+@item ALIGN(@var{exp})
+@kindex ALIGN(@var{exp})
+@cindex rounding up location counter
+returns the result of the current location counter (@code{.}) aligned to
+the next @var{exp} boundary.  @var{exp} must be an expression whose
+value is a power of two.  This is equivalent to 
+@example
+(. + @var{exp} -1) & ~(@var{exp}-1)
+@end example
+
+@code{ALIGN} doesn't change the value of the location counter---it just
+does arithmetic on it.  As an example, to align the output @code{.data}
+section to the next @code{0x2000} byte boundary after the preceding
+section and to set a variable within the section to the next
+@code{0x8000} boundary after the input sections:
+@example
+SECTIONS@{ @dots{}
+        .data ALIGN(0x2000): @{
+                *(.data)
+                variable = ALIGN(0x8000);
+        @}
+@dots{} @}
+@end example
+@noindent
+The first use of @code{ALIGN} in this example specifies the location of
+a section because it is used as the optional @var{start} attribute of a
+section definition (@pxref{Section Options}).  The second use simply
+defines the value of a variable.
+
+The built-in @code{NEXT} is closely related to @code{ALIGN}.
+
+@item DEFINED(@var{symbol})
+@kindex DEFINED(@var{symbol})
+@cindex symbol defaults
+Returns @code{1} if @var{symbol} is in the linker global symbol table and is
+defined, otherwise it returns @code{0}.  You can use this to provide default
+values for symbols.  For example, this command-file fragment shows how
+to set a global symbol @code{begin} to the first location in the
+@code{.text} section---but if a symbol called @code{begin} already
+existed, its value is preserved:
+@example
+SECTIONS@{ @dots{}
+        .text: @{
+                begin = DEFINED(begin) ? begin : . ;
+                @dots{}
+        @}
+@dots{} @}
 @end example
 
-@item @code{SIZEOF(@var{section name})}
-returns the size in bytes of the named section, if the section has
+@item NEXT(@var{exp})
+@kindex NEXT(@var{exp})
+@cindex unallocated address, next
+Returns the next unallocated address that is a multiple of @var{exp}.
+This command is closely related to @code{ALIGN(@var{exp})}; unless you
+use the @code{MEMORY} command to define discontinuous memory for the
+output file, the two commands are equivalent.
+
+@item SIZEOF(@var{section})
+@kindex SIZEOF(@var{section})
+@cindex section size
+returns the size in bytes of the named @var{section}, if the section has
 been allocated.  In the following example the @code{symbol_1} and
 @code{symbol_2} are assigned identical values:
 @example
+SECTIONS@{ @dots{}
         .output @{
                 .start = . ;
-                ...
+                @dots{}
                 .end = .;
                 @}
         symbol_1 = .end - .start;
         symbol_2 = SIZEOF(.output);
-@end example
+@dots{} @}
 
-@item @code{DEFINED(@var{symbol name})}
-Returns 1 if the symbol is in the linker global symbol table and is
-defined, otherwise it returns 0. For example, this command-file fragment
-shows how to set a global symbol @code{begin} to the first location in
-the @code{.text} section---but only if no symbol called @code{begin}
-existed:
-@example
-        .text: @{
-                begin = DEFINED(begin) ? begin : . ;
-                ...
-        @}
 @end example
-@end itemize
 
-@node MEMORY,,,
+@item SIZEOF_HEADERS
+@kindex SIZEOF_HEADERS
+@cindex header size
+@itemx sizeof_headers
+@kindex sizeof_headers
+the size in bytes of the output file's headers.  You can use this number
+as the start address of the first section, if you choose, to facilitate
+paging. 
+
+@end table
+
+@node MEMORY, SECTIONS, Expressions, Commands
 @section MEMORY Command
+@kindex MEMORY
+@cindex regions of memory
+@cindex discontinuous memory
+@cindex allocating memory
 The linker's default configuration permits allocation of all memory.
 You can override this by using the @code{MEMORY} command.  The
 @code{MEMORY} command describes the location and size of blocks of
@@ -784,36 +1239,42 @@ you wish.  The syntax is:
 MEMORY 
       @{
        @var{name} (@var{attr}): ORIGIN = @var{origin}, LENGTH = @var{len}
-       .
-       .
-       .
+       @dots{}
       @}
 @end example
 @table @code
 @item @var{name}
+@cindex naming memory regions
 is a name used internally by the linker to refer to the region. Any
 symbol name may be used.  The region names are stored in a separate
 name space, and will not conflict with symbols, filenames or section
 names.  Use distinct names to specify multiple regions.
 @item (@var{attr})
-is an optional list of attributes, parsed for compatibility with the
-AT@&T linker but ignored by the both the AT@&T and the GNU linker.
-Valid attribute lists must be made up of the characters ``@code{RWXL}''.
-If you omit the attribute list, you may omit the parentheses around it
-as well. 
+@cindex memory region attributes
+is an optional list of attributes, permitted for compatibility with the
+AT&T linker but not used by @code{gld} beyond checking that the
+attribute list is valid.  Valid attribute lists must be made up of the
+characters ``@code{LIRWX}''.  If you omit the attribute list, you may
+omit the parentheses around it as well.
 @item @var{origin}
+@kindex ORIGIN=
+@kindex o=
+@kindex org=
 is the start address of the region in physical memory.  It is expressed as
 an expression, which must evaluate to a constant before
 memory allocation is performed. The keyword @code{ORIGIN} may be
 abbreviated to @code{org} or @code{o}.
 @item @var{len}
+@kindex LENGTH=
+@kindex len=
+@kindex l=
 is the size in bytes of the region (an expression).
-The keyword @code{LENGTH} may be abbreviated to @code{len} or @code{l}
+The keyword @code{LENGTH} may be abbreviated to @code{len} or @code{l}.
 @end table 
 
 For example, to specify that memory has two regions available for
-allocation; one starting at 0 for 256k, and the other starting at
-0x40000000 for four megabytes:
+allocation---one starting at @code{0} for 256 kilobytes, and the other
+starting at @code{0x40000000} for four megabytes:
 
 @example
 MEMORY 
@@ -824,13 +1285,14 @@ MEMORY
 @end example
 
 Once you have defined a region of memory named @var{mem}, you can direct
-specific output sections there by using a command ending in @samp{>@var{mem}} 
-within the @code{SECTIONS} command.  If the combined output
-sections directed to a region are too big for the region, the linker will
-issue an error message.
+specific output sections there by using a command ending in
+@samp{>@var{mem}} within the @code{SECTIONS} command (@pxref{Section
+Options}).  If the combined output sections directed to a region are too
+big for the region, the linker will issue an error message.
 
-@node SECTIONS,,,
+@node SECTIONS, Entry Point, MEMORY, Commands
 @section SECTIONS Command
+@kindex SECTIONS
 The @code{SECTIONS} command controls exactly where input sections are
 placed into output sections, their order and to which output sections
 they are allocated.
@@ -849,7 +1311,7 @@ sections make it up.
 @end itemize
 
 The first two possibilities---defining the entry point, and defining
-symbols---can also be done outside the @samp{SECTIONS} command:
+symbols---can also be done outside the @code{SECTIONS} command:
 @pxref{Entry Point}, @pxref{Assignment}.  They are permitted here as
 well for your convenience in reading the script, so that symbols or the
 entry point can be defined at meaningful points in your output-file
@@ -862,8 +1324,15 @@ the input files; if all input sections are present in the first file,
 for example, the order of sections in the output file will match the
 order in the first input file.
 
-@node Section Definition,,,
+@menu
+* Section Definition::		Section Definitions
+* Section Contents::		Section Contents
+* Section Options::		Optional Section Attributes
+@end menu
+
+@node Section Definition, Section Contents, SECTIONS, SECTIONS
 @subsection Section Definitions
+@cindex section definition
 The most frequently used statement in the @code{SECTIONS} command is
 the @dfn{section definition}, which you can use to specify the
 properties of an output section: its location, alignment, contents,
@@ -871,19 +1340,13 @@ fill pattern, and target memory region can all be specified.  Most of
 these specifications are optional; the simplest form of a section
 definition is
 @example
-SECTIONS
-@{
-.
-.
-.
+SECTIONS @{ @dots{}
 @var{secname} : @{
                  @var{contents}
                 @}
-.
-.
-.
-@}
+@dots{} @}
 @end example
+@cindex naming output sections
 @noindent
 @var{secname} is the name of the output section, and @var{contents} a
 specification of what goes there---for example a list of input files or
@@ -894,15 +1357,16 @@ however.
 @var{secname} must meet the constraints of your output format.  In
 formats which only support a limited number of sections, such as
 @code{a.out}, the name must be one of the names supported by the format
-(in the case of @code{a.out}, @code{.text}, @code{.data} or @code{.bss}). If
-the output format supports any number of sections, but with numbers and
-not names (in the case of IEEE), the name should be supplied as a quoted
-numeric string.  A section name may consist of any sequence characters,
-but any name which does not conform to the standard @code{gld} symbol
-name syntax must be quoted.
-
-@node Section Contents,,,
+(@code{a.out}, for example, allows only @code{.text}, @code{.data} or
+@code{.bss}). If the output format supports any number of sections, but
+with numbers and not names (as is the case for Oasys), the name should be
+supplied as a quoted numeric string.  A section name may consist of any
+sequence characters, but any name which does not conform to the standard
+@code{gld} symbol name syntax must be quoted.
+
+@node Section Contents, Section Options, Section Definition, SECTIONS
 @subsection Section Contents
+@cindex contents of a section
 In a section definition, you can specify the contents of an output section by
 listing particular object files; by listing particular input-file
 sections; or a combination of the two.  You can also place arbitrary
@@ -915,31 +1379,41 @@ like in a single section definition, separated from one another by
 whitespace. 
 
 @table @code
-@item @var{filename}( @var{section} )
-@itemx @var{filename}( @var{section}, @var{section}, @dots{} )
-@itemx @var{filename}( @var{section} @var{section} @dots{} )
-You can name one or more sections from your input files, for
-insertion in the current output section.  If you wish to specify a list
-of input-file sections inside the parentheses, you may separate the
-section names by either commas or whitespace.
-
 @item @var{filename}
+@kindex @var{filename}
+@cindex input files, section defn
+@cindex files, including in output sections
 You may simply name a particular input file to be placed in the current
-output section; @emph{all} sections from that file are placed in
-the current section definition.  Since multiple statements may be
-present in the contents of a section definition, you can specify a list
-of particular files by name:
+output section; @emph{all} sections from that file are placed in the
+current section definition. To specify a list of particular files by
+name:
 @example
 .data: @{ afile.o bfile.o cfile.o @}
 @end example
+@noindent
+The example also illustrates that multiple statements can be included in
+the contents of a section definition, since each filename is a separate
+statement. 
 
 If the file name has already been mentioned in another section
 definition, with an explicit section name list, then only those sections
 which have not yet been allocated are used.
 
+@item @var{filename}( @var{section} )
+@itemx @var{filename}( @var{section}, @var{section}, @dots{} )
+@itemx @var{filename}( @var{section} @var{section} @dots{} )
+@kindex @var{filename}(@var{section})
+@cindex files and sections, section defn
+You can name one or more sections from your input files, for
+insertion in the current output section.  If you wish to specify a list
+of input-file sections inside the parentheses, you may separate the
+section names by either commas or whitespace.
+
 @item * (@var{section})
 @itemx * (@var{section}, @var{section}, @dots{})
-@itemx * (@var{section} @var{section} @dots{})
+@itemx * (@var{section} @var{section} @dots{}
+@cindex input sections to output section
+@kindex *(@var{section})
 Instead of explicitly naming particular input files in a link control
 script, you can refer to @emph{all} files from the @code{gld} command
 line: use @samp{*} instead of a particular filename before the
@@ -949,7 +1423,7 @@ For example, to copy sections @code{1} through @code{4} from a Oasys file
 into the @code{.text} section of an @code{a.out} file, and sections @code{13}
 and @code{14} into the @code{.data} section:
 @example
-SECTION @{
+SECTIONS @{
         .text :@{
                 *("1" "2" "3" "4")
         @}
@@ -967,12 +1441,16 @@ file have not yet been defined.
 @item [ @var{section} ]
 @itemx [ @var{section}, @var{section}, @dots{} ]
 @itemx [ @var{section} @var{section} @dots{} ]
+@kindex [ @var{sections} ]
 This is an alternate notation to specify named sections from all
 unallocated input files; its effect is exactly the same as that of
 @samp{* (@var{section}@dots{})}
 
 @item @var{filename}@code{( COMMON )}
 @itemx [ COMMON ]
+@kindex [COMMON]
+@cindex uninitialized data
+@cindex commons in output
 Specify where in your output file to place uninitialized data
 with this notation.  @code{[COMMON]} by itself refers to all
 uninitialized data from all input files (so far as it is not yet
@@ -984,17 +1462,16 @@ were in an input-file section named @code{COMMON}, regardless of the
 input file's format.
 @end table
 
-For example, the following command script arranges its output file into
+For example, the following command script arranges the output file into
 three consecutive sections, named @code{.text}, @code{.data}, and
 @code{.bss}, taking the input for each from the correspondingly named
 sections of all the input files:
 @example
-SECTIONS 
-{ 
-  .text: { *(.text) }  
-  .data: { *(.data) }  
-  .bss:  { *(.bss)  [COMMON] } 
-} 
+SECTIONS @{ 
+  .text: @{ *(.text) @}
+  .data: @{ *(.data) @} 
+  .bss:  @{ *(.bss)  [COMMON] @} 
+@} 
 @end example
 
 The following example reads all of the sections from file @code{all.o}
@@ -1007,8 +1484,7 @@ All of the remaining @code{.input1} and @code{.input2} sections from any
 files are written to output section @code{outputc}.
 
 @example
-SECTIONS        
-      @{
+SECTIONS @{
         outputa 0x10000 :
                 @{
                 all.o
@@ -1024,11 +1500,11 @@ SECTIONS
                 *(.input1)
                 *(.input2)
                 @}
-        @}
+@}
 @end example        
 
 There are still more kinds of statements permitted in the contents of
-output section definitions!  The foregoing statements permitted you to
+output section definitions.  The foregoing statements permitted you to
 arrange, in your output file, data originating from your input files.
 You can also place data directly in an output section from the link
 command script.  Most of these additional statements involve
@@ -1039,8 +1515,11 @@ intermix them freely with any of the statements we've just described.
 
 @table @code
 @item CREATE_OBJECT_SYMBOLS
-instructs the linker to create a symbol for each input file and place it
-into the current section, set with the address of the first byte of
+@kindex CREATE_OBJECT_SYMBOLS
+@cindex input filename symbols
+@cindex filename symbols
+instructs the linker to create a symbol for each input file
+in the current section, set with the address of the first byte of
 data written from the input file.  For instance, with @code{a.out}
 files it is conventional to have a symbol for each input file.  You can
 accomplish this by defining the output @code{.text} section as follows:
@@ -1052,10 +1531,8 @@ SECTIONS @{
                 *(.text)
                 _etext = ALIGN(0x2000);
                 @}
-        .
-        .
-        .
-        @}
+        @dots{}
+@}
 @end example
 
 If @code{objsym} is a file containing this script, and @code{a.o},
@@ -1064,7 +1541,7 @@ contents like the following---
 @example
 /* a.c */
 
-afunction() { }
+afunction() @{ @}
 int adata=1;
 int abss;
 @end example
@@ -1095,39 +1572,39 @@ containing symbols matching the object file names:
 00002068 t d.o
 @end example
 
-@item FORCE_COMMON_ALLOCATION
-@c FIXME!  I don't know what this does.
-
 @item @var{symbol} = @var{expression} ;
+@kindex @var{symbol} = @var{expression} ;
 @itemx @var{symbol} @var{f}= @var{expression} ;
-@var{symbol} is any symbol name (@pxref{Symbols}).  When you assign a
-value to a symbol within a particular section definition, the value is
-relative to the beginning of the section (@pxref{Assignment}).  If you write
+@kindex @var{symbol} @var{f}= @var{expression} ;
+@var{symbol} is any symbol name (@pxref{Symbols}).  ``@var{f}='' 
+refers to any of the operators @code{&= += -= *= /=} which combine
+arithmetic and assignment.
+
+@cindex assignment, in section defn
+When you assign a value to a symbol within a particular section
+definition, the value is relative to the beginning of the section
+(@pxref{Assignment}).  If you write
 @example
-SECTIONS
-{
+SECTIONS @{
   abs = 14 ;
-.
-.
-.
-  .data: { @dots{} rel = 14 ; @dots{} }
+  @dots{}
+  .data: @{ @dots{} rel = 14 ; @dots{} @}
   abs2 = 14 + ADDR(.data);
-.
-.
-.
-}
+  @dots{}
+@}
 @end example
-@c FIXME!  Try above example!
+@c FIXME:  Try above example!
 @noindent
 @code{abs} and @var{rel} do not have the same value; @code{rel} has the
 same value as @code{abs2}.
 
-``@var{f}='' here refers to any of the operators @code{&=  +=  -=  *=
-/=} which combine arithmetic and assignment.
-
 @item BYTE(@var{expression})
+@kindex BYTE(@var{expression})
 @itemx SHORT(@var{expression})
+@kindex SHORT(@var{expression})
 @itemx LONG(@var{expression})
+@kindex LONG(@var{expression})
+@cindex direct output
 By including one of these three statements in a section definition, you
 can explicitly place one, two, or four bytes (respectively) at the
 current address of that section.  Multiple-byte quantities are
@@ -1135,6 +1612,9 @@ represented in whatever byte order is appropriate for the output file
 format (@pxref{BFD}). 
 
 @item FILL(@var{expression})
+@kindex FILL(@var{expression})
+@cindex holes, filling
+@cindex unspecified memory
 Specifies the ``fill pattern'' for the current section.  Any otherwise
 unspecified regions of memory within the section (for example, regions
 you skip over by assigning a new value to the location counter @samp{.})
@@ -1145,31 +1625,30 @@ including more than one @code{FILL} statement, you can have different
 fill patterns in different parts of an output section.
 @end table
 
-@node Section Options,,,
+@node Section Options,  , Section Contents, SECTIONS
 @subsection Optional Section Attributes
+@cindex section defn, full syntax
 Here is the full syntax of a section definition, including all the
 optional portions:
 
 @example
-SECTIONS
-@{
-.
-.
-.
-@var{secname} @var{start} BLOCK(@var{align}) : @var{contents} =@var{fill} >@var{region}
-.
-.
-.
+SECTIONS @{
+@dots{}
+@var{secname} @var{start} BLOCK(@var{align}) : @{ @var{contents} @} =@var{fill} >@var{region}
+@dots{}
 @}
 @end example
 
 @var{secname} and @var{contents} are required.  @xref{Section
-Definition}, and @pxref{Section Contents} for the details of
-@var{contents}.  @var{start}, @code{BLOCK(@var{align)}},
-@code{=@var{fill}}, and @code{>@var{region}} are all optional.
+Definition}, and @pxref{Section Contents} for details on @var{contents}.
+The remaining elements---@var{start}, @code{BLOCK(@var{align)}},
+@code{=@var{fill}}, and @code{>@var{region}}---are all optional.
 
 @table @code
 @item @var{start} 
+@cindex start address, section
+@cindex section start
+@cindex section address
 You can force the output section to be loaded at a specified address by
 specifying @var{start} immediately following the section name.
 @var{start} can be represented as any expression. The following
@@ -1177,22 +1656,27 @@ example generates section @var{output} at location
 @code{0x40000000}:
 @example
 SECTIONS @{
-        .
-        .
-        .
+        @dots{}
         output 0x40000000: @{
                @dots{}
           @}
-        .
-        .
-        .
+        @dots{}
 @}
 @end example
 
 @item BLOCK(@var{align})
-@c FIXME!  Fill in BLOCK(align) description
+@kindex BLOCK(@var{align})
+@cindex section alignment
+@cindex aligning sections
+You can include @code{BLOCK()} specification to advance the location of
+the location counter @code{.} prior to the beginning of the section, so
+that the section will begin at the specified alignment.  @var{align} is
+an expression.
 
 @item =@var{fill}
+@kindex =@var{fill}
+@cindex section fill pattern
+@cindex fill pattern, entire section
 You may use any expression to specify @var{fill}.  Including
 @code{=@var{fill}} in a section definition specifies the initial fill
 value for that section. Any unallocated holes in the current output
@@ -1202,12 +1686,19 @@ also change the fill value with a @code{FILL} statement in the
 @var{contents} of a section definition.
 
 @item >@var{region}
-@c FIXME! Fill in >region description
+@kindex >@var{region}
+@cindex section, assigning to memory region
+@cindex memory regions and sections
+Assign this section to a previously defined region of memory.  
+@xref{MEMORY}.
 
 @end table
 
-@node Entry Point,,,
+@node Entry Point, Other Commands, SECTIONS, Commands
 @section The Entry Point
+@kindex ENTRY(@var{symbol})
+@cindex start of execution
+@cindex first instruction
 The linker command language includes a command specifically for
 defining the first executable instruction in an output file (its
 @dfn{entry point}).  Its argument is a symbol name:
@@ -1220,6 +1711,7 @@ as an independent command in the command file, or among the section
 definitions within the @code{SECTIONS} command---whatever makes the most
 sense for your layout.
 
+@cindex entry point, defaults
 @code{ENTRY} is only one of several ways of choosing the entry point.
 You may indicate it in any of the following ways (shown in descending
 order of priority: methods higher in the list override methods lower down).
@@ -1227,7 +1719,7 @@ order of priority: methods higher in the list override methods lower down).
 @item 
 the @code{-e} @var{entry} command-line option;
 @item 
-the @code{ENTRY} @var{symbol} command in a linker control script;
+the @code{ENTRY(@var{symbol}} command in a linker control script;
 @item 
 the value of the symbol @code{start}, if present;
 @item 
@@ -1238,9 +1730,10 @@ the address of the first byte of the @code{.text} section, if present;
 The address @code{0}.
 @end itemize
 
-For example, you can also generate an entry point with an assignment statement:
-if no symbol @code{start} is  defined within your input files, you can
-simply assign it an appropriate value---
+For example, you can use these rules to generate an entry point with an
+assignment statement: if no symbol @code{start} is defined within your
+input files, you can simply define it, assigning it an appropriate
+value---
 @example
 start = 0x2020;
 @end example
@@ -1254,7 +1747,7 @@ whatever symbol contains the start address to @code{start}:
 start = other_symbol;
 @end example
 
-@node Other Commands,,,
+@node Other Commands,  , Entry Point, Commands
 @section Other Commands
 The command language includes a number of other commands that you can
 use for specialized purposes.  They are similar in purpose to
@@ -1262,102 +1755,257 @@ command-line options.
 
 @table @code
 @item FLOAT
+@kindex FLOAT
 @itemx NOFLOAT
-Declare to the linker whether or not floating point support is
-available.  The default assumption is @code{NOFLOAT}.
-@c FIXME: So what?  What does it do once it knows FLOAT or NOFLOAT?
+@kindex NOFLOAT
+These keywords were used in some older linkers to request a particular
+math subroutine library.  @code{gld} doesn't use the keywords, assuming
+instead that any necessary subroutines are in libraries specified using
+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
+This command has the same effect as the @code{-d} command-line option:
+to make @code{ld} assign space to common symbols even if a relocatable
+output file is specified (@code{-r}).
 
 @item HLL ( @var{file}, @var{file}, @dots{} )
+@kindex HLL ( @var{files} )
 @itemx HLL ( @var{file} @var{file} @dots{} )
+@itemx HLL ( )
+Include ``high-level libraries'' or archives as input files in the link.
+Using @code{HLL(@var{file}} in a linker script is equivalent to
+including @code{-l}@var{file} on the command line.  
+
+@cindex @code{lnk960} command @code{HLL}
+The @code{HLL} command is only supported when @code{gld} emulates
+@code{lnk960}, as specified by the @code{LDEMULATION} environment
+variable.
 
 @item INPUT ( @var{file}, @var{file}, @dots{} )
+@kindex INPUT ( @var{files} )
 @itemx INPUT ( @var{file} @var{file} @dots{} )
+@cindex binary input files
+Use this command to include binary input files in the link, without
+including them in a particular section definition.  Files specified this
+way are treated identically to object files listed on the command line.
 
+@ignore
 @item MAP ( @var{name} )
+@kindex MAP ( @var{name} )
+@c MAP(...) appears to look for an F in the arg, ignoring all other
+@c chars; if it finds one, it sets "map_option_f" to true.  But nothing
+@c checks map_option_f.  Apparently a stub for the future...
+@end ignore
 
 @item OUTPUT ( @var{filename} )
-
-@item SEARCH_DIR ( @var{pathname} )
-
-@item STARTUP ( @var{name} )
+@kindex OUTPUT ( @var{filename} )
+@cindex naming the output file
+Name the link output file @var{filename}.  The effect of
+@code{OUTPUT(@var{filename})} is identical to the effect of 
+@w{@code{-o @var{filename}}}, and whichever is encountered last will
+control the name actually used to name the output file.  In particular,
+you can use this command to supply a default output-file name other than
+@code{a.out}. 
+
+@item OUTPUT_ARCH ( @var{bfdname} )
+@kindex OUTPUT_ARCH ( @var{bfdname} )
+@cindex machine architecture, output
+Specify a particular output machine architecture, with one of the names
+used by the BFD back-end routines (@pxref{BFD}).  This command is often
+unnecessary; the architecture is most often set implicitly by either the
+system BFD configuration or as a side effect of the @code{OUTPUT_FORMAT}
+command.  @refill
+
+@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}).  This selection will only affect
+the output file; the related command @code{TARGET} affects primarily
+input files.@refill
+
+@item SEARCH_DIR ( @var{path} )
+@kindex SEARCH_DIR ( @var{path} )
+@cindex path for libraries
+@cindex search path, libraries
+Add @var{path} to the list of paths where @code{gld} looks for
+archive libraries.  @code{SEARCH_DIR(@var{path})} has the same
+effect as @code{-L@var{path})} on the command line.
+
+@item STARTUP ( @var{filename} )
+@kindex STARTUP ( @var{filename} )
+@cindex first input file
+Ensure that @var{filename} is the first input file used in the link
+process. 
 
 @item SYSLIB ( @var{file}, @var{file}, @dots{} )
+@kindex SYSLIB ( @var{file}, @var{file}, @dots{} )
 @itemx SYSLIB ( @var{file} @var{file} @dots{} )
+Use the named @var{file}s as binary input files, searching for them in
+the same list of paths as archives.
+
+@cindex @code{lnk960} command @code{SYSLIB}
+The @code{SYSLIB} command is only supported when @code{gld} emulates
+@code{lnk960}, as specified by the @code{LDEMULATION} environment
+variable.
 
 @item TARGET ( @var{format} )
+@cindex input file format
+@kindex TARGET ( @var{format} )
+Change the input-file object code format (like the command-line option
+@code{-b} or its synonym @code{-format}).  The argument @var{format} is
+one of the strings used by BFD to name binary formats.  In the current
+@code{gld} implementation, 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{gld} output file.
+@xref{BFD}.@refill
+
+@kindex GNUTARGET
+If you don't use the @code{TARGET} command, @code{gld} uses the value of
+the environment variable @code{GNUTARGET}, if available, to select the
+output file format.  If that variable is also absent, @code{gld} uses
+the default format configured for your machine in the BFD libraries.
 
 @end table
 
-@node BFD,,,
+@node BFD, Index, Commands, Top
 @chapter BFD
 
-The linker accesses object and archive files using the @code{bfd}
-libraries. These libraries allow the linker to use the same routines
-to operate on object files whatever the object file format.
-
-A different object file format can be supported simply by creating a
-new @code{bfd} back end and adding it to the library.
+@cindex back end
+@cindex object file management
+The linker accesses object and archive files using the BFD libraries.
+These libraries allow the linker to use the same routines to operate on
+object files whatever the object file format.  A different object file
+format can be supported simply by creating a new BFD back end and adding
+it to the library.  BFD supports the following combinations of
+architectures (row labels below) and object formats (column headings):
+@cindex formats available
+@cindex architectures available
+@ifinfo
+@example
+                OBJECT FORMATS
+              \ ---------------------------------------
+               |ieee
+               |  |oasys
+               |  |  |a.out-generic-little
+               |  |  |  |a.out-generic-big
+               |  |  |  |  |m88kbcs
+               |  |  |  |  |  |srec
+               |  |  |  |  |  |  |coff-Intel-little
+               |  |  |  |  |  |  |  |coff-Intel-big
+               |  |  |  |  |  |  |  |  |b.out.little
+ARCHITECTURES  |  |  |  |  |  |  |  |  |  |b.out.big
+               |  |  |  |  |  |  |  |  |  |
+           m68k|**|**|  |  |  |**|  |  |  |
+            vax|**|**|  |  |  |**|  |  |  |
+           i960|**|**|  |  |  |**|**|**|**|**
+           a29k|**|**|**|**|  |**|  |  |  |
+          sparc|**|**|**|**|  |**|  |  |  |
+           mips|**|**|  |  |  |**|  |  |  |
+           i386|**|**|**|**|  |**|  |  |  |
+          ns32k|**|**|  |  |  |**|  |  |  |
+          tahoe|**|**|  |  |  |**|  |  |  |
+           i860|**|**|  |  |  |**|  |  |  |
+           romp|**|**|  |  |  |**|  |  |  |
+        alliant|**|**|  |  |  |**|  |  |  |
+         convex|**|**|  |  |  |**|  |  |  |
+           m88k|**|**|  |  |**|**|  |  |  |
+        pyramid|**|**|  |  |  |**|  |  |  |
+         H8/300|**|**|  |  |  |**|  |  |  |
 
-Formats currently supported:
-@itemize @bullet
-@item 
-Sun3 68k @code{a.out}
-@item 
-IEEE-695 68k Object Module Format
-@item 
-Oasys 68k Binary Relocatable Object File Format
-@item 
-Sun4 sparc @code{a.out}
-@item 
-88k bcs coff
-@item 
-i960 coff little endian
-@item 
-i960 coff big endian
-@item 
-i960 @code{b.out} little endian
-@item 
-i960 @code{b.out} big endian
-@end itemize
+@end example
+@end ifinfo
+@tex
+\def\sqbull{\vrule height12pt width 10pt depth 4pt}
+\vskip\baselineskip
+\vbox{\offinterlineskip
+\halign
+{\strut\hfil #\ &\vrule#&\quad #\quad &\vrule#&\quad #\quad
+&\vrule#&\quad #\quad &\vrule#&\quad #\quad &\vrule#&\quad #\quad &\vrule#&\quad #\quad &\vrule#&\quad #\quad &\vrule#&\quad #\quad &\vrule#&\quad #\quad &\vrule#&\quad #\quad &\vrule#\cr
+		    &&\multispan{20}\hfil{\it OBJECT FORMATS}\hfil\cr
+		    &&\multispan{20}\quad\vbox{\hrule}\cr
+		    &&\multispan{20}\quad\code{ieee}\hfil\cr
+		    &&  &&\multispan{18}\quad\code{oasys}\hfil\cr
+		    &&  &&  &&\multispan{16}\quad\code{a.out-generic-little}\hfil\cr
+		    &&  &&  &&  &&\multispan{14}\quad\code{a.out-generic-big}\hfil\cr
+		    &&  &&  &&  &&  &&\multispan{12}\quad\code{m88kbcs}\hfil\cr
+		    &&  &&  &&  &&  &&  &&\multispan{10}\quad\code{srec}\hfil\cr
+		    &&  &&  &&  &&  &&  &&  &&\multispan8\quad\code{coff-Intel-little}\hfil\cr
+		    &&  &&  &&  &&  &&  &&  &&  &&\multispan6\quad\code{coff-Intel-big}\hfil\cr
+		    &&  &&  &&  &&  &&  &&  &&  &&
+&&\multispan4\quad\code{b.out.little}\hfil \cr
+		    &&  &&  &&  &&  &&  &&  &&  &&  &&  &&\multispan2\quad\code{b.out.big}\hidewidth\cr
+{\it ARCHITECTURES} &&  &&  &&  &&  &&  &&  &&  &&  &&  &&  &\cr
+                    &&  &&  &&  &&  &&  &&  &&  &&  &&  &&  &\cr
+           \code{m68k}&&\sqbull&&\sqbull&&  &&  &&  &&\sqbull&&  &&  &&  &&  &\cr
+            \code{vax}&&\sqbull&&\sqbull&&  &&  &&  &&\sqbull&&  &&  &&  &&  &\cr
+           \code{i960}&&\sqbull&&\sqbull&&  &&  &&  &&\sqbull&&\sqbull&&\sqbull&&\sqbull&&\sqbull  &\cr
+           \code{a29k}&&\sqbull&&\sqbull&&\sqbull&&\sqbull&&  &&\sqbull&&  &&  &&  &&  &\cr
+          \code{sparc}&&\sqbull&&\sqbull&&\sqbull&&\sqbull&&  &&\sqbull&&  &&  &&  &&  &\cr
+           \code{mips}&&\sqbull&&\sqbull&&  &&  &&  &&\sqbull&&  &&  &&  &&  &\cr
+           \code{i386}&&\sqbull&&\sqbull&&\sqbull&&\sqbull&&  &&\sqbull&&  &&  &&  &&  &\cr
+          \code{ns32k}&&\sqbull&&\sqbull&&  &&  &&  &&\sqbull&&  &&  &&  &&  &\cr
+          \code{tahoe}&&\sqbull&&\sqbull&&  &&  &&  &&\sqbull&&  &&  &&  &&  &\cr
+           \code{i860}&&\sqbull&&\sqbull&&  &&  &&  &&\sqbull&&  &&  &&  &&  &\cr
+           \code{romp}&&\sqbull&&\sqbull&&  &&  &&  &&\sqbull&&  &&  &&  &&  &\cr
+        \code{alliant}&&\sqbull&&\sqbull&&  &&  &&  &&\sqbull&&  &&  &&  &&  &\cr
+         \code{convex}&&\sqbull&&\sqbull&&  &&  &&  &&\sqbull&&  &&  &&  &&  &\cr
+           \code{m88k}&&\sqbull&&\sqbull&&  &&  &&\sqbull&&\sqbull&&  &&  &&  &&  &\cr
+        \code{pyramid}&&\sqbull&&\sqbull&&  &&  &&  &&\sqbull&&  &&  &&  &&  &\cr
+         \code{H8/300}&&\sqbull&&\sqbull&&  &&  &&  &&\sqbull&&  &&  &&  &&  &\cr
+}}
+@end tex
 
-As with most implementations, @code{bfd} is a compromise between
+@cindex BFD requirements
+@cindex requirements for BFD
+As with most implementations, BFD is a compromise between
 several conflicting requirements. The major factor influencing
-@code{bfd} design was efficiency, any time used converting between
-formats is time which would not have been spent had @code{bfd} not
+BFD design was efficiency: any time used converting between
+formats is time which would not have been spent had BFD not
 been involved. This is partly offset by abstraction payback; since
-@code{bfd} simplifies applications and back ends, more time and care
+BFD simplifies applications and back ends, more time and care
 may be spent optimizing algorithms for a greater speed.
 
-One minor artifact of the @code{bfd} solution which the
-user should be aware of is the potential for information loss.
-There are two places where useful information can be lost using the 
-@code{bfd} mechanism; during conversion and during output. @xref{BFD
-information loss}.
+One minor artifact of the BFD solution which you should bear in
+mind is the potential for information loss.  There are two places where
+useful information can be lost using the BFD mechanism; during
+conversion and during output. @xref{BFD information loss}.
+
+@menu
+* BFD outline::			How it works: an outline of BFD
+* BFD information loss::	Information Loss
+* Mechanism::			Mechanism 
+@end menu
 
-@node BFD outline,,,
+@node BFD outline, BFD information loss, BFD, BFD
 @section How it works: an outline of BFD
-When an object file is opened, @code{bfd} subroutines automatically
+@cindex opening object files
+When an object file is opened, BFD subroutines automatically
 determine the format of the input object file, and build a descriptor in
 memory with pointers to routines that will be used to access elements of
 the object file's data structures.
 
 As different information from the the object files is required
-@code{bfd} reads from different sections of the file and processes them.
+BFD reads from different sections of the file and processes them.
 For example a very common operation for the linker is processing symbol
-tables.  Each @code{bfd} back end provides a routine for converting
+tables.  Each BFD back end provides a routine for converting
 between the object file's representation of symbols and an internal
 canonical format. When the linker asks for the symbol table of an object
-file, it calls through the memory pointer to the relevant @code{bfd}
+file, it calls through the memory pointer to the relevant BFD
 back end routine which reads and converts the table into a canonical
 form.  The linker then operates upon the common form. When the link is
 finished and the linker writes the symbol table of the output file,
-another @code{bfd} back end routine is called which takes the newly
+another BFD back end routine is called which takes the newly
 created symbol table and converts it into the chosen output format.
 
-@node BFD information loss,,,
+@node BFD information loss, Mechanism, BFD outline, BFD
 @section Information Loss
 @emph{Information can be lost during output.} The output formats
-supported by @code{bfd} do not provide identical facilities, and
+supported by BFD do not provide identical facilities, and
 information which may be described in one form has nowhere to go in
 another format. One example of this is alignment information in
 @code{b.out}. There is nowhere in an @code{a.out} format file to store
@@ -1375,37 +2023,39 @@ link cannot be done simply. You can circumvent this problem by
 describing the desired input-to-output section mapping with the command
 language.
 
-@emph{Information lost during canonicalization.}  The @code{bfd} internal
-canonical form of the external formats is not exhaustive; there are
-structures in input formats for which there is no direct representation
-internally.  This means that the @code{bfd} back ends cannot maintain
-all possible data richness through the transformation between external to
-internal and back to external formats.
+@emph{Information can be lost during canonicalization.} The BFD
+internal canonical form of the external formats is not exhaustive; there
+are structures in input formats for which there is no direct
+representation internally.  This means that the BFD back ends
+cannot maintain all possible data richness through the transformation
+between external to internal and back to external formats.
 
 This limitation is only a problem when using the linker to read one
-format and write another. Each @code{bfd} back end is responsible for
-maintaining as much data as possible, and the internal @code{bfd}
-canonical form has structures which are opaque to the @code{bfd} core,
+format and write another. Each BFD back end is responsible for
+maintaining as much data as possible, and the internal BFD
+canonical form has structures which are opaque to the BFD core,
 and exported only to the back ends. When a file is read in one format,
-the canonical form is generated for @code{bfd} and the linker. At the
+the canonical form is generated for BFD and the linker. At the
 same time, the back end saves away any information which may otherwise
-be lost. If the data is then written back to the same back end, the back
+be lost. If the data is then written back in the same format, the back
 end routine will be able to use the canonical form provided by the
-@code{bfd} core as well as the information it prepared earlier.  Since
+BFD core as well as the information it prepared earlier.  Since
 there is a great deal of commonality between back ends, this mechanism
 is very useful. There is no information lost for this reason when
 linking big endian COFF to little endian COFF, or from @code{a.out} to
 @code{b.out}.  When a mixture of formats is linked, the information is
 only lost from the files whose format differs from the destination.
 
-@node Mechanism,,,
+@node Mechanism,  , BFD information loss, BFD
 @section Mechanism 
 The greatest potential for loss of information is when there is least
 overlap between the information provided by the source format, that
-stored by the canonical format and the information needed by the
+stored by the canonical format, and the information needed by the
 destination format. A brief description of the canonical form may help
 you appreciate what kinds of data you can count on preserving across
 conversions.
+@cindex BFD canonical format
+@cindex internal object-file format
 
 @table @emph
 @item files
@@ -1416,24 +2066,25 @@ information like Unix magic numbers is not stored here---only the magic
 numbers' meaning, so a @code{ZMAGIC} file would have both the demand pageable
 bit and the write protected text bit set.
 
-The byte order of the target is stored on a per-file basis, so that
-both big- and little-endian object files may be linked with one another.
+The byte order of the target is stored on a per-file basis, so that big-
+and little-endian object files may be linked with one another.
 
 @item sections
 Each section in the input file contains the name of the section, the
 original address in the object file, various flags, size and alignment
-information and pointers into other @code{bfd} data structures.
+information and pointers into other BFD data structures.
 
 @item symbols
 Each symbol contains a pointer to the object file which originally
-defined it, its name, value and various flag bits. When a symbol table
-is read in, all symbols are relocated to make them relative to the base
-of the section where they were defined, so that each symbol points to
-its containing section. Each symbol also has a varying amount of hidden
-data to contain private data for the BFD back end. Since the symbol
-points to the original file, the private data format for that symbol is
-accessible.  @code{gld} can operate on a collection of symbols of wildly
-different formats without problems.
+defined it, its name, its value, and various flag bits.  When a
+BFD back end reads in a symbol table, the back end relocates all
+symbols to make them relative to the base of the section where they were
+defined.  This ensures that each symbol points to its containing
+section.  Each symbol also has a varying amount of hidden data to contain
+private data for the BFD back end.  Since the symbol points to the
+original file, the private data format for that symbol is accessible.
+@code{gld} can operate on a collection of symbols of wildly different
+formats without problems.
 
 Normal global and simple local symbols are maintained on output, so an
 output file (no matter its format) will retain symbols pointing to
@@ -1445,14 +2096,12 @@ appropriate command line switches. (The GNU debugger @code{gdb} does
 support @code{a.out} style debugging information in COFF).
 
 There is one word of type information within the symbol, so if the
-format supports symbol type information within symbols - (eg COFF,
+format supports symbol type information within symbols (for example COFF,
 IEEE, Oasys) and the type is simple enough to fit within one word
 (nearly everything but aggregates) the information will be preserved.
 
 @item relocation level
-@c FIXME: I don't understand "relocation record" from this so I can't
-@c FIXME...improve the explanation to make it clear...
-Each canonical relocation record contains a pointer to the symbol to
+Each canonical BFD relocation record contains a pointer to the symbol to
 relocate to, the offset of the data to relocate, the section the data
 is in and a pointer to a relocation type descriptor. Relocation is
 performed effectively by message passing through the relocation type
@@ -1465,7 +2114,9 @@ performed on a byte being written to a COFF file, even though 68k COFF
 has no such relocation type.
 
 @item line numbers
-Line numbers have to be relocated along with the symbol information.
+Object formats can contain, for debugging purposes, some form of mapping
+between symbols, source line numbers, and addresses in the output file.
+These addresses have to be relocated along with the symbol information.
 Each symbol with an associated list of line number records points to the
 first record of the list.  The head of a line number list consists of a
 pointer to the symbol, which allows divination of the address of the
@@ -1475,6 +2126,27 @@ which can simply derive this information can pass it successfully
 between formats (COFF, IEEE and Oasys).
 @end table
 
+@node Index,  , BFD, Top
+@unnumbered Index
+
+@printindex cp
+
+@tex
+% I think something like @colophon should be in texinfo.  In the
+% meantime:
+\long\def\colophon{\hbox to0pt{}\vfill
+\centerline{The body of this manual is set in}
+\centerline{\fontname\tenrm,}
+\centerline{with headings in {\bf\fontname\tenbf}}
+\centerline{and examples in {\tt\fontname\tentt}.}
+\centerline{{\it\fontname\tenit\/} and}
+\centerline{{\sl\fontname\tensl\/}}
+\centerline{are used for emphasis.}\vfill}
+\page\colophon
+% Blame: pesch@cygnus.com, 28mar91.
+@end tex
+
+
 @contents
 @bye