### Install DocLang Toolkit

Source: https://github.com/doclang-project/doclang/blob/main/README.md

Installs the DocLang package with Schematron support.

```bash
pip install "doclang[schematron-saxon]"
```

--------------------------------

### Install dependencies

Source: https://github.com/doclang-project/doclang/blob/main/CONTRIBUTING.md

Syncs the project dependencies using uv.

```bash
uv sync
```

--------------------------------

### Install DocLang Toolkit

Source: https://github.com/doclang-project/doclang/blob/main/doclang/README.md

Install the toolkit with full validation support or a minimal version for specific environments.

```bash
pip install "doclang[schematron-saxon]"
```

```bash
pip install doclang
```

--------------------------------

### Simple key-values example

Source: https://github.com/doclang-project/doclang/blob/main/spec.md

A basic example of key-value pairs extracted from a form.

```xml
<field_region>
      <field_item>
          <key>Firma:</key>
          <value>Holcim ... GmbH</value>
      </field_item>
      <field_item>
          <key>Datum:</key>
        <value>23.08.2019</value>
      </field_item>
      <!--...-->
      <field_item>
          <key>Petrograph. Typ:</key>
          <value>Quartiarer Sand + Kies</value>
      </field_item>
  </field_region>
```

--------------------------------

### Install pre-commit hooks

Source: https://github.com/doclang-project/doclang/blob/main/CONTRIBUTING.md

Installs pre-commit hooks locally to ensure code quality before commits.

```bash
uv run pre-commit install
```

--------------------------------

### Install doclang

Source: https://github.com/doclang-project/doclang/blob/main/_autodocs/configuration.md

Commands for installing the package with different feature sets or for development purposes.

```bash
pip install doclang
```

```bash
pip install "doclang[schematron-saxon]"
```

```bash
uv sync
```

--------------------------------

### Complete packaging example

Source: https://github.com/doclang-project/doclang/blob/main/_autodocs/pack.md

Demonstrates a full configuration including output, pages, assets, and validation.

```python
from doclang import pack

archive_path = pack(
    "markup.dclg",
    output="report.dclx",
    pages=["page1.png", "page2.png"],
    assets={"diagrams/": "assets/"},
    validate=True,
)
print(f"Archive created: {archive_path}")
```

--------------------------------

### Validating Element Start Tag Variants

Source: https://github.com/doclang-project/doclang/blob/main/spec.md

Examples of various valid start tag configurations for an element with optional properties.

```xml
<elem size="300" color="#aabbcc">
```

```xml
<elem size="42">
```

```xml
<elem color="#112233">
```

```xml
<elem>
```

--------------------------------

### Catch and handle exception

Source: https://github.com/doclang-project/doclang/blob/main/_autodocs/errors.md

Example of catching the exception to provide user feedback.

```python
from doclang import validate, SchematronBackendNotFound

try:
    validate("document.dclg")
except SchematronBackendNotFound as exc:
    print(f"Error: {exc}")
    print("Install doclang[schematron-saxon] to enable Schematron validation")
```

--------------------------------

### Validation Output Formats

Source: https://github.com/doclang-project/doclang/blob/main/_autodocs/cli.md

Examples of the CLI output in text and JSON formats.

```text
Validating: document.dclg
------------------------------------------------------------
XSD validation passed
Schematron validation passed
------------------------------------------------------------
VALIDATION SUCCESSFUL
```

```json
{
  "xsd": {
    "valid": true,
    "errors": []
  },
  "schematron": {
    "valid": true,
    "errors": []
  }
}
```

--------------------------------

### Handle SchematronBackendNotFound

Source: https://github.com/doclang-project/doclang/blob/main/_autodocs/types.md

Example of catching and printing the error message when a Schematron backend is missing.

```python
from doclang import validate, SchematronBackendNotFound

try:
    validate("document.dclg")
except SchematronBackendNotFound as exc:
    print(exc)
    # Output: "Schematron validation requires a backend. Install doclang[schematron-saxon] ..."
```

--------------------------------

### Fillable Form Example

Source: https://github.com/doclang-project/doclang/blob/main/examples/form/form-examples.md

Shows a form structure designed for user input, with fields for description, quantity, pricing, and delivery details. Some fields are intentionally left blank for user input.

```xml
<field_region>
    <field_item>
        <key>Description</key>
        <value>A.A. Cat</value>
    </field_item>
    <field_item>
        <key>Quant.</key>
        <value></value>
    </field_item>
    <field_item>
        <key>Un</key>
        <value></value>
    </field_item>
    <field_item>
        <key>Measure</key>
        <value></value>
    </field_item>
    <field_item>
        <key>Price (in currency)</key>
        <value></value>
    </field_item>
    <field_item>
        <key>Un</key>
        <value></value>
    </field_item>
    <field_item>
        <key>Total</key>
        <value></value>
    </field_item>
    <text></text>
    <field_region>
        <field_item>
            <key>Delivery Cost</key>
            <value></value>
        </field_item>
        <field_item>
            <key>Maintenance</key>
            <value></value>
        </field_item>
        <!--...-->
    </field_region>
    <field_region>
        <field_item>
            <key>Date and time of delivery:</key>
            <value></value>
        </field_item>
        <!--...-->
        <field_item>
            <key>Guarantee</key>
            <value></value>
        </field_item>
        <text>
            Delivery Suppl...Finance Department
        </text>
    </field_region>
    <!--...-->
</field_region>
```

--------------------------------

### Instantiate SchematronViolation

Source: https://github.com/doclang-project/doclang/blob/main/_autodocs/types.md

Example of creating a violation object and accessing its fields.

```python
from doclang import SchematronViolation

violation = SchematronViolation(
    message="Element must have at least one child",
    location="/doclang/page[1]/content",
    rule_id="content-not-empty",
)
print(f"At {violation.location}: {violation.message}")
```

--------------------------------

### XML Split Structure Example

Source: https://github.com/doclang-project/doclang/blob/main/spec.md

Demonstrates the use of text, list, and thread elements to represent split content across pages.

```xml
<!--...-->
<text>
    <location value="10"/><location value="20"/>
    <location value="30"/><location value="40"/>
    <![CDATA[Our multi-faceted DE&I program includes the following initiatives:]]>
</text>

<list>
    <thread thread_id="1"/>
    <ldiv/>
    <text>
        <location value="15"/><location value="25"/>
        <location value="35"/><location value="45"/>
        Mentorships and internship programs featuring diverse employees and students
    </text>
    <!--...-->
    <ldiv/>
    <text>
        <location value="20"/><location value="30"/>
        <location value="40"/><location value="50"/>
        Build Science, Technology, Engineering and Mathematics (STEM) employee candidate pipeline via involvement with:
        <list>
            <ldiv/>
            <text>
                <location value="25"/><location value="35"/>
                <location value="45"/><location value="55"/>
                Historically Black Colleges and Universities (HBCUs) site visits and career fairs
            </text>
            <!--...-->
            <ldiv/>
            <text>
                <location value="30"/><location value="40"/>
                <location value="50"/><location value="60"/>
                San Diego Squared (STEM-focused nonprofit organization connecting underrepresented student to the power
                of STEM by providing access to education, mentorship and resources to develop STEM careers)
            </text>
        </list>
    </text>
</list>

<page_footer>
    <location value="35"/><location value="45"/>
    <location value="55"/><location value="65"/>
    16 Neurocrine Biosciences
</page_footer>

<page_break/>

<list>
    <thread thread_id="1"/>
    <ldiv/>
    <text>
        <location value="40"/><location value="50"/>
        <location value="60"/><location value="70"/>
        <![CDATA[Build upon DE&I employee education initiatives including: ...]]>
    </text>
    <!--...-->
</list>
<!--...-->
```

--------------------------------

### Configure Schematron validation

Source: https://github.com/doclang-project/doclang/blob/main/_autodocs/configuration.md

Alternative installation or configuration methods when saxonche is not available.

```bash
pip install "doclang[schematron-saxon]"
```

```python
validate(..., xsd_only=True)
```

```python
validate(..., schematron=CustomValidator())
```

--------------------------------

### Consolidated DocLang Metadata Example

Source: https://github.com/doclang-project/doclang/blob/main/spec.md

Defines a complete document header including PII handling, data extraction rules, RAG retrieval constraints, and training prohibitions.

```xml
<doclang>
  <head>
    <!-- core metadata (illustrative) -->
    <title>Customer Support Case File</title>
    <date>2025-01-15</date>
    <language classifier="fastText" score="0.92">eng</language>
    <generated_by>example_pipeline/doc_ingest_v2</generated_by>

    <!-- licensing / classification / compliance (existing governance elements) -->
    <licenses>
      <license>https://www.apache.org/licenses/LICENSE-2.0</license>
    </licenses>

    <data_classification>
      <data_class>confidential</data_class>
      <data_class>personal information</data_class>
    </data_classification>

    <acceptable_use>
      <purpose>Customer support automation</purpose>
      <purpose>Internal analytics</purpose>
    </acceptable_use>

    <compliance_requirements>
      <compliance_req>GDPR</compliance_req>
      <compliance_req>ISO/IEC 27001</compliance_req>
      <compliance_req>ISO/IEC 27701</compliance_req>
    </compliance_requirements>

    <!-- Privacy and PII controls -->
    <pii_status>present</pii_status>
    <pii_sensitivity_level>medium</pii_sensitivity_level>
    <pii_source_type>user_provided</pii_source_type>
    <controller_processor_role>controller</controller_processor_role>
    <pii_processing_purpose>case_resolution</pii_processing_purpose>
    <pii_lawful_basis>legitimate_interest</pii_lawful_basis>
    <pii_minimisation_status>applied</pii_minimisation_status>
    <pii_transformation_level>pseudonymized</pii_transformation_level>
    <reidentification_risk>low</reidentification_risk>
    <access_control_level>restricted</access_control_level>
    <ai_use_restriction>no_general_training</ai_use_restriction>
    <cross_border_transfer_status>not_permitted</cross_border_transfer_status>
    <retention_category>support_case_records</retention_category>
    <dsr_impact_flag>true</dsr_impact_flag>
    <dpia_required>false</dpia_required>
    <logging_monitoring_enabled>true</logging_monitoring_enabled>

    <!-- Data extraction controls -->
    <extraction_permitted>true</extraction_permitted>
    <extraction_scope>tables_and_forms_only</extraction_scope>
    <extraction_purpose>case_metrics</extraction_purpose>
    <extraction_granularity>field_level</extraction_granularity>
    <pii_extraction_allowed>false</pii_extraction_allowed>
    <sensitive_data_extraction_allowed>false</sensitive_data_extraction_allowed>
    <extraction_transformation_required>redact</extraction_transformation_required>
    <extraction_output_constraints>internal_systems_only</extraction_output_constraints>
    <downstream_sharing_permitted>false</downstream_sharing_permitted>
    <extraction_audit_required>true</extraction_audit_required>
    <extraction_audit_retention unit="day">90</extraction_audit_retention>
    <human_in_the_loop_required>true</human_in_the_loop_required>

    <!-- RAG and retrieval controls -->
    <rag_permitted>true</rag_permitted>
    <rag_indexing_allowed>true</rag_indexing_allowed>
    <rag_embedding_scope>summaries_only</rag_embedding_scope>
    <rag_chunking_constraints>max_512_tokens</rag_chunking_constraints>
    <rag_query_restrictions>support_intent_only</rag_query_restrictions>
    <rag_output_attribution_required>true</rag_output_attribution_required>
    <rag_output_transformation_required>summarize_and_redact</rag_output_transformation_required>
    <rag_pii_exposure_allowed>false</rag_pii_exposure_allowed>
    <rag_sensitive_data_exposure_allowed>false</rag_sensitive_data_exposure_allowed>
    <rag_downstream_sharing_permitted>false</rag_downstream_sharing_permitted>
    <rag_caching_allowed>true</rag_caching_allowed>
    <rag_cache_retention unit="day">30</rag_cache_retention>
    <rag_audit_required>true</rag_audit_required>
    <rag_audit_retention unit="day">90</rag_audit_retention>
    <rag_model_scope>enterprise_internal_models</rag_model_scope>

    <!-- Document training controls -->
    <training_permitted>false</training_permitted>
    <training_scope>none</training_scope>
    <training_purpose>none</training_purpose>
    <training_model_type>none</training_model_type>
    <training_dataset_reuse_allowed>false</training_dataset_reuse_allowed>
    <training_derivative_sharing_permitted>false</training_derivative_sharing_permitted>
    <training_pii_included>false</training_pii_included>
    <training_sensitive_data_included>false</training_sensitive_data_included>
    <training_provenance_required>true</training_provenance_required>
    <training_audit_required>true</training_audit_required>
    <training_audit_retention unit="day">365</training_audit_retention>
    <model_output_usage_constraints>internal_only</model_output_usage_constraints>
    <right_to_be_forgotten_applicability>true</right_to_be_forgotten_applicability>

  </head>
  <!-- document content -->
</doclang>
```

--------------------------------

### Check Doclang version

Source: https://github.com/doclang-project/doclang/blob/main/_autodocs/cli.md

Displays the current version of the installed Doclang package.

```bash
doclang --version
# Output: doclang version 0.7.3
```

--------------------------------

### Handle PackagingError

Source: https://github.com/doclang-project/doclang/blob/main/_autodocs/types.md

Example of catching a PackagingError when providing invalid paths to the pack function.

```python
from doclang import pack, PackagingError

try:
    pack("document.dclg", assets={"invalid/path/..": "source.txt"})
except PackagingError as exc:
    print(exc)
    # Output: "Invalid asset path: ..."
```

--------------------------------

### Validation Command Examples

Source: https://github.com/doclang-project/doclang/blob/main/_autodocs/cli.md

Common usage patterns for the validation command including flags for specific validation types, output formats, and verbosity.

```bash
doclang validate document.dclg
```

```bash
doclang validate document.dclg --xsd-only
```

```bash
doclang validate document.dclg --quiet
```

```bash
doclang validate document.dclg --format json
```

```bash
doclang validate document.xml -n
```

```bash
doclang validate document.dclg --verbose
```

--------------------------------

### Define Tables with Threads and Headers

Source: https://github.com/doclang-project/doclang/blob/main/spec.md

Examples of table structures using thread and header elements to organize data.

```xml
<table>
  <thread thread_id="1"/>
  <h_thread h_thread_id="1"/>

  <ecel/>                                      <ecel/>                        <ecel/><nl/>
  <ecel/>                                      <ched/><text>Continent</text>  <ched/><text>Country</text><nl/>
  <rhed/><text><thread thread_id="2"/></text>  <rhed/><text>Asia</text>       <rhed/><text>Japan</text><nl/>
</table>
<page_break/>
```

```xml
<table>
  <thread thread_id="1"/>
  <h_thread h_thread_id="2"/>

  <rhed/><text><thread thread_id="2"/>G7 member</text>  <rhed/><text><thread thread_id="3"/>Europe</text>  <rhed/><text>France</text><nl/>
  <ucel/>                                               <ucel/>                                            <rhed/><text>Germany</text><nl/>
  <ucel/>                                               <ucel/>                                            <rhed/><text>Italy</text><nl/>
</table>
<page_break/>
```

```xml
<table>
  <thread thread_id="1"/>
  <h_thread h_thread_id="3"/>

  <rhed/><text><thread thread_id="2"/></text>  <rhed/><text><thread thread_id="3"/></text>  <rhed/><text>United Kingdom</text><nl/>
  <ucel/>                                      <rhed/><text>North America</text>            <rhed/><text>Canada</text><nl/>
  <ucel/>                                      <ucel/>                                      <rhed/><text>United States</text><nl/>
</table>
<page_break/>
```

```xml
<table>
  <h_thread h_thread_id="1"/>

  <ched/><text><h_thread h_thread_id="4"/>2025 d<text>  <lcel/>                                <lcel/><nl/>
  <ched/><text>GDP (PPP) per capita in USD</text>       <ched/><text>Currency</text>            <ched/><text><h_thread h_thread_id="5"/>Key l</text><nl/>
  <fcel/><text>46,097</text>                            <fcel/><text>Japanese yen (JPY)</text>  <fcel/><text>Shigeru Ishiba</text><nl/>
</table>
<page_break/>
```

```xml
<table>
  <thread thread_id="1"/>
  <h_thread h_thread_id="2"/>

  <fcel/><text>54,465</text>  <fcel/><text>Euro (EUR)</text>  <fcel/><text>Emmanuel Macron</text><nl/>
  <fcel/><text>62,830</text>  <fcel/><text>Euro (EUR)</text>  <fcel/><text>Friedrich Merz</text><nl/>
  <fcel/><text>53,115</text>  <fcel/><text>Euro (EUR)</text>  <fcel/><text>Giorgia Meloni</text><nl/>
</table>
<page_break/>
```

