doc: tweaks to the index

Make the index at least a little bit more legible.

Signed-off-by: H. Peter Anvin (Intel) <hpa@zytor.com>

doc/32bit.src

@@ -244,11 +244,11 @@ many function parameters will be of type \c{int} or pointers.
 \H{picdll} Writing NetBSD/FreeBSD/OpenBSD and Linux/ELF \i{Shared
 Libraries}
 
-\c{ELF} replaced the older \c{a.out} object file format under Linux
-because it contains support for \i{position-independent code}
-(\i{PIC}), which makes writing shared libraries much easier. NASM
-supports the \c{ELF} position-independent code features, so you can
-write Linux \c{ELF} shared libraries in NASM.
+\I{Linux}\i{ELF} replaced the older \c{a.out} object file format
+under Linux because it contains support for \i{position-independent
+code} (\i{PIC}), which makes writing shared libraries much
+easier. NASM supports the \c{ELF} position-independent code features,
+so you can write Linux \c{ELF} shared libraries in NASM.
 
 \i{NetBSD}, and its close cousins \i{FreeBSD} and \i{OpenBSD}, take
 a different approach by hacking PIC support into the \c{a.out}
@@ -400,13 +400,12 @@ Common variables must also be accessed in this way.
 
 \S{picglobal} Exporting Symbols to the Library User
 
-If you want to export symbols to the user of the library, you have
-to declare whether they are functions or data, and if they are data,
-you have to give the size of the data item. This is because the
-dynamic linker has to build \I{PLT}\i{procedure linkage table}
-entries for any exported functions, and also moves exported data
-items away from the library's data section in which they were
-declared.
+If you want to export symbols to the user of the library, you have to
+declare whether they are functions or data, and if they are data, you
+have to give the size of the data item. This is because the dynamic
+linker has to build \I{PLT}\e{procedure linkage table} entries for any
+exported functions, and also moves exported data items away from the
+library's data section in which they were declared.
 
 So to export a function to users of the library, you must use
 
@@ -468,7 +467,7 @@ function lives. Either address is a valid way to call the function.
 \S{picproc} Calling Procedures Outside the Library
 
 Calling procedures outside your shared library has to be done by
-means of a \i\e{procedure linkage table}, or \i{PLT}. The PLT is
+means of a \I\e{procedure linkage table}, or \i{PLT}. The PLT is
 placed at a known offset from where the library is loaded, so the
 library code can make calls to the PLT in a position-independent
 way. Within the PLT there is code to jump to offsets contained in
@@ -500,5 +499,3 @@ library file name, with a version number, into the library:
 
 You would then copy \c{library.so.1.2} into the library directory,
 and create \c{library.so.1} as a symbolic link to it.
-
-

doc/contact.src

@@ -41,7 +41,7 @@ there.
 If you do report a bug, \e{please} make sure your bug report includes
 the following information:
 
-\b What operating system you're running NASM under.  Linux,
+\b What operating system you're running NASM under: Linux,
 FreeBSD, NetBSD, MacOS X, Win16, Win32, Win64, MS-DOS, OS/2, VMS,
 whatever.
 
@@ -105,4 +105,3 @@ for example, the problem involves NASM failing to generate an object
 file while TASM can generate an equivalent file without trouble,
 then send us \e{both} object files, so we can see what TASM is doing
 differently from us.
-

doc/index.src

@@ -37,12 +37,16 @@
 \IR{$, here} here token
 \IR{$, prefix} \c{$}, prefix
 \IR{$$} \c{$$} token
-\IR{%} \c{%} operator
-\IR{%db} \c{%} prefix to \c{DB} lists
+\IR{%} \c{%}, operator
+\IR{%db} \c{%}, prefix to \c{DB} lists
 \IR{%%} \c{%%} operator
 \IR{%+1} \c{%+1} and \c{%-1} syntax
 \IA{%-1}{%+1}
-\IR{%0} \c{%0} parameter count
+\IR{%*?} \c{%*?} and \c{%*??}
+\IR{%?} \c{%?} and \c{%??}
+\IC{%*?}{_sname} macro name, single line
+\IC{%?}{_mname} macro name, multi-line
+\IR{%0} \c{%0}, parameter count
 \IR{&} \c{&} operator
 \IR{&&} \c{&&} operator
 \IR{*} \c{*} operator
