Add autogenerated instruction list to NASM documentation

1. Allow included files in rdsrc.pl
2. New program inslist.pl to generate instruction list from insns.dat
3. Mark certain comments in insns.dat as documentation subheaders
4. Add Instruction List appendix to nasmdoc.src
5. Update build process to invoke inslist.pl

7 files changed, 141 insertions, 33 deletions

diff --git a/doc/Makefile.in b/doc/Makefile.in
index 5c2f905..e0e245e 100644
--- a/doc/Makefile.in
+++ b/doc/Makefile.in
@@ -33,8 +33,9 @@ all: $(OUT)
 os2: nasm.inf
 
 # Consider html, txt and ps output a side effect
-nasmdoc.dip: nasmdoc.src rdsrc.pl
+nasmdoc.dip: nasmdoc.src rdsrc.pl inslist.pl ../insns.dat
 	mkdir -p html
+	$(PERL) $(srcdir)/inslist.pl
 	$(PERL) $(srcdir)/rdsrc.pl < $<
 	mv -f *.html html
 
diff --git a/doc/inslist.pl b/doc/inslist.pl
new file mode 100644
index 0000000..8cab04b
--- /dev/null
+++ b/doc/inslist.pl
@@ -0,0 +1,66 @@
+#!/usr/bin/perl
+#
+# inslist.pl   produce inslist.src
+#
+# The Netwide Assembler is copyright (C) 1996 Simon Tatham and
+# Julian Hall. All rights reserved. The software is
+# redistributable under the licence given in the file "Licence"
+# distributed in the NASM archive.
+
+# Opcode prefixes which need their own opcode tables
+# LONGER PREFIXES FIRST!
+@disasm_prefixes = qw(0F24 0F25 0F38 0F3A 0F7A 0FA6 0FA7 0F);
+
+print STDERR "Reading insns.dat...\n";
+
+@args   = ();
+undef $output;
+foreach $arg ( @ARGV ) {
+    if ( $arg =~ /^\-/ ) {
+	if  ( $arg =~ /^\-([adins])$/ ) {
+	    $output = $1;
+	} else {
+	    die "$0: Unknown option: ${arg}\n";
+	}
+    } else {
+	push (@args, $arg);
+    }
+}
+
+$fname = "../insns.dat" unless $fname = $args[0];
+open (F, $fname) || die "unable to open $fname";
+print STDERR "Writing inslist.src...\n";
+open S, ">inslist.src";
+$line = 0;
+$insns = 0;
+while (<F>) {
+  $line++;
+  if ( /^\s*;/ )  # comments
+  {
+    if ( /^\s*;\#\s*(.+)/ )  # section subheader
+    {
+      print S "\n\\S{} $1\n\n";
+    }
+    next;
+  }
+  chomp;
+  my @entry = split;
+  next if $#entry == -1; # blank lines
+  (warn "line $line does not contain four fields\n"), next if $#entry != 3;
+
+  @entry[1] =~ s/ignore//;
+  @entry[1] =~ s/void//;
+  @entry[3] =~ s/ignore//;
+  @entry[3] =~ s/,SB//;
+  @entry[3] =~ s/,SM//;
+  @entry[3] =~ s/,SM2//;
+  @entry[3] =~ s/,SQ//;
+  @entry[3] =~ s/,AR2//;
+  printf S "\\c %-16s %-24s %s\n",@entry[0],@entry[1],@entry[3];
+  $insns++;
+}
+print S "\n";
+close S;
+close F;
+printf STDERR "Done: %d instructions\n", $insns;
+
diff --git a/doc/makedocs.bat b/doc/makedocs.bat
index 70db811..5372394 100644
--- a/doc/makedocs.bat
+++ b/doc/makedocs.bat
@@ -39,6 +39,7 @@ echo                        This takes a while. Stretch!
 echo.
 echo.
 
+perl inslist.pl
 perl rdsrc.pl<nasmdoc.src
 echo.
 echo.
diff --git a/doc/nasmdoc.src b/doc/nasmdoc.src
index ad79744..a86ca8d 100644
--- a/doc/nasmdoc.src
+++ b/doc/nasmdoc.src
@@ -6880,3 +6880,14 @@ developer's site at
 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
+
+The following sections show the instructions which NASM currently supports. For each
+instruction, there is a separate entry for each supported addressing mode. The third
+column shows the processor type in which the instruction was introduced and,
+ when appropriate, one or more usage flags.
+
+\& inslist.src
+
diff --git a/doc/rdsrc.pl b/doc/rdsrc.pl
index 4965172..a6a7008 100644
--- a/doc/rdsrc.pl
+++ b/doc/rdsrc.pl
@@ -79,6 +79,12 @@
 #   defines document metadata, such as authorship, title and copyright;
 #   different output formats use this differently.
 #
+# Include subfile
+# \&{filename}
+#  Includes filename. Recursion is allowed.
+#
+ 
+use IO::File;
 
 $diag = 1, shift @ARGV if $ARGV[0] eq "-d";
 
@@ -96,15 +102,7 @@ $pname = "para000000";
 @pnames = @pflags = ();
 $para = undef;
 while (<>) {
-  chomp;
-  if (!/\S/ || /^\\(IA|IR|M)/) { # special case: \IA \IR \M imply new-paragraph
-    &got_para($para);
-    $para = undef;
-  }
-  if (/\S/) {
-    s/\\#.*$//; # strip comments
-    $para .= " " . $_;
-  }
+  &check_include($_);
 }
 &got_para($para);
 print "done.\n";
@@ -143,6 +141,33 @@ print "Producing Documentation Intermediate Paragraphs: ";
 &write_dip;
 print "done.\n";
 
+sub check_include {
+  local $_ = shift;
+  if (/\\& (\S+)/) {
+     &include($1);
+  } else {
+     &get_para($_);
+  }
+}
+sub get_para($_) {
+  chomp;
+  if (!/\S/ || /^\\(IA|IR|M)/) { # special case: \IA \IR \M imply new-paragraph
+    &got_para($para);
+    $para = undef;
+  }
+  if (/\S/) {
+    s/\\#.*$//; # strip comments
+    $para .= " " . $_;
+  }
+}
+sub include {
+  my $name = shift;
+  my $F = IO::File->new($name)
+     or die "Cannot open $name: $!";
+  while (<$F>) {
+     &check_include($_);
+  }
+}
 sub got_para {
   local ($_) = @_;
   my $pflags = "", $i, $w, $l, $t;
diff --git a/insns.dat b/insns.dat
index ae89071..8bb0050 100644
--- a/insns.dat
+++ b/insns.dat
@@ -14,8 +14,11 @@
 ; see the comment at the top of assemble.c.  For a detailed description
 ; of the flags (fourth field), please see insns.h.
 ;
+; Comments with a pound sign after the semicolon generate section
+; subheaders in the NASM documentation.
 
-; Special instructions...
+
+;# Special instructions...
 DB		ignore			ignore				ignore
 DW		ignore			ignore				ignore
 DD		ignore			ignore				ignore
@@ -29,7 +32,7 @@ RESQ		ignore			ignore				ignore
 REST		ignore			ignore				ignore
 RESO		ignore			ignore				ignore
 
-; Conventional instructions
+;# Conventional instructions
 AAA		void			\1\x37				8086,NOLONG
 AAD		void			\2\xD5\x0A			8086,NOLONG
 AAD		imm			\1\xD5\24			8086,SB,NOLONG
@@ -1375,7 +1378,7 @@ Jcc		imm			\330\x70\50			8086
 SETcc		mem			\1\x0F\330\x90\200		386,SB
 SETcc		reg8			\1\x0F\330\x90\200		386
 
-; Katmai Streaming SIMD instructions (SSE -- a.k.a. KNI, XMM, MMX2)
+;# Katmai Streaming SIMD instructions (SSE -- a.k.a. KNI, XMM, MMX2)
 ADDPS		xmmreg,xmmrm		\331\2\x0F\x58\110		KATMAI,SSE
 ADDSS		xmmreg,xmmrm		\333\2\x0F\x58\110		KATMAI,SSE
 ANDNPS		xmmreg,xmmrm		\2\x0F\x55\110			KATMAI,SSE
@@ -1457,11 +1460,12 @@ UNPCKHPS	xmmreg,xmmrm		\2\x0F\x15\110			KATMAI,SSE
 UNPCKLPS	xmmreg,xmmrm		\2\x0F\x14\110			KATMAI,SSE
 XORPS		xmmreg,xmmrm		\2\x0F\x57\110			KATMAI,SSE
 
-; Introduced in Deschutes but necessary for SSE support
+;# Introduced in Deschutes but necessary for SSE support
 FXRSTOR		mem			\2\x0F\xAE\201			P6,SSE,FPU
 FXSAVE		mem			\2\x0F\xAE\200			P6,SSE,FPU
 
-; These instructions are not SSE-specific; they are generic memory operations
+; These instructions are not SSE-specific; they are
+;# Generic memory operations
 ; and work even if CR4.OSFXFR == 0
 PREFETCHNTA	mem			\2\x0F\x18\200			KATMAI
 PREFETCHT0	mem			\2\x0F\x18\201			KATMAI
@@ -1469,7 +1473,7 @@ PREFETCHT1	mem			\2\x0F\x18\202			KATMAI
 PREFETCHT2	mem			\2\x0F\x18\203			KATMAI
 SFENCE		void			\3\x0F\xAE\xF8			KATMAI
 
-; New MMX instructions introduced in Katmai
+;# New MMX instructions introduced in Katmai
 MASKMOVQ	mmxreg,mmxreg		\2\x0F\xF7\110			KATMAI,MMX
 MOVNTQ		mem,mmxreg		\2\x0F\xE7\101			KATMAI,MMX,SM
 PAVGB		mmxreg,mmxrm		\2\x0F\xE0\110			KATMAI,MMX,SM
@@ -1490,14 +1494,14 @@ PMULHUW		mmxreg,mmxrm		\2\x0F\xE4\110			KATMAI,MMX,SQ
 PSADBW		mmxreg,mmxrm		\2\x0F\xF6\110			KATMAI,MMX,SQ
 PSHUFW		mmxreg,mmxrm,imm	\2\x0F\x70\110\22		KATMAI,MMX,SM2,SB,AR2
 
-; AMD Enhanced 3DNow! (Athlon) instructions
+;# AMD Enhanced 3DNow! (Athlon) instructions
 PF2IW		mmxreg,mmxrm		\2\x0F\x0F\110\01\x1C		PENT,3DNOW,SQ
 PFNACC		mmxreg,mmxrm		\2\x0F\x0F\110\01\x8A		PENT,3DNOW,SQ
 PFPNACC		mmxreg,mmxrm		\2\x0F\x0F\110\01\x8E		PENT,3DNOW,SQ
 PI2FW		mmxreg,mmxrm		\2\x0F\x0F\110\01\x0C		PENT,3DNOW,SQ
 PSWAPD		mmxreg,mmxrm		\2\x0F\x0F\110\01\xBB		PENT,3DNOW,SQ
 
-; Willamette SSE2 Cacheability Instructions
+;# Willamette SSE2 Cacheability Instructions
 MASKMOVDQU	xmmreg,xmmreg		\366\2\x0F\xF7\110		WILLAMETTE,SSE2
 ; CLFLUSH needs its own feature flag implemented one day
 CLFLUSH		mem			\2\x0F\xAE\207			WILLAMETTE,SSE2
@@ -1508,7 +1512,7 @@ PAUSE		void			\333\1\x90			WILLAMETTE,SSE2
 LFENCE		void			\3\x0F\xAE\xE8			WILLAMETTE,SSE2
 MFENCE		void			\3\x0F\xAE\xF0			WILLAMETTE,SSE2
 
-; Willamette MMX instructions (SSE2 SIMD Integer Instructions)
+;# Willamette MMX instructions (SSE2 SIMD Integer Instructions)
 MOVD		xmmreg,reg32		\366\2\x0F\x6E\110		WILLAMETTE,SSE2
 MOVD		reg32,xmmreg		\366\2\x0F\x7E\101		WILLAMETTE,SSE2
 MOVD		mem,xmmreg		\366\2\x0F\x7E\101		WILLAMETTE,SSE2,SD
@@ -1612,7 +1616,7 @@ PUNPCKLDQ	xmmreg,xmmrm		\366\2\x0F\x62\110		WILLAMETTE,SSE2,SM
 PUNPCKLQDQ	xmmreg,xmmrm		\366\2\x0F\x6C\110		WILLAMETTE,SSE2,SM
 PXOR		xmmreg,xmmrm		\366\2\x0F\xEF\110		WILLAMETTE,SSE2,SM
 
-; Willamette Streaming SIMD instructions (SSE2)
+;# Willamette Streaming SIMD instructions (SSE2)
 ADDPD		xmmreg,xmmrm		\331\366\2\x0F\x58\110		WILLAMETTE,SSE2,SM
 ADDSD		xmmreg,xmmrm		\331\332\2\x0F\x58\110		WILLAMETTE,SSE2
 ANDNPD		xmmreg,xmmrm		\331\366\2\x0F\x55\110		WILLAMETTE,SSE2,SM
@@ -1693,7 +1697,7 @@ UNPCKHPD	xmmreg,xmmrm		\366\2\x0F\x15\110		WILLAMETTE,SSE2,SM
 UNPCKLPD	xmmreg,xmmrm		\366\2\x0F\x14\110		WILLAMETTE,SSE2,SM
 XORPD		xmmreg,xmmrm		\366\2\x0F\x57\110		WILLAMETTE,SSE2,SM
 
-; Prescott New Instructions (SSE3)
+;# Prescott New Instructions (SSE3)
 ADDSUBPD	xmmreg,xmmrm		\366\2\x0F\xD0\110		PRESCOTT,SSE3,SM
 ADDSUBPS	xmmreg,xmmrm		\332\2\x0F\xD0\110		PRESCOTT,SSE3,SM
 HADDPD		xmmreg,xmmrm		\366\2\x0F\x7C\110		PRESCOTT,SSE3,SM
@@ -1705,7 +1709,7 @@ MOVDDUP		xmmreg,xmmrm		\332\2\x0F\x12\110		PRESCOTT,SSE3
 MOVSHDUP	xmmreg,xmmrm		\333\2\x0F\x16\110		PRESCOTT,SSE3
 MOVSLDUP	xmmreg,xmmrm		\333\2\x0F\x12\110		PRESCOTT,SSE3
 
-; VMX Instructions
+;# VMX Instructions
 VMCALL		void			\3\x0F\x01\xC1			VMX
 VMCLEAR		mem			\366\2\x0F\xC7\206		VMX
 VMLAUNCH	void			\3\x0F\x01\xC2			VMX
@@ -1721,7 +1725,7 @@ VMWRITE		reg32,rm32		\2\x0F\x79\110			VMX
 VMXOFF		void			\3\x0F\x01\xC4			VMX
 VMXON		mem			\333\2\x0F\xC7\206		VMX
 
-; Tejas New Instructions (SSSE3)
+;# Tejas New Instructions (SSSE3)
 PABSB		mmxreg,mmxrm		\364\3\x0F\x38\x1C\110		SSSE3,MMX,SQ
 PABSB		xmmreg,xmmrm		\366\3\x0F\x38\x1C\110		SSSE3
 PABSW		mmxreg,mmxrm		\364\3\x0F\x38\x1D\110		SSSE3,MMX,SQ
@@ -1755,7 +1759,7 @@ PSIGNW		xmmreg,xmmrm		\366\3\x0F\x38\x09\110		SSSE3
 PSIGND		mmxreg,mmxrm		\364\3\x0F\x38\x0A\110		SSSE3,MMX,SQ
 PSIGND		xmmreg,xmmrm		\366\3\x0F\x38\x0A\110		SSSE3
 
-; AMD SSE4A
+;# AMD SSE4A
 EXTRQ		xmmreg,imm,imm		\366\2\x0F\x78\200\25\26	SSE4A,AMD
 EXTRQ		xmmreg,xmmreg		\366\2\x0F\x79\110		SSE4A,AMD
 INSERTQ		xmmreg,xmmreg,imm,imm	\332\2\x0F\x78\110\26\27	SSE4A,AMD
@@ -1763,12 +1767,12 @@ INSERTQ		xmmreg,xmmreg		\332\2\x0F\x79\110		SSE4A,AMD
 MOVNTSD		mem,xmmreg		\332\2\x0F\x2B\101		SSE4A,AMD,SQ
 MOVNTSS		mem,xmmreg		\333\2\x0F\x2B\101		SSE4A,AMD,SD
 
-; New instructions in Barcelona
+;# New instructions in Barcelona
 LZCNT		reg16,rm16		\320\333\2\x0F\xBD\110		P6,AMD
 LZCNT		reg32,rm32		\321\333\2\x0F\xBD\110		P6,AMD
 LZCNT		reg64,rm64		\324\333\2\x0F\xBD\110		P6,AMD
 
-; Penryn New Instructions (SSE4.1)
+;# Penryn New Instructions (SSE4.1)
 BLENDPD		xmmreg,xmmrm,imm	\366\3\x0F\x3A\x0D\110\26	SSE41
 BLENDPS		xmmreg,xmmrm,imm	\366\3\x0F\x3A\x0C\110\26	SSE41
 BLENDVPD	xmmreg,xmmrm,xmm0	\366\3\x0F\x38\x15\110		SSE41
@@ -1825,7 +1829,7 @@ ROUNDPS		xmmreg,xmmrm,imm	\366\3\x0F\x3A\x08\110\26	SSE41
 ROUNDSD		xmmreg,xmmrm,imm	\366\3\x0F\x3A\x0B\110\26	SSE41
 ROUNDSS		xmmreg,xmmrm,imm	\366\3\x0F\x3A\x0A\110\26	SSE41
 
-; Nehalem New Instructions (SSE4.2)
+;# Nehalem New Instructions (SSE4.2)
 CRC32		reg32,rm8		\332\3\x0F\x38\1\xF0\110	SSE42
 CRC32		reg32,rm16		\332\3\x0F\x38\1\xF1\110	SSE42
 CRC32		reg32,rm32		\332\3\x0F\x38\1\xF1\110	SSE42
@@ -1840,7 +1844,7 @@ POPCNT		reg16,rm16		\320\333\2\x0F\xB8\110		NEHALEM
 POPCNT		reg32,rm32		\321\333\2\x0F\xB8\110		NEHALEM
 POPCNT		reg64,rm32		\324\333\2\x0F\xB8\110		NEHALEM,X64
 
-; AMD SSE5 instructions
+;# AMD SSE5 instructions
 
 ; Four operands with DREX
 FMADDPS		xmmreg,=0,xmmreg,xmmrm	\160\2\x0F\x24\170\132		SSE5,AMD
@@ -2006,14 +2010,14 @@ ROUNDPD		xmmreg,xmmrm,imm	\366\3\x0F\x3A\x08\110\26	SSE5,AMD
 ROUNDSS		xmmreg,xmmrm,imm	\366\3\x0F\x3A\x08\110\26	SSE5,AMD
 ROUNDSD		xmmreg,xmmrm,imm	\366\3\x0F\x3A\x08\110\26	SSE5,AMD
 
-; Intel SMX
+;# Intel SMX
 GETSEC		void			\2\x0F\x37			KATMAI
 
-; Geode (Cyrix) 3DNow! additions
+;# Geode (Cyrix) 3DNow! additions
 PFRCP		mmxreg,mmxrm		\2\x0F\x0F\110\1\x86		PENT,3DNOW,SM,CYRIX
 PFRSQRT		mmxreg,mmxrm		\2\x0F\x0F\110\1\x87		PENT,3DNOW,SM,CYRIX
 
-; VIA (Centaur) security instructions
+;# VIA (Centaur) security instructions
 XSTORE		void			\3\x0F\xA7\xC0			PENT,CYRIX
 XCRYPTECB	void			\333\3\x0F\xA7\xC8		PENT,CYRIX
 XCRYPTCBC	void			\333\3\x0F\xA7\xD0		PENT,CYRIX
@@ -2023,7 +2027,7 @@ MONTMUL		void			\333\3\x0F\xA6\xC0		PENT,CYRIX
 XSHA1		void			\333\3\x0F\xA6\xC8		PENT,CYRIX
 XSHA256		void			\333\3\x0F\xA6\xD0		PENT,CYRIX
 
-; Systematic names for the hinting nop instructions
+;# Systematic names for the hinting nop instructions
 HINT_NOP0	rm16			\320\2\x0F\x18\200		P6,UNDOC
 HINT_NOP0	rm32			\321\2\x0F\x18\200		P6,UNDOC
 HINT_NOP0	rm64			\324\2\x0F\x18\200		X64,UNDOC
diff --git a/misc/makedist.sh b/misc/makedist.sh
index e24afdc..3027196 100755
--- a/misc/makedist.sh
+++ b/misc/makedist.sh
@@ -60,7 +60,7 @@ zip -k ${NASM_DOS_ZIP} *.exe misc/exasm.zip
 rm -f nasm.doc
 (cd doc; zip -l -k ../${NASM_DOC_ZIP} \
   Readme \
-  nasmdoc.src rdsrc.pl \
+  nasmdoc.src rdsrc.pl inslist.pl \
   nasmdoc.txt \
   nasmdoc.ps \
   *.html