Skip to content
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.

Commit a512877

Browse files
committedApr 10, 2024
Merge branch 'feature/133-update-docs-re-new-reml-repo' into develop
2 parents 6d7a992 + fca862c commit a512877

File tree

3 files changed

+67
-857
lines changed

3 files changed

+67
-857
lines changed
 

‎Docs/Design/reml.html

Lines changed: 20 additions & 517 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@
1919
<script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
2020
<![endif]-->
2121
<meta name="author" content="Peter Johnson - https://en.gravatar.com/delphidabbler">
22-
<meta name="description" content="DelphiDabbler Code Snippets collection documentation - REML markup language">
22+
<meta name="description" content="DelphiDabbler Code Snippets documentation - REML markup language">
2323
<style>
2424
body {
2525
font-family: "Segoe UI", Tahoma, Geneva, Helvetica, Arial, sans-serif;
@@ -44,28 +44,6 @@
4444
text-align: center;
4545
margin: 0.5em;
4646
}
47-
header nav {
48-
display: block;
49-
margin: 1em;
50-
font-weight: normal;
51-
font-size: 90%;
52-
}
53-
header nav ul {
54-
list-style: none;
55-
margin: 0;
56-
text-align: center;
57-
}
58-
header nav li {
59-
display: inline;
60-
}
61-
header nav a {
62-
text-decoration: none;
63-
white-space: nowrap;
64-
padding: 0.5em;
65-
}
66-
header nav a:hover {
67-
background-color: #eeeeee;
68-
}
6947
h1 {
7048
font-weight: bold;
7149
font-size: 200%;
@@ -79,47 +57,11 @@
7957
padding: 0;
8058
margin: 0.75em 0;
8159
}
82-
aside {
83-
display: block;
84-
xfont-size: 100%;
85-
font-style: italic;
86-
padding: 0.25em 0.5em;
87-
margin: 0.75em 2em;
88-
border-left: 2px solid silver;
89-
border-right: 1px solid silver;
90-
border-top: 1px solid silver;
91-
border-bottom: 2px solid silver;
92-
border-radius: 6px;
93-
background-color: #f5f5f5;
94-
}
95-
aside code.value {
96-
background-color: #ddd;
97-
}
9860
p {
9961
font-size: 100%;
10062
padding: 0;
10163
margin: 0.75em 0;
10264
}
103-
pre, code {
104-
font-family: "Lucida Console", "Courier New", Courier, monospace;
105-
font-size: 90%;
106-
}
107-
pre.sample {
108-
margin: 0.75em 2em;
109-
background-color: #f5f5f5;
110-
padding: 0.5em;
111-
}
112-
code.key, code.value {
113-
background-color: #f5f5f5;
114-
padding: 1px 4px;
115-
}
116-
code.key {
117-
font-weight: bold;
118-
font-style: none;
119-
}
120-
code.value {
121-
font-style: normal;
122-
}
12365
ul {
12466
font-size: 100%;
12567
padding: 0;
@@ -141,21 +83,6 @@
14183
ul.unspaced li {
14284
margin: 0;
14385
}
144-
.very-strong {
145-
xtext-transform: uppercase;
146-
font-variant: small-caps;
147-
font-weight: bold;
148-
}
149-
dt {
150-
margin: 0;
151-
padding: 0;
152-
font-weight: bold;
153-
}
154-
dd {
155-
margin: 0 0 0 2em;
156-
padding: 0;
157-
font-weight: normal;
158-
}
15986
a {
16087
color: rgb(46, 46, 192);
16188
}
@@ -171,36 +98,6 @@
17198
margin-top: 0;
17299
margin-bottom: 0.5em;
173100
}
174-
table {
175-
border-collapse: collapse;
176-
}
177-
tr {
178-
border-bottom: 1px silver solid;
179-
}
180-
th {
181-
text-align: center;
182-
font-weight: bold;
183-
margin: 0;
184-
padding: 0;
185-
border-bottom: 2px silver solid;
186-
}
187-
td {
188-
border-bottom: 1px silver solid;
189-
margin: 0;
190-
padding: 0;
191-
}
192-
td, th {
193-
padding: 0.5em;
194-
}
195-
td:first-child, th:first-child {
196-
border-right: 1px silver solid;
197-
}
198-
td:last-child {
199-
text-align: center;
200-
}
201-
tr:nth-child(even), th {
202-
background-color: #eee;
203-
}
204101
</style>
205102

206103
<title>
@@ -219,450 +116,56 @@
219116
</p>
220117
</div>
221118

222-
<nav id="contents">
223-
<ul>
224-
<li>
225-
<a href="#intro">Introduction</a>
226-
</li>
227-
<li>
228-
<a href="#tags">Tags</a>
229-
</li>
230-
<li>
231-
<a href="#entities">Character Entities</a>
232-
</li>
233-
<li>
234-
<a href="#changes">Change Log</a>
235-
</li>
236-
</ul>
237-
</nav>
238-
239119
</header>
240120

241-
<section id="intro">
242-
243-
<h1>
244-
Introduction
245-
</h1>
246-
247-
<p>
248-
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.
249-
</p>
250-
<p>
251-
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.
252-
</p>
253-
<aside>
254-
<strong>Note:</strong> The language described here is REML v6. v4 is still in regular use in CodeSnip up to v4.20.x. Earlier versions are obsolete.
255-
</aside>
256-
257-
</section>
121+
<main>
258122

