Validation And Analysis Workflows

ProtoML includes a second layer beyond rendering: commands that help you inspect document quality, structure, references, and governance state.

Document validation

protoparser validate "meeting.pml"
protoparser -v validate "meeting.pml"
protoparser validate "meeting.pml" -trust=strict -trustRegistry="./authors-registry" -trustRegistry="./macro-registry"

Use validation when you want to catch missing imports, missing macros, duplicate IDs, unresolved references, or untrusted macro usage before focusing on visual output. The -trustRegistry=... flag is repeatable, so validation can merge multiple trust sources when authors and packages are split across different registries.

Trust inspection

protoparser trust "meeting.pml"
protoparser -vv trust "meeting.pml" -trustRegistry="./authors-registry" -trustRegistry="./macro-registry"

This is the best command when you want a dedicated trust report for the document, its used macros, and imported .pml files.

Signed governance documents

protoparser sign pml "./governance/release-approval.pml" "./keys/alice-private.pem" "Alice" alice-main
protoparser verify pml "./governance/release-approval.pml" -trustRegistry="./authors-registry"

Normal ProtoML documents can be signed too. That is useful for controlled governance files such as release approvals, operational procedures, policy texts, and reviewable internal records.

Shared tag validation and statistics

protoparser tags "_tags.pml" validate
protoparser tags "_tags.pml" statistics
protoparser tags "_tags.pml" html

This is useful when tags are a cross-document vocabulary and you want to understand how tasks are distributed across files.

General document analysis

protoparser analyze "meeting.pml" statistics
protoparser analyze "meeting.pml" html
protoparser analyze "meeting.pml" graph

Analysis is the best command when you need to understand imported content, merged structures, macro usage, or dependency shape.

Graph output

protoparser analyze "meeting.pml" graph -graphView=full -graphDirection=LR
protoparser analyze "meeting.pml" graph -output=meeting-graph

Graph output is especially helpful once documents start importing other ProtoML files or building shared tag trees.

Register workflow for directories

protoparser register "meetings" statistics
protoparser register "meetings" html
protoparser register "meetings" pdf

Use register reports when you care about document inventory, missing metadata, overdue reviews, or open work across a folder.

This command does not manage macro registries or macro packs. For external macro catalogs and installed macro packages, use macro_install and the macro registry workflow instead.

Macro usage inspection

protoparser macros "meeting.pml"

This is useful for understanding which registered macros are actually used, especially before cleanup or pack refactors.

Recommended quality workflow

Render the file for visual inspection
Run validate to catch structural issues
Run analyze when imports or cross-file structure matter
Run tags ... statistics when the shared task vocabulary matters
Run register across directories for governance-style collections

When each workflow matters most

Validation: before publishing or sharing
Analysis: when debugging structure or dependencies
Tag statistics: when workflow labels are part of reporting
Register reports: when the document set is managed like an inventory