fml 0.1.0

Friendly Markup Language
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
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287

<style>
code {
	white-space: pre;
}
</style>

# Friendly Markup Language
Friendly Markup Language, abbreviated as _lowercase_ fml.

Inspired by Markdown, its main goals are minimalism,
expressiveness and compatibility with both web and non-web targets.\
Purpose-made for the Starling communication protocol.

Friendly Markup Language and its specification are licensed under the
[Creative Commons Attribution-ShareAlike 4.0 International Public License](fml_LICENSE.txt).\
This crate's source code is licensed under the [GNU Affero General Public License](src/code_LICENSE.md).

## Crate state
This crate uses [semantic versioning](https://semver.org/spec/v1.0.0.html),
and as such it is currently **in development**, not having yet reached its 1.0 release.\
This means that right now, anything can change at any time.

Things left to do:
- [ ] Write a more thorough specification
- [ ] Finalize AST
- [ ] Finish writing the parser crate feature
	- [ ] Add parser test cases
- [ ] Add HTML render crate feature

### Why not use Markdown?

Full HTML+CSS allows for a *lot* of customizability,
forcing developers of non-web frontends to pick which elements and style properties will be implemented
in a round-about way, and which will be omitted and not rendered.\
In short, its scope is beyond what a lot of environments allow or need.

Additionally, from a user-perspective, having to write an HTML element with CSS style properties by hand
to achieve basic styling is a lot of work. This is something fml tries to address.

## Concepts

### No token overlapping

fml expects well-formed, properly-nested elements.

### Non-emptiness of token bodies.

The body of each token must not be empty.\
If the body is empty, the token syntax will be interpreted as plaintext, and the function syntax will not be used.

What non-emptiness means:
- For tokens written in syntax which need to be terminated with itself, this there must be 1 or more non-whitespace, non-fml-token symbols present in-between the two tokens, or in the case of the Code styles: 1 or more symbols, whitespace allowed (` ` is valid.).\
- For all other tokens, this means there must be 1 or more non-whitespace, non-fml-token symbols after the token.

### Definitions

**Content**
: any isolated sequence of text, for example: a file or one message.

**Section**
: a section starts either at the first non-whitespace glyph of the first non-blank line either at the start
of the content or after the last section has ended.\
A section lasts either until a blank line is found, or until the content ends.\
The blank line in-between the end of one section and the beginning of another is preserved during processing and display.\
Naturally, line-breaks (those created by carriage-return) and leading whitespace inside of a section
are both preserved during processing and display.

<!-- **Token and Function syntaxes**
: The _token syntax_ is what you might be accustomed to when coming from Markdown.\
Here it means using common characters like `*` or `_` as tokens to apply styling to text around them.\
_Function syntax_ is an uncertified fml original, it can be divided into: the function name, the parameters
and the body containing fml to which the function's style will be applied.\
Example: `#functionName<ParameterString>{Fml Body}`, or `#noParameterFn{ Inner Fml }`\
Don't worry, as you'll find out it's pretty intuitive and not scary at all. -->

### Code-block interpretation
#### fml tokens as plaintext
Inside of both Code styles, all fml tokens are interpreted as plaintext with two exceptions.

1. The first exception is the ending of the code style. If the closing backticks match the amount
needed to close the style (1 for Inline and 3 for Block), they will be interpreted as an fml token
and will terminate the style.

2. The second exception is preventing an unwanted termination by escaping one of the backticks
with the escape token. For this purpose, the backslash character will only be interpreted as an fml token
if it directly precedes a backtick.

<!-- #### Handling whitespace
If **all** lines of a codeblock share a common amount of leading indentation, that amount will be trimmed
during processing.\
Otherwise, whitespace is preserved. -->


## fml tokens

### Constraints

Constraints for each token are defined in the footnotes linked to each fml token cell.

### The exhaustive list of mandatory fml tokens

<table>
	<tr>
		<th>Style</th>
		<th>fml token</th>
		<th>fml function</th>
		<th>Example</th>
	</tr>
	<tr>
		<td>
			<h3>Headings [1,3]</h3>
		</td>
		<td>Hashtags ranging from <code># </code> to <code>### </code></td>
		<td></td>
		<td><code># I am heading 1</code></td>
	</tr>
	<tr>
		<td><strong>Bold</strong></td>
		<td><code>*</code></td>
		<td></td>
		<td><code>*bold text*</code></td>
	</tr>
	<tr>
		<td><i>Italic</i></td>
		<td><code>_</code></td>
		<td></td>
		<td><code>_Uwa!!_</code></td>
	</tr>
	<tr>
		<td><s>Strikethrough</s></td>
		<td><code>~</code></td>
		<td></td>
		<td><code>~This text got cancelled~</code></td>
	</tr>
	<tr>
		<td>
			<p style="text-decoration: underline;">Underline</p>
		</td>
		<td><code>__</code></td>
		<td></td>
		<td><code>__Especially, the don't!__</code></td>
	</tr>
	<tr>
		<td>
			<sup>Superscript</sup>
		</td>
		<td>
			<code>#^ </code> lasts until line-break, can be extended with a trailing <code>\</code>
		</td>
		<td>
			<code>^{}</code>
		</td>
		<td>
			<code>#^ up high</code><br>
			<code>σ^{2}</code>
		</td>
	</tr>
	<tr>
		<td>
			<sup>Subscript</sup>
		</td>
		<td>
			<code>#! </code> or <code>#_ </code>, lasts until line-break, can be extended with a trailing
			<code>\</code>
		</td>
		<td>
			<code>_{}</code>
		</td>
		<td>
			<code>#! down low</code><br>
			<code>NH_{3}</code>
		</td>
	</tr>
	<tr>
		<td>
			<li>List item</li>
		</td>
		<td>
			<code>- </code> lasts until line-break, can be extended with a trailing <code>\</code>
		</td>
		<td><code>#li{}</code></td>
		<td>
			<code>- Bag of milk</code><br>
			<code>#li{inside a bag of milk}</code>
		</td>
	</tr>
	<tr>
		<td>
			<blockquote>Quote</blockquote>
		</td>
		<td>
			<code>> </code> lasts until line-break, can be extended with a trailing <code>\</code>
		</td>
		<td><code>#quo{}</code><br></td>
		<td>
			<code>> Simplicity is prerequisite for reliability.</code><br>
			<code>#quo{#quo{one sick} nested quote}</code>
		</td>
	</tr>
	<tr>
		<td>Content warning</td>
		<td>
			<code>|</code> defaults the reason to "Spoilers"
		</td>
		<td>
			<code>#cw<<!--  -->reason>{}</code>
		</td>
		<td>
			<code>|Orpheus turns around|</code><br>
			<code>#cw<<!--  -->vent>{billionaires are boiling the planet still :(}</code>
		</td>
	</tr>
	<tr>
		<td>
			<code>Inline code</code>
		</td>
		<td>
			<code>`</code>
		</td>
		<td></td>
		<td>
			<code>`Arc::new(420);`</code>
		</td>
	</tr>
	<tr>
		<td>
			<a href="https://en.wikipedia.org/wiki/Hyperlink">Hyperlink</a>
		</td>
		<td>
			<code>[]()</code> text goes into the square brackets and the URI goes into the parentheses.
		</td>
		<td></td>
		<td>
			<code>[It's you!](http://127.0.0.1)</code><br>
		</td>
	</tr>
	<tr>
		<td>
			<p style="color: #7FFFD4">Foreground Color</p>
		</td>
		<td></td>
		<td>
			<code>#color<<!--  -->PARAM>{}</code>, or <code>#fg<<!--  -->PARAM>{}</code> for short.
			<code>PARAM</code> is either a case-insensitive joined
			<a href="https://www.w3schools.com/colors/colors_names.asp">HTML color name</a>
			or a six-digit hexadecimal encoding of the color's RRGGBB values with a leading <code>0x</code>
		</td>
		<td>
			<code>#color<<!--  -->darkblue>{blue text that}</code><br>
			<code>#fg<<!--  -->0x4169E1>{lightens up}</code>
		</td>
	</tr>
	<tr>
		<td>
			<p style="background-color: #047e55">Background Color</p>
		</td>
		<td></td>
		<td>
			<code>#bg<<!--  -->PARAM>{}</code>
			<code>PARAM</code> is either a case-insensitive joined
			<a href="https://www.w3schools.com/colors/colors_names.asp">HTML color name</a>
			or a six-digit hexadecimal encoding of the color's RRGGBB values with a leading <code>0x</code>
		</td>
		<td>
			<code>#bg<<!--  -->red>{angry text}</code><br>
		</td>
	</tr>
	<tr>
		<td>Escape</td>
		<td><code>\</code> makes the glyph to its right be interpreted as plaintext.</td>
		<td></td>
		<td>
			<code>\*surrounded by stars.. (not bold text!)*</code><br>
			<code>*\** <- a bold asterisk</code><br>
			<code>\#color<<!--  -->0x00FF00>{not a function call!}</code>
		</td>
	</tr>
</table>

### fml tokens optional for implementation:

| Optional style | fml token | Example |
| ---------------| --------- | ------- |
| Typst block | `$` | `$"area" = pi dot "radius"^2$` |

Since, unlike LaTeX, typst is rather human-readable, it shouldn't be too much of a compromise to allow
some implementations to render typst as plain-text surrounded with `$` signs, letting other implementations  compile and render it properly.