259-
<section id="tags">
123+
<section id="intro">
260124

261125
<h1>
262-
Tags
126+
About REML
263127
</h1>
264128

265129
<p>
266-
There are two types of tags: block level and in-line.
267-
</p>
268-
269-
<p>
270-
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.
271-
</p>
272-
273-
<h2>
274-
Block Level Tags
275-
</h2>
276-
277-
<p>
278-
Block level tags separate the enclosed text into paragraphs of some description. The supported tags are:
279-
</p>
280-
<ul class="half-spaced">
281-
<li>
282-
<code class="value">&lt;p&gt;...&lt;/p&gt;</code> &ndash; Renders the enclosed markup as a simple paragraph.
283-
</li>
284-
<li>
285-
<code class="value">&lt;heading&gt;...&lt;/heading&gt;</code> &ndash; Renders the enclosed markup as a heading.
286-
</li>
287-
<li>
288-
<code class="value">&lt;ol&gt;...&lt;/ol&gt;</code> &ndash; Renders the enclosed markup as an ordered list.
289-
</li>
290-
<li>
291-
<code class="value">&lt;ul&gt;...&lt;/ul&gt;</code> &ndash; Renders the enclosed markup as an unordered list.
292-
</li>
293-
<li>
294-
<code class="value">&lt;li&gt;...&lt;/li&gt;</code> &ndash; Renders the enclosed markup as a list item.
295-
</li>
296-
</ul>
297-
<p>
298-
The following rules apply to the use of block level tags:
299-
</p>
300-
<ul class="unspaced">
301-
<li>
302-
<span class="very-strong">Must</span> be matched, e.g. <code class="value">&lt;p&gt;</code> <span class="very-strong">must</span> have a matching <code class="value">&lt;/p&gt;</code>.
303-
</li>
304-
<li>
305-
<code class="value">&lt;p&gt;...&lt;/p&gt;</code> and <code class="value">&lt;heading&gt;...&lt;/heading&gt;</code> blocks <span class="very-strong">must not</span> contain other block level tags.
306-
</li>
307-
<li>
308-
<code class="value">&lt;ol&gt;...&lt;/ol&gt;</code> and <code class="value">&lt;ul&gt;...&lt;/ul&gt;</code> blocks <span class="very-strong">must only</span> contain one or more <code class="value">&lt;li&gt;...&lt;/li&gt;</code> blocks.
309-
</li>
310-
<li>
311-
<code class="value">&lt;li&gt;...&lt;/li&gt;</code> blocks <span class="very-strong">must</span> only be used within <code class="value">&lt;ol&gt;...&lt;/ol&gt;</code> and <code class="value">&lt;ul&gt;...&lt;/ul&gt;</code> blocks. <em>May</em> contain <code class="value">&lt;p&gt;...&lt;/p&gt;</code> and <code class="value">&lt;heading&gt;...&lt;/heading&gt;</code> blocks, but it is permitted to include text and inline tags directly without enclosing them one of the permitted blocks. Nested lists are permitted by including further <code class="value">&lt;ul&gt;...&lt;/ul&gt;</code> and <code class="value">&lt;ol&gt;...&lt;/ol&gt;</code> blocks.
312-
</li>
313-
<li>
314-
All text <em>should</em> be embedded within <code class="value">&lt;p&gt;...&lt;/p&gt;</code>, <code class="value">&lt;heading&gt;...&lt;/heading&gt;</code> or <code class="value">&lt;li&gt;...&lt;/li&gt;</code> 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>.
315-
</li>
316-
<li>
317-
White space between blocks <span class="very-strong">must</span> be ignored.
318-
</li>
319-
</ul>
320-
<p>
321-
Here is a valid example:
322-
</p>
323-
<pre class="sample">&lt;heading&gt;Hello&lt;/heading&gt;
324-
&lt;p&gt;Hello World&lt;/p&gt;
325-
&lt;ol&gt;
326-
&lt;li&gt;one&lt;/li&gt;
327-
&lt;li&gt;&lt;p&gt;two&lt;/p&gt;&lt;/li&gt;
328-
&lt;ul&gt;
329-
&lt;li&gt;two A&lt;/li&gt;
330-
&lt;li&gt;two B&lt;/li&gt;
331-
&lt;ul&gt;
332-
&lt;li&gt;three&lt;/li&gt;
333-
&lt;/ol&gt;</pre>
334-
<p>
335-
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.
336-
</p>
337-
<pre class="sample">wrong &lt;heading&gt;blah&lt;/heading&gt; wrong &lt;p&gt;blah&lt;/p&gt; wrong</pre>
338-
<p>
339-
However interpreting code <em>may</em> interpret this permissively. If this is done the text outside blocks <em>should</em> 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:
130+
REML is a little markup language that can be used to style text. It is a SGML language similar to HTML, albeit much smaller. A small number of tags and character entities are supported.
340131
</p>
341-
<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>
342-
<aside>
343-
<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.
344-
</aside>
345132

