PR28902, -T script with INSERT ordering

The answer to PR28902 may be deduced from the existing INSERT
documentation that says the default script is parsed after the -T
INSERT script, if you assume (correctly) that nothing special is done
when inserting into -T scripts overriding the default script.  In both
cases INSERT handling looks for the specified output section later on
the internal list of parsed script commands.  This isn't obvious
though, so make the ordering explicit, and mention that section
assignments are the same too.

	PR 28902
	* ld.texi (INSERT): Specify ordering when -T is used both to
	override the default script and to augment.

1 files changed, 8 insertions, 1 deletions

diff --git a/ld/ld.texi b/ld/ld.texi
index 012eec2e809..8038de39106 100644
--- a/ld/ld.texi
+++ b/ld/ld.texi
@@ -1085,7 +1085,8 @@ a linker bug report.
 @item -T @var{scriptfile}
 @itemx --script=@var{scriptfile}
 Use @var{scriptfile} as the linker script.  This script replaces
-@command{ld}'s default linker script (rather than adding to it), so
+@command{ld}'s default linker script (rather than adding to it),
+unless the script contains @code{INSERT}, so
 @var{commandfile} must specify everything necessary to describe the
 output file.  @xref{Scripts}.  If @var{scriptfile} does not exist in
 the current directory, @code{ld} looks for it in the directories
@@ -4442,6 +4443,12 @@ SECTIONS
 INSERT AFTER .text;
 @end smallexample
 
+Note that when @samp{-T} is used twice, once to override the default
+script and once to augment that script using @code{INSERT} the order
+of parsing and section assignments apply as for the default script.
+The script with @code{INSERT} should be specified @emph{first} on the
+command line.
+
 @item NOCROSSREFS(@var{section} @var{section} @dots{})
 @kindex NOCROSSREFS(@var{sections})
 @cindex cross references