nasmdoc.src: move bug reporting to appendix, mention forums

Move information about the bug reporting to the appendix.  Split
building from source and website/community info into separate
appendices.

Signed-off-by: H. Peter Anvin <hpa@linux.intel.com>

1 files changed, 126 insertions, 126 deletions

diff --git a/doc/nasmdoc.src b/doc/nasmdoc.src
index 1f39dc68..79eb59d0 100644
--- a/doc/nasmdoc.src
+++ b/doc/nasmdoc.src
@@ -7815,9 +7815,8 @@ Integer and SSE register arguments are counted together, so for the case of
 \C{trouble} Troubleshooting
 
 This chapter describes some of the common problems that users have
-been known to encounter with NASM, and answers them. It also gives
-instructions for reporting bugs in NASM if you find a difficulty
-that isn't listed here.
+been known to encounter with NASM, and answers them.  If you think you
+have found a bug in NASM, please see \k{bugs}.
 
 
 \H{problems} Common Problems
@@ -7920,93 +7919,6 @@ in which \c{$} and \c{$$} are offsets from the same section base,
 and so their difference is a pure number. This will solve the
 problem and generate sensible code.
 
-
-\H{bugs} \i{Bugs}\I{reporting bugs}
-
-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 firstly via the
-\i\c{bugtracker} at
-\W{http://www.nasm.us/}\c{http://www.nasm.us/}
-(click on "Bug Tracker"), or if that fails then through one of the
-contacts in \k{contact}.
-
-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
-is badly thought out, feel free to send us reasons why you think it
-should be changed, but don't just send us mail saying `This is a
-bug' if the documentation says we did it on purpose.) Then read
-\k{problems}, and don't bother reporting the bug if it's listed
-there.
-
-If you do report a bug, \e{please} give us all of the following
-information:
-
-\b What operating system you're running NASM under. DOS, Linux,
-NetBSD, Win16, Win32, VMS (I'd be impressed), whatever.
-
-\b If you're running NASM under DOS or Win32, tell us whether you've
-compiled your own executable from the DOS source archive, or whether
-you were using the standard distribution binaries out of the
-archive. If you were using a locally built executable, try to
-reproduce the problem using one of the standard binaries, as this
-will make it easier for us to reproduce your problem prior to fixing
-it.
-
-\b Which version of NASM you're using, and exactly how you invoked
-it. Give us the precise command line, and the contents of the
-\c{NASMENV} environment variable if any.
-
-\b Which versions of any supplementary programs you're using, and
-how you invoked them. If the problem only becomes visible at link
-time, tell us what linker you're using, what version of it you've
-got, and the exact linker command line. If the problem involves
-linking against object files generated by a compiler, tell us what
-compiler, what version, and what command line or options you used.
-(If you're compiling in an IDE, please try to reproduce the problem
-with the command-line version of the compiler.)
-
-\b If at all possible, send us a NASM source file which exhibits the
-problem. If this causes copyright problems (e.g. you can only
-reproduce the bug in restricted-distribution code) then bear in mind
-the following two points: firstly, we guarantee that any source code
-sent to us for the purposes of debugging NASM will be used \e{only}
-for the purposes of debugging NASM, and that we will delete all our
-copies of it as soon as we have found and fixed the bug or bugs in
-question; and secondly, we would prefer \e{not} to be mailed large
-chunks of code anyway. The smaller the file, the better. A
-three-line sample file that does nothing useful \e{except}
-demonstrate the problem is much easier to work with than a
-fully fledged ten-thousand-line program. (Of course, some errors
-\e{do} only crop up in large files, so this may not be possible.)
-
-\b A description of what the problem actually \e{is}. `It doesn't
-work' is \e{not} a helpful description! Please describe exactly what
-is happening that shouldn't be, or what isn't happening that should.
-Examples might be: `NASM generates an error message saying Line 3
-for an error that's actually on Line 5'; `NASM generates an error
-message that I believe it shouldn't be generating at all'; `NASM
-fails to generate an error message that I believe it \e{should} be
-generating'; `the object file produced from this source code crashes
-my linker'; `the ninth byte of the output file is 66 and I think it
-should be 77 instead'.
-
-\b If you believe the output file from NASM to be faulty, send it to
-us. That allows us to determine whether our own copy of NASM
-generates the same file, or whether the problem is related to
-portability issues between our development platforms and yours. We
-can handle binary files mailed to us as MIME attachments, uuencoded,
-and even BinHex. Alternatively, we may be able to provide an FTP
-site you can upload the suspect files to; but mailing them is easier
-for us.
-
-\b Any other information or data files that might be helpful. If,
-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.
-
-
 \A{ndisasm} \i{Ndisasm}
 
                   The Netwide Disassembler, NDISASM
@@ -8175,16 +8087,6 @@ data section which wouldn't contain anything you wanted to see
 anyway.
 
 
-\H{ndisbugs} Bugs and Improvements
-
-There are no known bugs. However, any you find, with patches if
-possible, should be sent to
-\W{mailto:nasm-bugs@lists.sourceforge.net}\c{nasm-bugs@lists.sourceforge.net}, or to the
-developer's site at
-\W{http://www.nasm.us/}\c{http://www.nasm.us/}
-and we'll try to fix them. Feel free to send contributions and
-new features as well.
-
 \A{inslist} \i{Instruction List}
 
 \H{inslistintro} Introduction
@@ -8200,36 +8102,25 @@ column shows the processor type in which the instruction was introduced and,
 
 \& changes.src
 
-\A{contact} Compiling and Contact Information
-
-\H{website} Where to Get NASM and How to Contact Us
+\A{source} Building NASM from Source
 
-NASM has a \i{website} at
-\W{http://www.nasm.us/}\c{http://www.nasm.us/}.
-
-\i{New releases}, \i{release candidates}, and \I{snapshots, daily
-development}\i{daily development snapshots} of NASM are available from
-the official web site in source form as well as binaries for a number
-of common platforms.
-
-If you want information about the current development status or
-participate in the development, please subscribe to the
-\i\c{nasm-devel} email list; see link from the website.
+The source code for NASM is available from our website,
+\W{http://www.nasm.us/}{http://wwww.nasm.us/}, see \k{website}.
 
-To report bugs in NASM, please file a bug report in the bug tracker on
-our website.
-
-\H{source} Building NASM from Source
+\H{tarball} Building from a Source Archive
 
 The source archives available on the web site should be capable of
-building on a number of platforms.  On a system which has Unix shell,
-run:
+building on a number of platforms.  This is the recommended method for
+building NASM to support platforms for which executables are not
+available.
+
+On a system which has Unix shell (\c{sh}), run:
 
-\c      ./configure
+\c      sh configure
 \c      make everything
 
-A number of options can be passed to \c{./configure}; see
-\c{./configure --help}.
+A number of options can be passed to \c{configure}; see
+\c{sh configure --help}.
 
 A set of Makefiles for some other environments are also available;
 please see the file \c{Mkfiles/README}.
@@ -8241,17 +8132,126 @@ To build the documentation, you will need a set of additional tools.
 The documentation is not likely to be able to build on non-Unix
 systems.
 
-\H{git} Building NASM from the \i\c{git} Repository
+\H{git} Building from the \i\c{git} Repository
 
 The NASM development tree is kept in a source code repository using
 the \c{git} distributed source control system.  The link is available
-on the website.
+on the website.  This is recommended only to participate in the
+development of NASM or to assist with testing the development code.
 
 To build NASM from the \c{git} repository you will need a Perl and, if
 building on a Unix system, GNU autoconf.
 
 To build on a Unix system, run:
 
-\c      ./autogen.sh
+\c      sh autogen.sh
 
 to create the \c{configure} script and then build as listed above.
+
+\A{contact} Contact Information
+
+\H{website} Website
+
+NASM has a \i{website} at
+\W{http://www.nasm.us/}\c{http://www.nasm.us/}.
+
+\i{New releases}, \i{release candidates}, and \I{snapshots, daily
+development}\i{daily development snapshots} of NASM are available from
+the official web site in source form as well as binaries for a number
+of common platforms.
+
+\S{forums} User Forums
+
+Users of NASM may find the Forums on the website useful.  These are,
+however, not frequented much by the developers of NASM, so they are
+not suitable for reporting bugs.
+
+\S{develcom} Development Community
+
+The development of NASM is coordinated primarily though the
+\i\c{nasm-devel} mailing list.  If you wish to participate in
+development of NASM, please join this mailing list.  Subscription
+links and archives of past posts are available on the website.
+
+\H{bugs} \i{Reporting Bugs}\I{bugs}
+
+To report bugs in NASM, please use the \i{bug tracker} at
+\W{http://www.nasm.us/}\c{http://www.nasm.us/} (click on "Bug
+Tracker"), or if that fails then through one of the contacts in
+\k{website}.
+
+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
+is badly thought out, feel free to send us reasons why you think it
+should be changed, but don't just send us mail saying `This is a
+bug' if the documentation says we did it on purpose.) Then read
+\k{problems}, and don't bother reporting the bug if it's listed
+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,
+FreeBSD, NetBSD, MacOS X, Win16, Win32, Win64, MS-DOS, OS/2, VMS,
+whatever.
+
+\b If you compiled your own executable from a source archive, compiled
+your own executable from \c{git}, used the standard distribution
+binaries from the website, or got an executable from somewhere else
+(e.g. a Linux distribution.) If you were using a locally built
+executable, try to reproduce the problem using one of the standard
+binaries, as this will make it easier for us to reproduce your problem
+prior to fixing it.
+
+\b Which version of NASM you're using, and exactly how you invoked
+it. Give us the precise command line, and the contents of the
+\c{NASMENV} environment variable if any.
+
+\b Which versions of any supplementary programs you're using, and
+how you invoked them. If the problem only becomes visible at link
+time, tell us what linker you're using, what version of it you've
+got, and the exact linker command line. If the problem involves
+linking against object files generated by a compiler, tell us what
+compiler, what version, and what command line or options you used.
+(If you're compiling in an IDE, please try to reproduce the problem
+with the command-line version of the compiler.)
+
+\b If at all possible, send us a NASM source file which exhibits the
+problem. If this causes copyright problems (e.g. you can only
+reproduce the bug in restricted-distribution code) then bear in mind
+the following two points: firstly, we guarantee that any source code
+sent to us for the purposes of debugging NASM will be used \e{only}
+for the purposes of debugging NASM, and that we will delete all our
+copies of it as soon as we have found and fixed the bug or bugs in
+question; and secondly, we would prefer \e{not} to be mailed large
+chunks of code anyway. The smaller the file, the better. A
+three-line sample file that does nothing useful \e{except}
+demonstrate the problem is much easier to work with than a
+fully fledged ten-thousand-line program. (Of course, some errors
+\e{do} only crop up in large files, so this may not be possible.)
+
+\b A description of what the problem actually \e{is}. `It doesn't
+work' is \e{not} a helpful description! Please describe exactly what
+is happening that shouldn't be, or what isn't happening that should.
+Examples might be: `NASM generates an error message saying Line 3
+for an error that's actually on Line 5'; `NASM generates an error
+message that I believe it shouldn't be generating at all'; `NASM
+fails to generate an error message that I believe it \e{should} be
+generating'; `the object file produced from this source code crashes
+my linker'; `the ninth byte of the output file is 66 and I think it
+should be 77 instead'.
+
+\b If you believe the output file from NASM to be faulty, send it to
+us. That allows us to determine whether our own copy of NASM
+generates the same file, or whether the problem is related to
+portability issues between our development platforms and yours. We
+can handle binary files mailed to us as MIME attachments, uuencoded,
+and even BinHex. Alternatively, we may be able to provide an FTP
+site you can upload the suspect files to; but mailing them is easier
+for us.
+
+\b Any other information or data files that might be helpful. If,
+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.