346-
<h2>
347-
Inline Tags
348-
</h2>
349-
350-
<p>
351-
In-line tags format the text enclosed between the start and end tags.
352-
</p>
353133
<p>
354-
Here are the available in-line tags:
134+
See the <a href="https://htmlpreview.github.io/?https://raw.githubusercontent.com/delphidabbler/reml/main/docs/reml-v6.html">REML v6 language definition</a> for full details.
355135
</p>
356-
<ul class="half-spaced">
357-
<li>
358-
<code class="value">&lt;strong&gt;...&lt;/strong&gt;</code> &ndash; Renders the enclosed markup with strong emphasis.
359-
</li>
360-
<li>
361-
<code class="value">&lt;em&gt;...&lt;/em&gt;</code> &ndash; Emphasises the enclosed markup.
362-
</li>
363-
<li>
364-
<code class="value">&lt;var&gt;...&lt;/var&gt;</code> &ndash; Used to indicate the enclosed markup is a variable.
365-
</li>
366-
<li>
367-
<code class="value">&lt;warning&gt;...&lt;/warning&gt;</code> &ndash; Used for warning text.
368-
</li>
369-
<li>
370-
<code class="value">&lt;mono&gt;...&lt;/mono&gt;</code> &ndash; Renders markup in a mono-spaced font.
371-
</li>
372-
<li>
373-
<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.
374-
</li>
375-
</ul>
376-
<p>
377-
The following rules apply to the use of in-line tags:
378-
</p>
379-
<ul class="unspaced">
380-
<li>
381-
In-line tags <span class="very-strong">must</span> be embedded inside a valid block level tag. E.g. <code class="value">&lt;p&gt;one&lt;strong&gt;two&lt;/strong&gt;three&lt;/p&gt;</code>.
382-
</li>
383-
<li>
384-
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>.
385-
</li>
386-
<li>
387-
Tags may be nested, providing the tags are balanced. 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.
388-
</li>
389-
</ul>
390-
<p>
391-
Examples:
392-
</p>
393-
<pre class="sample">&lt;p&gt;Make stuff &lt;strong&gt;stand out&lt;/strong&gt;.&lt;/p&gt;
394-
&lt;p&gt;&lt;em&gt;Emphasised &lt;warning&gt;warning!&lt;/warning&gt;&lt;/em&gt;&lt;/p&gt;
395-
&lt;p&gt;Refer to a function &lt;var&gt;parameter&lt;/var&gt;.&lt;/p&gt;
396-
&lt;p&gt;Use the: &lt;mono&gt;Windows&lt;/mono&gt; unit.&lt;/p&gt;
397-
&lt;p&gt;See this &lt;a href="https://example.com"&gt;example&lt;/a&gt;.&lt;/p&gt;</pre>
398136

399137
</section>
400138

401-
<section id="entities">
139+
<section id="reml-in-codesnip">
402140

403141
<h1>
404-
Character Entities
142+
REML in CodeSnip
405143
</h1>
406144

407145
<p>
408-
Some symbolic character entities are supported in REML. Many symbols, but not all, have analogues in the list of supported character entities in XHTML or HTML 5. Some entities have alternate symbols. Here is the complete list.
146+
Code snippets include REML to format snippets' description and extra fields. CodeSnip interprets and renders the REML when displaying snippets in its UI and when printing them.
409147
</p>
410148

