<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<!--
* $Rev$
* $Date$
*
* ***** BEGIN LICENSE BLOCK *****
*
* Version: MPL 1.1
*
* The contents of this file are subject to the Mozilla Public License Version
* 1.1 (the "License"); you may not use this file except in compliance with the
* License. You may obtain a copy of the License at http://www.mozilla.org/MPL/
*
* Software distributed under the License is distributed on an "AS IS" basis,
* WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for
* the specific language governing rights and limitations under the License.
*
* The Original Code is reml.htm
*
* The Initial Developer of the Original Code is Peter Johnson
* (http://www.delphidabbler.com/).
*
* Portions created by the Initial Developer are Copyright (C) 2009-2012 Peter
* Johnson. All Rights Reserved.
*
* ***** END LICENSE BLOCK *****
-->
<html>
<head>
<meta http-equiv="Content-Type" content="text-html; charset=Windows-1252">
<title>
About REML
</title>
<link rel="stylesheet" href="../css/codesnip.css" type="text/css">
<style type="text/css">
dl {
margin: 6px 0 0 0;
}
dl dt {
margin: 3px 0 0 0;
}
dl dd {
margin-left: 24px;
}
.code {
font-family: "Courier New";
color: purple;
}
.hilite {
background-color: #ff9;
}
</style>
</head>
<body>
<object
type="application/x-oleobject"
classid="clsid:1e2a7bd0-dab9-11d0-b93a-00c04fc99f9e"
>
<param name="ALink Name" value="REML">
</object>
<h1>
<a name="reml"></a>About the REML markup language
</h1>
<p>
The <em>REML</em> markup language can be used to format any extra
information you want to associate with a code snippet. It is entered on
the <em>Extra Information</em> tab of the
<a href="dlg_editsnippet.htm">Snippets Editor</a> dialogue box.
</p>
<h2>
Using plain text
</h2>
<p>
First note that you do not have to use REML to markup your extra text
– you can use plain text (with a couple of exceptions: see
<a href="#entities">character entities</a> below). <em>CodeSnip</em> will
convert your text into a simple REML paragraph by surrounding it in
suitable <span class="code"><p></span> and
<span class="code"></p></span> tags that you will see the next time
you edit the text.
</p>
<p>
You can create multiple paragraphs of text simply by separating the
paragraphs with blank lines. For example, entering:
</p>
<p class="indent code">
The cat sat<br><br>
on the mat
</p>
<p>
is interpreted as
</p>
<p class="indent code">
<p>the cat sat</p><br>
<p>on the mat</p>
</p>
<p>
Be careful though, because if you don't leave a blank line, as in
</p>
<p class="indent code">
The cat sat<br>
on the mat
</p>
<p>
you will get the equivalent of
</p>
<p class="indent code">
<p>the cat sat on the mat</p>
</p>
<h2>
Using markup
</h2>
<p>
The REML language is a simple SGML language similar to a greatly
simplified XHTML. The are a small number of tags you can use. Firstly
there are two block-level tags that render text in paragraphs, while the
other tags format text inline.
</p>
<h3>
Block level tags
</h3>
<dl>
<dt class="code"><p>...</p></dt>
<dd>
Renders the enclosed markup as a simple paragraph.
</dd>
<dt class="code"><heading>...</heading></dt>
<dd>
Renders the enclosed markup as a heading.
</dd>
</dl>
<p>
The following rules apply to the use of
<span class="code"><p></span> and
<span class="code"><heading></span>
</p>
<ol>
<li>
These tags must not be nested.
</li>
<li>
Furthermore, all your markup should be enclosed in one or more pairs of
these block level tags – that means that markup must start with
one of these tags and end with a suitable closing tags.
</li>
<li>
The tags must be matched, e.g.
<span class="code"><p></span> must have a matching
<span class="code"></p></span>.
</li>
</ol>
<p>
Here are some valid examples:
</p>
<ol>
<li class="extra-spacing">
<span class="code"><p>Hello World</p></span>
</li>
<li>
<span class="code"><heading>Hello</heading><br>
<p>Hello World</p></span>
</li>
</ol>
<p>
Srictly speaking, the following example is invalid code – the
highlighted sections are in error, because they are not contained within
block tags.
</p>
<p class="indent code">
<span class="hilite">blah</span>
<heading>blah</heading>
<span class="hilite">blah</span>
<p>blah</p>
<span class="hilite">blah</span>
</p>
<p>
However, because plain text can be entered without tags the
<a href="dlg_editsnippet.htm">Snippets Editor</a> will interpret this
code as:
</p>
<p class="indent code">
<p><span class="hilite">blah</span> </p><br>
<heading>blah</heading><br>
<p><span class="hilite">blah</span> </p><br>
<p>blah</p><br>
<p><span class="hilite">blah</span></p>
</p>
<h3>
Inline tags
</h3>
<p>
Here are the available inline tags:
</p>
<dl>
<dt class="code"><strong>...</strong></dt>
<dd>
Renders the enclosed markup with strong emphasis.<br>
<em>Example:</em> <code><p>Make stuff <strong>stand
out</strong>.</p></code>
</dd>
<dt class="code"><em>...</em></dt>
<dd>
Emphasises the enclosed markup.<br>
<em>Example:</em> <code><p>Draw <em>attention</em> to
something.</p></code>
</dd>
<dt class="code"><var>...</var></dt>
<dd>
Used to indicate the enclosed markup is a variable.<br>
<em>Example:</em> <span class="code"><p>Refer to a function
<var>parameter</var>.</p></span>
</dd>
<dt class="code"><warning>...</warning></dt>
<dd>
Used for warning text.<br>
<em>Example:</em>
<span class="code"><p><warning>Warning:</warning>
Don't do it!</p></span>
</dd>
<dt class="code"><mono>...</mono></dt>
<dd>
Renders markup in a mono-spaced font.<br>
<em>Example:</em> <span class="code"><p>Use the:
<mono>Windows:</mono> unit.</p></span>
</dd>
<dt class="code"><a href="url">...</a></dt>
<dd>
Creates a hyperlink. The <span class="code">href</span> attribute must
specify the required URL, which must use one of the <em>http:</em>,
<em>https:</em> or <em>file:</em> protocols; others are not permitted.
If you use the <em>file:</em> protocol it must reference a valid local
or network file. Be aware that if you submit or export a snippet
containing a hyperlink that uses the <em>file:</em> protocol it will
only work on the recipient's system if the specified file exists in the
same location.<br>
<em>Example:</em> <span class="code"><p><a
href="http://www.delphidabbler.com">Visit
DelphiDabbler.com</a></p>.</span>.
</dd>
</dl>
<h3 id="entities">
Character Entities
</h3>
<p>
The "<" and "&" characters are special within
the markup and must not be used directly, even when you are just entering
plain text. You must use the <span class="code">&lt;</span> character
entity in place of "<" and
<span class="code">&amp;</span> instead of "&".
</p>
<p>
A few other character entities are supported for convenience. Here is the
complete list:
</p>
<ul class="unspaced">
<li>
<code>&lt;</code> for <code><</code>
</li>
<li>
<code>&gt;</code> for <code>></code>
</li>
<li>
<code>&quot;</code> for <code>"</code>
</li>
<li>
<code>&amp;</code> for <code>&</code>
</li>
<li>
<code>&copy;</code> for <code>©</code>
</li>
</ul>
<p>
No other symbolic character entities are supported.
However, numeric character entities can be used to insert other characters
by specifying its code. For example <span class="code">&#64;</span> is
equivalent to "@".
</p>
<p>
By way of an example, if you want to display
<span class="code">x < y</span>, use:
</p>
<p class="indent">
<code>x &lt; y</code>
</p>
<h2>
Mix and Match
</h2>
<p>
You can mix plain text with markup if you like, but you may get unexpected results mixing plain text with block level tags: see the example of bad
code above.
</p>
<p>
However it can save some typing if you use plain text paragraphs,
separated by blank lines along with some inline tags, for example
</p>
<p class="indent code">
The <em>cat</em> sat<br><br>
on the <strong>mat</strong>.
</p>
<p>
Which is equivalent to
</p>
<p class="indent code">
<p>The <em>cat</em> sat</p><br>
<p>on the <strong>mat</strong>.</p>
</p>
</body>
</html>