@@ -70,14 +74,14 @@
 \IR{||} \c{||} operator
 \IR{%$} \c{%$} and \c{%$$} prefixes
 \IA{%$$}{%$}
-\IR{+ opaddition} \c{+} operator, binary
-\IR{+ opunary} \c{+} operator, unary
-\IR{+ modifier} \c{+} modifier
-\IR{- opsubtraction} \c{-} operator, binary
-\IR{- opunary} \c{-} operator, unary
-\IR{! opunary} \c{!} operator
+\IR{+ opaddition} \c{+}, operator, binary
+\IR{+ opunary} \c{+}, operator, unary
+\IR{+ modifier} \c{+}, modifier
+\IR{- opsubtraction} \c{-}, operator, binary
+\IR{- opunary} \c{-}, operator, unary
+\IR{! opunary} \c{!}, operator
 \IA{~}{~ opunary}
-\IR{~ opunary} \c{~} operator
+\IR{~ opunary} \c{~}, operator
 \IA{A16}{a16}
 \IA{A32}{a32}
 \IA{A64}{a64}
@@ -162,13 +166,19 @@ variables
 \IR{macos x} MacOS X
 \IR{masm} MASM
 \IR{masmdb} MASM, \c{DB} syntax
+\IR{masm compatibility} MASM, compatibility
 \IA{memory reference}{memory references}
 \IR{minix} Minix
 \IA{misc directory}{misc subdirectory}
 \IR{misc subdirectory} \c{misc} subdirectory
 \IR{microsoft omf} Microsoft OMF
+\IR{mixed-size addressing} mixed-size, addressing
+\IR{mixed-size instruction} mixed-size, instruction
 \IR{ms-dos} MS-DOS
-\IR{ms-dos device drivers} MS-DOS device drivers
+\IR{ms-dos device drivers} MS-DOS, device drivers
+\IA{ms-dos}{dos}
+\IA{multi-line macro}{multi-line macros}
+\IR{multi-line macro expansion} multi-line macro, expansion
 \IR{multipush} \c{multipush} macro
 \IR{nan} NaN
 \IR{nasm version} NASM version
@@ -193,15 +203,20 @@ variables
 \IR{pascal calling convention} Pascal calling convention
 \IR{pic} PIC
 \IR{pharlap} PharLap
-\IR{plt} PLT
-\IR{plt} \c{PLT} relocations
+\IR{plt} PLT, procedure linkage table
+\IR{plt relocations} PLT, relocations
+\IC{plt}{procedure linkage table} procedure linkage table
 \IA{pre-defining macros}{pre-define}
 \IR{preprocessor conditionals} preprocessor, conditionals
+\IR{preprocessor directives} preprocessor, directives
 \IR{preprocessor expansions} preprocessor, expansions
 \IR{preprocessor expressions} preprocessor, expressions
+\IR{preprocessor functions} preprocessor, functions
 \IR{preprocessor loops} preprocessor, loops
 \IR{preprocessor variables} preprocessor, variables
-\IR{preprocessor variables} variables, preprocessor
+\IC{preprocessor variables}{vpp} variables, preprocessor
+\IR{other preprocessor directives}, preprocessor, other directives
+\IR{stack relative preprocessor directives}, preprocessor, stack relative directives
 \IA{comments}{comment}
 \IR{relocations, pic-specific} relocations, PIC-specific
 \IA{repeating}{repeating code}
@@ -236,14 +251,17 @@ variables
 \IA{uninitialized storage}{storage, uninitialized}
 \IR{unicode} Unicode
 \IR{unix} Unix
-\IR{utf-8} UTF-8
-\IR{utf-16} UTF-16
-\IR{utf-32} UTF-32
+\IR{utf-8} Unicode, UTF-8
+\IR{utf-16} Unicode, UTF-16
+\IR{utf-32} Unicode, UTF-32
 \IA{sco unix}{unix, sco}
 \IR{unix, sco} Unix, SCO
 \IA{unix system v}{unix, system v}
 \IR{unix, system v} Unix, System V
-\IR{unixware} UnixWare
+\# Having just "UnixWare" is rather silly as it follows immediately
+\IR{unixware} Unix, UnixWare
+\IC{linux}{unix, linux} Unix, Linux
+\IC{bsd}{unix, bsd} Unix, BSD
 \IR{val} VAL
 \IA{version number of nasm}{nasm, version}
 \IR{visual c++} Visual C++

