Skip to content

Commit bd620a2

Browse files
delphidabblerdelphidabbler
committed
Merge branch 'feature/24-update-reml-docs' into develop
2 parents 22bef01 + 405bfe7 commit bd620a2

File tree

2 files changed

+25
-171
lines changed

2 files changed

+25
-171
lines changed

‎docs/collection-format.html

+2-2
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
<!DOCTYPE HTML>
22

33
<!--
4-
* This file copyright (C) 2020-2023, Peter Johnson (gravatar.com/delphidabbler)
4+
* This file copyright (C) 2020-2024, Peter Johnson (gravatar.com/delphidabbler)
55
* and is licensed under the MIT License: https://opensource.org/licenses/MIT
66
*
77
* DelphiDabbler Code Snippets Database Documentation: Collection file format
@@ -869,7 +869,7 @@ <h1>
869869
<ol>
870870
<li id="footnote-1">
871871
<p>
872-
REML is a text markup language used to format text. REML version 4 is supported. The REML format is documented in <a href="reml.html">reml.html</a>.
872+
REML is a text markup language used to format text. REML version 4 is supported. For more information see <a href="reml.html">reml.html</a>.
873873
</p>
874874
</li>
875875
<li id="footnote-2">

‎docs/reml.html

+23-169
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
<!DOCTYPE HTML>
22

33
<!--
4-
* This file copyright (C) 2020-2023, Peter Johnson (gravatar.com/delphidabbler)
4+
* This file copyright (C) 2020-2024, Peter Johnson (gravatar.com/delphidabbler)
55
* and is licensed under the MIT License: https://opensource.org/licenses/MIT
66
*
77
* DelphiDabbler Code Snippets Database Documentation: REML markup language
@@ -41,210 +41,64 @@
4141
</div>
4242
</div>
4343

44-
<nav id="contents">
45-
<ul>
46-
<li>
47-
<a href="#intro">Introduction</a>
48-
</li>
49-
<li>
50-
<a href="#tags">Tags</a>
51-
</li>
52-
<li>
53-
<a href="#entities">Character Entities</a>
54-
</li>
55-
</ul>
56-
</nav>
57-
5844
</header>
5945

60-
<section id="intro">
46+
<section id="about">
6147

6248
<h1>
63-
Introduction
49+
About REML
6450
</h1>
6551

6652
<p>
6753
REML is a little markup language that can be used to style text. It is used in the Code Snippets collection's meta data for certain properties of a snippet.
6854
</p>
69-
<p>
70-
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.
71-
</p>
72-
<aside>
73-
<strong>Note:</strong> The language described here is REML v4. Earlier versions are obsolete.
74-
</aside>
75-
76-
</section>
77-
78-
<section id="tags">
79-
80-
<h1>
81-
Tags
82-
</h1>
8355

8456
<p>
85-
There are two types of tags: block level and in-line.
57+
REML is a SGML language similar to HTML, albeit much smaller. A small number of tags and character entities are supported.
8658
</p>
8759

8860
<p>
89-
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.
61+
This collection supports REML v4. Earlier versions are obsolete.
62+
See the <a href="https://htmlpreview.github.io/?https://raw.githubusercontent.com/delphidabbler/reml/main/docs/reml-v4.html">REML v4 language definition</a> from the <a href="https://github.com/delphidabbler/reml"><code>delphidabbler/reml</code></a> repository for full details.
9063
</p>
9164

92-
<h2>
93-
Block Level Tags
94-
</h2>
95-
96-
<p>
97-
Block level tags separate the enclosed text into paragraphs of some description. The supported tags are:
98-
</p>
99-
<ul class="half-spaced">
100-
<li>
101-
<code class="value">&lt;p&gt;...&lt;/p&gt;</code> &ndash; Renders the enclosed markup as a simple paragraph.
102-
</li>
103-
<li>
104-
<code class="value">&lt;heading&gt;...&lt;/heading&gt;</code> &ndash; Renders the enclosed markup as a heading.
105-
</li>
106-
</ul>
107-
<p>
108-
The following rules apply to the use of block level tags:
109-
</p>
110-
<ul class="unspaced">
111-
<li>
112-
The tags <span class="very-strong">must not</span> be nested.
113-
</li>
114-
<li>
115-
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>.
116-
</li>
117-
<li>
118-
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>.
119-
</li>
120-
<li>
121-
White space between blocks is permitted but <span class="very-strong">must</span> be ignored.
122-
</li>
123-
</ul>
124-
<p>
125-
Here is a valid example:
126-
</p>
127-
<pre class="sample">&lt;heading&gt;Hello&lt;/heading&gt;
128-
&lt;p&gt;Hello World&lt;/p&gt;</pre>
129-
<p>
130-
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.
131-
</p>
132-
<pre class="sample">wrong &lt;heading&gt;blah&lt;/heading&gt; wrong &lt;p&gt;blah&lt;/p&gt; wrong</pre>
133-
<p>
134-
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:
135-
</p>
136-
<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>
13765
<aside>
13866
<p>
139-
<p>
140-
<strong>Note</strong>
141-
</p>
142-
<p>
143-
The Code Snippets Database collection v2.0.x contains such non-conforming REML. Therefore REML interpreters designed for use with that version of the collection <span class="very-strong">must</span> be able to handle text without enclosing block tags.
144-
</p>
67+
Before v2.1.0 of the collection, not all REML content was fully compliant with the specification: some text did not have enclosing block tags. Any REML interpreter designed to work with those versions <span class="very-strong">must</span> handle such text &quot;permissively&quot; as described in the language definition.
14568
</p>
14669
<p>
147-
From v2.1.0 of the collection all REML is fully conformant and REML interpreters designed only for v2.1.0 or later are <span class="very-strong">not required</span> to handle text with enclosing tags.
70+
From v2.1.0 the collection is fully compliant with the REML specification. Any interpreters that only need to handle v2.1.0 and later are <span class="very-strong">not required</span> to handle text outside enclosing tags.
14871
</p>
14972
</aside>
15073

