coradoc 1.1.7 → 2.0.1

data/docs/_pages/getting-started.adoc

@@ -0,0 +1,158 @@
+---
+title: Getting Started
+parent: Core Pages
+nav_order: 1
+---
+
+= Getting Started with Coradoc
+
+== Purpose
+
+This page helps you install Coradoc and write your first AsciiDoc parsing code. You'll learn how to parse AsciiDoc documents, access document structure, and serialize back to AsciiDoc.
+
+== Prerequisites
+
+* Ruby 3.1 or higher
+* Basic knowledge of AsciiDoc syntax
+
+== Installation
+
+Add Coradoc to your application's Gemfile:
+
+[source,ruby]
+----
+gem 'coradoc'
+----
+
+Then execute:
+
+[source,bash]
+----
+bundle install
+----
+
+Or install it yourself as a gem:
+
+[source,bash]
+----
+gem install coradoc
+----
+
+== Basic Parsing
+
+=== Parse a Simple Document
+
+Parse an AsciiDoc string into a document model:
+
+[source,ruby]
+----
+# Parse AsciiDoc input
+doc = Coradoc.parse("== Hello World\n\nThis is a paragraph.")
+
+# Access document structure
+doc.header.title                    # => "Hello World"
+doc.sections.first.title.level_int  # => 2
+doc.sections.first.paragraphs.first # => First paragraph object
+
+# Serialize back to AsciiDoc
+output = doc.to_adoc
+----
+
+=== Parse from File
+
+Parse an AsciiDoc file:
+
+[source,ruby]
+----
+# Parse from file
+doc = Coradoc.parse_file("document.adoc")
+
+# Work with the model
+doc.sections.each do |section|
+  puts "Section: #{section.title}"
+end
+----
+
+=== Accessing Document Structure
+
+The document model includes:
+
+* *header* - Title, author, revision info
+* *document_attributes* - Key-value metadata
+* *sections* - Hierarchical content structure
+* *blocks* - Paragraphs, lists, code blocks, tables, etc.
+* *inline elements* - Links, formatting, etc.
+
+[source,ruby]
+----
+# Access document structure
+doc.header.title                  # Document title
+doc.document_attributes.data     # Metadata attributes
+doc.sections                      # Top-level sections
+doc.sections.first.sections       # Nested sections
+doc.sections.first.paragraphs    # Content blocks
+----
+
+== Serialization
+
+Convert document models to AsciiDoc output:
+
+[source,ruby]
+----
+# Any Model object can be serialized to AsciiDoc
+paragraph = Coradoc::Model::Paragraph.new
+paragraph.content = [Coradoc::Model::TextElement.new("Hello")]
+paragraph.to_adoc  # => "Hello\n"
+----
+
+=== Using the Converter
+
+The `Coradoc.convert` method provides explicit format conversion:
+
+[source,ruby]
+----
+doc = Coradoc.parse_file("input.adoc")
+
+# Convert to AsciiDoc (same as to_adoc)
+asciidoc_output = Coradoc.convert(doc, to: :adoc)
+----
+
+== DOCX Conversion
+
+Convert Word documents to AsciiDoc or Markdown:
+
+[source,ruby]
+----
+require 'coradoc/docx'
+
+# Convert DOCX to AsciiDoc
+adoc = Coradoc.convert("input.docx", from: :docx, to: :asciidoc)
+
+# Convert DOCX to Markdown
+md = Coradoc.convert("input.docx", from: :docx, to: :markdown)
+
+# Parse DOCX to CoreModel for inspection
+core = Coradoc.parse("input.docx", format: :docx)
+core.title         # => "Document Title"
+core.children      # => Array of sections, paragraphs, tables
+----
+
+Install DOCX support:
+
+[source,ruby]
+----
+# Gemfile
+gem 'coradoc-docx'
+gem 'uniword'
+----
+
+== Next Steps
+
+* link:/coradoc/tutorials/basic-parsing[Basic Parsing Tutorial] - Deep dive into parsing
+* link:architecture[Architecture] - Understand Coradoc's architecture
+* link:model[Document Model] - Learn about the document model
+
+== References
+
+* link:/coradoc/references/api-reference[API Reference] - Complete API documentation
+* https://asciidoctor.org[AsciiDoctor Documentation] - AsciiDoc syntax reference

data/docs/_pages/model.adoc