411-
<table>
412-
<thead>
413-
<tr>
414-
<th>Character Entity</th>
415-
<th>Actual Character</th>
416-
</tr>
417-
</thead>
418-
<tbody>
419-
<tr>
420-
<td><code>&amp;amp;</code></td>
421-
<td>&amp;</td>
422-
</tr>
423-
<tr>
424-
<td><code>&amp;quot;</code></td>
425-
<td>&quot;</td>
426-
</tr>
427-
<tr>
428-
<td><code>&amp;gt;</code></td>
429-
<td>&gt;</td>
430-
</tr>
431-
<tr>
432-
<td><code>&amp;lt;</code></td>
433-
<td>&lt;</td>
434-
</tr>
435-
<tr>
436-
<td><code>&amp;copy;</code></td>
437-
<td>©</td>
438-
</tr>
439-
<tr>
440-
<td><code>&amp;times;</code></td>
441-
<td>×</td>
442-
</tr>
443-
<tr>
444-
<td><code>&amp;divide;</code> or <code>&amp;div;</code></td>
445-
<td>÷</td>
446-
</tr>
447-
<tr>
448-
<td><code>&amp;plusmn;</code></td>
449-
<td>±</td>
450-
</tr>
451-
<tr>
452-
<td><code>&amp;ne;</code> or <code>&amp;neq;</code></td>
453-
<td></td>
454-
</tr>
455-
<tr>
456-
<td><code>&amp;sum;</code></td>
457-
<td></td>
458-
</tr>
459-
<tr>
460-
<td><code>&amp;infin;</code></td>
461-
<td></td>
462-
</tr>
463-
<tr>
464-
<td><code>&amp;pound;</code></td>
465-
<td>£</td>
466-
</tr>
467-
<tr>
468-
<td><code>&amp;curren;</code></td>
469-
<td>¤</td>
470-
</tr>
471-
<tr>
472-
<td><code>&amp;yen;</code></td>
473-
<td>¥</td>
474-
</tr>
475-
<tr>
476-
<td><code>&amp;euro;</code></td>
477-
<td></td>
478-
</tr>
479-
<tr>
480-
<td><code>&amp;cent;</code></td>
481-
<td>¢</td>
482-
</tr>
483-
<tr>
484-
<td><code>&amp;dagger;</code></td>
485-
<td></td>
486-
</tr>
487-
<tr>
488-
<td><code>&amp;ddagger;</code> or <code>&amp;Dagger;</code></td>
489-
<td></td>
490-
</tr>
491-
<tr>
492-
<td><code>&amp;hellip;</code></td>
493-
<td></td>
494-
</tr>
495-
<tr>
496-
<td><code>&amp;para;</code></td>
497-
<td></td>
498-
</tr>
499-
<tr>
500-
<td><code>&amp;sect;</code></td>
501-
<td>§</td>
502-
</tr>
503-
<tr>
504-
<td><code>&amp;reg;</code></td>
505-
<td>®</td>
506-
</tr>
507-
<tr>
508-
<td><code>&amp;frac14;</code></td>
509-
<td>¼</td>
510-
</tr>
511-
<tr>
512-
<td><code>&amp;frac12;</code> or <code>&amp;half;</code></td>
513-
<td>½</td>
514-
</tr>
515-
<tr>
516-
<td><code>&amp;frac34;</code></td>
517-
<td>¾</td>
518-
</tr>
519-
<tr>
520-
<td><code>&amp;micro;</code></td>
521-
<td>µ</td>
522-
</tr>
523-
<tr>
524-
<td><code>&amp;deg;</code></td>
525-
<td>°</td>
526-
</tr>
527-
<tr>
528-
<td><code>&amp;laquo;</code></td>
529-
<td>«</td>
530-
</tr>
531-
<tr>
532-
<td><code>&amp;raquo;</code></td>
533-
<td>»</td>
534-
</tr>
535-
<tr>
536-
<td><code>&amp;iquest;</code></td>
537-
<td>¿</td>
538-
</tr>
539-
<tr>
540-
<td><code>&amp;apos;</code></td>
541-
<td>'</td>
542-
</tr>
543-
</tbody>
544-
</table>
545-
546-
<aside>
547-
<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>.
548-
</aside>
549-
550149
<p>
551-
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>Greek capital letter Omega</em>) use <code class="value">&amp;#937;</code>.
150+
CodeSnip currently supports REML v6. Earlier versions of CodeSnip supported different versions of REML:
552151
</p>
553-
554-
<aside>
555-
<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.
556-
</aside>
557-
558-
</section>
559-
560-
561-
<section id="changes">
562-
563-
<h1>Change Log</h1>
564-
565-
<p>
566-
This section notes the changes in the various versions of REML.
567-
</p>
568-
569-
<p>
570-
<strong>v1 of 2008-12-31</strong>
571-
</p>
572-
573-
<p>
574-
Introduced in CodeSnip v2.2.5
575-
</p>
576-
577-
<ul>
578-
<li>
579-
Supported tags: <code class="value">&lt;strong&gt;</code> and <code class="value">&lt;a&gt;</code>.
580-
</li>
581-
<li>
582-
Supported entities: <code class="value">&amp;gt;</code>, <code class="value">&amp;lt;</code>, <code class="value">&amp;quot;</code> and <code class="value">&amp;amp;</code>.
583-
</li>
584-
<li>
585-
Supported protocols for use in <code class="value">&lt;a&gt;</code> tags: <code class="value">http</code>.
586-
</li>
587-
</ul>
588-
589-
<p>
590-
<strong>v2 of 2009-06-29</strong>
591-
</p>
592-
593-
<p>
594-
Introduced in CodeSnip v3.0
595-
</p>
596-
597-
<ul>
598-
<li>
599-
Added tags: <code class="value">&lt;em&gt;</code>, <code class="value">&lt;var&gt;</code>, <code class="value">&lt;warning&gt;</code>, <code class="value">&lt;mono&gt;</code>, <code class="value">&lt;p&gt;</code> and <code class="value">&lt;heading&gt;</code>.
600-
</li>
601-
<li>
602-
Added entity: <code class="value">&amp;copy;</code>.
603-
</li>
604-
</ul>
605-
606-
<p>
607-
<strong>v3 of 2009-07-06</strong>
608-
</p>
609-
610-
<p>
611-
Introduced in CodeSnip v3.0.1
612-
</p>
613-
614-
<ul>
615-
<li>
616-
Added protocol for use in <code class="value">&lt;a&gt;</code> tags: <code class="value">file</code>.
617-
</li>
618-
</ul>
619-
620-
<p>
621-
<strong>v4 of 2011-12-31</strong>
622-
</p>
623-
624-
<p>
625-
Introduced in CodeSnip v4.0 alpha 1 (preview)
626-
</p>
627-
628-
<ul>
629-
<li>
630-
Added protocol for use in <code class="value">&lt;a&gt;</code> tags: <code class="value">https</code>.
631-
</li>
632-
</ul>
633-
634-
<p>
635-
<strong>v5 of 2022-12-16</strong>
636-
</p>
637-
638-
<p>
639-
Introduced in CodeSnip v4.21.0
640-
</p>
641-
152+
642153
<ul>
643-
<li>
644-
Added support for lists with the <code class="value">&lt;ol&gt;</code>, <code class="value">&lt;ul&gt;</code> &amp; <code class="value">&lt;li&gt;</code> block tags.
645-
</li>
646-
<li>
647-
Added entities: <code class="value">&amp;times;</code>, <code class="value">&amp;divide;</code>, <code class="value">&amp;div;</code> <code class="value">&amp;plusmn;</code>, <code class="value">&amp;ne;</code>, <code class="value">&amp;neq;</code>, <code class="value">&amp;sum;</code>, <code class="value">&amp;infin;</code>, <code class="value">&amp;pound;</code>, <code class="value">&amp;curren;</code>, <code class="value">&amp;yen;</code>, <code class="value">&amp;euro;</code>, <code class="value">&amp;cent;</code>, <code class="value">&amp;dagger;</code>, <code class="value">&amp;ddagger;</code>, <code class="value">&amp;Dagger;</code>, <code class="value">&amp;hellip;</code>, <code class="value">&amp;para;</code>, <code class="value">&amp;sect;</code>, <code class="value">&amp;reg;</code>, <code class="value">&amp;frac14;</code>, <code class="value">frac12</code>, <code class="value">&amp;half;</code>, <code class="value">&amp;frac34;</code>, <code class="value">&amp;micro;</code>, <code class="value">&amp;deg;</code>, <code class="value">&amp;laquo;</code>, <code class="value">&amp;raquo;</code> &amp; <code class="value">&amp;iquest;</code>.
648-
</li>
154+
<li>REML v1 was first supported by CodeSnip v2.2.5</li>
155+
<li>REML v2 was first supported by CodeSnip v3.0</li>
156+
<li>REML v3 was first supported by CodeSnip v3.0.1</li>
157+
<li>REML v4 was first supported by CodeSnip v4.0 alpha 1 (preview)</li>
158+
<li>REML v5 was first supported by CodeSnip v4.21.0</li>
159+
<li>REML v6 was first supported by CodeSnip v4.23.0</li>
649160
</ul>
650161

651162
<p>
652-
<strong>v6 of 2024-04-02</strong>
163+
All CodeSnip versions are backward compatible with earlier versions of REML.
653164
</p>
654165

655-
<p>
656-
Introduced in CodeSnip v4.23.0
657-
</p>
166+
</section>
658167

659-
<ul>
660-
<li>
661-
Added entity: <code class="value">&amp;apos;</code>.
662-
</li>
663-
</ul>
664-
665-
</section>
168+
</main>
666169

667170
</body>
668171

‎Src/Help/HTML/reml.htm

Lines changed: 47 additions & 340 deletions
Original file line numberDiff line numberDiff line change
@@ -15,20 +15,6 @@
1515
About REML
1616
</title>
1717
<link rel="stylesheet" href="../css/codesnip.css" type="text/css">
18-
<style type="text/css">
19-
dl {
20-
margin: 6px 0 0 0;
21-
}
22-
dl dt {
23-
margin: 3px 0 0 0;
24-
}
25-
dl dd {
26-
margin-left: 24px;
27-
}
28-
.hilite {
29-
background-color: #ff9;
30-
}
31-
</style>
3218
</head>
3319
<body>
3420
<object
@@ -41,341 +27,62 @@ <h1>
4127
<a name="reml"></a>About the REML markup language
4228
</h1>
4329
<p>
44-
<em>REML</em> is <em>CodeSnip</em>'s own little markup language that can
45-
be used to style the text of a snippet's description and / or extra
46-
information. The latest version is v6, which is backwards compatible with
47-
all other versions.
30+
REML is a little markup language that can be used to style text. It is a SGML language similar to HTML, albeit much smaller. A small number of tags and character entities are supported.
4831
</p>
49-
<h2>
50-
Language Details
51-
</h2>
5232
<p>
53-
The <em>REML</em> language is a SGML language similar to a greatly
54-
simplified XHTML. The are a small number of tags you can use. Firstly
55-
there are two block-level tags that render text in paragraphs, while the
56-
other tags format text inline or embed hyplerlinks.
33+
CodeSnip currently supports REML v6. See the <a href="https://htmlpreview.github.io/?https://raw.githubusercontent.com/delphidabbler/reml/main/docs/reml-v6.html">REML v6 language definition</a> for full details.
5734
</p>
58-
<h3>
59-
Block level tags
60-
</h3>
61-
<dl>
62-
<dt><code class="reml">&lt;p&gt;...&lt/p&gt;</code></dt>
63-
<dd>
64-
Renders the enclosed markup as a simple paragraph.
65-
</dd>
66-
<dt><code class="reml">&lt;heading&gt;...&lt;/heading&gt;</code></dt>
67-
<dd>
68-
Renders the enclosed markup as a heading.
69-
</dd>
70-
<dt><code class="reml">&lt;ol&gt;...&lt;/ol&gt;</code></dt>
71-
<dd>
72-
Renders the enclosed HTML as an ordered list. Must contain
73-
<code class="value">&lt;li&gt;...&lt;/li&gt</code> blocks and nothing
74-
else.
75-
</dd>
76-
<dt><code class="reml">&lt;ul&gt;...&lt;/ul&gt;</code></dt>
77-
<dd>
78-
Renders the enclosed HTML as an unordered list. Must contain
79-
<code class="value">&lt;li&gt;...&lt;/li&gt</code> blocks and nothing
80-
else.
81-
</dd>
82-
<dt><code class="reml">&lt;l1&gt;...&lt;/li&gt;</code></dt>
83-
<dd>
84-
Renders the enclosed HTML as a list item. May only be used within
85-
<code class="value">&lt;ol&gt;...&lt;/ol&gt;</code> and
86-
<code class="value">&lt;ul&gt;...&lt;/ul&gt;</code> blocks.
87-
</dd>
88-
</dl>
8935
<p>
90-
The following rules apply to the use of block level tags:
91-
</p>
92-
<ol>
93-
<li>
94-
Must be matched, e.g.
95-
<code class="value">&lt;p&gt;</code> must have a matching
96-
<code class="value">&lt;/p&gt;</code>.
97-
</li>
98-
<li>
99-
<code class="value">&lt;p&gt;...&lt;/p&gt;</code> and
100-
<code class="value">&lt;heading&gt;...&lt;/heading&gt;</code> blocks
101-
must not contain other block level tags.
102-
</li>
103-
<li>
104-
<code class="value">&lt;ol&gt;...&lt;/ol&gt;</code> and
105-
<code class="value">&lt;ul&gt;...&lt;/ul&gt;</code> blocks must only
106-
contain one or more
107-
<code class="value">&lt;li&gt;...&lt;/li&gt;</code> blocks.
108-
</li>
109-
<li>
110-
<code class="value">&lt;li&gt;...&lt;/li&gt;</code> blocks may contain
111-
<code class="value">&lt;p&gt;...&lt;/p&gt;</code> and
112-
<code class="value">&lt;heading&gt;...&lt;/heading&gt;</code> blocks,
113-
but it is permitted to include text and inline tags directly without
114-
enclosing them one of the permitted blocks. Nested lists are permitted
115-
by including further <code class="value">&lt;ul&gt;...&lt;/ul&gt;</code>
116-
and <code class="value">&lt;ol&gt;...&lt;/ol&gt;</code> blocks.
117-
</li>
118-
<li>
119-
All text should be embedded within
120-
<code class="value">&lt;p&gt;...&lt;/p&gt;</code>,
121-
<code class="value">&lt;heading&gt;...&lt;/heading&gt;</code> or
122-
<code class="value">&lt;li&gt;...&lt;/li&gt;</code> block level tags,
123-
e.g. <code class="value"
124-
>&lt;heading&gt;heading&lt;/heading&gt;&lt;p&gt;text&lt;/p&gt;</code>
125-
or simply <code class="value">&lt;p&gt;text&lt;/p&gt;</code>.
126-
</li>
127-
<li>
128-
White space between blocks must be ignored.
129-
</li>
130-
</ol>
131-
<p>
132-
Here is a valid example:
133-
</p>
134-
<pre class="sample">&lt;heading&gt;Hello&lt;/heading&gt;
135-
&lt;p&gt;Hello World&lt;/p&gt;
36+
The following whimsical example demonstrates every supported REML tag along with a couple of character entities:
37+
<pre class="reml">&lt;heading&gt;
38+
Wombat converter
39+
&lt;/heading&gt;
40+
&lt;p&gt;
41+
Transforms &lt;strong&gt;wombats&lt;/strong&gt; into &lt;em&gt;dongles&lt;/em&gt;.
42+
&lt;warning&gt;&lt;em&gt;W&lt;/em&gt;arning:&lt;/warning&gt; The &lt;var&gt;Foo&lt;/var&gt;
43+
variable stores &amp;lt;=&lt;mono&gt;12&lt;/mono&gt; accumulated &lt;mono&gt;dongles&lt;/mono&gt;.
44+
&lt;/p&gt;
45+
&lt;p&gt;
46+
All 3 species of wombat are supported:
47+
&lt;/p&gt;
13648
&lt;ol&gt;
137-
&lt;li&gt;one&lt;/li&gt;
138-
&lt;li&gt;&lt;p&gt;two&lt;/p&gt;&lt;/li&gt;
139-
&lt;ul&gt;
140-
&lt;li&gt;two A&lt;/li&gt;
141-
&lt;li&gt;two B&lt;/li&gt;
142-
&lt;ul&gt;
143-
&lt;li&gt;three&lt;/li&gt;
144-
&lt;/ol&gt;</pre>
145-
<p>
146-
Srictly speaking, the following example is invalid code &ndash; the
147-
highlighted sections are in error, because they are not contained within
148-
block tags.
149-
</p>
150-
<pre class="reml indent"><span class="hilite">blah</span>&lt;heading&gt;blah&lt;/heading&gt;<span class="hilite">blah</span>&lt;p&gt;blah&lt;/p&gt;<span class="hilite">blah</span></pre>
151-
<p>
152-
However, <em>CodeSnip</em> is quite permissive and, in many cases,
153-
automatically adds block level tags for text that is not enclosed in block
154-
level tags. The above code is interpreted similar ro:
155-
</p>
156-
<pre class="reml indent">&lt;p&gt;<span class="hilite">blah</span> &lt;/p&gt;
157-
&lt;heading&gt;blah&lt;/heading&gt;
158-
&lt;p&gt;<span class="hilite">blah</span> &lt;/p&gt;
159-
&lt;p&gt;blah&lt;/p&gt;
160-
&lt;p&gt;<span class="hilite">blah</span>&lt;/p&gt;</pre>
161-
<h3>
162-
Inline tags
163-
</h3>
164-
<p>
165-
Here are the available inline tags:
166-
</p>
167-
<dl>
168-
<dt><code class="reml">&lt;strong&gt;...&lt/strong&gt;</code></dt>
169-
<dd>
170-
Renders the enclosed markup with strong emphasis.<br>
171-
<em>Example:</em> <code class="reml">&lt;p&gt;Make stuff
172-
&lt;strong&gt;stand out&lt;/strong&gt;.&lt;/p&gt;</code>
173-
</dd>
174-
<dt><code class="reml">&lt;em&gt;...&lt;/em&gt;</code></dt>
175-
<dd>
176-
Emphasises the enclosed markup.<br>
177-
<em>Example:</em> <code class="reml">&lt;p&gt;Draw
178-
&lt;em&gt;attention&lt;/em&gt; to something.&lt;/p&gt;</code>
179-
</dd>
180-
<dt><code class="reml">&lt;var&gt;...&lt;/var&gt;</code></dt>
181-
<dd>
182-
Used to indicate the enclosed markup is a variable.<br>
183-
<em>Example:</em> <code class="reml">&lt;p&gt;Refer to a function
184-
&lt;var&gt;parameter&lt;/var&gt;.&lt;/p&gt;</code>
185-
</dd>
186-
<dt><code class="reml">&lt;warning&gt;...&lt;/warning&gt;</code></dt>
187-
<dd>
188-
Used for warning text.<br>
189-
<em>Example:</em>
190-
<code class="reml">&lt;p&gt;&lt;warning&gt;Warning:&lt;/warning&gt;
191-
Don't do it!&lt;/p&gt;</code>
192-
</dd>
193-
<dt><code class="reml">&lt;mono&gt;...&lt;/mono&gt;</code></dt>
194-
<dd>
195-
Renders markup in a mono-spaced font.<br>
196-
<em>Example:</em> <code class="reml">&lt;p&gt;Use the:
197-
&lt;mono&gt;Windows&lt;/mono&gt; unit.&lt;/p&gt;</code>
198-
</dd>
199-
<dt><code class="reml">&lt;a href=&quot;url&quot;&gt;...&lt;/a&gt;</code></dt>
200-
<dd>
201-
Creates a hyperlink. The <code class="reml">href</code> attribute must
202-
specify the required URL, which must use one of the <em>http:</em>,
203-
<em>https:</em> or <em>file:</em> protocols; others are not permitted.
204-
If you use the <em>file:</em> protocol it must reference a valid local
205-
or network file. Be aware that if you export a snippet
206-
containing a hyperlink that uses the <em>file:</em> protocol it will
207-
only work on the recipient's system if the specified file exists in the
208-
same location.<br>
209-
<em>Example:</em> <code class="reml">&lt;p&gt;&lt;a
210-
href=&quot;https://example.com&quot;&gt;Visit
211-
example.com&lt;/a&gt;&lt/p&gt;.</code>.
212-
</dd>
213-
</dl>
214-
<h3 id="entities">
215-
Character Entities
216-
</h3>
217-
<p>
218-
The &quot;&lt;&quot; and &quot;&amp;&quot; characters are special within
219-
the markup and must not be used directly, even when you are just entering
220-
plain text. You must use the <code class="reml">&amp;lt;</code> character
221-
entity in place of &quot;&lt;&quot; and
222-
<code class="reml">&amp;amp;</code> instead of &quot;&amp;&quot;.
223-
</p>
224-
<p>
225-
A few other character entities are supported for convenience. Here is the
226-
complete list:
227-
</p>
228-
<table class="bordered" cellspacing="1" cellpadding="0">
229-
<thead>
230-
<tr>
231-
<th>Character Entity</th>
232-
<th>Actual Character</th>
233-
</tr>
234-
</thead>
235-
<tbody>
236-
<tr>
237-
<td><code>&amp;amp;</code></td>
238-
<td class="centre">&amp;</td>
239-
</tr>
240-
<tr>
241-
<td><code>&amp;quot;</code></td>
242-
<td class="centre">&quot;</td>
243-
</tr>
244-
<tr>
245-
<td><code>&amp;gt;</code></td>
246-
<td class="centre">&gt;</td>
247-
</tr>
248-
<tr>
249-
<td><code>&amp;lt;</code></td>
250-
<td class="centre">&lt;</td>
251-
</tr>
252-
<tr>
253-
<td><code>&amp;copy;</code></td>
254-
<td class="centre">&copy;</td>
255-
</tr>
256-
<tr>
257-
<td><code>&amp;times;</code></td>
258-
<td class="centre">&times;</td>
259-
</tr>
260-
<tr>
261-
<td><code>&amp;divide;</code> or <code>&amp;div;</code></td>
262-
<td class="centre">&divide;</td>
263-
</tr>
264-
<tr>
265-
<td><code>&amp;plusmn;</code></td>
266-
<td class="centre">&plusmn;</td>
267-
</tr>
268-
<tr>
269-
<td><code>&amp;ne;</code> or <code>&amp;neq;</code></td>
270-
<td class="centre">&ne;</td>
271-
</tr>
272-
<tr>
273-
<td><code>&amp;sum;</code></td>
274-
<td class="centre">&sum;</td>
275-
</tr>
276-
<tr>
277-
<td><code>&amp;infin;</code></td>
278-
<td class="centre">&infin;</td>
279-
</tr>
280-
<tr>
281-
<td><code>&amp;pound;</code></td>
282-
<td class="centre">&pound;</td>
283-
</tr>
284-
<tr>
285-
<td><code>&amp;curren;</code></td>
286-
<td class="centre">&curren;</td>
287-
</tr>
288-
<tr>
289-
<td><code>&amp;yen;</code></td>
290-
<td class="centre">&yen;</td>
291-
</tr>
292-
<tr>
293-
<td><code>&amp;euro;</code></td>
294-
<td class="centre">&euro;</td>
295-
</tr>
296-
<tr>
297-
<td><code>&amp;cent;</code></td>
298-
<td class="centre">&cent;</td>
299-
</tr>
300-
<tr>
301-
<td><code>&amp;dagger;</code></td>
302-
<td class="centre">&dagger;</td>
303-
</tr>
304-
<tr>
305-
<td><code>&amp;ddagger;</code> or <code>&amp;Dagger;</code></td>
306-
<td class="centre">&ddagger;</td>
307-
</tr>
308-
<tr>
309-
<td><code>&amp;hellip;</code></td>
310-
<td class="centre">&hellip;</td>
311-
</tr>
312-
<tr>
313-
<td><code>&amp;para;</code></td>
314-
<td class="centre">&para;</td>
315-
</tr>
316-
<tr>
317-
<td><code>&amp;sect;</code></td>
318-
<td class="centre">&sect;</td>
319-
</tr>
320-
<tr>
321-
<td><code>&amp;reg;</code></td>
322-
<td class="centre">&reg;</td>
323-
</tr>
324-
<tr>
325-
<td><code>&amp;frac14;</code></td>
326-
<td class="centre">&frac14;</td>
327-
</tr>
328-
<tr>
329-
<td><code>&amp;frac12;</code> or <code>&amp;half;</code></td>
330-
<td class="centre">&frac12;</td>
331-
</tr>
332-
<tr>
333-
<td><code>&amp;frac34;</code></td>
334-
<td class="centre">&frac34;</td>
335-
</tr>
336-
<tr>
337-
<td><code>&amp;micro;</code></td>
338-
<td class="centre">&micro;</td>
339-
</tr>
340-
<tr>
341-
<td><code>&amp;deg;</code></td>
342-
<td class="centre">&deg;</td>
343-
</tr>
344-
<tr>
345-
<td><code>&amp;laquo;</code></td>
346-
<td class="centre">&laquo;</td>
347-
</tr>
348-
<tr>
349-
<td><code>&amp;raquo;</code></td>
350-
<td class="centre">&raquo;</td>
351-
</tr>
352-
<tr>
353-
<td><code>&amp;iquest;</code></td>
354-
<td class="centre">&iquest;</td>
355-
</tr>
356-
<tr>
357-
<td><code>&amp;apos;</code></td>
358-
<td class="centre">&apos;</td>
359-
</tr>
360-
</tbody>
361-
</table>
362-
<p>
363-
By way of an example, if you want to display <code>x &ne; y</code>, use:
364-
</p>
365-
<p class="indent">
366-
<code class="reml">x &amp;ne; y</code>
49+
&lt;li&gt;
50+
&lt;p&gt;
51+
&lt;a href="https://en.wikipedia.org/wiki/Common_wombat"&gt;Common
52+
wombat&lt;/a&gt;. The following sub-species are supported:
53+
&lt;/p&gt;
54+
&lt;ul&gt;
55+
&lt;li&gt;
56+
Bass Strait wombat
57+
&lt;/li&gt;
58+
&lt;li&gt;
59+
Hirsute wombat
60+
&lt;/li&gt;
61+
&lt;li&gt;
62+
Tasmanian wombat
63+
&lt;/li&gt;
64+
&lt;/ul&gt;
65+
&lt;/li&gt;
66+
&lt;li&gt;
67+
Northen hairy-nosed wombat
68+
&lt;/li&gt;
69+
&lt;li&gt;
70+
Southern hairy-nosed wombat
71+
&lt;/li&gt;
72+
&lt;/ol&gt;
73+
&lt;p&gt;
74+
Copyright &amp;copy; wombaterama, 2024.
75+
&lt;/p&gt;</pre>
36776
</p>
36877
<p>
369-
No other symbolic character entities are supported.
370-
However, numeric character entities can be used to insert other characters
371-
by specifying its code. For example <code class="reml">&amp;#64;</code> is
372-
equivalent to &quot;&#64;&quot;.
78+
All this silliness renders something like this:
37379
</p>
37480
<p>
375-
Numeric entities should be used with caution. Using a code that is
376-
specific to an ANSI character set may cause unexpected results because
377-
<em>CodeSnip</em> uses Unicode internally and the specified character code
378-
may not represent the same character in ANSI and Unicode.
81+
<img
82+
src="..\Images\REMLExample.png"
83+
width="379"
84+
height="198"
85+
>
37986
</p>
38087
</body>
38188
</html>

‎Src/Help/Images/REMLExample.png

46.2 KB
Loading

0 commit comments

Comments
 (0)
Please sign in to comment.