protoml-parser/docs/chm/html_docs/06_concepts.html at master · OpenDucks/protoml-parser · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
<!DOCTYPE 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>