@@ -0,0 +1,333 @@
+---
+title: Document Model
+parent: Core Pages
+nav_order: 5
+---
+
+= Document Model
+
+== Purpose
+
+This page explains the Coradoc Document Model - the Ruby object representation of AsciiDoc documents. You'll learn about the model classes, their relationships, and how to work with them programmatically.
+
+== Overview
+
+The Document Model represents AsciiDoc structure as Ruby objects. Every element in an AsciiDoc document has a corresponding model class. All model classes inherit from `Coradoc::Model::Base`.
+
+== Core Model Classes
+
+=== Document
+
+The root container for all document content.
+
+[source,ruby]
+----
+Coradoc::Model::Document
+  ├── header: Header
+  ├── document_attributes: DocumentAttributes
+  └── sections: Array<Section>
+----
+
+[source,ruby]
+----
+doc = Coradoc.parse("= Title\n\nContent")
+doc.class  # => Coradoc::Model::Document
+----
+
+=== Header
+
+Document metadata including title, author, and revision information.
+
+[source,ruby]
+----
+Coradoc::Model::Header
+  ├── title: String
+  ├── author: Array<Author>
+  └── revision: Revision
+----
+
+[source,ruby]
+----
+doc.header.title          # Document title
+doc.header.author&.first  # First author, if present
+doc.header.revision       # Revision information
+----
+
+=== Section
+
+Hierarchical sections organizing document content.
+
+[source,ruby]
+----
+Coradoc::Model::Section
+  ├── title: Title
+  ├── sections: Array<Section>  # Nested sections
+  ├── paragraphs: Array<Paragraph>
+  └── blocks: Array<Block>
+----
+
+[source,ruby]
+----
+section = Coradoc::Model::Section.new
+section.title = Coradoc::Model::Title.new
+section.title.level_int = 2
+section.title.content = ["Chapter 1"]
+
+# Add paragraphs
+para = Coradoc::Model::Paragraph.new
+para.content = [Coradoc::Model::TextElement.new("Content here")]
+section.blocks = [para]
+----
+
+=== Title
+
+Section or block title with level information.
+
+[source,ruby]
+----
+Coradoc::Model::Title
+  ├── level_int: Integer
+  └── content: Array<String>
+----
+
+=== Paragraph
+
+Text paragraph containing inline elements.
+
+[source,ruby]
+----
+Coradoc::Model::Paragraph
+  ├── content: Array<TextElement | Inline>
+  └── attributes: AttributeList
+----
+
+[source,ruby]
+----
+para = Coradoc::Model::Paragraph.new
+
+# Add mixed content
+para.content = [
+  Coradoc::Model::TextElement.new("Regular text"),
+  Coradoc::Model::Inline::Bold.new,
+  Coradoc::Model::Inline::Link.new(path: "https://example.com"),
+]
+
+# Add attributes
+para.attributes = Coradoc::Model::AttributeList.new
+para.attributes.add_named("id", "para1")
+----
+
+== Block Classes
+
+Blocks are delimited content sections like code listings and quotes.
+
+### Block::Core
+
+Base class for all delimited blocks.
+
+[source,ruby]
+----
+Coradoc::Model::Block::Core
+  ├── delimiter_char: String
+  ├── delimiter_len: Integer
+  ├── lines: Array<String>
+  └── attributes: AttributeList
+----
+
+### Block Types
+
+* `Block::Listing` - Code listing block
+* `Block::Literal` - Literal text block
+* `Block::Example` - Example block
+* `Block::Quote` - Quoted text block
+* `Block::Pass` - Pass-through content
+
+[source,ruby]
+----
+# Create a listing block
+listing = Coradoc::Model::Block::Listing.new
+listing.lines = ["def hello", "  puts 'world'", "end"]
+listing.attributes = Coradoc::Model::AttributeList.new
+listing.attributes.add_positional("ruby")
+----
+
+== List Classes
+
+Lists organize items hierarchically.
+
+### List::Core
+
+Base class for all list types.
+
+[source,ruby]
+----
+Coradoc::Model::List::Core
+  └── items: Array<ListItem>
+----
+
+### List Types
+
+* `List::Unordered` - Bulleted list (`*`)
+* `List::Ordered` - Numbered list (`.`)
+* `List::Definition` - Definition list (`::`)
+
+[source,ruby]
+----
+# Unordered list
+list = Coradoc::Model::List::Unordered.new
+item = Coradoc::Model::ListItem.new
+item.content = [Coradoc::Model::TextElement.new("First item")]
+list.items << item
+
+# Ordered list
+ordered = Coradoc::Model::List::Ordered.new
+item = Coradoc::Model::ListItem.new
+item.content = [Coradoc::Model::TextElement.new("Step one")]
+ordered.items << item
+
+# Definition list
+definition = Coradoc::Model::List::Definition.new
+def_item = Coradoc::Model::List::DefinitionItem.new
+def_item.terms = [Coradoc::Model::Term.new(term: "Ruby", type: "language")]
+def_item.contents = [Coradoc::Model::TextElement.new("A programming language")]
+definition.items << def_item
+----
+
+== Table Classes
+
+Tables represent tabular data.
+
+[source,ruby]
+----
+Coradoc::Model::Table
+  ├── rows: Array<TableRow>
+  └── attributes: AttributeList
+
+Coradoc::Model::TableRow
+  └── columns: Array<TableCell>
+
+Coradoc::Model::TableCell
+  └── content: Array<TextElement | Inline>
+----
+
+[source,ruby]
+----
+table = Coradoc::Model::Table.new
+
+row = Coradoc::Model::TableRow.new
+cell = Coradoc::Model::TableCell.new
+cell.content = [Coradoc::Model::TextElement.new("Cell content")]
+row.columns << cell
+table.rows << row
+----
+
+== Inline Classes
+
+Inline elements represent text formatting within blocks.
+
+### Inline::Base
+
+Base class for all inline elements.
+
+### Inline Types
+
+* `Inline::Bold` - Bold text (`*text*`)
+* `Inline::Italic` - Italic text (`_text_`)
+* `Inline::Monospace` - Monospace text (`` `text` ``)
+* `Inline::Link` - Hyperlink (`https://example.com[label]`)
+* `Inline::Anchor` - Cross-reference target (`[[id]]`)
+
+[source,ruby]
+----
+# Bold text
+bold = Coradoc::Model::Inline::Bold.new
+bold.content = "Important text"
+
+# Links
+link = Coradoc::Model::Inline::Link.new
+link.path = "https://example.com"
+link.name = "Example"
+
+# Anchors (cross-reference targets)
+anchor = Coradoc::Model::Inline::Anchor.new
+anchor.id = "section1"
+----
+
+== Helper Classes
+
+### TextElement
+
+Plain text content.
+
+[source,ruby]
+----
+Coradoc::Model::TextElement.new("Hello, world!")
+----
+
+### AttributeList
+
+Block or inline attributes.
+
+[source,ruby]
+----
+attrs = Coradoc::Model::AttributeList.new
+attrs.add_named("id", "my-id")
+attrs.add_positional("ruby")
+----
+
+### DocumentAttributes
+
+Document-level metadata attributes.
+
+[source,ruby]
+----
+doc.document_attributes.data.each do |key, value|
+  puts "#{key}: #{value}"
+end
+----
+
+## Working with the Model
+
+### Navigation
+
+[source,ruby]
+----
+doc = Coradoc.parse("= Main\n\n== Section 1\n\nContent.\n\n=== Subsection\n\nMore.")
+
+# Navigate to sections
+doc.sections.each do |section|
+  puts section.title.content
+  section.sections.each do |subsection|
+    puts "  #{subsection.title.content}"
+  end
+end
+----
+
+### Manipulation
+
+[source,ruby]
+----
+doc = Coradoc.parse("= Title\n\n== Section\n\nOld content.")
+
+# Find section
+section = doc.sections.first
+
+# Modify paragraph
+section.paragraphs.first.content = [
+  Coradoc::Model::TextElement.new("New content.")
+]
+
+# Serialize changes
+output = doc.to_adoc
+----
+
+## Related Documentation
+
+* link:architecture[Architecture] - Model hierarchy diagrams
+* link:/coradoc/references/model-classes[Model Classes Reference] - Complete catalog
+* link:/coradoc/tutorials/document-modeling[Document Modeling Tutorial] - Hands-on examples
+* link:/coradoc/references/api-reference[API Reference] - Model class API
+
+## Bibliography
+
+* https://github.com/lutaml/lutaml-model[lutaml-model] - Model definition framework

