doc: improve the build from source documentation

Update and improve the build from source documentation, including add
an auto-generated list of Perl build dependencies.

Signed-off-by: H. Peter Anvin (Intel) <hpa@zytor.com>

Author: H. Peter Anvin

.gitignore

@@ -71,6 +71,7 @@ TAGS
 /doc/inslist.src
 /doc/version.src
 /doc/warnings.src
+/doc/perlbreq.src
 /doc/fontpath
 /doc/Fontmap
 /include/warnings.h

Makefile.in

@@ -442,7 +442,7 @@ cscope:
 	$(FIND) . -name '*.[hcS]' -print > cscope.files
 	cscope -b -f cscope.out
 
-doc: doc/warnings.src
+doc: doc/warnings.src doc/perlbreq.src
 	$(MAKE) -C doc all
 
 doc_install install_doc:
@@ -478,6 +478,11 @@ perlbreq.si: $(ALLPERLSRC)
 	sed -r -e '/perl\((Win32.*)\)/d' | \
 	sort | uniq > perlbreq.si
 
+doc/perlbreq.src: perlbreq.si
+	sed -n -r -e 's/^BuildRequires: perl\((.*)\)$$/\\c      \1/p' \
+		< perlbreq.si > doc/perlbreq.src
+	echo '\c      Win32 (if building on Windows only)' >> doc/perlbreq.src
+
 nasm.spec: nasm.spec.in nasm.spec.sed version.sed perlbreq.si
 	sed -f version.sed -f nasm.spec.sed \
 	< nasm.spec.in > nasm.spec

doc/Makefile.in

@@ -20,7 +20,8 @@ INSTALL		= @INSTALL@
 INSTALL_PROGRAM	= @INSTALL_PROGRAM@
 INSTALL_DATA	= @INSTALL_DATA@
 
-PERL		= perl -I$(top_srcdir)/perllib -I$(srcdir)
+PERL		= perl
+RUNPERL		= $(PERL) -I$(top_srcdir)/perllib -I$(srcdir)
 
 PDFOPT		= @PDFOPT@
 
@@ -39,7 +40,8 @@ XZFILES         = @XZFILES@
 # Auxiliary files referenced by the HTML files
 HTMLAUX		= nasmdoc.css local.css nasmlogw.png
 
-SRCS		= nasmdoc.src inslist.src changes.src warnings.src version.src
+SRCS		= nasmdoc.src inslist.src changes.src \
+		  warnings.src version.src perlbreq.src
 OUT		= html nasmdoc.txt nasmdoc.pdf $(XZFILES)
 XZOUT           = nasmdoc.pdf.xz
 
@@ -59,14 +61,14 @@ all: $(OUT)
 xzfiles: $(XZOUT)
 
 inslist.src: inslist.pl ../x86/insns.dat
-	$(PERL) $(srcdir)/inslist.pl $(srcdir)/../x86/insns.dat
+	$(RUNPERL) $^
 
 html: $(HTMLAUX)
 	$(MKDIR_P) html
 	for f in $(HTMLAUX); do $(CP_UF) "$(srcdir)/$$f" html/; done
 	$(MAKE) html/nasmdoc0.html
 
