aboutsummaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authorH. Peter Anvin <hpa@zytor.com>2002-04-30 20:58:18 +0000
committerH. Peter Anvin <hpa@zytor.com>2002-04-30 20:58:18 +0000
commit41bf8002b2fa402bd344a290fcc9f65de328859c (patch)
treefa1638dfbf73e3a6b96ce99cda1cd5ad9c1adf61 /doc
parentef7468f4ec05f23e8d866493593d7c1f07df5e03 (diff)
downloadnasm-daily-41bf8002b2fa402bd344a290fcc9f65de328859c.tar.gz
nasm-daily-41bf8002b2fa402bd344a290fcc9f65de328859c.tar.xz
nasm-daily-41bf8002b2fa402bd344a290fcc9f65de328859c.zip
Diffstat (limited to 'doc')
-rw-r--r--doc/Makefile29
-rw-r--r--doc/Makefile.in50
-rw-r--r--doc/nasmdoc.src143
-rw-r--r--doc/rdsrc.pl4
4 files changed, 166 insertions, 60 deletions
diff --git a/doc/Makefile b/doc/Makefile
deleted file mode 100644
index c5104052..00000000
--- a/doc/Makefile
+++ /dev/null
@@ -1,29 +0,0 @@
-#
-# UNIX Makefile for NASM documentation
-#
-
-SRCS = nasmdoc.src
-OUT = nasm.info
-
-all: $(OUT)
-
-.SUFFIXES: .src .texi .info .ps .rtf .hpj .ps .txt .pl
-
-# Consider html, txt and src output a side effect
-.src.texi:
- mkdir -p html
- perl ./rdsrc.pl < $<
- mv -f *.html html
-
-nasm.info: nasmdoc.texi
- mkdir -p info
- makeinfo $<
- mv -f *.info *.info-* info
-
-clean:
- -rm -f *.rtf *.hpj *.texi
-
-spotless: clean
- -rm -rf html info *.hlp *.txt *.ps
-
-
diff --git a/doc/Makefile.in b/doc/Makefile.in
new file mode 100644
index 00000000..78fafa3b
--- /dev/null
+++ b/doc/Makefile.in
@@ -0,0 +1,50 @@
+# $Id$
+#
+# UNIX Makefile for NASM documentation
+#
+
+srcdir = @srcdir@
+VPATH = @srcdir@
+prefix = @prefix@
+exec_prefix = @exec_prefix@
+bindir = @bindir@
+mandir = @mandir@
+docdir = $(prefix)/doc/nasm
+infodir = @infodir@
+
+INSTALL = @INSTALL@
+INSTALL_PROGRAM = @INSTALL_PROGRAM@
+INSTALL_DATA = @INSTALL_DATA@
+
+PERL = perl
+MAKEINFO = makeinfo
+
+SRCS = nasmdoc.src
+OUT = nasm.info
+
+all: $(OUT)
+
+.SUFFIXES: .src .texi .info .ps .rtf .hpj .dvi .ps .txt .pl
+
+# Consider html, txt and src output a side effect
+.src.texi:
+ mkdir -p html
+ $(PERL) ./rdsrc.pl < $<
+ mv -f *.html html
+
+nasm.info: nasmdoc.texi
+ mkdir -p info
+ $(MAKEINFO) $<
+ mv -f *.info *.info-* info
+
+clean:
+ -rm -f *.rtf *.hpj *.texi *.ph *.gid
+
+spotless: clean
+ -rm -rf html info *.hlp *.txt *.ps
+
+install: all
+ $(INSTALL_DATA) info/* $(INSTALLROOT)$(infodir)
+ mkdir -p $(INSTALLROOT)$(docdir)/html
+ $(INSTALL_DATA) html/* $(INSTALLROOT)$(docdir)/html
+ $(INSTALL_DATA) nasmdoc.ps nasmdoc.txt $(INSTALLROOT)$(docdir)
diff --git a/doc/nasmdoc.src b/doc/nasmdoc.src
index 2828c7f3..29657073 100644
--- a/doc/nasmdoc.src
+++ b/doc/nasmdoc.src
@@ -1,12 +1,22 @@
-\IR{-o} \c{-o} option
+\# $Id$
+\#
+\# Source code to NASM documentation
+\#
+\IR{-D} \c{-D} option
+\IR{-E} \c{-E} option
+\IR{-I} \c{-I} option
+\IR{-P} \c{-P} option
+\IR{-U} \c{-U} option
+\IR{-a} \c{-a} option
+\IR{-d} \c{-d} option
+\IR{-e} \c{-e} option
\IR{-f} \c{-f} option
-\IR{-l} \c{-l} option
-\IR{-s} \c{-s} option
\IR{-i} \c{-i} option
+\IR{-l} \c{-l} option
+\IR{-o} \c{-o} option
\IR{-p} \c{-p} option
-\IR{-d} \c{-d} option
-\IR{-e} \c{-e} option
-\IR{-a} \c{-a} option
+\IR{-s} \c{-s} option
+\IR{-u} \c{-u} option
\IR{-w} \c{-w} option
\IR{!=} \c{!=} operator
\IR{$ here} \c{$} Here token
@@ -226,14 +236,19 @@ may use NASM.
\H{contact} Contact Information
+The current version of NASM (since 0.98) are maintained by H. Peter
+Anvin, \W{mailto:hpa@zytor.com}\c{hpa@zytor.com}. If you want to report
+a bug, please read \k{bugs} first.
+
NASM has a \i{WWW page} at
-\W{http://www.cryogen.com/Nasm}\c{http://www.cryogen.com/Nasm}. The
-authors are \i{e\-mail}able as
+\W{http://www.cryogen.com/Nasm}\c{http://www.cryogen.com/Nasm}.
+
+The original authors are \i{e\-mail}able as
\W{mailto:jules@earthcorp.com}\c{jules@earthcorp.com} and
-\W{mailto:anakin@pobox.com}\c{anakin@pobox.com}. If you want to
-report a bug to us, please read \k{bugs} first.
+\W{mailto:anakin@pobox.com}\c{anakin@pobox.com}.
\i{New releases} of NASM are uploaded to
+\W{ftp://ftp.kernel.org/pub/software/devel/nasm/}\i\c{ftp.kernel.org},
\W{ftp://sunsite.unc.edu/pub/Linux/devel/lang/assemblers/}\i\c{sunsite.unc.edu},
\W{ftp://ftp.simtel.net/pub/simtelnet/msdos/asmutl/}\i\c{ftp.simtel.net}
and
@@ -247,9 +262,15 @@ Announcements are posted to
\W{ftp://ftp.simtel.net/pub/simtelnet/msdos/asmutl/}\c{ftp.simtel.net}).
If you don't have Usenet access, or would rather be informed by
-\i{e\-mail} when new releases come out, e\-mail
-\W{mailto:anakin@pobox.com}\c{anakin@pobox.com}
-and ask.
+\i{e\-mail} when new releases come out, you can subscribe to the
+\c{nasm-announce} email list by sending an email containing the line
+\c{subscribe nasm-announce} to
+\W{mailto:majordomo@linux.kernel.org}\c{majordomo@linux.kernel.org}.
+
+If you want information about NASM beta releases, please subscribe to
+the \c{nasm-beta} email list by sending an email containing the line
+\c{subscribe nasm-beta} to
+\W{mailto:majordomo@linux.kernel.org}\c{majordomo@linux.kernel.org}.
\H{install} Installation
@@ -281,14 +302,20 @@ want to keep the documentation or test programs.
If you've downloaded the \i{DOS source archive}, \i\c{nasmXXXs.zip},
the \c{nasm} directory will also contain the full NASM \i{source
code}, and a selection of \i{Makefiles} you can (hopefully) use to
-rebuild your copy of NASM from scratch. The file \c{Readme} lists
-the various Makefiles and which compilers they work with. Note that
-the source files \c{insnsa.c} and \c{insnsd.c} are automatically
-generated from the master instruction table \c{insns.dat} by a Perl
-script; a \i{QBasic} version of the program is provided, but it is
-recommended that you use the Perl version. A DOS port of \i{Perl} is
-available from
-\W{http://www.perl.org/CPAN/ports/msdos/}\i{www.perl.org}.
+rebuild your copy of NASM from scratch. The file \c{Readme} lists the
+various Makefiles and which compilers they work with.
+
+Note that the source files \c{insnsa.c}, \c{insnsd.c}, \c{insnsi.h}
+and \c{insnsn.c} are automatically generated from the master
+instruction table \c{insns.dat} by a Perl script; the file
+\c{macros.c} is generated from \c{standard.mac} by another Perl
+script. Although the NASM 0.98 distribution includes these generated
+files, you will need to rebuild them (and hence, will need a Perl
+interpreter) if you change \c{insns.dat}, \c{standard.mac} or the
+documentation. It is possible future source distributions may not
+include these files at all. Ports of \i{Perl} for a variety of
+platforms, including DOS and Windows, are available from
+\W{http://www.cpan.org/ports/}\i{www.cpan.org}.
\S{instdos} Installing NASM under \i{Unix}
@@ -369,7 +396,8 @@ 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
-\c{-f aout} instead.
+\c{-f aout} instead (Linux \c{a.out} systems are considered obsolete,
+and are rare these days.)
Like Unix compilers and assemblers, NASM is silent unless it
goes wrong: you won't see any output at all, unless it gives error
@@ -427,7 +455,7 @@ right. For example:
\c nasm -f elf myfile.asm -l myfile.lst
-\S{opt-s} The \i\c{-s} Option: Send Errors to \i\c{stdout}
+\S{opt-E} The \i\c{-E} Option: Send Errors to a File
Under MS-\i{DOS} it can be difficult (though there are ways) to
redirect the standard-error output of a program to a file. Since
@@ -435,14 +463,25 @@ NASM usually produces its warning and \i{error messages} on
\i\c{stderr}, this can make it hard to capture the errors if (for
example) you want to load them into an editor.
-NASM therefore provides the \c{-s} option, requiring no argument,
-which causes errors to be sent to standard output rather than
+NASM therefore provides the \c{-E} option, taking a filename argument
+which causes errors to be sent to the specified files rather than
standard error. Therefore you can \I{redirecting errors}redirect
the errors into a file by typing
-\c nasm -s -f obj myfile.asm > myfile.err
+\c nasm -E myfile.err -f obj myfile.asm
+
+\S{opt-s} The \i\c{-s} Option: Send Errors to \i\c{stdout}
+
+The \c{-s} option redirects \i{error messages} to \c{stdout} rather
+than \c{stderr}, so it can be redirected under MS-\i{DOS}. To
+assemble the file \c{myfile.asm} and pipe its output to the \c{more}
+program, you can type:
+
+\c nasm -s -f obj myfile.asm | more
+
+See also the \c{-E} option, \k{opt-E}.
-\S{opt-i} The \i\c{-i} Option: Include File Search Directories
+\S{opt-i} The \i\c{-i}\I\c{-I} Option: Include File Search Directories
When NASM sees the \i\c{%include} directive in a source file (see
\k{include}), it will search for the given file not only in the
@@ -471,7 +510,10 @@ similar to \c{/usr/include} on Unix systems, you should place one or
more \c{-i} directives in the \c{NASM} environment variable (see
\k{nasmenv}).
-\S{opt-p} The \i\c{-p} Option: \I{pre-including files}Pre-Include a File
+For Makefile compatibility with many C compilers, this option can also
+be specified as \c{-I}.
+
+\S{opt-p} The \i\c{-p}\I\c{-P} Option: \I{pre-including files}Pre-Include a File
\I\c{%include}NASM allows you to specify files to be
\e{pre-included} into your source file, by the use of the \c{-p}
@@ -482,7 +524,10 @@ option. So running
is equivalent to running \c{nasm myfile.asm} and placing the
directive \c{%include "myinc.inc"} at the start of the file.
-\S{opt-d} The \i\c{-d} Option: \I{pre-defining macros} Pre-Define a Macro
+For consistency with the \c{-I}, \c{-D} and \c{-U} options, this
+option can also be specified as \c{-P}.
+
+\S{opt-d} The \i\c{-d}\I\c{-D} Option: \I{pre-defining macros} Pre-Define a Macro
\I\c{%define}Just as the \c{-p} option gives an alternative to placing
\c{%include} directives at the start of a source file, the \c{-d}
@@ -501,6 +546,26 @@ form of the directive may be useful for selecting \i{assembly-time
options} which are then tested using \c{%ifdef}, for example
\c{-dDEBUG}.
+For Makefile compatibility with many C compilers, this option can also
+be specified as \c{-D}.
+
+\S{opt-u} The \i\c{-u}\I\c{-U} Option: \I{Undefining macros} Undefine a Macro
+
+\I\c{%undef}The \c{-u} option undefines a macro that would otherwise
+have been pre-defined, either automatically or by a \c{-p} or \c{-d}
+option specified earlier on the command lines.
+
+For example, the following command line:
+
+\c nasm myfile.asm -dFOO=100 -uFOO
+
+would result in \c{FOO} \e{not} being a predefined macro in the
+program. This is useful to override options specified at a different
+point in a Makefile.
+
+For Makefile compatibility with many C compilers, this option can also
+be specified as \c{-U}.
+
\S{opt-e} The \i\c{-e} Option: Preprocess Only
NASM allows the \i{preprocessor} to be run on its own, up to a
@@ -1427,6 +1492,22 @@ when defining single-line macros with \c{%assign} (see \k{assign}).
You can \i{pre-define} single-line macros using the `-d' option on
the NASM command line: see \k{opt-d}.
+\S{undef} Undefining macros: \i\c{%undef}
+
+Single-line macros can be removed with the \c{%undef} command. For
+example, the following sequence:
+
+\c %define foo bar
+\c %undef foo
+\c mov eax, foo
+
+will expand to the instruction \c{mov eax, foo}, since after
+\c{%undef} the macro \c{foo} is no longer defined.
+
+Macros that would otherwise be pre-defined can be undefined on the
+command-line using the `-u' option on the NASM command line: see
+\k{opt-u}.
+
\S{assign} \i{Preprocessor Variables}: \i\c{%assign}
An alternative way to define single-line macros is by means of the
@@ -5007,7 +5088,7 @@ problem and generate sensible code.
We have never yet released a version of NASM with any \e{known}
bugs. That doesn't usually stop there being plenty we didn't know
about, though. Any that you find should be reported to
-\W{mailto:anakin@pobox.com}\c{anakin@pobox.com}.
+\W{mailto:hpa@zytor.com}\c{hpa@zytor.com}.
Please read \k{qstart} first, and don't report the bug if it's
listed in there as a deliberate feature. (If you think the feature
@@ -5093,7 +5174,7 @@ each one.
It is not intended to be exhaustive documentation on the fine
details of the instructions' function, such as which exceptions they
can trigger: for such documentation, you should go to Intel's Web
-site, \W{http://www.intel.com}\c{http://www.intel.com}.
+site, \W{http://www.intel.com/}\c{http://www.intel.com/}.
Instead, this appendix is intended primarily to provide
documentation on the way the instructions may be used within NASM.
diff --git a/doc/rdsrc.pl b/doc/rdsrc.pl
index 1a981287..38044b16 100644
--- a/doc/rdsrc.pl
+++ b/doc/rdsrc.pl
@@ -1519,6 +1519,10 @@ sub write_texi {
print "\input texinfo \@c -*-texinfo-*-\n";
print "\@c \%**start of header\n";
print "\@setfilename nasm.info\n";
+ print "\@dircategory Programming\n";
+ print "\@direntry\n";
+ print "* NASM: (nasm). The Netwide Assembler for x86.\n";
+ print "\@end direntry\n";
print "\@settitle NASM: The Netwide Assembler\n";
print "\@setchapternewpage odd\n";
print "\@c \%**end of header\n";