doc/intro.src

@@ -4,7 +4,7 @@
 
 The Netwide Assembler, NASM, is an 80x86 and x86-64 assembler designed
 for portability and modularity. It supports a range of object file
-formats, including Linux and *BSD \c{a.out}, ELF, Mach-O, 16-bit and
+formats, including \i{Linux} and \i{BSD} \c{a.out}, ELF, Mach-O, 16-bit and
 32-bit \c{.obj} (OMF) format, COFF (including its Win32 and Win64
 variants.) It can also output plain binary files, Intel hex and
 Motorola S-Record formats. Its syntax is designed to be simple and
@@ -43,4 +43,3 @@ HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
 EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-

doc/outfmt.src

@@ -1098,7 +1098,7 @@ Format} Object Files
 
 The \c{elf32}, \c{elf64} and \c{elfx32} output formats generate
 \c{ELF32 and ELF64} (Executable and Linkable Format) object files, as
-used by Linux as well as \i{Unix System V}, including \i{Solaris x86},
+used by \i{Linux} as well as \i{Unix System V}, including \i{Solaris x86},
 \i{UnixWare} and \i{SCO Unix}. ELF provides a default output
 file-name extension of \c{.o}. \c{elf} is a synonym for \c{elf32}.
 
@@ -1383,7 +1383,7 @@ note that only the ".text" section is executable by default.
 \H{aoutfmt} \i\c{aout}: Linux \I{a.out, Linux version}\I{linux, a.out}\c{a.out} Object Files
 
 The \c{aout} format generates \c{a.out} object files, in the form used
-by early Linux systems (current Linux systems use ELF, see
+by early \i{Linux} systems (current Linux systems use ELF, see
 \k{elffmt}.) These differ from other \c{a.out} object files in that
 the magic number in the first four bytes of the file is
 different; also, some implementations of \c{a.out}, for example
@@ -1490,5 +1490,3 @@ them all to its output file.
 where \c{<size>} is either a number or \c{unlimited}, can be used to
 control the maximum size for dumping the full contents of a
 \c{rawdata} output object.
-
-

doc/preproc.src

@@ -396,7 +396,7 @@ Using this feature, we can simplify references to a lot of macros (and,
 in turn, reduce typing errors).
 
 
-\S{selfref%?} The Macro Name Itself: \i\c{%?} and \i\c{%??}
+\S{selfref%?} The Macro Name Itself: \i\c{%?} and \c{%??}
 
 The special symbols \c{%?} and \c{%??} can be used to reference the
 macro name itself inside a macro expansion, this is supported for both
@@ -422,7 +422,7 @@ will expand to:
 These tokens can be used for single-line macros \e{if defined outside
 any multi-line macros.} See below.
 
-\S{selfref%*?} The Single-Line Macro Name: \i\c{%*?} and \i\c{%*??}
+\S{selfref%*?} The Single-Line Macro Name: \i\c{%*?} and \c{%*??}
 
 If the tokens \c{%?} and \c{%??} are used inside a multi-line macro,
 they are expanded before any directives are processed. As a result,

doc/running.src

@@ -28,7 +28,7 @@ To get further usage instructions from NASM, try typing
 
 The option \c{--help} is an alias for the \c{-h} option.
 
-If you use Linux but aren't sure whether your system is \c{a.out}
+If you use \i{Linux} but aren't sure whether your system is \c{a.out}
 or ELF, type
 
 \c file nasm
@@ -38,12 +38,12 @@ installed it). If it says something like
 
 \c nasm: ELF 32-bit LSB executable i386 (386 and up) Version 1
 
-then your system is \c{ELF}, and you should use the option \c{-f elf}
+then your system is \i\c{ELF}, and you should use the option \c{-f elf}
 when you want NASM to produce Linux object files. If it says
 
 \c nasm: Linux/i386 demand-paged executable (QMAGIC)
 
-or something similar, your system is \c{a.out}, and you should use
+or something similar, your system is \i\c{a.out}, and you should use
 \c{-f aout} instead (Linux \c{a.out} systems have long been obsolete,
 and are rare these days.)
 
@@ -807,5 +807,3 @@ details.
 \S{masm-compat} MASM compatibility package
 
 See \k{pkg_masm}.
-
-