-RDSRC = $(PERL) $(srcdir)/rdsrc.pl -I$(srcdir)/
+RDSRC = $(RUNPERL) $(srcdir)/rdsrc.pl -I$(srcdir)/
 
 html/nasmdoc0.html: $(SRCS) rdsrc.pl
 	$(RM_F) html/*.html
@@ -79,12 +81,12 @@ nasmdoc.txt: $(SRCS) rdsrc.pl
 	$(RDSRC) txt nasmdoc.src
 
 version.src: $(top_srcdir)/version.pl $(top_srcdir)/version
-	$(PERL) $(top_srcdir)/version.pl docsrc \
+	$(RUNPERL) $(top_srcdir)/version.pl docsrc \
 		< $(top_srcdir)/version > version.src
 
 nasmdoc.ps: nasmdoc.dip genps.pl afmmetrics.ph ttfmetrics.ph \
 	pswidth.ph nasmlogo.eps psfonts.ph head.ps
-	$(PERL) $(srcdir)/genps.pl -epsdir "$(srcdir)" \
+	$(RUNPERL) $(srcdir)/genps.pl -epsdir "$(srcdir)" \
 		-headps $(srcdir)/head.ps \
 		-fontpath fontpath \
 		-fontmap Fontmap \
@@ -97,11 +99,11 @@ Fontmap: nasmdoc.ps
 	@: Generated by side effect
 
 nasmdoc.pdf: nasmdoc.ps pspdf.pl fontpath
-	$(PERL) $(srcdir)/pspdf.pl \
+	$(RUNPERL) $(srcdir)/pspdf.pl \
 		$(PDFOPT) $< $@ fontpath
 
 nasmdoc-raw.pdf: nasmdoc.ps pspdf.pl fontpath
-	$(PERL) $(srcdir)/pspdf.pl -nocompress \
+	$(RUNPERL) $(srcdir)/pspdf.pl -nocompress \
 		$(PDFOPT) $< $@ fontpath
 
 nasmdoc.pdf.xz: nasmdoc-raw.pdf
@@ -111,7 +113,7 @@ nasmdoc.pdf.xz: nasmdoc-raw.pdf
 clean:
 	-$(RM_F) *.rtf *.hpj *.texi *.gid *.ipf *.dip
 	-$(RM_F) *.aux *.cp *.fn *.ky *.pg *.log *.toc *.tp *.vr
-	-$(RM_F) inslist.src version.src fontpath Fontmap
+	-$(RM_F) inslist.src version.src perlbreq.src fontpath Fontmap
 	-$(RM_F) nasmdoc*.ps nasmdoc-raw.pdf
 
 spotless: clean

doc/changes.src

@@ -9,8 +9,7 @@ since 2007.
 
 \S{cl-2.17} Version 2.17
 
-\b ... here goes release notes not intended to be included in the
-2.16.xx stable series ...
+\b Improve the documentation for building from source (\k{source}).
 
 \S{cl-2.16.04} Version 2.16.04
 

doc/nasmdoc.src

@@ -8946,7 +8946,7 @@ a zero-extended absolute displacement can access from 0 to 4 GB.
 On Unix, the 64-bit ABI as well as the x32 ABI (32-bit ABI with the
 CPU in 64-bit mode) is defined by the documents at:
 
-\W{http://www.nasm.us/abi/unix64}\c{http://www.nasm.us/abi/unix64}
+\W{https://www.nasm.us/abi/unix64}\c{https://www.nasm.us/abi/unix64}
 
 Although written for AT&T-syntax assembly, the concepts apply equally
 well for NASM-style assembly.  What follows is a simplified summary.
@@ -8980,7 +8980,7 @@ Integer and SSE register arguments are counted separately, so for the case of
 
 The Win64 ABI is described by the document at:
 
-\W{http://www.nasm.us/abi/win64}\c{http://www.nasm.us/abi/win64}
+\W{https://www.nasm.us/abi/win64}\c{https://www.nasm.us/abi/win64}
 
 What follows is a simplified summary.
 
@@ -9294,32 +9294,109 @@ anyway.
 \A{source} Building NASM from Source
 
 The source code for NASM is available from our website,
-\W{http://www.nasm.us/}{http://www.nasm.us/}, see \k{website}.
+\w{https://www.nasm.us/}, see \k{website}.
 
 \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.  This is the recommended method for
 building NASM to support platforms for which executables are not
-available.
+available, if you do not require changing the source code.
 
-On a system which has Unix shell (\c{sh}), run:
+The preferred build platforms are development environments which
+support POSIX (Unix)-style tools (a "POSIX environment"). For Windows,
+MSYS2 (\w{https://www.msys2.org/}) is such a development environment.
+
+In a POSIX environment, run:
 
 \c      sh configure
-\c      make everything
+\c      make
 
 A number of options can be passed to \c{configure}; see
-\c{sh configure --help}.
+\c{sh configure --help}. In particular, the \c{--host} option can be
+used to cross-compile NASM to run on another host system.
+
+For non-POSIX environments, a set of Makefiles for some other
+environments are also available; please see the file
+\c{Mkfiles/README}.
+
+The \c{.zip} version of the source archive has DOS/Windows line
+endings (\c{CR LF}), which many POSIX systems will not recognize. To
+extract the \c{.zip} version on such a system, use \c{unzip
+-a}. The \c{.tar} versions of the source archive has POSIX line
+endings (\c{LF}).
+
+
+\H{buildtools} Optional Build Tools
+
+The following additional tools are required to build specific
+subsystems, to build from the \c{git} repository, or if the sources
+are modified.
+
+Note that some of these tools will have their own dependencies.
+
+Make sure all tools are available in your \c{PATH} (or equivalent.)
+
+To build the installer for the Windows platform:
+
+\b The \i{Nullsoft Scriptable Installer} (\i{NSIS},
+\w{https://nsis-dev.github.io/}).
+
+To modify the sources, \e{or} to build the documentation:
+
+\b A Perl interpreter (\w{https://www.perl.org/}).
+
+\b Modules from CPAN (\w{https://www.cpan.org/}). The following Perl
+modules are currently required, some of which will be bundled with the
+Perl interpreter or into larger CPAN packages:
+
+\& perlbreq.src
+
+To build the documentation:
+
+\b Either Ghostscript (\w{https://www.ghostscript.com/}) or Adobe
+Acrobat Distiller (untested.)
+
+\b The Adobe \e{Source Sans} (or \e{Source Sans 3}) and \e{Source
+Code} fonts, which are freely available under the SIL Open Font
+License (\w{https://fonts.adobe.com/}).
+
+To build the Unix man pages:
+
+\b AsciiDoc (\w{https://asciidoc.org/}).
+
+\b xmlto (\w{https://pagure.io/xmlto/}).
+
+To build from the \c{git} repository on a POSIX platform:
 
-A set of Makefiles for some other environments are also available;
-please see the file \c{Mkfiles/README}.
+\b GNU \c{m4}, \c{autoconf} and \c{autoheader}
+(\w{https://www.gnu.org/}).
 
-To build the installer for the Windows platform, you will need the
-\i\e{Nullsoft Scriptable Installer}, \i{NSIS}, installed.
 
-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{buildopt} Building Optional Components
+
+Install the required tools for the subsystem in question as described
+in \k{buildtools}.
+
+To build the documentation:
+
+\c      make doc
+
+Building the documentation may not work in a non-POSIX environment.
+
+To build the Windows installer:
+
+\c      make nsis
+
+To build the Unix man pages:
+
+\c      make manpages
+
+To build everything available on the current platform:
+
+\c      make everything
+
 
 \H{git} Building from the \i\c{git} Repository
 
@@ -9328,30 +9405,45 @@ the \c{git} distributed source control system.  The link is available
 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
-interpreter and, if building on a Unix system, GNU autoconf installed
-on your system.
+Install the required tools as described in section \k{buildtools}.
+
+In a POSIX environment:
 
-To build on a Unix system, run:
+Run:
 
 \c      sh autogen.sh
 
-to create the \c{configure} script and then build as listed above.
+to create the \c{configure} script and then build as described in
+\k{tarball}.
+
+In a non-POSIX environment, use the tool-specific Makefiles
+as described in \k{tarball}.
+
+
+\H{modifysrc} Modifying the Sources
+
+To build modified sources, you will need the tools described in
+\k{buildtools}.
+
+Some build system changes might not be possible without a POSIX
+environment.
+
+If you have modified the sources to change the embedded declarations
+of warning classes, you may have to manually re-build the warning
+catalog:
+
+\c      make warnings
 
-\H{builddoc} Building the documentation
+This is not done automatically, as the tools do not have the ability
+to automatically detect when it is necessary to do so.
 
-To build the documentation, you will need a Perl interpreter, a
-Postscript to PDF converter such as Ghostscript, and suitable fonts
-installed on your system. The recommended (and default) fonts are
-Adobe's Source Sans and Source Code fonts, which are freely available
-under the SIL Open Font License.
 
 \A{contact} Contact Information
 
 \H{website} Website
 
 NASM has a \i{website} at
-\W{http://www.nasm.us/}\c{http://www.nasm.us/}.
+\w{https://www.nasm.us/}.
 
 \i{New releases}, \i{release candidates}, and \I{snapshots, daily
 development}\i{daily development snapshots} of NASM are available from
@@ -9374,7 +9466,7 @@ 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
+\w{https://www.nasm.us/} (click on "Bug
 Tracker"), or if that fails then through one of the contacts in
 \k{website}.