[nasm:nasm-2.16.xx] doc: be more clear than .bin is simply a linker built into NASM

[nasm-bot for H. Peter Anvin]

Commit-ID:  d31dca58604b74a357d8d51f3d9c552b5ace2de9
Gitweb:     http://repo.or.cz/w/nasm.git?a=commitdiff;h=d31dca58604b74a357d8d51f3d9c552b5ace2de9
Author:     H. Peter Anvin <hpa at zytor.com>
AuthorDate: Fri, 13 Oct 2023 17:05:53 -0700
Committer:  H. Peter Anvin <hpa at zytor.com>
CommitDate: Fri, 13 Oct 2023 17:05:53 -0700

doc: be more clear than .bin is simply a linker built into NASM

.bin really is nothing other than a linker built into NASM. Make that
very very clear to users.

Signed-off-by: H. Peter Anvin <hpa at zytor.com>


---
 doc/nasmdoc.src | 27 +++++++++++++++++++--------
 1 file changed, 19 insertions(+), 8 deletions(-)

diff --git a/doc/nasmdoc.src b/doc/nasmdoc.src
index 12efa926..6da2b7b7 100644
--- a/doc/nasmdoc.src
+++ b/doc/nasmdoc.src
@@ -1,7 +1,7 @@
 \# --------------------------------------------------------------------------
 \#
-\#   Copyright 1996-2022 The NASM Authors - All Rights Reserved
-\M{year}{1996-2022}
+\#   Copyright 1996-2023 The NASM Authors - All Rights Reserved
+\M{year}{1996-2023}
 \#   See the file AUTHORS included with the NASM distribution for
 \#   the specific copyright holders.
 \#
@@ -5770,6 +5770,13 @@ leaves your file name as it is once the original extension has been
 removed. Thus, the default is for NASM to assemble \c{binprog.asm}
 into a binary file called \c{binprog}.
 
+It is extremely important to understand that the binary output format
+is simply nothing other than \e{a linker built into the NASM
+executable.} As such, NASM behaves just as it does when given any
+other output format; notably the list file reflects the code output
+\e{before} relocation, and addresses in the list file are addresses
+relative to the start of the output section.
+
 
 \S{org} \i\c{ORG}: Binary File \i{Program Origin}
 
@@ -5870,11 +5877,13 @@ brackets must be used.
 
 The \c{ith} file format produces Intel hex-format files.  Just as the
 \c{bin} format, this is a flat memory image format with no support for
-relocation or linking.  It is usually used with ROM programmers and
-similar utilities.
+further relocation or linking.  It is usually used with ROM
+programmers and similar utilities.
 
-All extensions supported by the \c{bin} file format is also supported by
-the \c{ith} file format.
+From a programmer point of view, this behaves identically to the
+\c{.bin} format; the only difference is the encoding of the
+output. All extensions supported by the \c{bin} file format is also
+supported by the \c{ith} file format.
 
 \c{ith} provides a default output file-name extension of \c{.ith}.
 
@@ -5886,8 +5895,10 @@ The \c{srec} file format produces Motorola S-records files.  Just as the
 relocation or linking.  It is usually used with ROM programmers and
 similar utilities.
 
-All extensions supported by the \c{bin} file format is also supported by
-the \c{srec} file format.
+From a programmer point of view, this behaves identically to the
+\c{.bin} format; the only difference is the encoding of the
+output. All extensions supported by the \c{bin} file format is also
+supported by the \c{srec} file format.
 
 \c{srec} provides a default output file-name extension of \c{.srec}.