diff --git a/examples/comprehensive-document/content/document.json b/examples/comprehensive-document/content/document.json index 4e3f727..2875e47 100644 --- a/examples/comprehensive-document/content/document.json +++ b/examples/comprehensive-document/content/document.json @@ -742,6 +742,131 @@ "type": "horizontalRule", "id": "hr-9" }, + { + "type": "heading", + "id": "admonition-heading", + "level": 2, + "children": [ + { "type": "text", "value": "Admonitions" } + ] + }, + { + "type": "paragraph", + "id": "admonition-intro", + "children": [ + { "type": "text", "value": "Admonition blocks highlight important information with visual callouts:" } + ] + }, + { + "type": "admonition", + "id": "admonition-note", + "variant": "note", + "children": [ + { + "type": "paragraph", + "children": [ + { "type": "text", "value": "This is a note admonition. Use it for supplementary information that readers may find helpful." } + ] + } + ] + }, + { + "type": "admonition", + "id": "admonition-warning", + "variant": "warning", + "title": "Caution Required", + "children": [ + { + "type": "paragraph", + "children": [ + { "type": "text", "value": "Warning admonitions highlight potential issues or important considerations." } + ] + } + ] + }, + { + "type": "admonition", + "id": "admonition-tip", + "variant": "tip", + "children": [ + { + "type": "paragraph", + "children": [ + { "type": "text", "value": "Tip admonitions provide helpful suggestions and best practices." } + ] + } + ] + }, + { + "type": "admonition", + "id": "admonition-danger", + "variant": "danger", + "children": [ + { + "type": "paragraph", + "children": [ + { "type": "text", "value": "Danger admonitions warn about critical issues that could cause serious problems." } + ] + } + ] + }, + { + "type": "horizontalRule", + "id": "hr-admonition" + }, + { + "type": "heading", + "id": "subfigure-heading", + "level": 2, + "children": [ + { "type": "text", "value": "Subfigures" } + ] + }, + { + "type": "paragraph", + "id": "subfigure-intro", + "children": [ + { "type": "text", "value": "Multi-panel figures with individual sub-captions:" } + ] + }, + { + "type": "figure", + "id": "fig-comparison", + "subfigures": [ + { + "id": "fig-comparison-a", + "label": "a", + "children": [ + { + "type": "image", + "src": "assets/images/before.png", + "alt": "Sample before processing" + } + ], + "caption": "Before processing" + }, + { + "id": "fig-comparison-b", + "label": "b", + "children": [ + { + "type": "image", + "src": "assets/images/after.png", + "alt": "Sample after processing" + } + ], + "caption": "After processing" + } + ], + "caption": [ + { "type": "text", "value": "Comparison of sample images showing the effects of processing. (a) Original sample. (b) Processed sample with enhanced contrast." } + ], + "numbering": "auto" + }, + { + "type": "horizontalRule", + "id": "hr-subfigure" + }, { "type": "heading", "id": "i18n-heading", diff --git a/schemas/academic.schema.json b/schemas/academic.schema.json index a714aa9..2b8ab1b 100644 --- a/schemas/academic.schema.json +++ b/schemas/academic.schema.json @@ -4,6 +4,35 @@ "title": "Codex Academic Extension", "description": "Schema for academic extension blocks and marks in a Codex document", "$defs": { + "abstractBlock": { + "type": "object", + "description": "Abstract block for papers and reports", + "required": ["type"], + "properties": { + "type": { "const": "academic:abstract" }, + "children": { + "type": "array", + "description": "Abstract content (paragraph blocks)" + }, + "keywords": { + "type": "array", + "description": "List of keywords/key phrases", + "items": { "type": "string" } + }, + "sections": { + "type": "object", + "description": "Structured abstract sections", + "additionalProperties": { + "type": "array", + "description": "Section content (paragraph blocks)" + } + } + }, + "oneOf": [ + { "required": ["children"] }, + { "required": ["sections"] } + ] + }, "theoremVariant": { "type": "string", "description": "Built-in theorem-like environment variants", diff --git a/schemas/content.schema.json b/schemas/content.schema.json index 63e613a..8049c42 100644 --- a/schemas/content.schema.json +++ b/schemas/content.schema.json @@ -124,6 +124,10 @@ { "if": { "properties": { "type": { "const": "break" } } }, "then": { "$ref": "#/$defs/break" } + }, + { + "if": { "properties": { "type": { "const": "admonition" } } }, + "then": { "$ref": "#/$defs/admonition" } } ] }, @@ -647,7 +651,7 @@ }, "figure": { "type": "object", - "required": ["type", "children"], + "required": ["type"], "properties": { "type": { "const": "figure" }, "numbering": { @@ -662,6 +666,59 @@ "description": "Figure content and optional caption", "minItems": 1, "maxItems": 2 + }, + "subfigures": { + "type": "array", + "description": "Array of subfigure objects for multi-panel figures", + "items": { "$ref": "#/$defs/subfigure" }, + "minItems": 1 + }, + "caption": { + "oneOf": [ + { "type": "string", "description": "Simple caption text" }, + { + "type": "array", + "description": "Rich caption with text nodes", + "items": { "$ref": "#/$defs/textNode" } + } + ], + "description": "Overall figure caption (used with subfigures)" + } + }, + "oneOf": [ + { "required": ["children"] }, + { "required": ["subfigures"] } + ] + }, + "subfigure": { + "type": "object", + "description": "A subfigure within a multi-panel figure", + "required": ["children"], + "properties": { + "id": { + "type": "string", + "description": "Unique subfigure identifier for cross-referencing" + }, + "label": { + "type": "string", + "description": "Subfigure label (e.g., 'a', 'b', 'i', 'ii')" + }, + "children": { + "type": "array", + "description": "Content block(s) for this subfigure", + "items": { "$ref": "#/$defs/block" }, + "minItems": 1 + }, + "caption": { + "oneOf": [ + { "type": "string", "description": "Simple caption text" }, + { + "type": "array", + "description": "Rich caption with text nodes", + "items": { "$ref": "#/$defs/textNode" } + } + ], + "description": "Subfigure-specific caption" } } }, @@ -675,6 +732,28 @@ "items": { "$ref": "#/$defs/textNode" } } } + }, + "admonition": { + "type": "object", + "description": "Callout box for notes, warnings, tips, and other highlighted content", + "required": ["type", "variant", "children"], + "properties": { + "type": { "const": "admonition" }, + "variant": { + "type": "string", + "description": "Admonition type", + "enum": ["note", "tip", "info", "warning", "caution", "danger", "important", "example"] + }, + "title": { + "type": "string", + "description": "Custom title (defaults to variant label)" + }, + "children": { + "type": "array", + "description": "Block-level content (typically paragraph blocks)", + "items": { "$ref": "#/$defs/block" } + } + } } } } diff --git a/schemas/presentation.schema.json b/schemas/presentation.schema.json index a6d8e3b..f6ece9b 100644 --- a/schemas/presentation.schema.json +++ b/schemas/presentation.schema.json @@ -50,6 +50,44 @@ "additionalProperties": { "$ref": "#/$defs/style" } + }, + "typography": { + "type": "object", + "description": "Document-level typography settings", + "properties": { + "hyphenation": { + "type": "object", + "description": "Hyphenation settings", + "properties": { + "enabled": { "type": "boolean" }, + "language": { "type": "string" }, + "minWordLength": { "type": "integer", "minimum": 1 }, + "minBefore": { "type": "integer", "minimum": 1 }, + "minAfter": { "type": "integer", "minimum": 1 }, + "maxConsecutive": { "type": "integer", "minimum": 1 } + } + }, + "widows": { + "type": "integer", + "description": "Minimum lines at top of page", + "minimum": 1 + }, + "orphans": { + "type": "integer", + "description": "Minimum lines at bottom of page", + "minimum": 1 + }, + "baselineGrid": { + "type": "object", + "description": "Baseline grid settings", + "properties": { + "enabled": { "type": "boolean" }, + "lineHeight": { "type": "string" }, + "offset": { "type": "string" } + } + }, + "lineNumbering": { "$ref": "#/$defs/lineNumbering" } + } } }, "$defs": { @@ -271,6 +309,57 @@ } ] }, + "lineNumbering": { + "type": "object", + "description": "Line numbering configuration for margins", + "required": ["enabled"], + "properties": { + "enabled": { + "type": "boolean", + "description": "Whether line numbering is active" + }, + "start": { + "type": "integer", + "description": "Starting line number", + "minimum": 1, + "default": 1 + }, + "interval": { + "type": "integer", + "description": "Number every N lines (1 = every line, 5 = every 5th line)", + "minimum": 1, + "default": 1 + }, + "side": { + "type": "string", + "description": "Which margin to display numbers", + "enum": ["left", "right"], + "default": "left" + }, + "restart": { + "type": "string", + "description": "When to restart numbering", + "enum": ["page", "section", "none"], + "default": "page" + }, + "scope": { + "type": "array", + "description": "Block types to number (if omitted, all content is numbered)", + "items": { "type": "string" } + }, + "style": { + "type": "object", + "description": "Styling for line numbers", + "properties": { + "fontSize": { "type": "string" }, + "color": { "type": "string" }, + "fontFamily": { "type": "string" }, + "marginRight": { "type": "string" }, + "marginLeft": { "type": "string" } + } + } + } + }, "style": { "type": "object", "properties": { diff --git a/schemas/semantic.schema.json b/schemas/semantic.schema.json index a0aaa6c..25e142e 100644 --- a/schemas/semantic.schema.json +++ b/schemas/semantic.schema.json @@ -42,7 +42,7 @@ "footnoteMark": { "type": "object", "description": "Footnote mark for referencing footnote content", - "required": ["type", "number"], + "required": ["type"], "properties": { "type": { "const": "footnote" }, "number": { @@ -50,11 +50,20 @@ "description": "Sequential footnote number", "minimum": 1 }, + "symbol": { + "type": "string", + "description": "Symbol-based footnote marker for author notes", + "enum": ["asterisk", "dagger", "ddagger", "section", "parallel", "paragraph"] + }, "id": { "type": "string", "description": "Unique footnote identifier for cross-referencing" } - } + }, + "oneOf": [ + { "required": ["number"] }, + { "required": ["symbol"] } + ] }, "entityMark": { "type": "object", @@ -93,7 +102,7 @@ "footnoteBlock": { "type": "object", "description": "Footnote content block", - "required": ["type", "number"], + "required": ["type"], "properties": { "type": { "const": "semantic:footnote" }, "number": { @@ -101,6 +110,11 @@ "description": "Footnote number (must match corresponding mark)", "minimum": 1 }, + "symbol": { + "type": "string", + "description": "Symbol-based footnote marker (must match corresponding mark)", + "enum": ["asterisk", "dagger", "ddagger", "section", "parallel", "paragraph"] + }, "id": { "type": "string", "description": "Unique identifier (must match mark if present)" @@ -114,9 +128,19 @@ "description": "Simple text content (alternative to children)" } }, - "oneOf": [ - { "required": ["children"] }, - { "required": ["content"] } + "allOf": [ + { + "oneOf": [ + { "required": ["number"] }, + { "required": ["symbol"] } + ] + }, + { + "oneOf": [ + { "required": ["children"] }, + { "required": ["content"] } + ] + } ] }, "bibliographyEntry": { diff --git a/spec/core/03-content-blocks.md b/spec/core/03-content-blocks.md index 5ae74f1..42f22a2 100644 --- a/spec/core/03-content-blocks.md +++ b/spec/core/03-content-blocks.md @@ -799,6 +799,7 @@ Container for figures with optional captions. Figures group visual content (imag | Attribute | Type | Required | Description | |-----------|------|----------|-------------| | `numbering` | string or integer | No | Figure numbering mode | +| `subfigures` | array | No | Array of subfigure objects (alternative to children) | #### 4.20.1 Numbering Values @@ -808,12 +809,66 @@ Container for figures with optional captions. Figures group visual content (imag | `none` | No numbering | | (integer) | Explicit figure number | -**Children:** The figure block MAY contain: -- Exactly one content block: `image`, `svg`, `table`, `math`, or `barcode` -- Zero or one `figcaption` block +**Children:** The figure block MAY contain either: +1. **Standard figure content:** + - Exactly one content block: `image`, `svg`, `table`, `math`, or `barcode` + - Zero or one `figcaption` block +2. **Subfigures array** (for multi-panel figures) The `figcaption` block MAY appear before or after the content block. +#### 4.20.2 Subfigures + +For multi-panel figures with individual sub-images and captions, use the `subfigures` array: + +```json +{ + "type": "figure", + "id": "fig-comparison", + "subfigures": [ + { + "id": "fig-comparison-a", + "label": "a", + "children": [ + { + "type": "image", + "src": "assets/images/before.png", + "alt": "Tissue sample before treatment" + } + ], + "caption": "Before treatment" + }, + { + "id": "fig-comparison-b", + "label": "b", + "children": [ + { + "type": "image", + "src": "assets/images/after.png", + "alt": "Tissue sample after treatment" + } + ], + "caption": "After treatment" + } + ], + "caption": [ + { "type": "text", "value": "Comparison of tissue samples showing treatment effects" } + ], + "numbering": "auto" +} +``` + +| Subfigure Field | Type | Required | Description | +|-----------------|------|----------|-------------| +| `id` | string | No | Unique subfigure identifier for cross-referencing | +| `label` | string | No | Subfigure label (e.g., "a", "b", "i", "ii") | +| `children` | array | Yes | Content block(s) for this subfigure | +| `caption` | string or array | No | Subfigure-specific caption | + +When using `subfigures`, the top-level `caption` field (instead of a `figcaption` child) provides the overall figure caption. This can be a simple string or an array of text nodes for rich formatting. + +**Rendering:** Subfigure labels are typically rendered in parentheses (e.g., "(a)", "(b)") adjacent to or below each sub-image. The overall caption references subfigures by their labels (e.g., "Figure 1: (a) Before treatment. (b) After treatment."). + ### 4.21 Figure Caption Caption for a figure. Only valid as a child of `figure`. @@ -829,6 +884,48 @@ Caption for a figure. Only valid as a child of `figure`. Children: Text nodes or inline content (including links, marks) +### 4.22 Admonition + +Callout boxes for notes, warnings, tips, and other highlighted content commonly used in technical documentation, textbooks, and tutorials. + +```json +{ + "type": "admonition", + "variant": "warning", + "title": "Caution", + "children": [ + { + "type": "paragraph", + "children": [ + { "type": "text", "value": "High voltage. Disconnect power before servicing." } + ] + } + ] +} +``` + +| Attribute | Type | Required | Description | +|-----------|------|----------|-------------| +| `variant` | string | Yes | Admonition type (see below) | +| `title` | string | No | Custom title (defaults to variant label) | + +#### 4.22.1 Admonition Variants + +| Variant | Typical Use | +|---------|-------------| +| `note` | General information or supplementary content | +| `tip` | Helpful suggestions or best practices | +| `info` | Additional context or background information | +| `warning` | Potential issues or important considerations | +| `caution` | Actions that may cause problems | +| `danger` | Critical warnings about harmful actions | +| `important` | Key information that should not be missed | +| `example` | Illustrative examples or demonstrations | + +Children: Block-level content (typically paragraph blocks) + +The `title` field is OPTIONAL. When omitted, implementations SHOULD use a localized label based on the `variant` (e.g., "Note", "Warning", "Tip"). + ## 5. Extension Block Types Extensions MAY define additional block types. Extension blocks: @@ -928,8 +1025,9 @@ All text content MUST be valid Unicode (UTF-8 encoded in JSON). Implementations 6. TableCell children MUST be block-level content (typically paragraph blocks) 7. DefinitionList children MUST be definitionItem blocks 8. DefinitionItem children MUST include at least one definitionTerm and one definitionDescription -9. Figure children MUST include exactly one content block and zero or one figcaption -10. Figcaption is only valid as a child of figure +9. Figure children MUST include exactly one content block and zero or one figcaption (or use subfigures array) +10. Figcaption is only valid as a child of figure or subfigure +11. Admonition children MUST be block-level content (typically paragraph blocks) ### 7.3 Cross-References diff --git a/spec/extensions/academic/README.md b/spec/extensions/academic/README.md index 607f6b5..30facb5 100644 --- a/spec/extensions/academic/README.md +++ b/spec/extensions/academic/README.md @@ -34,9 +34,72 @@ The Academic Extension provides structured support for academic and scientific d } ``` -## 3. Theorem-Like Blocks +## 3. Abstract Block -### 3.1 academic:theorem +### 3.1 academic:abstract + +The abstract block provides semantic structure for paper/report abstracts with optional keywords and structured sections. + +```json +{ + "type": "academic:abstract", + "children": [ + { + "type": "paragraph", + "children": [ + { "type": "text", "value": "This paper presents a novel approach to..." } + ] + } + ], + "keywords": ["machine learning", "document formats", "semantic web"] +} +``` + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `type` | string | Yes | Always `"academic:abstract"` | +| `children` | array | Yes | Abstract content (paragraph blocks) | +| `keywords` | array | No | List of keywords/key phrases | +| `sections` | object | No | Structured abstract sections (see below) | + +#### 3.1.1 Structured Abstracts + +For journals requiring structured abstracts (common in medical and scientific publishing): + +```json +{ + "type": "academic:abstract", + "sections": { + "background": [ + { "type": "paragraph", "children": [{ "type": "text", "value": "..." }] } + ], + "methods": [ + { "type": "paragraph", "children": [{ "type": "text", "value": "..." }] } + ], + "results": [ + { "type": "paragraph", "children": [{ "type": "text", "value": "..." }] } + ], + "conclusions": [ + { "type": "paragraph", "children": [{ "type": "text", "value": "..." }] } + ] + }, + "keywords": ["clinical trial", "randomized controlled"] +} +``` + +Common structured abstract sections: +- `background` / `introduction` / `context` +- `objective` / `purpose` / `aim` +- `methods` / `materials` +- `results` / `findings` +- `conclusions` / `discussion` +- `significance` / `implications` + +When `sections` is provided, `children` SHOULD be omitted. Implementations render structured sections with their labels (e.g., "**Background:** ..."). + +## 4. Theorem-Like Blocks + +### 4.1 academic:theorem Covers built-in variants: theorem, lemma, proposition, corollary, definition, conjecture, remark, example. @@ -68,7 +131,7 @@ Covers built-in variants: theorem, lemma, proposition, corollary, definition, co | `restate` | boolean | No | If `true`, this is a restatement of a previously stated theorem | | `children` | array | Yes | Content blocks | -### 3.2 Built-in Variants +### 4.2 Built-in Variants | Variant | Typical Use | |---------|-------------| @@ -81,7 +144,7 @@ Covers built-in variants: theorem, lemma, proposition, corollary, definition, co | `remark` | Observations and notes | | `example` | Illustrative examples | -### 3.3 Custom Variants +### 4.3 Custom Variants Define custom theorem-like environments in the numbering configuration: @@ -113,9 +176,9 @@ Define custom theorem-like environments in the numbering configuration: | `label` | string | Yes | Display label for the variant | | `sharesWith` | string\|null | No | Share counter with this variant, or `null` for independent counter | -## 4. Proof Blocks +## 5. Proof Blocks -### 4.1 academic:proof +### 5.1 academic:proof ```json { @@ -139,7 +202,7 @@ Define custom theorem-like environments in the numbering configuration: | `qed` | string | No | QED style: `"symbol"` (default), `"text"`, `"none"` | | `children` | array | Yes | Proof content | -### 4.2 Proof Methods +### 5.2 Proof Methods | Method | Description | |--------|-------------| @@ -154,9 +217,9 @@ Define custom theorem-like environments in the numbering configuration: | `counting` | Combinatorial/counting argument | | `probabilistic` | Probabilistic method | -## 5. Exercises +## 6. Exercises -### 5.1 academic:exercise +### 6.1 academic:exercise ```json { @@ -200,7 +263,7 @@ Define custom theorem-like environments in the numbering configuration: | `hints` | array | No | Hint paragraphs (applies to whole exercise) | | `solution` | object | No | Solution with visibility control | -### 5.2 Exercise Parts +### 6.2 Exercise Parts Each part in the `parts` array: @@ -211,7 +274,7 @@ Each part in the `parts` array: | `hints` | array | No | Part-specific hints | | `solution` | object | No | Part-specific solution | -### 5.3 Solution Visibility +### 6.3 Solution Visibility ```json { @@ -237,7 +300,7 @@ Optional date-based reveal: } ``` -### 5.4 Exercise Sets +### 6.4 Exercise Sets Group related exercises with shared context: @@ -268,9 +331,9 @@ Group related exercises with shared context: | `preamble` | array | No | Shared context/instructions for all exercises | | `exercises` | array | Yes | Array of `academic:exercise` blocks | -## 6. Multi-Line Equations +## 7. Multi-Line Equations -### 6.1 academic:equation-group +### 7.1 academic:equation-group ```json { @@ -303,7 +366,7 @@ Group related exercises with shared context: | `id` | string | No | Group identifier | | `lines` | array | Yes | Array of equation lines | -### 6.2 Equation Lines +### 7.2 Equation Lines Each line in the `lines` array: @@ -316,9 +379,85 @@ Each line in the `lines` array: **Note:** Use either `number` or `tag`, not both. If `tag` is present, it takes precedence. -## 7. Algorithm Blocks +## 7.3 Chemical Formulas (mhchem) + +For chemical formulas and reaction equations, use the core `math` block with the mhchem LaTeX package notation. The mhchem package provides intuitive syntax for molecular formulas and chemical reactions. + +### 7.3.1 Basic Chemical Formulas + +```json +{ + "type": "math", + "display": true, + "format": "latex", + "value": "\\ce{H2SO4}" +} +``` + +This renders as: H₂SO₄ + +### 7.3.2 Chemical Reactions + +```json +{ + "type": "math", + "display": true, + "format": "latex", + "value": "\\ce{2H2 + O2 -> 2H2O}" +} +``` + +### 7.3.3 mhchem Syntax Reference + +| Syntax | Description | Example | Result | +|--------|-------------|---------|--------| +| `\\ce{H2O}` | Molecular formula | `\\ce{H2O}` | H₂O | +| `->` | Reaction arrow | `\\ce{A -> B}` | A → B | +| `<->` | Equilibrium | `\\ce{A <-> B}` | A ⇌ B | +| `<=>>` | Equilibrium (shifted right) | `\\ce{A <=>> B}` | A ⇄ B | +| `^{2+}` | Charge | `\\ce{Ca^{2+}}` | Ca²⁺ | +| `v` | Precipitate | `\\ce{AgCl v}` | AgCl↓ | +| `^` | Gas evolution | `\\ce{CO2 ^}` | CO₂↑ | +| `[aq]` | State symbols | `\\ce{NaCl[aq]}` | NaCl(aq) | +| `+` | Reactant separator | `\\ce{A + B}` | A + B | + +### 7.3.4 Complex Examples + +**Acid-base reaction:** +```json +{ + "type": "math", + "display": true, + "format": "latex", + "value": "\\ce{H2SO4 + 2NaOH -> Na2SO4 + 2H2O}" +} +``` + +**Redox reaction with states:** +```json +{ + "type": "math", + "display": true, + "format": "latex", + "value": "\\ce{Fe^{2+}[aq] + Ce^{4+}[aq] -> Fe^{3+}[aq] + Ce^{3+}[aq]}" +} +``` + +**Organic chemistry:** +```json +{ + "type": "math", + "display": true, + "format": "latex", + "value": "\\ce{CH3CH2OH ->[\\text{oxidation}] CH3CHO ->[\\text{oxidation}] CH3COOH}" +} +``` + +**Note:** Implementations rendering math blocks SHOULD support the mhchem package syntax. For maximum compatibility, documents MAY include pre-rendered display text in accompanying elements. + +## 8. Algorithm Blocks -### 7.1 academic:algorithm +### 8.1 academic:algorithm ```json { @@ -362,7 +501,7 @@ Each line in the `lines` array: | `inputs` | array | No | Input parameters | | `outputs` | array | No | Output description | -### 7.2 Algorithm Lines +### 8.2 Algorithm Lines Each line in the `lines` array: @@ -373,7 +512,7 @@ Each line in the `lines` array: | `label` | string | No | Label for line references | | `comment` | string | No | Inline comment | -### 7.3 Algorithm Input/Output +### 8.3 Algorithm Input/Output ```json { @@ -387,9 +526,9 @@ Each line in the `lines` array: | `name` | string | Yes | Parameter name | | `description` | string | No | Parameter description | -## 8. Cross-References +## 9. Cross-References -### 8.1 theorem-ref Mark +### 9.1 theorem-ref Mark Reference a theorem-like block: @@ -418,7 +557,7 @@ Format placeholders: - `{number}` - Theorem number - `{title}` - Theorem title (if present) -### 8.2 equation-ref Mark +### 9.2 equation-ref Mark Reference a numbered equation: @@ -442,7 +581,7 @@ Reference a numbered equation: | `target` | string | Yes | Content Anchor URI to the equation | | `format` | string | No | Display format (default: `"({number})"`) | -### 8.3 algorithm-ref Mark +### 9.3 algorithm-ref Mark Reference an algorithm or algorithm line: @@ -484,7 +623,7 @@ For line references: | `line` | string | No | Line label for line-specific references | | `format` | string | No | Display format | -## 9. Numbering Configuration +## 10. Numbering Configuration Location: `academic/numbering.json` @@ -528,7 +667,7 @@ Location: `academic/numbering.json` } ``` -### 9.1 Numbering Styles +### 10.1 Numbering Styles | Style | Example | Description | |-------|---------|-------------| @@ -537,7 +676,7 @@ Location: `academic/numbering.json` | `chapter.section.number` | 2.3.1, 2.3.2 | Full hierarchical | | `section.number` | 3.1, 3.2 | Section-prefixed | -### 9.2 Counter Sharing +### 10.2 Counter Sharing Theorem-like environments can share counters. When counters are shared, all variants in the group increment the same counter: @@ -549,7 +688,7 @@ Theorem-like environments can share counters. When counters are shared, all vari This produces: Theorem 1, Lemma 2, Proposition 3, Theorem 4, etc. -### 9.3 Reset Triggers +### 10.3 Reset Triggers | Reset On | Description | |----------|-------------| @@ -557,9 +696,9 @@ This produces: Theorem 1, Lemma 2, Proposition 3, Theorem 4, etc. | `section` | Reset at each section | | `none` | Never reset (document-wide numbering) | -## 10. Examples +## 11. Examples -### 10.1 Complete Theorem with Proof +### 11.1 Complete Theorem with Proof ```json [ @@ -624,7 +763,7 @@ This produces: Theorem 1, Lemma 2, Proposition 3, Theorem 4, etc. ] ``` -### 10.2 Multi-Part Exercise with Solution +### 11.2 Multi-Part Exercise with Solution ```json { @@ -707,7 +846,7 @@ This produces: Theorem 1, Lemma 2, Proposition 3, Theorem 4, etc. } ``` -### 10.3 Algorithm with References +### 11.3 Algorithm with References ```json [ @@ -763,7 +902,7 @@ This produces: Theorem 1, Lemma 2, Proposition 3, Theorem 4, etc. ] ``` -### 10.4 Equation Group with Custom Tags +### 11.4 Equation Group with Custom Tags ```json { @@ -799,7 +938,7 @@ This produces: Theorem 1, Lemma 2, Proposition 3, Theorem 4, etc. } ``` -### 10.5 Exercise Set with Shared Context +### 11.5 Exercise Set with Shared Context ```json { @@ -858,7 +997,7 @@ This produces: Theorem 1, Lemma 2, Proposition 3, Theorem 4, etc. } ``` -### 10.6 Restated Theorem Before Proof +### 11.6 Restated Theorem Before Proof ```json [ @@ -898,11 +1037,11 @@ This produces: Theorem 1, Lemma 2, Proposition 3, Theorem 4, etc. ] ``` -## 11. Author Identification +## 12. Author Identification For scholarly documents, author identification is critical for attribution and citation. The Codex specification uses a base `person` object defined in `anchor.schema.json` that includes an `identifier` field for persistent identifiers. -### 11.1 ORCID Recommendation +### 12.1 ORCID Recommendation For academic documents, the `identifier` field SHOULD use ORCID (Open Researcher and Contributor ID) format: @@ -920,7 +1059,7 @@ ORCID provides: - Links to affiliations, grants, and publications - Integration with major publishers and funding agencies -### 11.2 Other Identifier Formats +### 12.2 Other Identifier Formats The `identifier` field also supports: @@ -931,7 +1070,7 @@ The `identifier` field also supports: | DID | `did:web:example.com:jane` | Decentralized identity | | Institutional | `https://university.edu/faculty/jdoe` | University profiles | -### 11.3 Dublin Core Integration +### 12.3 Dublin Core Integration Author identifiers should also be included in Dublin Core metadata (`metadata/dublin-core.json`) for discoverability: diff --git a/spec/extensions/presentation/README.md b/spec/extensions/presentation/README.md index f98e18d..e6ffce2 100644 --- a/spec/extensions/presentation/README.md +++ b/spec/extensions/presentation/README.md @@ -311,6 +311,79 @@ Common features: } ``` +### 6.7 Line Numbering + +Line numbering in margins is common for legal briefs, manuscripts, and code review documents. + +```json +{ + "typography": { + "lineNumbering": { + "enabled": true, + "start": 1, + "interval": 1, + "side": "left", + "restart": "page" + } + } +} +``` + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `enabled` | boolean | Yes | Whether line numbering is active | +| `start` | integer | No | Starting line number (default: 1) | +| `interval` | integer | No | Number every N lines (default: 1, every 5 is common) | +| `side` | string | No | Which margin: `"left"` (default) or `"right"` | +| `restart` | string | No | When to restart numbering (see below) | +| `style` | object | No | Number styling (see below) | + +#### 6.7.1 Restart Options + +| Value | Description | +|-------|-------------| +| `page` | Restart numbering on each page | +| `section` | Restart at section boundaries | +| `none` | Continuous numbering throughout document | + +#### 6.7.2 Line Number Styling + +```json +{ + "typography": { + "lineNumbering": { + "enabled": true, + "interval": 5, + "side": "left", + "restart": "page", + "style": { + "fontSize": "8pt", + "color": "#666666", + "fontFamily": "monospace", + "marginRight": "0.5em" + } + } + } +} +``` + +#### 6.7.3 Selective Line Numbering + +For documents where only certain blocks should be numbered (e.g., code blocks only): + +```json +{ + "typography": { + "lineNumbering": { + "enabled": true, + "scope": ["codeBlock", "blockquote"] + } + } +} +``` + +When `scope` is specified, only the listed block types receive line numbers. If omitted, all content is numbered. + ## 7. Figures and Floats > **Note:** The `figure` and `figcaption` block types are now part of the core specification (see Content Blocks, Sections 4.20-4.21). This extension provides additional float positioning and advanced numbering capabilities. diff --git a/spec/extensions/semantic/README.md b/spec/extensions/semantic/README.md index b046117..b97b67c 100644 --- a/spec/extensions/semantic/README.md +++ b/spec/extensions/semantic/README.md @@ -216,9 +216,47 @@ Use a footnote mark on text to create a footnote reference: | Field | Type | Required | Description | |-------|------|----------|-------------| | `type` | string | Yes | Always `"footnote"` | -| `number` | integer | Yes | Sequential footnote number | +| `number` | integer | No | Sequential footnote number (required if `symbol` not used) | +| `symbol` | string | No | Symbol-based footnote marker (required if `number` not used) | | `id` | string | No | Unique footnote identifier for cross-referencing | +Either `number` or `symbol` MUST be provided, but not both. + +#### 4.5.1a Symbol Footnotes + +For author footnotes on title pages and special contexts, symbol-based footnotes provide a non-numeric sequence: + +```json +{ + "type": "text", + "value": "Corresponding author", + "marks": [ + { + "type": "footnote", + "symbol": "dagger", + "id": "fn-corresponding" + } + ] +} +``` + +| Symbol Value | Display | Typical Use | +|--------------|---------|-------------| +| `asterisk` | * | First author note | +| `dagger` | † | Corresponding author, second note | +| `ddagger` | ‡ | Third note | +| `section` | § | Fourth note | +| `parallel` | ‖ | Fifth note | +| `paragraph` | ¶ | Sixth note | + +Symbol footnotes are commonly used for: +- Author affiliations and correspondence information +- Acknowledgments and funding sources +- Equal contribution statements +- Disclaimers and conflicts of interest + +For documents requiring more than six symbol footnotes, the sequence typically doubles (**, ††, ‡‡, etc.). Implementations MAY support this extended sequence. + #### 4.5.2 Footnote Block Footnote content is stored as a block, typically at the end of a section or document: