Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings

Commit 64de48a

Browse files
Rewrite docs/reml.html
docs/reml.html now contains a brief overview of REML with some examples but links to documentation in the new delphidabbler/reml repository for a full language definition of REML v4.
1 parent 22bef01 commit 64de48a

File tree

1 file changed

+23
-169
lines changed

1 file changed

+23
-169
lines changed

‎docs/reml.html‎

Lines changed: 23 additions & 169 deletions
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)

AltStyle によって変換されたページ (->オリジナル) /