```xml
<table>
  <thread thread_id="1"/>
  <h_thread h_thread_id="3"/>

  <fcel/><text>52,518</text>  <fcel/><text>Pound sterling (GBP)</text>        <fcel/><text>Keir Starmer</text><nl/>
  <fcel/><text>62,830</text>  <fcel/><text>Canadian dollar</text>             <fcel/><text>Mark Carney</text><nl/>
  <fcel/><text>53,115</text>  <fcel/><text>United States dollar (USD)</text>  <fcel/><text>Donald Trump</text><nl/>
</table>
<page_break/>
```

```xml
<table>
  <thread thread_id="1"/>
  <h_thread h_thread_id="1"/>

  <ched/><text><h_thread h_thread_id="4"/>etails</text>  <lcel/>                                     <lcel/><nl/>
  <ched/><text><h_thread h_thread_id="5"/>eader</text>   <ched/><text>Population in millions</text>  <ched/><text>Area in km2</text><nl/>
  <fcel/><text>Prime Minister</text>                     <fcel/><text>125.1</text>                   <fcel/><text>377,975</text><nl/>
</table>
<page_break/>
```

--------------------------------

### Parse SVRL output

Source: https://github.com/doclang-project/doclang/blob/main/_autodocs/schematron-backend.md

Example demonstrating how to parse an SVRL XML string into an element tree and extract violations.

```python
from lxml import etree
from doclang.backends._svrl import _svrl_failed_asserts_to_violations

# Parse SVRL XML result from stylesheet execution
svrl_doc = etree.fromstring(svrl_output.encode("utf-8"))
violations = _svrl_failed_asserts_to_violations(svrl_doc)
```

--------------------------------

### Represent Tables and Form Regions

Source: https://github.com/doclang-project/doclang/blob/main/spec.md

Example of mixing table structures with field regions and lists.

```xml
<!--...-->
  <heading>Part III</heading>
  <text>Figure Your Credit</text>
  <text>10</text>
  <table>
    <ched/><text>If you checked (in Part l):</text><ched/><text>Enter</text><nl/>
    <fcel/><text>Box 1, 2, 4, or 7</text><fcel/><text>$5,000</text><nl/>
    <fcel/><text>Box 3, 5, or 6</text><fcel/><text>$7,500</text><nl/>
    <fcel/><text>Box 8 or 9</text><fcel/><text>$3,750</text><nl/>
  </table>
  <field_region><field_item><key>10</key><value></value></field_item></field_region>
  <text>11 If you checked (in Part I):</text>
  <list>
      <ldiv/>
      <text>Box 6, add $5,000 to the taxable...</text>
      <ldiv/>
      <text>Box 2, 4, or 9, enter your taxable...</text>
      <ldiv/>
      <text>BBox 5, add your taxable disabilit...</text>
  </list>
  <field_region><field_item><key>11</key><value>.</value></field_item></field_region>
  <picture><label value="logo"/></picture>
  <text>For more details on what to include on line 11...</text>
  <text>12 If you completed line 11, enter the smaller...</text>
  <field_region><field_item><key>12</key><value>74,992</value></field_item></field_region>
  <!--...-->
```

--------------------------------

### Perform XSD validation on a file

Source: https://github.com/doclang-project/doclang/blob/main/_autodocs/xsd-validation.md

Example usage of the _validate_xsd function to check a document and print any reported errors.

```python
from doclang.xsd_validation import _validate_xsd

errors = _validate_xsd("document.dclg")
if errors:
    for error in errors:
        print(f"Line {error['line']}: {error['message']}")
else:
    print("XSD validation passed")
```

--------------------------------

### Define Cross-Column Structure

Source: https://github.com/doclang-project/doclang/blob/main/spec.md

Example of using thread IDs and location tags to map content across columns.

```xml
<!-- ... -->
<text>
  <thread thread_id="1"/>
  <location value="10"/><location value="20"/>
  <location value="30"/><location value="40"/>
  where τ<subscript>x,y,z</subscript> are the Pauli matrices acting
  on Nambu space. We consider a circular-shaped boundary, the nor-
</text>

<picture>
  <caption>
    <location value="20"/><location value="30"/>
    <location value="40"/><location value="50"/>
    FIG. 3. The modules of the inner product of two MES spinors
    <formula><!-- ... --></formula>
    <!-- ... -->
  </caption>
  <!-- ... -->
</picture>

<text>
  <thread thread_id="1"/>
  <location value="30"/><location value="40"/>
  <location value="50"/><location value="60"/>
  mal direction of the boundary tangent for arbitrary angle θ is
  <formula><!-- ... --></formula>
  <!-- ... -->
</text>
```

--------------------------------

### Define DocLang document metadata

Source: https://github.com/doclang-project/doclang/blob/main/spec.md

Example of a <head> block containing core metadata elements like title, author, language, and custom filter tags.

```xml
<doclang>
  <head>
    <!-- reserved elements -->
    <title>My Company's Annual Report</title>
    <author_info>
      <author>Author 1 Name</author>
      <author>
        <affiliation>Affiliation A</affiliation>
        <affiliation>Affiliation B</affiliation>
        Author 2 Name
      </author>
    </author_info>
    <date>2024-01-01</date>
    <language classifier="fastText" score="0.7">eng</language>
    <language classifier="fastText" score="0.2">spa</language>
    <topic topic_taxonomy="taxonomy" score="0.5">Technology</topic>
    <topic topic_taxonomy="taxonomy" score="0.5">Math</topic>
    <document_hash hash_function="sha256sum">75f2db0c6124527bf6dd48440f95fc864a5108d28517633f937923a7d8199185</document_hash>
    <summary>This is a summary of the document</summary>
    <generated_by>example_vlm_org/example_vlm_name</generated_by>
    <default_resolution width="512" height="512"/>
    <page_size width="612" height="792"/>
    <page_size page_no="4" width="792" height="612"/>

      <!-- examples of custom elements -->
    <my_company_hap_filter_hate>0.1</my_company_hap_filter_hate>
    <my_company_hap_filter_abuse>0.1</my_company_hap_filter_abuse>
    <my_company_hap_filter_profanity>0.1</my_company_hap_filter_profanity>
  </head>
  <!-- document content -->
</doclang>
```

