protoml-parser
Version:
ProtoML is a lightweight, declarative markup language designed for writing and structuring meeting protocols, notes and task lists in a human-readable and machine-parseable format.
57 lines (54 loc) • 3.16 kB
HTML
<html>
<head>
<meta charset="UTF-8">
<title>ProtoML Concepts - ProtoML 1.4.2+build67</title>
<link rel="stylesheet" href="help.css">
</head>
<body>
<nav class="topnav">
<a href="../toc.html">Contents</a>
<span class="version">ProtoML 1.4.2+build67</span>
</nav>
<main class="page">
<h1>ProtoML Concepts</h1>
<p>ProtoML is not just Markdown with a few extra commands. It behaves more like a small document system for structured protocols, reusable building blocks, and machine-readable exports.</p>
<h2>Document shape</h2>
<p>A typical ProtoML file combines metadata, structured blocks such as <code>@participants</code> or <code>@tasks</code>, and a freeform <code>@meeting</code> block for the readable narrative.</p>
<p>The structured blocks act as the source of truth. The meeting block is where that structured data is turned into a readable document.</p>
<h2>IDs and references</h2>
<ul>
<li><code>=lead:Jane Doe,...</code> defines a participant ID</li>
<li><code>=0:Release status</code> defines a subject ID</li>
<li><code>@@e=lead</code> echoes a known entry into the meeting text</li>
<li><code>@@ref=participants:lead:email</code> fetches a specific field</li>
</ul>
<p>This is what makes ProtoML maintainable: values are defined once and then referenced consistently.</p>
<h2>Imports vs. macros</h2>
<p>Use <code>@import</code> when you want to reuse content. Use <code>@macro</code> when you want reusable rendering templates.</p>
<ul>
<li>Imports help you split large documents into maintainable pieces</li>
<li>Macros help you standardize repeated render patterns</li>
<li>They can be combined, but they solve different problems</li>
</ul>
<h2>Tags as shared classification</h2>
<p>Tags are ProtoML's reusable classification layer for tasks. Define them locally with <code>@tags</code>, share them with <code>@tags_import</code>, and analyze them with <code>protoparser tags ...</code>. Participant lists can be reused in a similar way with <code>@participants_import</code>.</p>
<p>That means ProtoML can support not just writing, but also reporting on work across a document set.</p>
<h2>When to use what</h2>
<ul>
<li>Use metadata for document-level facts</li>
<li>Use structured blocks when data should be referenceable</li>
<li>Use <code>@meeting</code> for the human-readable story</li>
<li>Use <code>@import</code> to split content across files</li>
<li>Use <code>@macro</code> to standardize repeated rendered patterns</li>
<li>Use shared tags when multiple files should use the same task vocabulary</li>
</ul>
<h2>Related guides</h2>
<ul>
<li><a href="07_authoring_guide.html">Authoring Guide</a></li>
<li><a href="04_macros_guide.html">Macros Guide</a></li>
<li><a href="12_reference_map.html">Reference Map</a></li>
</ul>
</main>
</body>
</html>