[nasm:nasm-2.16.xx] doc: improve some formatting, mostly of the warning list
nasm-bot for H. Peter Anvin
hpa at zytor.com
Thu Apr 4 13:00:12 PDT 2024
Commit-ID: 33ef63669c3eaad55b050f9354df5a03734756fb
Gitweb: http://repo.or.cz/w/nasm.git?a=commitdiff;h=33ef63669c3eaad55b050f9354df5a03734756fb
Author: H. Peter Anvin <hpa at zytor.com>
AuthorDate: Thu, 4 Apr 2024 12:58:32 -0700
Committer: H. Peter Anvin <hpa at zytor.com>
CommitDate: Thu, 4 Apr 2024 12:58:32 -0700
doc: improve some formatting, mostly of the warning list
Fix some formatting markups, especially with regards to warnings.
Signed-off-by: H. Peter Anvin <hpa at zytor.com>
---
asm/assemble.c | 10 +++++-----
asm/error.c | 6 +++---
asm/parser.c | 4 ++--
asm/pragma.c | 8 ++++----
asm/preproc.c | 24 ++++++++++++------------
asm/stdscan.c | 13 ++++++++-----
doc/nasmdoc.src | 11 ++++++-----
7 files changed, 40 insertions(+), 36 deletions(-)
diff --git a/asm/assemble.c b/asm/assemble.c
index 008b483f..fd768089 100644
--- a/asm/assemble.c
+++ b/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
diff --git a/asm/error.c b/asm/error.c
index 6e3d881c..5c8c0e38 100644
--- a/asm/error.c
+++ b/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.
*/
diff --git a/asm/parser.c b/asm/parser.c
index 26673196..e4c3961b 100644
--- a/asm/parser.c
+++ b/asm/parser.c
@@ -671,7 +671,7 @@ restart_parse:
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 @@ restart_parse:
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}.
diff --git a/asm/pragma.c b/asm/pragma.c
index 0049c069..1b5066e9 100644
--- a/asm/pragma.c
+++ b/asm/pragma.c
@@ -193,7 +193,7 @@ found_it:
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 @@ found_it:
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,7 +237,7 @@ found_it:
/* 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.
@@ -245,7 +245,7 @@ found_it:
/* 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.
diff --git a/asm/preproc.c b/asm/preproc.c
index cf495bcd..ae1ef5ca 100644
--- a/asm/preproc.c
+++ b/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 @@ issue_error:
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 @@ issue_error:
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 @@ issue_error:
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.
*/
diff --git a/asm/stdscan.c b/asm/stdscan.c
index b8f0c850..882b0b8a 100644
--- a/asm/stdscan.c
+++ b/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);
diff --git a/doc/nasmdoc.src b/doc/nasmdoc.src
index 3aabd6c8..a28933b6 100644
--- a/doc/nasmdoc.src
+++ b/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}:
More information about the Nasm-commits
mailing list