doc: prettify the HTML documentation

- Improve the look of the TOC
- Add some highlight to code blocks

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

doc/changes.src

@@ -2717,7 +2717,7 @@ an error.
 specification warning when sizes agree).
 
 
-\H{cl-0.9x} NASM 0.9 Series
+\H{cl-0.9x} NASM 0.90-0.97
 
 Revisions before 0.98.
 

doc/nasmdoc.css

@@ -9,9 +9,29 @@ div.title {
     margin: 0.67em 0;
 }
 h1 {
-    font-size: 2em;
+    font-size: 250%;
     margin: 0;
 }
+h2 {
+    font-size: 200%;
+    font-weight: bold;
+}
+h3 {
+    font-size: 160%;
+    font-weight: bold;
+}
+h4 {
+    font-size: 128%;
+    font-weight: bold;
+}
+h5 {
+    font-size: 100%;
+    font-weight: bold;
+}
+h6 {
+    font-size: 100%;
+    text-decoration: underline;
+}
 span.subtitle {
     font-size: 1.25em;
     font-style: italic;
@@ -23,32 +43,49 @@ code, pre {
 pre, blockquote {
     margin-left: 4em;
     margin-right: 4em;
+    padding: 0.25em 0.4em;
+}
+pre {
+    background: #f0f0f0;
 }
 code {
     display: inline;
     white-space: nowrap;
+    /* Extra padding due to monospaced font */
+    padding-left: 0.2em;
+    padding-right: 0.2em;
 }
 a {
     text-decoration: none;
 }
-div.toc {
-    padding-left: 0;
-    font-size: 195%;
-}
-div.toc li {
-    list-style-type: none;
-    padding-left: 0;
-}
 div.toc ol {
     padding-left: 2em;
     font-size: 80%;
+    list-style-type: none;
 }
-li.toc1 {
+div.toc ol.toc1 {
+    /* Compensate for the size reduction for each level */
+    font-size: 150%;
+}
+/* -- TOC numbering using data-name attribute -- */
+ol li[data-name]::marker {
+    content: attr(data-name) '.';
+}
+ol.toc1 > li {
+    padding-left: 1em;
     padding-top: 0.7em;
+    font-weight: bold;
 }
-li.toc2 {
+ol.toc2 > li {
     padding-top: 0.3em;
 }
+ol.toc2 li {
+    padding-left: 0.4em;
+    font-weight: normal;
+}
+div.toc span.node {
+    display: none;
+}
 .index li {
     list-style-type: none;
     display: flex;
@@ -68,6 +105,9 @@ li.toc2 {
     vertical-align: top;
     flex: 1 1 0;
 }
+div.contents {
+    column-width: 35em;
+}
 /* This is overridden for @media screen */
 ul.navbar {
     display: none;
@@ -98,21 +138,6 @@ ul.navbar {
 	column-rule: 1px dotted black;
     }
 }
-@media only screen and (min-width: 90em) {
-    /* For a very wide screen, go to a columnar layout */
-    div.contents {
-	-webkit-column-count: 2;
-	-moz-column-count: 2;
-	column-count: 2;
-    }
-}
-@media only screen and (min-width: 135em) {
-    div.contents {
-	-webkit-column-count: 3;
-	-moz-column-count: 3;
-	column-count: 3;
-    }
-}
 @media screen {
     /* Setting an explicit margin to keep the navbar from moving */
     body {

doc/rdsrc.pl

@@ -885,42 +885,66 @@ sub write_html {
   undef $html_nav_last;
   $html_nav_next = $tstruct_next{'Top'};
   &html_preamble(0);
-  print "<p>This manual documents NASM, the Netwide Assembler: an assembler\n";
-  print "targeting the Intel x86 series of processors, with portable source.\n</p>";
   print "<div class=\"toc\">\n";
+  print "<h2>Table of Contents</h2>\n";
   $level = 0;
-  for ($node = $tstruct_next{'Top'}; $node; $node = $tstruct_next{$node}) {
-      my $lastlevel = $level;
-      while ($tstruct_level{$node} < $level) {
-	  print "</li>\n</ol>\n";
-	  $level--;
-      }
-      while ($tstruct_level{$node} > $level) {
-	  print "<ol class=\"toc", ++$level, "\">\n";
-      }
-      if ($lastlevel >= $level) {
+  $ollevel = 0;
+
+  sub toc_close_tags($) {
+      my($plevel) = @_;
+      while ($plevel < $level) {
 	  print "</li>\n";
+	  if ($level-- <= $ollevel) {
+	      print "</ol>\n";
+	      $ollevel--;
+	  }
       }
-      $level = $tstruct_level{$node};
+  }
+
+  undef $ctype;			# Chapter or Appendix
+  for ($node = $tstruct_next{'Top'}; $node; $node = $tstruct_next{$node}) {
+      my $plevel = $tstruct_level{$node};
+      my @pnn = split(/[ \.]/, $node);
+      (my $nname = $node) =~ s/^.*?\s+//;
+      my $nnum = $pnn[-1] + 0 || ord($pnn[-1]) - ord('A') + 1;
+      my $nctype = lc($pnn[0]);
+
+      toc_close_tags($plevel);
+      if ($plevel < 2 && $nctype ne $ctype) {
+	  toc_close_tags(0);
+	  my $plural = $nctype;
+	  $plural =~ s/^(.)/\U$1/;
+	  $plural =~ s/ix$/ice/; # ix -> ice + s -> ices
+	  $plural .= 's';
+	  print "<h3 class=\"tocheading $nctype\">$plural</h3>\n";
+	  $ctype = $nctype;
+      }
+
+      while ($plevel > $level) {
+	  $level++;
+	  my $cclass = ($level == 1) ? " $ctype" : '';
+	  print "<ol class=\"toc${level}${cclass}\"", ">\n";
+	  $ollevel = $level;
+      }
+
       if ($level == 1) {
 	  $link = $fname = html_filename($node);
       } else {
 	  # Use the preceding filename plus a marker point.
 	  $link = $fname . "#$xrefnodes{$node}";
       }
-      $pname = $tstruct_pname{$node};
-      $title = plist_to_html(@$pname);
-      print "<li class=\"toc${level}\">\n";
-      print "<span class=\"node\">$node: </span><a href=\"$link\">$title</a>\n";
-  }
-  while ($level--) {
-      print "</li>\n</ol>\n";
+
+      my $pname = $tstruct_pname{$node};
+      my $title = plist_to_html(@$pname);
+      printf "<li value=\"%d\" data-name=\"%s\">\n", $nnum, $nname;
+      # The $node span is obsolete and is only included for now to avoid
+      # breaking any existing local.css files.
+      printf "<a href=\"%s\"><span class=\"node\">%s: </span>%s</a>\n",
+	  $link, $node, $title;
   }
+  toc_close_tags(0);
   print "</div>\n";
-  print "</body>\n";
-  print "</html>\n";
-  select STDOUT;
-  close TEXT;
+  &html_postamble; select STDOUT; close TEXT;
 
   # Open a null file, to ensure output (eg random &html_jumppoints calls)
   # goes _somewhere_.