docbook 0.1.0

data/docs/features/numbering.adoc

@@ -0,0 +1,183 @@
+---
+layout: default
+title: Section Numbering
+parent: Features
+nav_order: 3
+---
+
+# Section Numbering
+
+The `NumberingBuilder` class computes formatted section numbers for all numbered document divisions. Numbering follows DocBook conventions: Roman numerals for Parts, Arabic numerals for Chapters, hierarchical dot notation for Sections, and Alpha letters for Appendices.
+
+## Numbering Schemes
+
+[cols="1,2,3"]
+|===
+| Division | Scheme | Examples
+
+| Part | Roman numerals (I, II, III, ...)
+| Part I, Part II, Part III
+
+| Chapter | Arabic numerals scoped per Part
+| 1, 2, 3 (resets at each Part)
+
+| Section | Hierarchical dot notation
+| 1.1, 1.2, 1.2.3, 2.1
+
+| Appendix | Alpha letters (A, B, C, ...)
+| Appendix A, Appendix B, Appendix C
+
+| Preface | Unnumbered
+| (no number)
+
+| Glossary | Unnumbered
+| (no number)
+
+| Bibliography | Unnumbered
+| (no number)
+
+| Index | Unnumbered
+| (no number)
+|===
+
+## NumberingBuilder Class
+
+The `NumberingBuilder` maintains independent counters for each numbering scope:
+
+[source,ruby]
+----
+class NumberingBuilder
+  def initialize
+    @numbering = {}                      # id => formatted_number_string
+    @part_counter = 0                    # Global part counter
+    @chapter_counters = {}               # part_index => chapter_counter
+    @appendix_counter = 0                # Global appendix counter
+    @section_counters = {}               # scope_id => sequential_counter
+  end
+end
+----
+
+### Part Numbering
+
+Parts use uppercase Roman numerals. The counter is global across the entire document:
+
+[source,ruby]
+----
+def next_part
+  @part_counter += 1
+  roman_numeral(@part_counter)  # "I", "II", "III", "IV", "V", ...
+end
+----
+
+Roman numerals are computed using the standard subtractive notation algorithm with mappings for 1000 (M), 900 (CM), 500 (D), 400 (CD), 100 (C), 90 (XC), 50 (L), 40 (XL), 10 (X), 9 (IX), 5 (V), 4 (IV), 1 (I).
+
+### Chapter Numbering
+
+Chapters use Arabic numerals scoped per Part. Each Part maintains its own chapter counter, which resets when a new Part begins. Chapters outside of Parts use a global counter:
+
+[source,ruby]
+----
+def next_chapter(part_index)
+  @chapter_counters[part_index] ||= 0
+  @chapter_counters[part_index] += 1
+  @chapter_counters[part_index].to_s
+end
+----
+
+This means:
+
+- Part I contains Chapters 1, 2, 3
+- Part II contains Chapters 1, 2 (reset)
+- Chapters without a Part share counter scope 0
+
+### Section Numbering
+
+Sections use flat sequential numbering per parent scope, combined into hierarchical dot notation:
+
+[source,ruby]
+----
+def next_section(scope_id)
+  @section_counters[scope_id] ||= 0
+  @section_counters[scope_id] += 1
+  @section_counters[scope_id].to_s
+end
+----
+
+The hierarchical number is built by prefixing with the parent's number:
+
+[source,ruby]
+----
+# For a section in Chapter 1:
+#   scope_id = "ch01" -> 1
+#   Child scope = "ch01_s1" -> 1.1
+#   Grandchild scope = "ch01_s1_ss1" -> 1.1.1
+
+prefix = parent_number || chapter_num
+full_num = prefix ? "#{prefix}.#{section_num}" : section_num
+----
+
+### Appendix Numbering
+
+Appendices use uppercase Alpha letters:
+
+[source,ruby]
+----
+def next_appendix
+  @appendix_counter += 1
+  alpha_numeral(@appendix_counter)  # "A", "B", "C", ..., "Z", "AA", "AB"
+end
+----
+
+The Alpha algorithm supports double-letter notation for more than 26 appendices (A through Z, then AA, AB, etc.).
+
+Appendix sections are prefixed with the appendix letter: `A.1`, `A.2`, `B.1`, etc.
+
+## Numbering Map
+
+The computed numbering is stored as a flat hash mapping section `xml:id` to formatted number string:
+
+[source,ruby]
+----
+numbering = {
+  "part1"        => "I",
+  "ch-intro"     => "1",
+  "ch-intro-s1"  => "1.1",
+  "ch-intro-s2"  => "1.2",
+  "ch-intro-s2a" => "1.2.1",
+  "part2"        => "II",
+  "ch-advanced"  => "1",     # Reset because new Part
+  "ch-advanced-s1" => "1.1",
+  "app-changes"  => "Appendix A",
+  "app-changes-s1" => "A.1",
+  "app-license"  => "Appendix B",
+}
+----
+
+This flat map is serialized as an array of `NumberingEntry` objects in the output JSON, and the Vue frontend converts it back to a `Record<string, string>` for O(1) lookup during rendering.
+
+## Unnumbered Sections
+
+The following section types are explicitly not numbered:
+
+- **Preface** -- Front matter that precedes numbered content
+- **Glossary** -- Alphabetical term list
+- **Bibliography** -- Reference list
+- **Index** -- Generated back-of-book index
+
+When the numbering traversal encounters these types, it skips numbering assignment but still recurses into their children (which may contain numbered elements in some document structures).
+
+## Integration with TOC
+
+The numbering map is computed alongside the TOC tree and stored in the `Toc` model:
+
+[source,ruby]
+----
+output = DocbookOutput.new(
+  title: extract_title,
+  toc: Toc.new(
+    sections: sections_data,
+    numbering: numbering_hash.map { |id, value| NumberingEntry.new(id: id, value: value) }
+  ),
+  # ...
+)
+----

