From 94b6f7750d45a393bfacd424d49379d45349eade Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Aki=20=F0=9F=8C=B9?= Date: Wed, 8 Oct 2025 09:23:45 +0200 Subject: [PATCH 1/5] 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 --- spec/index.html | 3 ++- src/Spec.ts | 2 +- src/args.ts | 8 +++++++- src/clauseNums.ts | 7 ++++--- src/cli.ts | 3 +++ src/ecmarkup.ts | 1 + 6 files changed, 18 insertions(+), 6 deletions(-) diff --git a/spec/index.html b/spec/index.html index 36df617a..199a2b97 100644 --- a/spec/index.html +++ b/spec/index.html @@ -55,7 +55,8 @@

Options

`--assets-dir``assetsDir`Directory in which to place assets when using `--assets=external`. Defaults to "assets". `--lint-spec``lintSpec`Enforce some style and correctness checks. `--error-formatter`The eslint formatter 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. - `--max-clause-depth N`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. + `--max-clause-depth N``maxClauseDepth`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. + `--toc-depth N``tocDepth`Maximum level of subclause to be emitted in table of contents. Default 3. `--strict`Exit with an error if there are warnings. Cannot be used with `--watch`. `--multipage`Emit a distinct page for each top-level clause. diff --git a/src/Spec.ts b/src/Spec.ts index 52de1f36..bc6557a5 100644 --- a/src/Spec.ts +++ b/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)); } diff --git a/src/args.ts b/src/args.ts index 9c4453cc..6f588502 100644 --- a/src/args.ts +++ b/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', diff --git a/src/clauseNums.ts b/src/clauseNums.ts index 143a6c06..70a6e806 100644 --- a/src/clauseNums.ts +++ b/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; } diff --git a/src/cli.ts b/src/cli.ts index fd038dbc..31d9e501 100644 --- a/src/cli.ts +++ b/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']; } diff --git a/src/ecmarkup.ts b/src/ecmarkup.ts index d642a6fe..a3a33dbb 100644 --- a/src/ecmarkup.ts +++ b/src/ecmarkup.ts @@ -33,6 +33,7 @@ export interface Options { date?: Date; location?: string; maxClauseDepth?: number; + tocDepth?: number; multipage?: boolean; extraBiblios?: ExportedBiblio[]; contributors?: string; From 2cf79df31f12cc0cbca4a228d4634cdd951bab3e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Aki=20=F0=9F=8C=B9?= Date: Fri, 14 Nov 2025 15:30:00 +0900 Subject: [PATCH 2/5] allow max_levels to be infinity if set --- src/clauseNums.ts | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/clauseNums.ts b/src/clauseNums.ts index 70a6e806..244e8059 100644 --- a/src/clauseNums.ts +++ b/src/clauseNums.ts @@ -11,7 +11,7 @@ export default function iterator(spec: Spec): ClauseNumberIterator { let currentLevel = 0; let hasWarnedForExcessNesting = false; // Ecma house style calls for a maximum of 5 levels of clause division - const MAX_LEVELS = spec.opts.maxClauseDepth ?? 6; + const MAX_LEVELS = spec.opts.maxClauseDepth ? spec.opts.maxClauseDepth || Infinity : 6; return { next(clauseStack: Clause[], node: HTMLElement) { @@ -33,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 ?? 6)) { + if (!hasWarnedForExcessNesting && level + 1 > MAX_LEVELS) { spec.warn({ type: 'node', node, ruleId: 'max-clause-depth', - message: `clause exceeds maximum nesting depth of ${spec.opts.maxClauseDepth ?? 'six'}`, + message: `clause exceeds maximum nesting depth of ${MAX_LEVELS}`, }); hasWarnedForExcessNesting = true; } From 8301cd3966a924c2c2ea8e08ab20ef6488e8ca4f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Aki=20=F0=9F=8C=B9?= Date: Mon, 17 Nov 2025 13:46:56 +0900 Subject: [PATCH 3/5] Clarify toc depth documentation --- spec/index.html | 2 +- src/args.ts | 4 ++-- src/cli.ts | 4 ++-- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/spec/index.html b/spec/index.html index 199a2b97..928284c2 100644 --- a/spec/index.html +++ b/spec/index.html @@ -56,7 +56,7 @@

Options

`--lint-spec``lintSpec`Enforce some style and correctness checks. `--error-formatter`The eslint formatter 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. `--max-clause-depth N``maxClauseDepth`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. - `--toc-depth N``tocDepth`Maximum level of subclause to be emitted in table of contents. Default 3. + `--printed-toc-depth N``printedTocDepth`Maximum level of subclause to be emitted in printed table of contents. Default 3. (ignored if `--printable` option omitted) `--strict`Exit with an error if there are warnings. Cannot be used with `--watch`. `--multipage`Emit a distinct page for each top-level clause. diff --git a/src/args.ts b/src/args.ts index 6f588502..bf049345 100644 --- a/src/args.ts +++ b/src/args.ts @@ -74,10 +74,10 @@ export const options = [ 'The maximum nesting depth for clauses; exceeding this will cause a warning. Defaults to six (per Ecma house style.)', }, { - name: 'toc-depth', + name: 'printed-toc-depth', type: Number, description: - 'The maximum depth for listing clauses in print table of contents. Defaults to three (per Ecma house style.)', + 'Maximum level of subclause to be emitted in printed table of contents. Default 3. (ignored if `--printable` option omitted)', }, { name: 'multipage', diff --git a/src/cli.ts b/src/cli.ts index 31d9e501..ae0745a6 100644 --- a/src/cli.ts +++ b/src/cli.ts @@ -116,8 +116,8 @@ 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['printed-toc-depth']) { + opts.tocDepth = args['printed-toc-depth']; } if (args['no-toc'] != null) { opts.toc = !args['no-toc']; From 7c88604659de82f77f77d00f69780439902bbdeb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Aki=20=F0=9F=8C=B9?= Date: Mon, 17 Nov 2025 14:14:34 +0900 Subject: [PATCH 4/5] Adjust max clause depth based on secretariat feedback --- src/clauseNums.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/clauseNums.ts b/src/clauseNums.ts index 244e8059..cb477ca2 100644 --- a/src/clauseNums.ts +++ b/src/clauseNums.ts @@ -10,8 +10,8 @@ export default function iterator(spec: Spec): ClauseNumberIterator { let inAnnex = false; let currentLevel = 0; let hasWarnedForExcessNesting = false; - // Ecma house style calls for a maximum of 5 levels of clause division - const MAX_LEVELS = spec.opts.maxClauseDepth ? spec.opts.maxClauseDepth || Infinity : 6; + // Ecma house style calls for a maximum of 5 clause levels + const MAX_LEVELS = spec.opts.maxClauseDepth ? spec.opts.maxClauseDepth || Infinity : 5; return { next(clauseStack: Clause[], node: HTMLElement) { From 2e5f71066ec9dae399c4029972d623827c0f2439 Mon Sep 17 00:00:00 2001 From: Aki Date: Mon, 17 Nov 2025 18:46:51 +0900 Subject: [PATCH 5/5] Fix text representations of max clause depth thanks Michael Co-authored-by: Michael Ficarra --- spec/index.html | 2 +- src/args.ts | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/spec/index.html b/spec/index.html index 928284c2..4a5505e4 100644 --- a/spec/index.html +++ b/spec/index.html @@ -55,7 +55,7 @@

Options

`--assets-dir``assetsDir`Directory in which to place assets when using `--assets=external`. Defaults to "assets". `--lint-spec``lintSpec`Enforce some style and correctness checks. `--error-formatter`The eslint formatter 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. - `--max-clause-depth N``maxClauseDepth`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. + `--max-clause-depth N``maxClauseDepth`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 5. `--printed-toc-depth N``printedTocDepth`Maximum level of subclause to be emitted in printed table of contents. Default 3. (ignored if `--printable` option omitted) `--strict`Exit with an error if there are warnings. Cannot be used with `--watch`. `--multipage`Emit a distinct page for each top-level clause. diff --git a/src/args.ts b/src/args.ts index bf049345..88cd7cd1 100644 --- a/src/args.ts +++ b/src/args.ts @@ -71,7 +71,7 @@ export const options = [ name: 'max-clause-depth', type: Number, description: - 'The maximum nesting depth for clauses; exceeding this will cause a warning. Defaults to six (per Ecma house style.)', + 'The maximum nesting depth for clauses; exceeding this will cause a warning. Defaults to five (per Ecma house style.)', }, { name: 'printed-toc-depth',