--------------------------------

### Basic packaging

Source: https://github.com/doclang-project/doclang/blob/main/_autodocs/cli.md

Creates a .dclx archive with the default filename in the same directory as the source document.

```bash
doclang pack document.dclg
# Creates: document.dclx
```

--------------------------------

### Basic packaging with doclang

Source: https://github.com/doclang-project/doclang/blob/main/_autodocs/pack.md

Creates a default archive from a source document.

```python
from doclang import pack

archive_path = pack("document.dclg")
print(f"Created {archive_path}")
# Output: /home/user/document.dclx
```

--------------------------------

### Define Setuptools packages in pyproject.toml

Source: https://github.com/doclang-project/doclang/blob/main/_autodocs/configuration.md

Specifies the source packages to be included in the build.

```toml
[tool.setuptools]
packages = ["doclang", "doclang.backends"]
```

--------------------------------

### Advanced Packaging Scenarios

Source: https://github.com/doclang-project/doclang/blob/main/doclang/README.md

Customize packaging with output files, page inclusions, asset mapping, and validation.

```bash
doclang pack markup.dclg -o report.dclx
doclang pack markup.dclg --pages screenshots/
doclang pack markup.dclg --page a.png --page b.png
doclang pack markup.dclg --asset chart.svg=exports/diagram.svg
doclang pack markup.dclg --assets payload/
doclang pack markup.dclg --validate
```

--------------------------------

### Handle ValidationError

Source: https://github.com/doclang-project/doclang/blob/main/_autodocs/types.md

Example of catching and accessing error details from a ValidationError.

```python
from doclang import validate, ValidationError

try:
    validate("document.dclg")
except ValidationError as exc:
    print(f"XSD: {exc.xsd_errors}")
    print(f"Schematron: {exc.schematron_errors}")
```

--------------------------------

### Package with Media

Source: https://github.com/doclang-project/doclang/blob/main/_autodocs/index.md

Creates an OPC archive from a document, including specified pages and assets.

```python
from doclang import pack

archive = pack(
    "document.dclg",
    pages="screenshots/",
    assets={"diagrams/": "assets/"},
)
print(f"Created {archive}")
```

--------------------------------

### Packaging with assets

Source: https://github.com/doclang-project/doclang/blob/main/_autodocs/pack.md

Maps local files to specific paths within the archive.

```python
from doclang import pack

archive_path = pack(
    "document.dclg",
    assets={"charts/diagram.svg": "exports/architecture.svg"},
)
# Result: assets/charts/diagram.svg (mapped from exports/architecture.svg)
```

--------------------------------

### Perform XSD-only validation

Source: https://github.com/doclang-project/doclang/blob/main/_autodocs/validate.md

Run validation without Schematron, useful when the Saxon/C backend is not installed.

```python
from doclang import validate

# Useful when saxonche is not available
validate("document.dclg", xsd_only=True)
```

--------------------------------

### Basic Validation Usage

Source: https://github.com/doclang-project/doclang/blob/main/_autodocs/schematron-backend.md

Demonstrates initializing the validator and executing a validation check against a document.

```python
from pathlib import Path
from doclang.backends.saxonche import SaxoncheValidator
from doclang import validate

validator = SaxoncheValidator()
violations = validator.validate(
    Path("document.dclg"),
    schema_path=Path("doclang.sch"),
)
print(f"Found {len(violations)} violations")
```

--------------------------------

### Package documents via Python

Source: https://github.com/doclang-project/doclang/blob/main/_autodocs/00-START-HERE.md

Bundle a document with associated assets into a packaged output file.

```python
pack("document.dclg", pages="screenshots/", output="report.dclx")
```

--------------------------------

### Project Directory Structure

Source: https://github.com/doclang-project/doclang/blob/main/_autodocs/configuration.md

Visual representation of the doclang package file hierarchy.

```text
doclang/
├── __init__.py                  # Public API
├── cli.py                       # CLI commands
├── validation.py                # validate() function
├── packaging.py                 # pack() function
├── _packaging.py                # Internal packaging logic
├── schematron.py                # SchematronValidator protocol
├── tokenization.py              # get_special_tokens() function
├── xsd_validation.py            # XSD validation logic
├── utils.py                     # Shared utilities
├── _schemas.py                  # Schema file discovery
├── version.py                   # Version resolution
├── doclang.xsd                  # Bundled XSD schema
├── doclang.sch                  # Bundled Schematron rules
└── backends/
    ├── __init__.py              # Backends module
    ├── saxonche.py              # Saxon/C backend
    └── _svrl.py                 # SVRL parsing helpers
```

--------------------------------

### Include pages as sequence

Source: https://github.com/doclang-project/doclang/blob/main/_autodocs/cli.md

Adds individual image files as pages in the specified order, renumbering them within the archive.

```bash
doclang pack document.dclg --page cover.png --page intro.png --page body.png
# Renumbered as: pages/1.png, pages/2.png, pages/3.png
```

--------------------------------

### Register CLI entry point

Source: https://github.com/doclang-project/doclang/blob/main/_autodocs/configuration.md

Defines the doclang command-line interface entry point in the project configuration.

```toml
[project.scripts]
doclang = "doclang.cli:app"
```

--------------------------------

### Form Elements for Field Items

Source: https://github.com/doclang-project/doclang/blob/main/examples/form/form-examples.md

This XML snippet defines individual form items, each with a key, an optional value, and a hint. These are referenced by the tabular form example.

