Skip to content

Commit 8d343c0

Browse files
author
delphidabbler
committed
Add documentation of REML file format
1 parent 0627b14 commit 8d343c0

File tree

1 file changed

+389
-0
lines changed

1 file changed

+389
-0
lines changed

‎Docs/Design/reml.html

Lines changed: 389 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,389 @@
1+
<!DOCTYPE HTML>
2+
3+
<!--
4+
* This file copyright (C) 2020, Peter Johnson (gravatar.com/delphidabbler) and
5+
* is licensed under the MIT License: https://opensource.org/licenses/MIT
6+
*
7+
* DelphiDabbler Code Snippets Database Documentation: REML markup language
8+
* documentation.
9+
-->
10+
<html lang="en">
11+
12+
<head>
13+
14+
<meta charset="UTF-8" />
15+
<meta http-equiv=X-UA-Compatible content="IE=edge">
16+
<meta name=viewport content="width=device-width,initial-scale=1">
17+
<!--[if lt IE 9]>
18+
<script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script>
19+
<script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
20+
<![endif]-->
21+
<meta name="author" content="Peter Johnson - https://en.gravatar.com/delphidabbler">
22+
<meta name="description" content="DelphiDabbler Code Snippets collection documentation - REML markup language">
23+
<style>
24+
body {
25+
font-family: "Segoe UI", Tahoma, Geneva, Helvetica, Arial, sans-serif;
26+
font-size: 13pt;
27+
font-weight: normal;
28+
margin: 1em 3em;
29+
padding: 0;
30+
line-height: 150%;
31+
background-color: white;
32+
color: #444444;
33+
}
34+
header {
35+
padding: 0;
36+
background-color: #f5f5f5;
37+
border-radius: 16px;
38+
border: 1px silver solid;
39+
display: block;
40+
}
41+
#title {
42+
font-size: 200%;
43+
font-weight: bold;
44+
text-align: center;
45+
margin: 0.5em;
46+
}
47+
48+
header nav {
49+
display: block;
50+
margin: 1em;
51+
font-weight: normal;
52+
font-size: 90%;
53+
}
54+
header nav ul {
55+
list-style: none;
56+
margin: 0;
57+
text-align: center;
58+
}
59+
header nav li {
60+
display: inline;
61+
}
62+
header nav a {
63+
text-decoration: none;
64+
white-space: nowrap;
65+
padding: 0.5em;
66+
}
67+
header nav a:hover {
68+
background-color: #eeeeee;
69+
}
70+
h1 {
71+
font-weight: bold;
72+
font-size: 200%;
73+
padding: 0 0 0.5em 0;
74+
margin: 1em 0;
75+
border-bottom: 1px silver solid;
76+
}
77+
h2 {
78+
font-weight: bold;
79+
font-size: 175%;
80+
padding: 0;
81+
margin: 0.75em 0;
82+
}
83+
aside {
84+
display: block;
85+
xfont-size: 100%;
86+
font-style: italic;
87+
padding: 0.25em 0.5em;
88+
margin: 0.75em 2em;
89+
border-left: 2px solid silver;
90+
border-right: 1px solid silver;
91+
border-top: 1px solid silver;
92+
border-bottom: 2px solid silver;
93+
border-radius: 6px;
94+
background-color: #f5f5f5;
95+
}
96+
aside code.value {
97+
background-color: #ddd;
98+
}
99+
p {
100+
font-size: 100%;
101+
padding: 0;
102+
margin: 0.75em 0;
103+
}
104+
pre, code {
105+
font-family: "Lucida Console", "Courier New", Courier, monospace;
106+
font-size: 90%;
107+
}
108+
pre.sample {
109+
margin: 0.75em 2em;
110+
background-color: #f5f5f5;
111+
padding: 0.5em;
112+
}
113+
code.key, code.value {
114+
background-color: #f5f5f5;
115+
padding: 1px 4px;
116+
}
117+
code.key {
118+
font-weight: bold;
119+
font-style: none;
120+
}
121+
code.value {
122+
font-style: normal;
123+
}
124+
ul {
125+
font-size: 100%;
126+
padding: 0;
127+
margin: 0.75em 0 0.75em 2em;
128+
}
129+
ul ul {
130+
margin: 0.25em 0 0.25em 2em;
131+
}
132+
li {
133+
padding: 0;
134+
margin: 0.75em 0;
135+
}
136+
li li, li div {
137+
margin: 0.25em 0;
138+
}
139+
ul.half-spaced li {
140+
margin: 0.4em 0;
141+
}
142+
ul.unspaced li {
143+
margin: 0;
144+
}
145+
.very-strong {
146+
xtext-transform: uppercase;
147+
font-variant: small-caps;
148+
font-weight: bold;
149+
}
150+
dt {
151+
margin: 0;
152+
padding: 0;
153+
font-weight: inherited;
154+
}
155+
dd {
156+
margin: 0 0 0 2em;
157+
padding: 0;
158+
font-weight: normal;
159+
}
160+
a {
161+
color: rgb(46, 46, 192);
162+
}
163+
section {
164+
display: block;
165+
margin: 2em 0 2em 0;
166+
padding: 1em;
167+
background-color: transparent;
168+
border-radius: 16px;
169+
border: 1px silver solid;
170+
}
171+
section h1 {
172+
margin-top: 0;
173+
margin-bottom: 0.5em;
174+
}
175+
</style>
176+
177+
<title>
178+
REML Documentation
179+
</title>
180+
181+
</head>
182+
183+
<body>
184+
185+
<header>
186+
187+
<div id="title">
188+
<p>
189+
REML Markup Language
190+
</p>
191+
</div>
192+
193+
<nav id="contents">
194+
<ul>
195+
<li>
196+
<a href="#intro">Introduction</a>
197+
</li>
198+
<li>
199+
<a href="#tags">Tags</a>
200+
</li>
201+
<li>
202+
<a href="#entities">Character Entities</a>
203+
</li>
204+
</ul>
205+
</nav>
206+
207+
</header>
208+
209+
<section id="intro">
210+
211+
<h1>
212+
Introduction
213+
</h1>
214+
215+
<p>
216+
REML is a little markup language that can be used to style text. It is used in Code Snippets collection meta data for certain properties of a snippet.
217+
</p>
218+
<p>
219+
The REML language is a SGML language similar to a greatly simplified XHTML. The are a small number of tags and character entities that can be used.
220+
</p>
221+
<aside>
222+
<strong>Note:</strong> The language described here is REML v4. Earlier versions are obsolete.
223+
</aside>
224+
225+
</section>
226+
227+
<section id="tags">
228+
229+
<h1>
230+
Tags
231+
</h1>
232+
233+
<p>
234+
There are two types of tags: block level and in-line.
235+
</p>
236+
237+
<p>
238+
If an unrecognised tag is encountered an REML code the interpreter <em>should</em> report an error. However, providing start and end tags are matched, the interpreter <em>may</em> choose to simply ignore the tags.
239+
</p>
240+
241+
<h2>
242+
Block Level Tags
243+
</h2>
244+
245+
<p>
246+
Block level tags separate the enclosed text into paragraphs of some description. The supported tags are:
247+
</p>
248+
<ul class="half-spaced">
249+
<li>
250+
<code class="value">&lt;p&gt;...&lt;/p&gt;</code> &ndash; Renders the enclosed markup as a simple paragraph.
251+
</li>
252+
<li>
253+
<code class="value">&lt;heading&gt;...&lt;/heading&gt;</code> &ndash; Renders the enclosed markup as a heading.
254+
</li>
255+
</ul>
256+
<p>
257+
The following rules apply to the use of block level tags:
258+
</p>
259+
<ul class="unspaced">
260+
<li>
261+
The tags <span class="very-strong">must not</span> be nested.
262+
</li>
263+
<li>
264+
The tags <span class="very-strong">must</span> be matched, e.g. <code class="value">&lt;p&gt;</code> must have a matching <code class="value">&lt;/p&gt;</code>.
265+
</li>
266+
<li>
267+
All text <em>should</em> be embedded within block level tags, e.g. <code class="value">&lt;heading&gt;heading&lt;/heading&gt;&lt;p&gt;text&lt;/p&gt;</code> or simply <code class="value">&lt;p&gt;text&lt;/p&gt;</code>.
268+
</li>
269+
<li>
270+
White space between blocks <span class="very-strong">must</span> be ignored.
271+
</li>
272+
</ul>
273+
<p>
274+
Here is a valid example:
275+
</p>
276+
<pre class="sample">&lt;p&gt;Hello World&lt;/p&gt;
277+
&lt;heading&gt;Hello&lt;/heading&gt;
278+
&lt;p&gt;Hello World&lt;/p&gt;</pre>
279+
<p>
280+
Strictly speaking, the following example is invalid code &ndash; all occurrences of <code class="value">wrong</code> are in error because they are not contained within block tags.
281+
</p>
282+
<pre class="sample">wrong &lt;heading&gt;blah&lt;/heading&gt; wrong &lt;p&gt;blah&lt;/p&gt; wrong</pre>
283+
<p>
284+
However interpreting code <em>may</em> interpret this permissively. If this is done the text outside blocks <span class="very-strong">must</span> be interpreted as if it was enclosed in <code class="value">&lt;p&gt;</code> and <code class="value">&lt;/p&gt;</code> tags. Therefore the above code would be interpreted as:
285+
</p>
286+
<pre class="sample">&lt;p&gt;wrong &lt;/p&gt;&lt;heading&gt;blah&lt;/heading&gt;&lt;p&gt;wrong &lt;/p&gt;&lt;p&gt;blah&lt;/p&gt;&lt;p&gt;wrong&lt;/p&gt;</pre>
287+
<aside>
288+
<strong>Note:</strong> Code Snippets Database collections <em>may</em> contain such non-conforming REML. Therefore interpreters of REML that need to accept such collections <span class="very-strong">must</span> be able to handle text without enclosing block tags.
289+
</aside>
290+
291+
<h2>
292+
Inline Tags
293+
</h2>
294+
295+
<p>
296+
In-line tags format the text enclosed between the start and end tags.
297+
</p>
298+
<p>
299+
Here are the available in-line tags:
300+
</p>
301+
<ul class="half-spaced">
302+
<li>
303+
<code class="value">&lt;strong&gt;...&lt;/strong&gt;</code> &ndash; Renders the enclosed markup with strong emphasis.
304+
</li>
305+
<li>
306+
<code class="value">&lt;em&gt;...&lt;/em&gt;</code> &ndash; Emphasises the enclosed markup.
307+
</li>
308+
<li>
309+
<code class="value">&lt;var&gt;...&lt;/var&gt;</code> &ndash; Used to indicate the enclosed markup is a variable.
310+
</li>
311+
<li>
312+
<code class="value">&lt;warning&gt;...&lt;/warning&gt;</code> &ndash; Used for warning text.
313+
</li>
314+
<li>
315+
<code class="value">&lt;mono&gt;...&lt;/mono&gt;</code> &ndash; Renders markup in a mono-spaced font.
316+
</li>
317+
<li>
318+
<code class="value">&lt;a href="url"&gt;...&lt;/a&gt;</code> &ndash; Creates a hyper-link. The <code class="value">href</code> attribute <span class="very-strong">must</span> specify the required URL, which <span class="very-strong">must</span> use one of the <code class="value">http</code>, <code class="value">https</code> or <code class="value">file</code> protocols; others are not permitted. If you use the <code class="value">file</code> protocol it <span class="very-strong">must</span> reference a valid local or network file.
319+
</li>
320+
</ul>
321+
<p>
322+
The following rules apply to the use of in-line tags:
323+
</p>
324+
<ul class="unspaced">
325+
<li>
326+
In-line tags <span class="very-strong">must</span> be embedded inside a block level tag. E.g. <code class="value">&lt;p&gt;one&lt;strong&gt;two&lt;/strong&gt;three&lt;/p&gt;</code>.
327+
</li>
328+
<li>
329+
Tags <span class="very-strong">must</span> match. E.g. <code class="value">&lt;em&gt;</code> must be matched with <code class="value">&lt;/em&gt;</code>.
330+
</li>
331+
<li>
332+
Tags may be nested, providing the tags match. E.g. <code class="value">&lt;em&gt;blah &lt;var&gt;blah&lt;/var&gt;&lt;/em&gt;</code> is valid but <code class="value">&lt;em&gt;blah &lt;var&gt;blah&lt;/em&gt;&lt;/var&gt;</code> is not.
333+
</li>
334+
</ul>
335+
<p>
336+
Examples:
337+
</p>
338+
<pre class="sample">&lt;p&gt;Make stuff &lt;strong&gt;stand out&lt;/strong&gt;.&lt;/p&gt;
339+
&lt;p&gt;&lt;em&gt;Emphasised &lt;warning&gt;warning!&lt;/warning&gt;&lt;/em&gt;&lt;/p&gt;
340+
&lt;p&gt;Refer to a function &lt;var&gt;parameter&lt;/var&gt;.&lt;/p&gt;
341+
&lt;p&gt;Use the: &lt;mono&gt;Windows&lt;/mono&gt; unit.&lt;/p&gt;
342+
&lt;p&gt;See this &lt;a href="http://example.com"&gt;example&lt;/a&gt;.&lt;/p&gt;</pre>
343+
344+
</section>
345+
346+
<section id="entities">
347+
348+
<h1>
349+
Character Entities
350+
</h1>
351+
352+
<p>
353+
A few symbolic character entities are supported in REML. Here is the complete list:
354+
</p>
355+
<ul class="half-spaced">
356+
<li>
357+
<code class="value">&amp;lt;</code> for <code class="value">&lt;</code>
358+
</li>
359+
<li>
360+
<code class="value">&amp;gt;</code> for <code class="value">&gt;</code>
361+
</li>
362+
<li>
363+
<code class="value">&amp;quot;</code> for <code class="value">&quot;</code>
364+
</li>
365+
<li>
366+
<code class="value">&amp;amp;</code> for <code class="value">&amp;</code>
367+
</li>
368+
<li>
369+
<code class="value">&amp;copy;</code> for <code class="value">&copy;</code>
370+
</li>
371+
</ul>
372+
373+
<aside>
374+
<strong>Note:</strong> the '&lt;' and '&amp;' characters are special within the markup and cannot be used literally, even when you are just entering plain text. You <span class="very-strong">must</span> use the <code class="value">&amp;lt;</code> character entity in place of <code class="value">&lt;</code> and <code class="value">&amp;amp;</code> instead of <code class="value">&amp;</code>. For example to write <code class="value">x&lt;y</code> in REML use <code class="value">x&amp;lt;y</code> and to write <code class="value">you &amp; me</code> use <code class="value">you &amp;amp; me</code>.
375+
</aside>
376+
377+
<p>
378+
To express other special symbols for which there is no symbolic character entity, numeric character entities can be used. For example to display the '¶' character (Unicode <em>pilcrow sign</em>) use <code class="value">&amp;#182;</code>.
379+
</p>
380+
381+
<aside>
382+
<strong>Note:</strong> Numeric entities should be used with caution because the characters they represent may vary across different text encodings, whereas symbolic entities are safe across encodings.
383+
</aside>
384+
385+
</section>
386+
387+
</body>
388+
389+
</html>

0 commit comments

Comments
 (0)