151-
<h2>
152-
Inline Tags
153-
</h2>
154-
155-
<p>
156-
In-line tags format the text enclosed between the start and end tags.
157-
</p>
158-
<p>
159-
Here are the available in-line tags:
160-
</p>
161-
<ul class="half-spaced">
162-
<li>
163-
<code class="value">&lt;strong&gt;...&lt;/strong&gt;</code> &ndash; Renders the enclosed markup with strong emphasis.
164-
</li>
165-
<li>
166-
<code class="value">&lt;em&gt;...&lt;/em&gt;</code> &ndash; Emphasises the enclosed markup.
167-
</li>
168-
<li>
169-
<code class="value">&lt;var&gt;...&lt;/var&gt;</code> &ndash; Used to indicate the enclosed markup is a variable.
170-
</li>
171-
<li>
172-
<code class="value">&lt;warning&gt;...&lt;/warning&gt;</code> &ndash; Used for warning text.
173-
</li>
174-
<li>
175-
<code class="value">&lt;mono&gt;...&lt;/mono&gt;</code> &ndash; Renders markup in a mono-spaced font.
176-
</li>
177-
<li>
178-
<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.
179-
</li>
180-
</ul>
181-
<p>
182-
The following rules apply to the use of in-line tags:
183-
</p>
184-
<ul class="unspaced">
185-
<li>
186-
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>. However those REML interpreters that allow for the omission of some block level tags relax this restriction (see above).
187-
</li>
188-
<li>
189-
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>.
190-
</li>
191-
<li>
192-
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.
193-
</li>
194-
</ul>
195-
<p>
196-
Examples:
197-
</p>
198-
<pre class="sample">&lt;p&gt;Make stuff &lt;strong&gt;stand out&lt;/strong&gt;.&lt;/p&gt;
199-
&lt;p&gt;&lt;em&gt;Emphasised &lt;warning&gt;warning!&lt;/warning&gt;&lt;/em&gt;&lt;/p&gt;
200-
&lt;p&gt;Refer to a function &lt;var&gt;parameter&lt;/var&gt;.&lt;/p&gt;
201-
&lt;p&gt;Use the: &lt;mono&gt;Windows&lt;/mono&gt; unit.&lt;/p&gt;
202-
&lt;p&gt;See this &lt;a href="http://example.com"&gt;example&lt;/a&gt;.&lt;/p&gt;</pre>
203-
20474
</section>
20575

206-
<section id="entities">
76+
<section id="examples">
20777

20878
<h1>
209-
Character Entities
79+
Examples
21080
</h1>
21181

21282
<p>
213-
A few symbolic character entities are supported in REML. Here is the complete list:
83+
Here are some examples of valid REML markup.
21484
</p>
215-
<ul class="half-spaced">
216-
<li>
217-
<code class="value">&amp;lt;</code> for <code class="value">&lt;</code>
218-
</li>
219-
<li>
220-
<code class="value">&amp;gt;</code> for <code class="value">&gt;</code>
221-
</li>
222-
<li>
223-
<code class="value">&amp;quot;</code> for <code class="value">&quot;</code>
224-
</li>
225-
<li>
226-
<code class="value">&amp;amp;</code> for <code class="value">&amp;</code>
227-
</li>
228-
<li>
229-
<code class="value">&amp;copy;</code> for <code class="value">&copy;</code>
230-
</li>
231-
</ul>
23285

233-
<aside>
234-
<strong>Note:</strong> the '&lt;' and '&amp;' characters are special within the markup and cannot be used literally. 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>.
235-
</aside>
86+
<pre class="sample">&lt;heading&gt;Hello&lt;/heading&gt;
87+
&lt;p&gt;Hello World&lt;/p&gt;</pre>
88+
89+
<pre class="sample">&lt;p&gt;Make stuff &lt;strong&gt;stand out&lt;/strong&gt;.&lt;/p&gt;</pre>
23690

237-
<p>
238-
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>.
239-
</p>
91+
<pre class="sample">&lt;p&gt;&lt;em&gt;Emphasised &lt;warning&gt;warning!&lt;/warning&gt;&lt;/em&gt;&lt;/p&gt;</pre>
24092

241-
<aside>
242-
<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.
243-
</aside>
93+
<pre class="sample">&lt;p&gt;Refer to a function &lt;var&gt;parameter&lt;/var&gt;.&lt;/p&gt;</pre>
24494

245-
</section>
95+
<pre class="sample">&lt;p&gt;Use the: &lt;mono&gt;Windows&lt;/mono&gt; unit.&lt;/p&gt;</pre>
96+
97+
<pre class="sample">&lt;p&gt;See this &lt;a href="http://example.com"&gt;example&lt;/a&gt;.&lt;/p&gt;</pre>
24698

247-
<footer />
99+
<pre class="sample">&lt;p&gt;Sometimes &amp;quot;character entities&amp;quot; are needed.&lt;/p&gt;</pre>
100+
101+
</section>
248102

249103
</body>
250104

0 commit comments

Comments
 (0)