data/docs/features/toc-generation.adoc

@@ -0,0 +1,150 @@
+---
+layout: default
+title: TOC Generation
+parent: Features
+nav_order: 4
+---
+
+# TOC Generation
+
+The table of contents is generated as a recursive tree of `SectionData` objects. Each node carries an ID, title, section type, and children. The Vue SPA renders this tree as a collapsible sidebar with type badges and section numbering.
+
+## SectionData Tree
+
+Each node in the TOC is a `SectionData` with four fields:
+
+[cols="1,1,3"]
+|===
+| Field | Type | Description
+
+| `id` | `String` | Section's `xml:id` attribute or a generated slug from the title
+| `title` | `String` | Section title (from `info/title` or direct `title` child)
+| `type` | `String` | Section type used for badge rendering and numbering
+| `children` | `SectionData[]` | Nested child sections
+|===
+
+### Type Values
+
+The `type` field determines how the section is displayed in the sidebar:
+
+[cols="1,3,2"]
+|===
+| Type | Badge | Color
+
+| `part` | Pt | Purple
+| `chapter` | Ch | Blue
+| `appendix` | App | Green
+| `section` | (none) | Gray
+| `glossary` | Gl | Yellow
+| `bibliography` | Bib | Red
+| `index` | Idx | Indigo
+| `preface` | Pref | Orange
+| `reference` | Ref | Cyan
+|===
+
+## Tree Structure by Document Type
+
+The TOC tree varies depending on the root document element.
+
+### Book
+
+For `<book>` documents, the top-level sections include:
+
+- **Preface** -- Direct children of the book
+- **Parts** -- Contain chapters, references, appendices, glossary, bibliography, index
+- **Chapters** -- Direct children of the book (when no Parts are used), contain nested sections
+- **Appendices** -- May contain nested sections
+- **Glossary** -- Leaf node
+- **Bibliography** -- Leaf node
+- **Index** -- Leaf node
+
+[source,ruby]
+----
+# Book TOC collection
+def collect_sections
+  sections = []
+  case @document
+  when Docbook::Elements::Book
+    each_attr(@document, :preface) { |pf| sections << SectionData.new(type: 'preface', ...) }
+    each_attr(@document, :part)    { |p|  sections << SectionData.new(type: 'part', children: collect_part_children(p)) }
+    each_attr(@document, :chapter) { |ch| sections << SectionData.new(type: 'chapter', ...) }
+    each_attr(@document, :appendix){ |ap| sections << SectionData.new(type: 'appendix', children: collect_appendix_children(ap)) }
+    each_attr(@document, :glossary){ |g|  sections << SectionData.new(type: 'glossary', ...) }
+    each_attr(@document, :bibliography){ |b| sections << SectionData.new(type: 'bibliography', ...) }
+    each_attr(@document, :index)   { |i|  sections << SectionData.new(type: 'index', ...) }
+  end
+  sections
+end
+----
+
+### Article
+
+For `<article>` documents, the TOC contains top-level sections and their recursive children:
+
+- **Sections** -- Nested recursively via `collect_section_children`
+
+### Reference
+
+For `<reference>` documents, the TOC contains reference entries:
+
+- **RefEntry** -- Each `refentry` becomes a top-level TOC item with type `reference`
+
+## Recursive Collection
+
+Section children are collected recursively through dedicated methods:
+
+- `collect_part_children` -- Collects chapters, references, appendices, prefaces, glossary, bibliography, and index within a Part
+- `collect_section_children` -- Recursively collects nested `section` elements
+- `collect_appendix_children` -- Collects sections within an Appendix
+
+The recursion depth is unbounded, supporting arbitrarily nested section hierarchies.
+
+## Vue Sidebar Rendering
+
+The Vue frontend renders the TOC tree using the recursive `TocTreeItem` component:
+
+[source,typescript]
+----
+// TocTreeItem.vue renders each TOC node:
+// - Collapsible toggle for nodes with children
+// - Type badge (Pt, Ch, App, etc.) based on item.type
+// - Section number from the numbering map
+// - Title text
+// - Active state highlighting
+// - Recursive rendering of children with indentation
+----
+----
+
+The sidebar features:
+
+- **Collapsible tree** -- Items with children show an expand/collapse toggle
+- **Type badges** -- Color-coded labels indicating section type
+- **Section numbers** -- Right-aligned monospace numbers from the numbering map
+- **Active tracking** -- The currently visible section is highlighted via `IntersectionObserver`
+- **Deep linking** -- Clicking a TOC item scrolls to the section via anchor link
+
+## Title Resolution
+
+Section titles are resolved using a priority chain:
+
+. `element.info.title.content` -- Title inside an `info` element
+. `element.title.content` -- Direct title child
+. Fallback string (e.g., "Preface", "Chapter", "Glossary")
+
+[source,ruby]
+----
+def best_title(el)
+  title_of(el)
+end
+
+def title_of(el)
+  case el
+  when Elements::Book, Elements::Article
+    el.info&.title&.content
+  when Elements::Chapter, Elements::Appendix, Elements::Section,
+       Elements::Part, Elements::Preface
+    el.info&.title&.content || el.title&.content
+  # ...
+  end
+end
+----