data/docs/_pages/parsing.adoc

@@ -0,0 +1,198 @@
+---
+title: Parsing
+parent: Core Pages
+nav_order: 3
+---
+
+= Parsing Layer
+
+== Purpose
+
+This page explains how Coradoc parses AsciiDoc documents into a structured document model. You'll learn about the parser layer, what it produces, and how to work with parsed documents.
+
+== Overview
+
+Coradoc parses AsciiDoc documents into a rich object model using the https://github.com/kschiess/parslet[Parslet] parsing expression grammar library. The parser converts text into an Abstract Syntax Tree (AST), which is then transformed into Model objects.
+
+== Parsing Methods
+
+=== Coradoc.parse(input, **options)
+
+Parse an AsciiDoc string into a document model.
+
+[source,ruby]
+----
+doc = Coradoc.parse("== Title\n\nContent")
+----
+
+*Parameters:*
+
+* `input` (String) - AsciiDoc string to parse
+* `**options` (Hash) - Optional parsing parameters
+
+*Returns:* `Coradoc::Model::Document`
+
+=== Coradoc.parse_file(filename, **options)
+
+Parse an AsciiDoc file into a document model.
+
+[source,ruby]
+----
+doc = Coradoc.parse_file("document.adoc")
+----
+
+*Parameters:*
+
+* `filename` (String) - Path to AsciiDoc file
+* `**options` (Hash) - Optional parsing parameters
+
+*Returns:* `Coradoc::Model::Document`
+
+== The Parsing Process
+
+=== Stage 1: Lexical Analysis
+
+The AsciiDoc text is tokenized into meaningful elements:
+
+* Headings (`== Title`)
+* Delimiters (`----`, `____`)
+* List markers (`*`, `.`)
+* Inline formatting (`*bold*`, `_italic_`)
+* Attributes (`:name: value`)
+
+=== Stage 2: AST Generation
+
+Parslet constructs an Abstract Syntax Tree representing the syntactic structure of the document. The AST captures:
+
+* Hierarchical heading structure
+* Block boundaries and types
+* List nesting
+* Inline element boundaries
+
+=== Stage 3: Transformation
+
+The AST is transformed into Model objects by the Transformer layer. This is where syntax becomes semantics:
+
+* AST heading node → `Coradoc::Model::Title`
+* AST paragraph node → `Coradoc::Model::Paragraph`
+* AST list node → `Coradoc::Model::List::Unordered`
+
+== Working with Parsed Documents
+
+=== Accessing the Header
+
+[source,ruby]
+----
+doc = Coradoc.parse("= Document Title\n\nContent")
+
+doc.header.title              # => "Document Title"
+doc.header.author             # => Array of Author objects
+doc.header.revision           # => Revision object
+----
+
+=== Accessing Sections
+
+[source,ruby]
+----
+doc = Coradoc.parse("== Section 1\n\nContent\n\n== Section 2\n\nContent")
+
+# All top-level sections
+doc.sections.each do |section|
+  puts section.title.content
+end
+
+# First section
+section = doc.sections.first
+puts section.title.level_int  # => 2
+puts section.paragraphs       # => Array of paragraphs
+
+# Nested sections
+section.sections.each do |subsection|
+  puts subsection.title.content
+end
+----
+
+=== Accessing Document Attributes
+
+[source,ruby]
+----
+doc = Coradoc.parse(":author: John Doe\n\n== Title\n\nContent")
+
+# All attributes
+doc.document_attributes.data.each do |key, value|
+  puts "#{key}: #{value}"
+end
+
+# Specific attribute
+doc.document_attributes.data["author"]  # => "John Doe"
+----
+
+=== Accessing Blocks
+
+[source,ruby]
+----
+doc = Coradoc.parse("== Section\n\nParagraph 1.\n\nParagraph 2.")
+
+section = doc.sections.first
+
+# Paragraphs
+section.paragraphs.each do |para|
+  puts para.content
+end
+
+# All blocks (paragraphs, lists, tables, etc.)
+section.blocks.each do |block|
+  puts block.class.name
+end
+----
+
+=== Accessing Inline Elements
+
+[source,ruby]
+----
+doc = Coradoc.parse("= Title\n\nThis has *bold* and _italic_ text.")
+
+paragraph = doc.sections.first.paragraphs.first
+
+paragraph.content.each do |element|
+  case element
+  when Coradoc::Model::TextElement
+    puts "Text: #{element.text}"
+  when Coradoc::Model::Inline::Bold
+    puts "Bold: #{element.content}"
+  when Coradoc::Model::Inline::Italic
+    puts "Italic: #{element.content}"
+  end
+end
+----
+
+== What Gets Parsed
+
+Coradoc parses the following AsciiDoc elements:
+
+* **Structure:** Document title, sections, headers
+* **Blocks:** Paragraphs, delimited blocks, lists, tables
+* **Inline:** Bold, italic, monospace, links, anchors
+* **Attributes:** Document attributes, block attributes
+* **Metadata:** Author, revision info
+
+== Parser Limitations
+
+The parser focuses on semantic AsciiDoc elements. Some advanced features may not be fully supported:
+
+* Complex include directives
+* All macro types
+* Conditional processing
+
+See link:/coradoc/guides/troubleshooting[Troubleshooting] for known limitations.
+
+== Related Documentation
+
+* link:transformation[Transformation Layer] - How AST becomes Model
+* link:model[Document Model] - Model object details
+* link:/coradoc/tutorials/basic-parsing[Basic Parsing Tutorial] - Hands-on examples
+
+== Bibliography
+
+* https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/[AsciiDoc Syntax Quick Reference]
+* https://github.com/kschiess/parslet[Parslet Documentation]