doc: improve some formatting, mostly of the warning list

Fix some formatting markups, especially with regards to warnings.

Signed-off-by: H. Peter Anvin <[email protected]>

Author: H. Peter Anvin

asm/assemble.c

@@ -342,8 +342,8 @@ static void debug_macro_out(const struct out_data *data)
  * This warning is currently issued by backends, but in the future
  * this code should be centralized.
  *
- *!zeroing [on] RESx in initialized section becomes zero
- *!  a \c{RESx} directive was used in a section which contains
+ *!zeroing [on] \c{RES}\e{x} in initialized section becomes zero
+ *!  a \c{RES}\e{x} directive was used in a section which contains
  *!  initialized data, and the output format does not support
  *!  this. Instead, this will be replaced with explicit zero
  *!  content, which may produce a large output file.
@@ -698,7 +698,7 @@ static bool jmp_match(int32_t segment, int64_t offset, int bits,
         /* jmp short (opcode eb) cannot be used with bnd prefix. */
         ins->prefixes[PPS_REP] = P_none;
         /*!
-         *!prefix-bnd [on] invalid BND prefix
+         *!prefix-bnd [on] invalid \c{BND} prefix
          *!=bnd
          *!  warns about ineffective use of the \c{BND} prefix when the
          *!  \c{JMP} instruction is converted to the \c{SHORT} form.
@@ -1847,14 +1847,14 @@ static int64_t calcsize(int32_t segment, int64_t offset, int bits,
         if ((!itemp_has(temp,IF_LOCK)  || !is_class(MEMORY, ins->oprs[0].type)) &&
             (!itemp_has(temp,IF_LOCK1) || !is_class(MEMORY, ins->oprs[1].type))) {
             /*!
-             *!prefix-lock-error [on] LOCK prefix on unlockable instruction
+             *!prefix-lock-error [on] \c{LOCK} prefix on unlockable instruction
              *!=lock
              *!  warns about \c{LOCK} prefixes on unlockable instructions.
              */
             nasm_warn(WARN_PREFIX_LOCK_ERROR|ERR_PASS2 , "instruction is not lockable");
         } else if (temp->opcode == I_XCHG) {
             /*!
-             *!prefix-lock-xchg [on] superfluous LOCK prefix on XCHG instruction
+             *!prefix-lock-xchg [on] superfluous \c{LOCK} prefix on \c{XCHG} instruction
              *!  warns about a \c{LOCK} prefix added to an \c{XCHG} instruction.
              *!  The \c{XCHG} instruction is \e{always} locking, and so this
              *!  prefix is not necessary; however, NASM will generate it if

asm/error.c

@@ -132,9 +132,9 @@ void pop_warnings(void)
 	if (!ws->next) {
 		/*!
 		 *!warn-stack-empty [on] warning stack empty
-		 *!  a [WARNING POP] directive was executed when
+		 *!  a \c{[WARNING POP]} directive was executed when
 		 *!  the warning stack is empty. This is treated
-		 *!  as a [WARNING *all] directive.
+		 *!  as a \c{[WARNING *all]} directive.
 		 */
 		nasm_warn(WARN_WARN_STACK_EMPTY, "warning stack empty");
 	} else {
@@ -280,7 +280,7 @@ bool set_warning_status(const char *value)
 
         if (!ok && value) {
             /*!
-             *!unknown-warning [off] unknown warning in -W/-w or warning directive
+             *!unknown-warning [off] unknown warning in \c{-W}/\c{-w} or warning directive
              *!  warns about a \c{-w} or \c{-W} option or a \c{[WARNING]} directive
              *!  that contains an unknown warning name or is otherwise not possible to process.
              */

asm/parser.c

@@ -671,7 +671,7 @@ insn *parse_line(char *buffer, insn *result)
             i = stdscan(NULL, &tokval);
         } else if (i == 0) {
             /*!
-             *!label-orphan [on] labels alone on lines without trailing `:'
+             *!label-orphan [on] labels alone on lines without trailing \c{:}
              *!=orphan-labels
              *!  warns about source lines which contain no instruction but define
              *!  a label without a trailing colon. This is most likely indicative
@@ -831,7 +831,7 @@ insn *parse_line(char *buffer, insn *result)
             if (oper_num == 0)
                 /*!
                  *!db-empty [on] no operand for data declaration
-                 *!  warns about a \c{DB}, \c{DW}, etc declaration
+                 *!  warns about a \c{D}\e{x} declaration
                  *!  with no operands, producing no output.
                  *!  This is permitted, but often indicative of an error.
                  *!  See \k{db}.

asm/pragma.c

@@ -193,7 +193,7 @@ search_pragma_list(const struct pragma_facility *list,
         switch (pragma.opcode) {
         case D_none:
             /*!
-             *!pragma-bad [off] malformed %pragma
+             *!pragma-bad [off] malformed \c{%pragma}
              *!=bad-pragma
              *!  warns about a malformed or otherwise unparsable
              *!  \c{%pragma} directive.
@@ -203,7 +203,7 @@ search_pragma_list(const struct pragma_facility *list,
             break;
         default:
             /*!
-             *!pragma-unknown [off] unknown %pragma facility or directive
+             *!pragma-unknown [off] unknown \c{%pragma} facility or directive
              *!=unknown-pragma
              *!  warns about an unknown \c{%pragma} directive.
              *!  This is not yet implemented for most cases.
@@ -237,15 +237,15 @@ search_pragma_list(const struct pragma_facility *list,
 
 /* This warning message is intended for future use */
 /*!
- *!pragma-na [off] %pragma not applicable to this compilation
+ *!pragma-na [off] \c{%pragma} not applicable to this compilation
  *!=not-my-pragma
  *!  warns about a \c{%pragma} directive which is not applicable to
  *!  this particular assembly session.  This is not yet implemented.
  */
 
 /* Naked %pragma */
 /*!
- *!pragma-empty [off] empty %pragma directive
+ *!pragma-empty [off] empty \c{%pragma} directive
  *!  warns about a \c{%pragma} directive containing nothing.
  *!  This is treated identically to \c{%pragma ignore} except
  *!  for this optional warning.

asm/preproc.c

@@ -1379,12 +1379,12 @@ static Token *tokenize(const char *line)
                      */
                     if (!*p) {
                         /*!
-                         *!pp-open-brackets [on] unterminated %[...]
+                         *!pp-open-brackets [on] unterminated \c{%[...]}
                          *!  warns that a preprocessor \c{%[...]} construct
                          *!  lacks the terminating \c{]} character.
                          */
                         /*!
-                         *!pp-open-braces [on] unterminated %{...}
+                         *!pp-open-braces [on] unterminated \c{%\{...\}}
                          *!  warns that a preprocessor parameter
                          *!  enclosed in braces \c{%\{...\}} lacks the
                          *!  terminating \c{\}} character.
@@ -1449,7 +1449,7 @@ static Token *tokenize(const char *line)
                 type = '%';     /* % operator */
                 if (unlikely(*line == '{')) {
                     /*!
-                     *!pp-empty-braces [on] empty %{} construct
+                     *!pp-empty-braces [on] empty \c{%\{\}} construct
                      *!  warns that an empty \c{%\{\}} was encountered.
                      *!  This expands to a single \c{%} character, which
                      *!  is normally the \c{%} arithmetic operator.
@@ -4432,7 +4432,7 @@ static int do_directive(Token *tline, Token **output)
         goto issue_error;
     case PP_WARNING:
         /*!
-         *!user [on] %warning directives
+         *!user [on] \c{%warning} directives
          *!  controls output of \c{%warning} directives (see \k{pperror}).
          */
         severity = ERR_WARNING|WARN_USER|ERR_PASS2;
@@ -4491,10 +4491,10 @@ static int do_directive(Token *tline, Token **output)
         case COND_ELSE_TRUE:
         case COND_ELSE_FALSE:
             /*!
-             *!pp-else-elif [on] %elif after %else
-             *!  warns that an \c{%%elif}-type directive was encountered
-             *!  after \c[%%else} has already been encounted. As a result, the
-             *!  content of the \c{%%elif} will never be expanded.
+             *!pp-else-elif [on] \c{%elif} after \c{%else}
+             *!  warns that an \c{%elif}-type directive was encountered
+             *!  after \c{%else} has already been encounted. As a result, the
+             *!  content of the \c{%elif} will never be expanded.
              */
             nasm_warn(WARN_PP_ELSE_ELIF|ERR_PP_PRECOND,
                        "`%s' after `%%else', ignoring content", dname);
@@ -4541,7 +4541,7 @@ static int do_directive(Token *tline, Token **output)
         case COND_ELSE_TRUE:
         case COND_ELSE_FALSE:
             /*!
-             *!pp-else-else [on] %else after %else
+             *!pp-else-else [on] \c{%else} after \c{%else}
              *!  warns that a second \c{%else} clause was found for
              *!  the same \c{%if} statement. The content of this \c{%else}
              *!  clause will never be expanded.
@@ -4785,7 +4785,7 @@ static int do_directive(Token *tline, Token **output)
                 count = 0;
             } else if (count < 0) {
                 /*!
-                 *!pp-rep-negative [on] regative %rep count
+                 *!pp-rep-negative [on] regative \c{%rep} count
                  *!=negative-rep
                  *!  warns about a negative count given to the \c{%rep}
                  *!  preprocessor directive.
@@ -7303,8 +7303,8 @@ stdmac_cond_sel(const SMacro *s, Token **params, int nparams)
         }
     } else {
             /*!
-             *!pp-sel-range [on] %sel() argument out of range
-             *!  warns that the %sel() preprocessor function was passed
+             *!pp-sel-range [on] \c{%sel()} argument out of range
+             *!  warns that the \c{%sel()} preprocessor function was passed
              *!  a value less than 1 or larger than the number of available
              *!  arguments.
              */

asm/stdscan.c

@@ -174,11 +174,14 @@ static int stdscan_token(struct tokenval *tv)
 
         token_type = nasm_token_hash(tv->t_charptr, tv);
         if (unlikely(tv->t_flag & TFLAG_WARN)) {
-            /*!
-             *!ptr [on] non-NASM keyword used in other assemblers
-             *!  warns about keywords used in other assemblers that might
-             *!  indicate a mistake in the source code.  Currently only the MASM
-             *!  \c{PTR} keyword is recognized. See also \k{pkg_masm}.
+            /*! ptr [on] non-NASM keyword used in other assemblers
+             *!  warns about keywords used in other assemblers that
+             *!  might indicate a mistake in the source code.
+             *!  Currently only the MASM \c{PTR} keyword is
+             *!  recognized. If (limited) MASM compatibility is
+             *!  desired, the \c{%use masm} macro package is
+             *!  available, see \k{pkg_masm}; however, carefully note
+             *!  the caveats listed.
              */
             nasm_warn(WARN_PTR, "`%s' is not a NASM keyword",
                        tv->t_charptr);

doc/nasmdoc.src

@@ -1264,14 +1264,15 @@ uninitialized}\i{uninitialized} counterparts \i\c{RESB}, \i\c{RESW},
 \i\c\{RESZ}; the \i\c{INCBIN} command, the \i\c{EQU} command, and the
 \i\c{TIMES} prefix.
 
-In this documentation, the notation "\c{Dx}" and "\c{RESx}" is used to
-indicate all the \c{DB} and \c{RESB} type directives, respectively.
+In this documentation, the notation "\c{D}\e{x}" and "\c{RES}\e{x}" is
+used to indicate all the \c{DB} and \c{RESB} type directives,
+respectively.
 
 
-\S{db} \c{Dx}: Declaring Initialized Data
+\S{db} \c{D}\e{x}: Declaring Initialized Data
 
 \i\c{DB}, \i\c{DW}, \i\c{DD}, \i\c{DQ}, \i\c{DT}, \i\c{DO}, \i\c{DY}
-and \i\c{DZ} (collectively "\c{Dx}" in this documentation) are used,
+and \i\c{DZ} (collectively "\c{D}\e{x}" in this documentation) are used,
 much as in MASM, to declare initialized data in the output file. They
 can be invoked in a wide range of ways:
 \I{floating-point}\I{character constant}\I{string constant}
@@ -1337,7 +1338,7 @@ valid:
 \c        dd 16 dup (0xaaaa, ?, 0xbbbbbb)
 \c        dd 64 dup (?)
 
-\I{baddb} The use of \c{$} (current address) in a \c{Dx} statement is
+\I{baddb} The use of \c{$} (current address) in a \c{D}\e{x} statement is
 undefined in the current version of NASM, \e{except in the following
 cases}: