Skip to content

Commit 2bbf4ac

Browse files
bryan-entebryan-ente
authored
Create README.md
1 parent d6b99e7 commit 2bbf4ac

1 file changed

Lines changed: 177 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 177 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,177 @@
1+
# ProtoML - A minimal structured protocol language
2+
3+
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.
4+
5+
## Key Concepts
6+
7+
- **Purely declarative** - no logic, no runtime, just the code
8+
- **Flat structure** with modular references
9+
- **External resources** such as tags or files are importable
10+
- **Styling & referencing syntax** included
11+
- **Fully parsable into structured JSON, HTML or PDF files**
12+
13+
## Syntax Overview
14+
| Symbol | Meaning |
15+
| ------ | ------- |
16+
| `@command` | Starts a data block (e.g. `@participants`) |
17+
| `@@command` | Used inside `@meeting`, acts as inline macro |
18+
| `=` | Declare an ID for referencing |
19+
| `:` | Assigns value to the declared ID |
20+
| `-` | Declares a plain list entry |
21+
| `#`, `##` | Markdown-style headers |
22+
| `//` | Comment, ignored by parser |
23+
| `-b Text -b-`, `-i Text -i-`, `-a=url Text -a-` | Inline text styling |
24+
25+
## Example
26+
```plaintext
27+
@tags_import "tags.pml"
28+
29+
@date:21.05.2025
30+
@participants // or @ptp
31+
=pt1=John Doe,jdoe,jdoe@example.com
32+
=pt2=Jane Doe
33+
34+
@subjects
35+
=0:Project Status: TimeTrack
36+
=1:Security: TLS Check
37+
38+
@tasks
39+
-[ ] Renew SSL certificate @ptp=pt1 =1 @tag=important // Assigns the tasks to participant "pt1", assigns it to subject with ID 1 and tags it with the "important" tag
40+
41+
@notes
42+
- PDF export works -b very well -b-
43+
44+
@meeting
45+
# Meeting Title: @@e=0 // echoes value of ID 0
46+
## Participants
47+
@@e=pt1 , @@e=pt2
48+
.....
49+
50+
```
51+
52+
## External tags file (tags.pml)
53+
54+
```plaintext
55+
@tags // this command behaves differently when used in the tags.pml
56+
=0:Important
57+
=important:Critical, high priority
58+
```
59+
60+
## Parser logic (simplified)
61+
62+
- `@` starts a block
63+
- `@@` is used inside `@meeting` for inline substitution/macros
64+
- `=` declares an ID (`=pt1`) that can be referenced later
65+
- `@tags_import` includes external tag file
66+
- Markdown-style headers can be used in `@meeting` content
67+
- Styling uses `-i -i-` for italic, `-b -b-` for bold and `-a=url -a-` for links, similarly to the Tags in HTML
68+
69+
## Output Format (Example: JSON)
70+
71+
```json
72+
{
73+
"date": "2025-05-21",
74+
"participants": [
75+
{
76+
"name": "John Doe",
77+
"alias": "jdoe",
78+
"email": "jdoe@example.com",
79+
"id": "pt1"
80+
},
81+
{
82+
"name": "Jane Doe",
83+
"id": "pt2"
84+
}
85+
],
86+
"subjects": {
87+
"0": "Project Status: TimeTrack",
88+
"1": "Security: TLS Check"
89+
},
90+
"tasks": [
91+
{
92+
"done": false,
93+
"text": "Renew SSL certificate",
94+
"assigned_to": "pt1",
95+
"subject": "1",
96+
"tag": {
97+
"id": "important",
98+
"label": "Critical, high priority"
99+
}
100+
}
101+
],
102+
"notes": [
103+
"PDF export works <b>very well</b>"
104+
]
105+
}
106+
```
107+
108+
## protoparser (protoml-parser)
109+
110+
`protoparser` is the command-line tool for parsing `.pml` files (ProtoML) and converting them into structured formats such as JSON, HTML, PDF and more.
111+
112+
### Basic Usage
113+
114+
```bash
115+
protparser [options] [filename] [format]
116+
```
117+
118+
#### Example
119+
120+
```bash
121+
protoparser -vvv -output=myfile MeetingYesterday.pml html
122+
```
123+
124+
### Output
125+
126+
```plaintext
127+
[INFO] Parsing file: MeetingYesterday.pml
128+
[DEBUG] Format selected: html
129+
[DEBUG] Filename: MeetingYesterday.html
130+
[DEBUG] Filename overwrite: myfile.html
131+
[DEBUG] Participants: @pt1: John Doe,jdoe,jdoe@example.com
132+
[DEBUG] Participants: @pt2: Jane Doe
133+
[DEBUG] IMPORTING TAGS
134+
[DEBUG] Importing tags from: tags.pml
135+
[DEBUG] Date: 21.05.2025
136+
...
137+
[INFO] DONE
138+
[INFO] Output written to: myfile.html
139+
```
140+
141+
### Available Options
142+
143+
| Flag | Description |
144+
| ---- | ----------- |
145+
| `-v`, `-vv`, `-vvv` | Verbosity levels: info, debug, trace |
146+
| `-output=FILENAME` | Define custom output file (without extension) |
147+
| `-strict` | Enable strict parsing (fail on missing refs) |
148+
| `-theme=name` | Set export theme (used in HTML/PDF) |
149+
| `-config=PATH` | Use external config for rendering/export |
150+
| `--help` | Show CLI help |
151+
152+
### Supported formats
153+
154+
- `json`
155+
- `html`
156+
- `pdf`
157+
- `markdown`
158+
- `text`
159+
160+
### Notes
161+
162+
- If no format is given, defaults to HTML
163+
- If no output is given, the filename (without extension) is used
164+
- Error and warnings are printed based on verbosity levels.
165+
166+
## What ProtoML is NOT (yet?)
167+
168+
- It it not a programming language
169+
- It does not include logic, loops or real variables
170+
- It is not intended to render HTML or provide full Markdown support
171+
172+
## What ProtoML IS
173+
174+
- A semantic markup for protocols, tasks, topics and notes
175+
- Extremely easy to read and write
176+
- Expandable via IDs and modular includes
177+
- Perfectly suited for Electron apps, PDF generators and structured JSON storage

0 commit comments

Comments
 (0)