Date: Tue, 19 Jun 2001 20:56:14 +0300
From: "Eli Zaretskii" <eliz AT is DOT elta DOT co DOT il>
Sender: halo1 AT zahav DOT net DOT il
To: djgpp-workers AT delorie DOT com
Message-Id: <2950-Tue19Jun2001205614+0300-eliz@is.elta.co.il>
X-Mailer: Emacs 20.6 (via feedmail 8.3.emacs20_6 I) and Blat ver 1.8.9
In-reply-to: <200106191551.LAA27550@delorie.com> (cvs@delorie.com)
Subject: Re: djgpp: djgpp/src/utils/djasm.txi,shift.txi
References:  <200106191551 DOT LAA27550 AT delorie DOT com>
Reply-To: djgpp-workers AT delorie DOT com
Errors-To: nobody AT delorie DOT com
X-Mailing-List: djgpp-workers AT delorie DOT com
X-Unsubscribes-To: listserv AT delorie DOT com
Precedence: bulk

> Date: Tue, 19 Jun 2001 11:51:36 -0400
> From: "cvs-jtw AT delorie DOT com" <cvs AT delorie DOT com>

Some nitpicking:

> ! The @acronym{GNU} assembler @acronym{AS} (@file{as.exe})

I think the official name of the GNU assembler is Gas, not AS.  So I
think we should use either @acronym{GAS} or simply Gas.

>                                                            is part of
> ! the DJGPP @file{bnuNNNb.zip} archive and should be available in the

In Texinfo, bnuNNNb.zip is better written as @file{bnu AT var{nnn}b.zip}.
(Note that nnn is in lower case.)  This will produce `bnuNNNb.zip' in
Info, like what you wrote, but in the printed manual `nnn' will be
typeset in italics, which is much nicer.

>   Produce a @file{.db} array for other @code{djasm} @file{.asm} files.
>   @item .ah
> ! Produce a @file{.byte} array for @sc{gas} @file{.s} or @file{.S} files.
>   @end table
>   
> --- 334,338 ----
>   Produce a @file{.db} array for other @code{djasm} @file{.asm} files.
>   @item .ah
> ! Produce a @file{.byte} array for @acronym{AS} @file{.s} or @file{.S} files.
>   @end table

Why are .db and .byte in @file?  They aren't files, right?  They
should be in @code, I think.

> ! Emit bytes (if necessary) so that the program counter @var{cs:ip}

@var{cs:ip} is wrong, because cs:ip does not stand for something else;
cs:ip is a literal string, a pair of processor registers.  It's true
that @var produces caps in the Info manual, but in a printed manual it
produces italics, which is not what you want.  So it should be
@code{CS:IP}, I think, or maybe just CS:IP.

>   Usage:  .org @var{offset}
>   
> ! Sets the instruction pointer @var{ip} to @var{offset}.
> ! The @var{ip} can only be increased using @code{.org}, never decreased.

For the same reason, this should be IP and @var{offset}, respectively,
since only `offset' stands for some value.

> + Use an enumeration to define a new type, @samp{boolean}.
> + Load register @var{ax} with the value @samp{false} and
> + register @var{bx} with the value @samp{true}.

`boolean', `true', and `false' should be in @code, not @samp.  @samp
is generally reserved for something you type, whereas these are
symbols.  `ax' and `bx' should be AX and BX, since they are not names
of meta-syntactic variables, but names of registers.

Last, but not least, thanks for this documentation effort, I think it
makes djasm much more acessible and less mysterious for DJGPP users.