# _STANDARDS

Standards, engine and templates for documents produced in this project.

| File | What it is |
|---|---|
| `MPM_Document_Standard.md` | **The rules**: types, numbering, revisions, files, layout, writing. Read this first. |
| `glossary_zh.md` | Master English → Simplified Chinese terms for Chinese editions (standard §12). |
| `registry.md` | Customer codes and every issued document number (a snapshot: claim numbers in the shared master registry, standard §11). |
| `mpmdoc/` | The build engine: stylesheet, header/footer, components, PDF renderer. Fonts and logos come from `../_ASSETS/mpm/`. |
| `templates/<TYPE>/` | Starter `build.py` + `figs.py` per MPM document type (TN, INS, SOP, BOM, SVY, TAP, DWG, TSB, PRO, SOW, WO), with a `_preview_*.pdf`. TN and DWG also have `build_zh.py` (Chinese edition). |

## Start a new document

1. Register the number in `registry.md` (and the customer code in `mpmdoc/brand.py` if new).
2. Copy `templates/<TYPE>/` to `<PROJECT FOLDER>/source/`.
3. Fill in `build.py` (content) and `figs.py` (source numbers + figures).
4. Run `python3 build.py` from `source/`. The PDF lands in the project folder.

`build.py` finds `_STANDARDS` by walking up from its own folder, so a project folder
can sit anywhere under DOCUMENTATION PROJECT.

## Requirements

Python 3.10+, `pip install playwright && playwright install chromium`.
Run `setup.sh` in the kit root once to install them, plus poppler (see `START_HERE.md`).

## Engine cheat sheet

```python
doc = Doc(number, rev, date, title, lede, meta=[(k, v), (k, v)], slug, history,
          customer=None, subject="", kicker=None, footer=None, classification=None)
doc.add(
    doc.kpis([(label, value, sub, tone)]),            # tone: None|key|strong|ok|bad
    doc.result([...]) / doc.before_you_start([...]),
    doc.section("Title", new_page=False),
    doc.table(cols, rows, caption=, ref=),            # KeyRow([...]), TotalRow([...]), up(), dn(), TBC
    doc.calc(["# comment", (name, working, result, "PASS")]),
    doc.figure(svg, caption, ref=),                   # cite as [[fig:ref]] / [[tab:ref]]
    doc.note(kicker, body, tone="info|warn|ok|verify"),
    doc.two(left_html, right_html), doc.bullets([...], check=True),
    doc.assumptions([...], [...]), doc.signoff(),
    # procedures (INS / SOP)
    doc.before_you_start([...]), doc.glance([(label, sub[, mark, other])]),
    doc.step(n, kicker, title, doc.steps([...]) + doc.note(...), figure, wide=False, side="35%"),
    doc.shot("img/x.jpg", caption, width), doc.shots(...), ui("Button"), doc.chain([...]),
    doc.special(kicker, title, body, figure), doc.checklist(title, [...], cols=2),
    # BOM
    doc.bom([(section, [(item, spec, qty, uom[, part_no])], subtotal_label)]),
    # surveys / plans (SVY / TAP)
    doc.kv([(label, value)]), doc.part(label, title, internal=False), doc.photo("img/x.jpg", caption, ref),
    doc.photos(...), verify(), doc.transcript(heading, [lines]), doc.approval(name, role, date),
    # commercial and field (PRO / SOW / WO / TSB); MPM provider block: from mpmdoc.brand import PROVIDER
    doc.parties([(heading, {name, contact, address, phone, email, web, coordinates})]),
    doc.priced([(subtotal_label, [(sku, description, qty, extended)])]),   # totals computed -> doc.price_total
    doc.milestones([(milestone, criteria, share, amount)], expect=doc.price_total), doc.money(v),
    doc.pill(text, "red|gold|grey|ink|green"), doc.fields([label | (label, hint)], cols=2, title=),
    doc.table(cols, [[""] * n] * 6, cls="fill"), doc.signatures([(role, who)]),
)
# Chinese edition (TN / DWG): source/build_zh.py next to build.py, same figs.py; build English first
# tr = i18n.Translator({doc phrases}); F = {k: tr.svg(f()) for k, f in FIGS.items()}; tr.check()
# Doc(..., lang="zh") / Drawing(..., lang="zh")  ->  {NUMBER}_{slug}_ZH_Rev{X.Y}.pdf
# TSB: one build.py loops over editions ("customer", slug "_TSB") and ("internal", slug "_TSB-Internal")

# drawings (DWG): see templates/DWG/build.py
dwg = Drawing(number, rev, date, title, subtitle, project, client, slug, history, location, discipline, drawn, checked, approved)
dwg.sheet(views=[dwg.view(svg, n, title, scale, area="1 / 1 / 5 / 3")], schedule=[(tag, name, desc, qty)], notes=[...])
dwg.build()
doc.build()

```

## Changing the standard

Edit `MPM_Document_Standard.md` and the engine together, bump the standard's version line,
and rebuild one document of each affected type to check.