```xml
*FORM1*: <field_item><key>300</key><value></value><hint>EUR</hint></field_item>
*FORM2*: <field_item><key>400</key><value></value><hint>EUR</hint></field_item>
*FORM4*: <field_item><key>401</key><value></value></field_item>
*FORM5*: <field_item><key>302</key><value></value></field_item>
*FORM3*: <field_item><key>301</key><value></value></field_item>
*FORM6*: <field_item><key>402</key><value></value></field_item>
*FORM7*: <field_item><key>309</key><value></value></field_item>
*FORM8*: <field_item><key>409</key><value></value></field_item>
```

--------------------------------

### Configure IDE file associations

Source: https://github.com/doclang-project/doclang/blob/main/CONTRIBUTING.md

Maps the .dclg file extension to XML in VS Code settings.

```json
{
  "files.associations": {
    "*.dclg": "xml"
  }
}
```

--------------------------------

### Package document with media

Source: https://github.com/doclang-project/doclang/blob/main/_autodocs/README.md

Packages a document and associated media into a single output file.

```python
from doclang import pack

archive = pack("document.dclg", pages="screenshots/", output="report.dclx")
```

--------------------------------

### doclang pack (CLI)

Source: https://github.com/doclang-project/doclang/blob/main/_autodocs/index.md

Command-line interface for archive packaging.

```APIDOC
## doclang pack

### Description
CLI command used to package DocLang documents into an archive.
```

--------------------------------

### Packaging with page images

Source: https://github.com/doclang-project/doclang/blob/main/_autodocs/pack.md

Includes page images from a directory or as a specific sequence.

```python
from doclang import pack

archive_path = pack(
    "document.dclg",
    pages="screenshots/",
)
# archive_path contains: document.xml, pages/1.png, pages/2.png, ...
```

```python
from doclang import pack

archive_path = pack(
    "document.dclg",
    pages=["page_a.png", "page_b.png"],
)
# Pages are renumbered: pages/1.png, pages/2.png
```

```python
from doclang import pack

archive_path = pack(
    "document.dclg",
    pages={1: "cover.png", 3: "toc.png"},
)
# Result: pages/1.png, pages/3.png (page 2 is absent)
```

--------------------------------

### doclang.pack(source, output=None, pages=None, assets=None, validate=False)

Source: https://github.com/doclang-project/doclang/blob/main/_autodocs/pack.md

Packages a document source into an archive. Returns the path to the created archive.

```APIDOC
## doclang.pack

### Description
Packages a document file into a .dclx archive. Supports custom output paths, page image inclusion, asset mapping, and document validation.

### Signature
`pack(source, output=None, pages=None, assets=None, validate=False)`

### Parameters
- **source** (str) - Required - Path to the source document file (e.g., .dclg).
- **output** (str) - Optional - Path for the resulting archive file.
- **pages** (str|list|dict) - Optional - Page images to include. Can be a directory path, a list of file paths, or a dictionary mapping page numbers to file paths.
- **assets** (dict) - Optional - Dictionary mapping destination paths to source asset paths.
- **validate** (bool) - Optional - If True, validates the document before packaging.

### Raises
- **PackagingError** - Raised when files are missing, directories don't exist, paths are invalid, or symbolic links are encountered.
- **ValidationError** - Raised when validate=True and the document fails validation.

### Example
```python
from doclang import pack

archive_path = pack(
    "markup.dclg",
    output="report.dclx",
    pages=["page1.png", "page2.png"],
    assets={"diagrams/": "assets/"},
    validate=True,
)
```
```

--------------------------------

### pack(document, pages=None, assets=None)

Source: https://github.com/doclang-project/doclang/blob/main/_autodocs/index.md

Creates an OPC (.dclx) archive containing the document and associated media or assets.

```APIDOC
## pack(document, pages=None, assets=None)

### Description
Packages a document into an Open Packaging Convention (OPC) archive.

### Parameters
- **document** (str) - Required - Path to the .dclg document.
- **pages** (str) - Optional - Path to directory containing page images.
- **assets** (dict) - Optional - Mapping of source directories to destination paths within the archive.
```

--------------------------------

### Apply basic text formatting

Source: https://github.com/doclang-project/doclang/blob/main/spec.md

Use tags like <bold>, <italic>, <underline>, and <strikethrough> to style text content.

```xml
<text>
  This text contains <bold>bold</bold>, <italic>italic</italic>,
  <underline>underlined</underline>, and <strikethrough>struck-through</strikethrough> text.
</text>
```

--------------------------------

### pack(document, *, output=None, pages=None, assets=None, validate=False)

Source: https://github.com/doclang-project/doclang/blob/main/_autodocs/pack.md

Packs a DocLang markup file and optional media into a .dclx OPC archive.

```APIDOC
## pack(document, *, output=None, pages=None, assets=None, validate=False)

### Description
Pack a DocLang markup file and optional media into a .dclx OPC archive.

### Parameters
- **document** (str | Path) - Required - Path to the DocLang markup file (.dclg, .xml, or any text format).
- **output** (str | Path | None) - Optional - Output path for the .dclx archive. If None, creates <document>.dclx in the same directory.
- **pages** (str | Path | Sequence | Mapping | None) - Optional - Page images to include. Can be a directory path, sequence of image paths, or mapping of page number to image path.
- **assets** (str | Path | Mapping | None) - Optional - Additional assets to include. Can be a directory path or mapping of archive-relative path to source file.
- **validate** (bool) - Optional - If True, validate the document against DocLang XSD/Schematron before packing.

### Return Type
- **Path** - Resolved absolute path to the created .dclx archive.

### Exceptions
- **PackagingError** - Packaging fails (missing files, invalid paths, symbolic links in pages/assets).
- **ValidationError** - validate=True and the document fails validation (XSD or Schematron).
```

--------------------------------

### Generate reference documentation

