add ToC & max clause depth to provide flexibility

Ecma house style is a ToC 3 deep and max clauses 6, but there may be scenarios where a TC wants to generate a draft with fewer or more in the context of their specific standard

Author: gesa

spec/index.html

@@ -55,7 +55,8 @@ <h1>Options</h1>
       <tr><td>`--assets-dir`</td><td>`assetsDir`</td><td>Directory in which to place assets when using `--assets=external`. Defaults to "assets".</td></tr>
       <tr><td>`--lint-spec`</td><td>`lintSpec`</td><td>Enforce some style and correctness checks.</td></tr>
       <tr><td>`--error-formatter`</td><td></td><td>The <a href="https://eslint.org/docs/user-guide/formatters/">eslint formatter</a> to be used for printing warnings and errors when using `--verbose`. Either the name of a built-in eslint formatter or the package name of an installed eslint compatible formatter.</td></tr>
-      <tr><td>`--max-clause-depth N`</td><td></td><td>Warn when clauses exceed a nesting depth of N, and cause those clauses to be numbered by incrementing their parent clause's number rather than by nesting a new number within their parent clause.</td></tr>
+      <tr><td>`--max-clause-depth N`</td><td>`maxClauseDepth`</td><td>Warn when clauses exceed a nesting depth of N, and cause those clauses to be numbered by incrementing their parent clause's number rather than by nesting a new number within their parent clause. Default 6.</td></tr>
+      <tr><td>`--toc-depth N`</td><td>`tocDepth`</td><td>Maximum level of subclause to be emitted in table of contents. Default 3.</td></tr>
       <tr><td>`--strict`</td><td></td><td>Exit with an error if there are warnings. Cannot be used with `--watch`.</td></tr>
       <tr><td>`--multipage`</td><td></td><td>Emit a distinct page for each top-level clause.</td></tr>
     </table>

src/Spec.ts

@@ -647,7 +647,7 @@ export default class Spec {
 
       if (this.opts.printable) {
         // Ecma guidance directs three levels of clause in ToC
-        new Toc(this).build(3);
+        new Toc(this).build(this.opts.tocDepth ?? 3);
       } else {
         ({ js: tocJs, eles: commonEles } = makeMenu(this));
       }

src/args.ts

@@ -71,7 +71,13 @@ export const options = [
     name: 'max-clause-depth',
     type: Number,
     description:
-      'The maximum nesting depth for clauses; exceeding this will cause a warning. Defaults to no limit.',
+      'The maximum nesting depth for clauses; exceeding this will cause a warning. Defaults to six (per Ecma house style.)',
+  },
+  {
+    name: 'toc-depth',
+    type: Number,
+    description:
+      'The maximum depth for listing clauses in print table of contents. Defaults to three (per Ecma house style.)',
   },
   {
     name: 'multipage',

src/clauseNums.ts

@@ -10,7 +10,8 @@ export default function iterator(spec: Spec): ClauseNumberIterator {
   let inAnnex = false;
   let currentLevel = 0;
   let hasWarnedForExcessNesting = false;
-  const MAX_LEVELS = spec.opts.maxClauseDepth ?? Infinity;
+  // Ecma house style calls for a maximum of 5 levels of clause division
+  const MAX_LEVELS = spec.opts.maxClauseDepth ?? 6;
 
   return {
     next(clauseStack: Clause[], node: HTMLElement) {
@@ -32,12 +33,12 @@ export default function iterator(spec: Spec): ClauseNumberIterator {
           message: 'clause is being numbered without numbering its parent clause',
         });
       }
-      if (!hasWarnedForExcessNesting && level + 1 > (spec.opts.maxClauseDepth ?? Infinity)) {
+      if (!hasWarnedForExcessNesting && level + 1 > (spec.opts.maxClauseDepth ?? 6)) {
         spec.warn({
           type: 'node',
           node,
           ruleId: 'max-clause-depth',
-          message: `clause exceeds maximum nesting depth of ${spec.opts.maxClauseDepth}`,
+          message: `clause exceeds maximum nesting depth of ${spec.opts.maxClauseDepth ?? 'six'}`,
         });
         hasWarnedForExcessNesting = true;
       }

src/cli.ts

@@ -116,6 +116,9 @@ const build = debounce(async function build() {
     if (args['max-clause-depth']) {
       opts.maxClauseDepth = args['max-clause-depth'];
     }
+    if (args['toc-depth']) {
+      opts.tocDepth = args['toc-depth'];
+    }
     if (args['no-toc'] != null) {
       opts.toc = !args['no-toc'];
     }

src/ecmarkup.ts

@@ -33,6 +33,7 @@ export interface Options {
   date?: Date;
   location?: string;
   maxClauseDepth?: number;
+  tocDepth?: number;
   multipage?: boolean;
   extraBiblios?: ExportedBiblio[];
   contributors?: string;