Commentary: fewer chapters

bin/verilator

@@ -965,27 +965,6 @@ Really, you're better off using a Makefile to do all this for you.  Then,
 when your source changes it will automatically run all of these steps.  See
 the test_sp directory in the distribution for an example.
 
-=head1 CADENCE NC-SYSTEMC EXECUTION
-
-Similar to compiling Verilated designs with gcc, Verilated designs may be
-compiled inside other simulators that support SystemC models.  One such
-simulator is Cadence's NC-SystemC, part of their Incisive Verification
-Suite.  (Highly recommended.)
-
-Using the example files above, the following command will build the model
-underneath NC:
-
-   cd obj_dir
-   ncsc_run \
-	sc_main.cpp \
-	Vour__ALLcls.cpp \
-	Vour__ALLsup.cpp \
-	verilated.cpp
-
-For larger designs you'll want to automate this using makefiles, which pull
-the names of the .cpp files to compile in from the make variables generated
-in obj_dir/Vour_classes.mk.
-
 =head1 BENCHMARKING & OPTIMIZATION
 
 For best performance, run Verilator with the "-O3 -x-assign=fast
@@ -1236,6 +1215,8 @@ Verilator supports SystemVerilog Direct Programming Interface import and
 export statements.  Only the SystemVerilog form ("DPI-C") is supported, not
 the original Synopsys-only DPI.
 
+=head2 DPI Example
+
 In the SYSTEMC example above, if you wanted to import C++ functions into
 Verilog, put in our.v:
 
@@ -1257,7 +1238,9 @@ command line, or the link), you'd then:
     #include "Vour__Dpi.h"
     int add (int a, int b) { return a+b; }
 
-Verilator also extends the DPI format to allow using the same scheme to
+=head2 DPI System Task/Functions
+
+Verilator extends the DPI format to allow using the same scheme to
 efficiently add system functions.  Simply use a dollar-sign prefixed system
 function name for the import, but note it must be escaped.
 
@@ -1292,7 +1275,9 @@ DPI compatible but is easier to read and better supports multiple designs.
     Vour::publicSetBool(value);
     // or top->publicSetBool(value);
 
-Verilator also allows writing $display like functions using this syntax:
+=head2 DPI Display Functions
+
+Verilator allows writing $display like functions using this syntax:
 
    import "DPI-C" function void
          \$my_display (input string formatted /*verilator sformat*/ );
@@ -1301,6 +1286,8 @@ The /*verilator sformat*/ indicates that this function accepts a $display
 like format specifier followed by any number of arguments to satisfy the
 format.
 
+=head2 Public Functions 
+
 Instead of DPI exporting, there's also Verilator public functions, which
 are slightly faster, but less compatible.
 
@@ -1332,6 +1319,27 @@ The target system may also require edits to the Makefiles, the simple
 Makefiles produced by Verilator presume the target system is the same type
 as the build system.
 
+=head2 Cadence NC-SystemC Models
+
+Similar to compiling Verilated designs with gcc, Verilated designs may be
+compiled inside other simulators that support C++ or SystemC models.  One
+such simulator is Cadence's NC-SystemC, part of their Incisive Verification
+Suite.  (Highly recommended.)
+
+Using the example files above, the following command will build the model
+underneath NC:
+
+   cd obj_dir
+   ncsc_run \
+	sc_main.cpp \
+	Vour__ALLcls.cpp \
+	Vour__ALLsup.cpp \
+	verilated.cpp
+
+For larger designs you'll want to automate this using makefiles, which pull
+the names of the .cpp files to compile in from the make variables generated
+in obj_dir/Vour_classes.mk.
+
 =head1 CONFIGURATION FILES
 
 In addition to the command line, warnings and other features may be
@@ -1376,19 +1384,21 @@ if ommitted).
 
 =back
 
-=head1 VERILOG 2001 (IEEE 1364-2001) SUPPORT
+=head1 LANGUAGE STANDARD SUPPORT
+
+=head2 Verilog 2001 (IEEE 1364-2001) Support
 
 Verilator supports most Verilog 2001 language features.  This includes
 signed numbers, "always @*", generate statements, multidimensional arrays,
 localparam, and C-style declarations inside port lists.
 
-=head1 VERILOG 2005 (IEEE 1364-2005) SUPPORT
+=head2 Verilog 2005 (IEEE 1364-2005) Support
 
 Verilator supports most Verilog 2005 language features.  This includes the
 `begin_keywords and `end_keywords compiler directives, $clog2, and the
 uwire keyword.
 
-=head1 SYSTEMVERILOG 2005 (IEEE 1800-2005) SUPPORT
+=head2 SystemVerilog 2005 (IEEE 1800-2005) Support
 
 Verilator currently has some support for SystemVerilog synthesis
 constructs. As SystemVerilog features enter common usage they are added;
@@ -1405,13 +1415,13 @@ It also supports .name and .* interconnection.
 Verilator partially supports concurrent assert and cover statements; see
 the enclosed coverage tests for the syntax which is allowed.
 
-=head1 SYSTEMVERILOG 2009 (IEEE 1800-2009) SUPPORT
+=head2 SystemVerilog 2009 (IEEE 1800-2009) Support
 
 Verilator implements a full SystemVerilog 2009 preprocessor, including
 function call-like preprocessor defines, default define arguments,
 `__FILE__, `__LINE__ and `undefineall.
 
-=head1 SUGAR/PSL SUPPORT
+=head2 Sugar/PSL Support
 
 Most future work is being directed towards improving SystemVerilog
 assertions instead of PSL.  If you are using these PSL features, please
@@ -1439,7 +1449,7 @@ Verilator only supports (posedge CLK) or (negedge CLK), where CLK is the
 name of a one bit signal.  You may not use arbitrary expressions as
 assertion clocks.
 
-=head1 SYNTHESIS DIRECTIVE ASSERTION SUPPORT
+=head2 Synthesis Directive Assertion Support
 
 With the --assert switch, Verilator reads any "//synopsys full_case" or "//
 synopsys parallel_case" directives.  The same applies to any "//cadence" or
@@ -1931,7 +1941,7 @@ Verilator does not support SEREs yet.  All assertion and coverage
 statements must be simple expressions that complete in one cycle.
 (Arguably SEREs are much of the point, but one must start somewhere.)
 
-=head1 LANGUAGE KEYWORD LIMITATIONS
+=head2 Language Keyword Limitations
 
 This section describes specific limitations for each language keyword.