Source: https://github.com/doclang-project/doclang/blob/main/CONTRIBUTING.md

Updates Appendix A in the specification using input data.

```bash
uv run python utils/generate_reference.py reference/input
```

--------------------------------

### Inject namespace and validate

Source: https://github.com/doclang-project/doclang/blob/main/_autodocs/validate.md

Automatically prepend the DocLang namespace to the root element if it is missing.

```python
from doclang import validate

# Auto-inject DocLang namespace if missing
validate("document.xml", allow_empty_namespace=True)
```

--------------------------------

### Package with validation

Source: https://github.com/doclang-project/doclang/blob/main/_autodocs/cli.md

Performs XSD and Schematron validation on the document before creating the archive.

```bash
doclang pack document.dclg --pages screenshots/ --validate
```

--------------------------------

### Define Development Dependencies

Source: https://github.com/doclang-project/doclang/blob/main/_autodocs/architecture.md

Lists the development-time dependencies used for testing, linting, and document processing.

```text
doclang[dev]
├── pytest ~= 8.3           Testing
├── mypy ~= 1.6             Type checking
├── ruff >= 0.14.11         Linting and formatting
├── pre-commit ~= 3.7       Git hooks
├── python-docx >= 1.2.0    DOCX handling
├── pydantic >= 2.11.10     Data validation
├── pyyaml >= 6.0.3         YAML support
├── openpyxl >= 3.1.0       Excel handling
└── docling >= 2.0.0        Document processing
```

--------------------------------

### Define Production Dependencies

Source: https://github.com/doclang-project/doclang/blob/main/_autodocs/architecture.md

Lists the core production dependencies required for XML parsing, CLI functionality, and optional Schematron support.

```text
doclang
├── lxml >= 4.8.0           XML parsing and validation
├── typer >= 0.15.1         CLI framework
└── (optional) saxonche >= 12.9.0   Schematron backend
```

--------------------------------

### Run test suite

Source: https://github.com/doclang-project/doclang/blob/main/CONTRIBUTING.md

Executes the full pytest suite.

```bash
uv run pytest
```

--------------------------------

### Complex packaging

Source: https://github.com/doclang-project/doclang/blob/main/_autodocs/cli.md

Combines multiple options including custom output, page sequences, asset mapping, validation, and quiet mode.

```bash
doclang pack markup.dclg \
  -o report.dclx \
  --page page1.png --page page2.png \
  --asset diagrams/architecture.svg=exports/architecture.svg \
  --validate \
  --quiet
```

--------------------------------

### pack(path, pages=None, assets=None)

Source: https://github.com/doclang-project/doclang/blob/main/doclang/README.md

Packages a document with its associated pages and assets into a final output.

```APIDOC
## pack(path, pages=None, assets=None)

### Description
Packages a .dclg document with external resources.

### Parameters
- **path** (str) - Required - Path to the source document.
- **pages** (str) - Optional - Path to directory containing page content.
- **assets** (dict) - Optional - Mapping of source file paths to destination paths within the package.

### Returns
- **path** (Path) - The path to the created package.
```

--------------------------------

### Packaging with explicit output path

Source: https://github.com/doclang-project/doclang/blob/main/_autodocs/pack.md

Specifies a custom filename for the generated archive.

```python
from doclang import pack

archive_path = pack("markup.dclg", output="report.dclx")
```

--------------------------------

### Include pages from directory

Source: https://github.com/doclang-project/doclang/blob/main/_autodocs/cli.md

Includes all images from a directory as pages, assuming they are named sequentially (e.g., 1.png, 2.png).

```bash
doclang pack document.dclg --pages screenshots/
# Directory must contain: 1.png, 2.png, 3.png, …
```

--------------------------------

### Simple Key-Value Form Fields

Source: https://github.com/doclang-project/doclang/blob/main/examples/form/form-examples.md

Illustrates a basic form structure with key-value pairs for simple data entry.

```xml
<field_region>
    <field_item>
        <key>Firma:</key>
        <value>Holcim ... GmbH</value>
    </field_item>
    <field_item>
        <key>Datum:</key>
        <value>23.08.2019</value>
    </field_item>
    <!--...-->
    <field_item>
        <key>Petrograph. Typ:</key>
        <value>Quartiarer Sand + Kies</value>
    </field_item>
</field_region>
```

--------------------------------

### Include assets from directory tree

Source: https://github.com/doclang-project/doclang/blob/main/_autodocs/cli.md

Copies an entire directory structure into the assets/ folder of the archive.

```bash
doclang pack document.dclg --assets payload/
# Entire payload/ directory tree copied into assets/
```

--------------------------------

### Execute CLI commands

Source: https://github.com/doclang-project/doclang/blob/main/_autodocs/README.md

Common command-line interface operations for validating and packaging documents.

```bash
# Validate
doclang validate document.dclg
doclang validate document.dclg --xsd-only
doclang validate document.dclg --format json

# Package
doclang pack document.dclg
doclang pack document.dclg -o report.dclx --pages screenshots/ --validate
```

--------------------------------

### Sync project version

Source: https://github.com/doclang-project/doclang/blob/main/CONTRIBUTING.md

Propagates version numbers across project artifacts.

```bash
uv run python utils/sync_version.py 0.4.0   # explicit target release (typical before tagging)
uv run python utils/sync_version.py         # release triple from latest git tag
```

--------------------------------

### Import Doclang API components

Source: https://github.com/doclang-project/doclang/blob/main/_autodocs/00-START-HERE.md

Essential imports for accessing validation, packaging, and tokenization utilities along with specific exception classes.

```python
from doclang import validate, pack, get_special_tokens
from doclang import ValidationError, SchematronBackendNotFound, PackagingError
from doclang import SchematronValidator, SchematronViolation
```

--------------------------------

