gram: docs

> ./reference/README.md

# OOXML Reference Documentation

Reference materials for implementing the DOCX editor.

## Fetching the heavy files

ECMA-376 PDFs and supplementary ZIPs (~58 MB) are gitignored. Fetch them on demand:

```bash
bun run reference:fetch

Idempotent. The handwritten quick-refs and XSDs under ecma-376/part1/schemas/ stay committed for offline schema lookups.

Folder structure

reference/
├── quick-ref/                    # Committed. Human quick references.
│   ├── wordprocessingml.md       # Paragraphs, runs, formatting
│   └── themes-colors.md          # Theme colors, fonts
└── ecma-376/
    ├── overview.pdf              # Optional; fetch manually
    ├── part1/
    │   ├── *.pdf                 # Gitignored. `bun run reference:fetch`
    │   ├── *.zip                 # Gitignored. Same.
    │   └── schemas/              # Committed. XSDs for lookup.
    │       ├── wml.xsd           # WordprocessingML schema
    │       └── dml-main.xsd      # DrawingML (colors, themes)
    └── part4/
        ├── *.pdf                 # Gitignored.
        └── *.zip                 # Gitignored.

Key Files for DOCX Editing

Online Resources

• ECMA-376 Official: https://ecma-international.org/publications-and-standards/standards/ecma-376/
• Microsoft Open Specs: https://learn.microsoft.com/en-us/openspecs/office_standards/ms-oe376/
• OfficeOpenXML.com: http://officeopenxml.com/ (human-readable element docs)
• Open XML SDK: https://learn.microsoft.com/en-us/office/open-xml/open-xml-sdk

Common Element Reference

WordprocessingML (wml)

<w:document>           <!-- Root document -->
  <w:body>             <!-- Document body -->
    <w:p>              <!-- Paragraph -->
      <w:pPr>          <!-- Paragraph properties -->
        <w:jc w:val="center"/>     <!-- Alignment -->
        <w:spacing w:line="360"/>  <!-- Line spacing -->
      </w:pPr>
      <w:r>            <!-- Run (text with formatting) -->
        <w:rPr>        <!-- Run properties -->
          <w:b/>       <!-- Bold -->
          <w:i/>       <!-- Italic -->
          <w:sz w:val="24"/>       <!-- Font size (half-points) -->
          <w:color w:val="FF0000"/> <!-- Text color -->
        </w:rPr>
        <w:t>Text</w:t> <!-- Actual text content -->
      </w:r>
    </w:p>
  </w:body>
</w:document>

Theme Colors (DrawingML)

<a:clrScheme name="Office">
  <a:dk1>...</a:dk1>      <!-- Dark 1 (usually black) -->
  <a:lt1>...</a:lt1>      <!-- Light 1 (usually white) -->
  <a:dk2>...</a:dk2>      <!-- Dark 2 -->
  <a:lt2>...</a:lt2>      <!-- Light 2 -->
  <a:accent1>...</a:accent1>  <!-- Accent colors 1-6 -->
  ...
</a:clrScheme>

Styles (styles.xml)

<w:style w:type="paragraph" w:styleId="Heading1">
  <w:name w:val="heading 1"/>
  <w:basedOn w:val="Normal"/>
  <w:pPr>...</w:pPr>      <!-- Paragraph formatting -->
  <w:rPr>...</w:rPr>      <!-- Character formatting -->
</w:style>

How to Use

1. Quick lookup: Check this README or quick-ref/ markdown files
2. Schema validation: Use .xsd files to understand valid attributes
3. Deep dive: Search the Part 1 PDF for specific element documentation
4. Real-world behavior: Check Microsoft Open Specs for implementation details