data/docs/features/xinclude/fragid-schemes.adoc

@@ -0,0 +1,287 @@
+---
+layout: default
+title: fragid Schemes
+parent: XInclude Resolution
+grand_parent: Features
+nav_order: 3
+---
+
+# fragid Schemes
+
+The `fragid` attribute on text-mode XIncludes enables selective extraction of file content. Three filtering schemes are supported: `search=` for pattern-based extraction, `line=` for line-number ranges, and `char=` for character offsets. This is a key feature for including specific portions of source files in documentation.
+
+## Overview
+
+The `fragid` attribute is applied to `xi:include` elements with `parse="text"`:
+
+[source,xml]
+----
+<programlisting language="ruby">
+  <xi:include href="lib/example.rb" parse="text" fragid="line=10,25"/>
+</programlisting>
+----
+
+The resolver dispatches to the appropriate filter based on the scheme prefix:
+
+[source,ruby]
+----
+def self.apply_fragid(content, fragid)
+  if fragid.start_with?("search=")
+    apply_search_fragid(content, fragid[7..])
+  elsif fragid.start_with?("line=")
+    apply_line_fragid(content, fragid[5..])
+  elsif fragid.start_with?("char=")
+    apply_char_fragid(content, fragid[5..])
+  end
+end
+----
+
+## search= Scheme (DocBook xslTNG Extension)
+
+The `search=` scheme is an extension inspired by the https://github.com/docbook/xslTNG[DocBook xslTNG stylesheets]. It extracts content by matching patterns, with support for literal and regex matching, directional modifiers, and stop patterns.
+
+### Syntax
+
+----
+search=DELIMITER pattern DELIMITER [;after|;before] [,DELIMITER stop_pattern DELIMITER]
+----
+
+Where `DELIMITER` is `#` (literal match) or `/` (regex match).
+
+### Literal Match with `#`
+
+The `#` delimiter performs literal string matching:
+
+[source,xml]
+----
+<!-- Include lines containing "xmlns:css" up to lines containing "a border" -->
+<programlisting language="xml">
+  <xi:include href="stylesheets/main.xsl" parse="text"
+             fragid="search=#xmlns:css#,#a border#"/>
+</programlisting>
+----
+
+This extracts all lines from the first line containing `xmlns:css` up to (but not including) the first line containing `a border`.
+
+### Regex Match with `/`
+
+The `/` delimiter performs regular expression matching:
+
+[source,xml]
+----
+<!-- Include lines matching a regex pattern -->
+<programlisting language="ruby">
+  <xi:include href="lib/docbook.rb" parse="text"
+             fragid="search=/def process_image/"/>
+</programlisting>
+----
+
+This extracts the first line matching the regex `def process_image`.
+
+### Modifiers
+
+Two modifiers control which lines around the match are included:
+
+**`;after`** -- Extract lines *after* the match (excludes the matching line itself):
+
+[source,xml]
+----
+<!-- Include lines after the "class Html" match, up to the "end" match -->
+<programlisting language="ruby">
+  <xi:include href="lib/docbook/output/html.rb" parse="text"
+             fragid="search=#class Html#;after,#private#"/>
+</programlisting>
+----
+
+**`;before`** -- Extract lines *before* the match (excludes the matching line itself):
+
+[source,xml]
+----
+<!-- Include all lines before the "Copyright" notice -->
+<programlisting language="ruby">
+  <xi:include href="lib/docbook.rb" parse="text"
+             fragid="search=#Copyright#;before"/>
+</programlisting>
+----
+
+### Stop Patterns
+
+A stop pattern terminates extraction at the first matching line (exclusive -- the stop line is not included):
+
+[source,xml]
+----
+<!-- Extract from "class Html" to "def initialize" -->
+<programlisting language="ruby">
+  <xi:include href="lib/docbook/output/html.rb" parse="text"
+             fragid="search=#class Html#,#def initialize#"/>
+</programlisting>
+----
+
+[source,xml]
+----
+<!-- Extract from regex match to regex stop -->
+<programlisting language="ruby">
+  <xi:include href="lib/docbook/output/html.rb" parse="text"
+             fragid="search=/def to_html/,/end$/"/>
+</programlisting>
+----
+
+### Complete search= Examples
+
+[source,xml]
+----
+<!-- Example 1: Single line literal match -->
+<programlisting>
+  <xi:include href="config.yaml" parse="text"
+             fragid="search=#database:#"/>
+</programlisting>
+
+<!-- Example 2: Range from literal start to literal stop -->
+<programlisting language="ruby">
+  <xi:include href="lib/parser.rb" parse="text"
+             fragid="search=#class Parser#,#class SyntaxError#"/>
+</programlisting>
+
+<!-- Example 3: Lines after a match, with stop -->
+<programlisting language="xml">
+  <xi:include href="schema.xsd" parse="text"
+             fragid="search=#complexType name=&quot;Book&quot;#;after,#</complexType>#"/>
+</programlisting>
+
+<!-- Example 4: Regex range -->
+<programlisting language="ruby">
+  <xi:include href="spec/example_spec.rb" parse="text"
+             fragid="search=/describe.*Html/,/end$/"/>
+</programlisting>
+
+<!-- Example 5: Lines before a marker -->
+<programlisting language="yaml">
+  <xi:include href="docker-compose.yml" parse="text"
+             fragid="search=#volumes:#;before"/>
+</programlisting>
+----
+
+## line= Scheme (RFC 5147)
+
+The `line=` scheme implements the https://www.rfc-editor.org/rfc/rfc5147[RFC 5147] line-based text range fragment identifier. It extracts a range of lines by 1-based line number.
+
+### Syntax
+
+----
+line=START,END[;length=N]
+----
+
+- `START` -- First line to include (1-based)
+- `END` -- Last line to include (inclusive)
+- `length=N` -- Optional maximum character length for the extracted content
+
+### Basic Line Range
+
+[source,xml]
+----
+<!-- Include lines 10 through 25 of the file -->
+<programlisting language="ruby">
+  <xi:include href="lib/docbook.rb" parse="text" fragid="line=10,25"/>
+</programlisting>
+----
+
+This extracts lines 10, 11, 12, ..., 25 from the file (1-based indexing).
+
+### Line Range with Length Truncation
+
+[source,xml]
+----
+<!-- Include lines 3 through 50, truncated to 889 characters -->
+<programlisting language="ruby">
+  <xi:include href="lib/docbook/output/html.rb" parse="text"
+             fragid="line=3,50;length=889"/>
+</programlisting>
+----
+
+The `length=` modifier truncates the output to at most N characters. This is useful for:
+
+- Showing a representative sample of a long file
+- Limiting output size in generated documentation
+- Ensuring consistent example lengths
+
+### Examples
+
+[source,xml]
+----
+<!-- First 5 lines of a file -->
+<programlisting>
+  <xi:include href="README.md" parse="text" fragid="line=1,5"/>
+</programlisting>
+
+<!-- Lines 100-120 (a specific function) -->
+<programlisting language="python">
+  <xi:include href="app.py" parse="text" fragid="line=100,120"/>
+</programlisting>
+
+<!-- A specific range, max 500 characters -->
+<programlisting language="javascript">
+  <xi:include href="index.js" parse="text" fragid="line=1,100;length=500"/>
+</programlisting>
+----
+
+## char= Scheme (RFC 5147)
+
+The `char=` scheme implements the https://www.rfc-editor.org/rfc/rfc5147[RFC 5147] character-based text range fragment identifier. It extracts content by character offset.
+
+### Syntax
+
+----
+char=START,END
+----
+
+- `START` -- Starting character offset (0-based)
+- `END` -- Ending character offset (exclusive)
+
+### Usage
+
+[source,xml]
+----
+<!-- Extract characters 0 through 500 (first 500 characters) -->
+<programlisting>
+  <xi:include href="data/output.txt" parse="text" fragid="char=0,500"/>
+</programlisting>
+----
+
+[source,xml]
+----
+<!-- Extract a specific section by character offset -->
+<programlisting>
+  <xi:include href="large-file.txt" parse="text" fragid="char=1024,2048"/>
+</programlisting>
+----
+
+### Examples
+
+[source,xml]
+----
+<!-- First 1000 characters -->
+<programlisting>
+  <xi:include href="CHANGELOG.md" parse="text" fragid="char=0,1000"/>
+</programlisting>
+
+<!-- Characters from offset 500 to 1000 -->
+<programlisting language="json">
+  <xi:include href="package.json" parse="text" fragid="char=500,1000"/>
+</programlisting>
+----
+
+## Scheme Comparison
+
+[cols="1,1,3,3"]
+|===
+| Scheme | Standard | Best For | Example
+
+| `search=` | DocBook xslTNG | Pattern-based extraction, code with markers
+| `search=#def process#;after,#end$#`
+
+| `line=` | RFC 5147 | Known line ranges, fixed-position content
+| `line=10,25;length=889`
+
+| `char=` | RFC 5147 | Known byte offsets, binary-adjacent content
+| `char=0,500`
+|===