### CLI Command Structure

Source: https://github.com/doclang-project/doclang/blob/main/_autodocs/architecture.md

Visual representation of the Typer-based CLI command hierarchy and execution flow.

```text
doclang (entry point)
   │
   └─→ app = typer.Typer()
       │
       ├─→ @app.command() validate()
       │   │
       │   ├─→ Parse arguments (xml_file, xsd_only, schematron_only, etc.)
       │   ├─→ Call validate_document(xml_file, ...)
       │   ├─→ Handle ValidationError, SchematronBackendNotFound
       │   ├─→ Format output (text or JSON)
       │   └─→ Exit with code 0 (success) or 1 (failure)
       │
       ├─→ @app.command() pack()
       │   │
       │   ├─→ Parse arguments (document, pages, assets, output, validate)
       │   ├─→ Construct pages/assets parameters
       │   ├─→ Call pack_document(document, ...)
       │   ├─→ Handle ValidationError, PackagingError
       │   └─→ Exit with code 0 (success) or 1 (failure)
       │
       └─→ @app.callback() main()
           └─→ Handle global options (--version)
```

--------------------------------

### Include multiple assets

Source: https://github.com/doclang-project/doclang/blob/main/_autodocs/cli.md

Adds multiple individual assets to the archive by repeating the --asset flag.

```bash
doclang pack document.dclg --asset diagram.svg=exports/arch.svg --asset table.csv=data/table.csv
```

--------------------------------

### Configure package data in pyproject.toml

Source: https://github.com/doclang-project/doclang/blob/main/_autodocs/configuration.md

Ensures XML and Schematron schema files are included in the distribution package.

```toml
[tool.setuptools.package-data]
doclang = ["*.xsd", "*.sch"]
```

--------------------------------

### Define custom vocabulary with project prefixes

Source: https://github.com/doclang-project/doclang/blob/main/spec.md

Use a collision-resistant prefix for local or private custom metadata without formal namespaces.

```xml
<picture>
  <label value="chemistry_structure"/>
  <custom>
    <acme_smiles>C1=CC=C(C=C1)C(=O)O</acme_smiles>
  </custom>
  <src uri="molecule.svg"/>
</picture>
```

--------------------------------

### --version, -v

Source: https://github.com/doclang-project/doclang/blob/main/_autodocs/cli.md

Displays the current version of the doclang CLI and exits the process.

```APIDOC
## --version, -v

### Description
Show the installed version of the doclang CLI and exit.

### Usage
`doclang --version` or `doclang -v`

### Example
```bash
doclang --version
# Output: doclang version 0.7.3
```
```

--------------------------------

### Create a secure lxml parser

Source: https://github.com/doclang-project/doclang/blob/main/_autodocs/utilities.md

Initializes an lxml XMLParser with security settings enabled to prevent common XML attacks like entity resolution and network loading.

```python
from lxml import etree
from doclang.utils import _safe_xml_parser

parser = _safe_xml_parser()
doc = etree.parse("document.xml", parser=parser)
```

--------------------------------

### pack(file)

Source: https://github.com/doclang-project/doclang/blob/main/_autodocs/index.md

Packages a document file.

```APIDOC
## pack(file)

### Description
Performs packaging operations on the specified document file.

### Signature
`doclang.pack(file)`
```

--------------------------------

### Inspect vocabulary contents

Source: https://github.com/doclang-project/doclang/blob/main/_autodocs/get_special_tokens.md

Demonstrates how to view the generated token list, including both fixed and location-based tokens.

```python
from doclang import get_special_tokens

tokens = get_special_tokens(max_resolution=10)
print(tokens[:20])  # First 20 tokens
# Includes:
# ['<doclang>', '</doclang>', '<page_break/>', ...]
# and location tokens: ['<location value="0"/>', '<location value="1"/>', ...]
```

--------------------------------

### Integrate with tokenizer

Source: https://github.com/doclang-project/doclang/blob/main/_autodocs/get_special_tokens.md

Shows how to register the generated special tokens with an existing LLM tokenizer.

```python
from doclang import get_special_tokens

# For integration with an LLM tokenizer:
vocab = get_special_tokens(max_resolution=512)

# Example: register tokens with a tokenizer
for token in vocab:
    tokenizer.add_special_token(token)
```

--------------------------------

### Fillable fields with hints

Source: https://github.com/doclang-project/doclang/blob/main/spec.md

Uses the fillable class for editable fields and includes hint elements to provide user guidance.

```xml
<field_region>
  <field_heading>Application Form</field_heading>

  <field_item>
    <key>Full Name:</key>
    <value class="fillable"></value>
    <hint>Enter your first and last name</hint>
  </field_item>

  <field_item>
    <key>Date of Birth:</key>
    <value class="fillable"></value>
    <hint>Format: YYYY-MM-DD</hint>
  </field_item>

  <field_item>
    <key>Email Address:</key>
    <value class="fillable"></value>
    <hint>example@domain.com</hint>
  </field_item>

  <field_item>
    <key>Status:</key>
    <value class="read_only">Pending Review</value>
  </field_item>
</field_region>
```

--------------------------------

### Configure Ruff in pyproject.toml

Source: https://github.com/doclang-project/doclang/blob/main/_autodocs/configuration.md

Sets the target Python version and line length for linting and formatting.

```toml
[tool.ruff]
target-version = "py310"
line-length = 120
```

--------------------------------

### Implement Lazy Backend Loading

Source: https://github.com/doclang-project/doclang/blob/main/_autodocs/architecture.md

Loads the Schematron backend only when required, raising an error if the dependency is missing.

```python
def _default_schematron_validator():
    _require_saxonche_backend()  # Raises SchematronBackendNotFound if missing
    from doclang.backends.saxonche import SaxoncheValidator
    return SaxoncheValidator()
```