<!DOCTYPE html>
<!-- ========================================== kroc camen of camen design ============================================= -->
<title>code · ReMarkable!</title>
<link rel="stylesheet" type="text/css" href="/design/design.css" />
<meta name="viewport" content="width=device-width, maximum-scale=1.0, user-scalable=no" />
<link rel="alternate" type="application/rss+xml" href="/code/rss" title="Just code" />
<link rel="canonical" href="/code/remarkable" />
<!-- =================================================================================================================== -->
<header>
	<h1><a href="/" rel="index">
		Camen Design
	</a></h1>
	<nav><ul>
		<li><a href="/">all</a></li>
		<li><a href="/projects">projects</a></li>
		<li><a href="http://forum.camendesign.com">forum</a></li>
	</ul><ul>
		<li><a href="/quote/">quote</a></li>
		<li><a href="/writing/">writing</a></li>
		<li><a href="/blog/">blog</a></li>
		<li><a href="/photo/">photo</a></li>
		<li><a href="/code/" rel="tag">code</a></li>
		<li><a href="/art/">art</a></li>
		<li><a href="/link/">link</a></li>
		<li><a href="/poem/">poem</a></li>
		<li><a href="/audio/">audio</a></li>
	</ul><ul>
		<li><a href="/web-dev/">web-dev</a></li>
		<li><a href="/annoyances/">annoyances</a></li>
		<li><a href="/eve/">eve</a></li>
		<li><a href="/code-is-art/">code-is-art</a></li>
		<li><a href="/inspiration/">inspiration</a></li>
		<li><a href="/windows/">windows</a></li>
		<li><a href="/gift/">gift</a></li>
		<li><a href="/gaming/">gaming</a></li>
		<li><a href="/mac/">mac</a></li>
		<li><a href="/osnews/">osnews</a></li>
		<li><a href="/c64/">c64</a></li>
		<li><a href="/linux/">linux</a></li>
	</ul>
	<a rel="previous" href="/code/abbr_redux">
		older article →
	</a><a rel="next" href="/code/forums">
		← newer article
	</a></nav>
</header>
<!-- =================================================================================================================== -->
<article><header>
	<!-- date published or updated -->
	<time pubdate datetime="2010-10-05T15:53:00+01:00">
		<sup>3:53<abbr>pm</abbr> • 2010</sup>
		<abbr title="October">Oct</abbr> 5
	</time>
	<!-- categories -->
	<ul>
		<li><a href="/code/remarkable" rel="bookmark tag">code</a></li>
		<li><a href="/web-dev/remarkable">web-dev</a></li>
		<li><a href="/code-is-art/remarkable">code-is-art</a></li>
	</ul>
	<!-- enclosure -->
	<a type="application/zip" href="/code/remarkable/remarkable.zip">
		remarkable <em>49.5 KB</em>
	</a>
</header>
<!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -->
<section>
<h1>ReMarkable!</h1>
<p>
	<strong>ReMarkable is</strong> my own
	<a href="http://daringfireball.net/projects/markdown/" rel="external">Markdown</a>-like syntax, used to write and
	publish the content on this site.<br />It is a plain-text method of writing articles that is then converted into
	HTML.
</p>
<ul>
	<li><a href="/code/remarkable/remarkable.zip" type="application/zip">Download</a></li>
	<li><a href="/code/remarkable/documentation.html">Documentation</a></li>
	<li><a href="/code/remarkable/quickref.txt" type="text/plain">Quick Reference Guide</a></li>
	<li><a href="/code/remarkable/remarkable.php">View source</a></li>
	<li><a href="http://github.com/Kroc/ReMarkable" rel="external">ReMarkable on GitHub</a></li>
</ul>
<p>
	To skip the talk and see it in use, you can add “.rem” to the end of any article on this site (or click the
	“rem” link at the bottom of each page) to see the original ReMarkable source for the article. For example:
	<a href="/code/remarkable.rem">“/code/remarkable.rem”</a>.
</p>


<h2 id="remarkable-history">Version History</h2>
<dl>
	<dt>v0.4.5—14<sup>th</sup> January ’12</dt>
	<dd>
		<ul>
			<li>Incorrect text-escaping in e-mode regexes caused “<samp>$</samp>” to break text in
			table of contents (essentially some text was being interpreted as PHP code)</li>
		</ul>
	</dd>
	<dt>v0.4.4–9<sup>th</sup> February ’11</dt>
	<dd>
		<ul>
			<li>Applied some changes made by
			<a href="https://github.com/Zegnat/ReMarkable" rel="external">Zengnat</a></li>
			<li>Stop throwing a Notice when no title is specified for a link</li>
			<li>Fixes two more Notices that apply to e-mail links</li>
			<li>Add support for the HTML5 <code>hgroup</code> element (this is paragraph processing, not
			syntax support)</li>
		</ul>
	</dd>
	<dt>v0.4.3—5<sup>th</sup> October ’10</dt>
	<dd>
		<ul>
			<li>Large update to documentation, including
			<a href="/code/remarkable/documentation.html#html">how to mix HTML and ReMarkable
			syntax</a></li>
			<li>Changed command line to accept source text from <samp>stdin</samp>—<strong>will break
			existing code</strong>—see source for examples</li>
			<li>Added <samp>options</samp> parameter for output preferences (<samp>NOXHTML</samp> /
			<samp>TABSPACE_2</samp> / <samp>TABSPACE_4</samp>),<br />
			see <a href="/code/remarkable/documentation.html">documentation</a>. This will expand
			over time.</li>
			<li>Titles allowed on links “<code>&lt;description (/href) "title"&gt;</code>”</li>
		</ul>
	</dd>
	<dt>v0.4.2—22<sup>nd</sup> August ’10</dt>
	<dd>
		<ul>
			<li>Spelling mistake with <code>&lt;figcaption&gt;</code></li>
			<li>A hyperlink as the only thing on a line should not be wrapped in a paragraph<br />
			(was supposed to be doing this since 0.4 but was broken)</li>
		</ul>
	</dd>
	<dt>v0.4.1—15<sup>th</sup> August ’10</dt>
	<dd>
		<ul>
			<li>Added <dfn title="definition">dfn</dfn> support to help with
			<a href="/code/abbr_redux">abbreviations, definitions and citations</a> best-practices</li>
		</ul>
	</dd>
	<dt>v0.4—12<sup>th</sup> August ’10</dt>
	<dd>
		<ul>
			<li>Shaved 38 lines off the code (was about 100 but added comments and tidy formatting)</li>
			<li>Added <a href="/code/remarkable/quickref.txt" type="text/plain">Quick Reference Guide</a></li>
			<li>Anything allowed in the bookmark portion of hyperlink URLs<br />(this is being abused by
			more and more sites now)</li>
			<li>Changed en-dash syntax to “<samp> -to- </samp>” (requires spaces either side) because
			it was clashing too much with common writing like “up-to-date”
			<abbr title="et cetera">&amp;c.</abbr></li>
			<li>If a hyperlink is the only thing on a line, it does not get wrapped in a paragraph<br />
			(useful for block images / figures)</li>
			<li>Added image linking “<code>&lt;"alt" thumb.jpg = image.png&gt;</code>”</li>
			<li><a href="/code/remarkable/documentation.html#figure">Syntax for HTML5
			<code>&lt;figure&gt;</code></a></li>
			<li>Don’t wrongly exit if calling a PHP script from the command line that then includes
			ReMarkable</li>
			<li>Do not warn if “<code>$_SERVER['argc']</code>” is not present (thanks Andrew Rowls)</li>
			<li>Title casing now capitalises correctly after em/en dash</li>
			<li>DTs now support IDs. Use “<samp>:: (#id) …</samp>”</li>
			<li>LIs now support IDs. Use “<samp>• (#id)</samp>” before the tab character (any bullet
			type allowed), you can also indent the following lines more to account for an ID bumping
			the margin to two tabs or more</li>
			<li>Added “¾” to autocorrection</li>
			<li>Ellipses converted to unicode “<samp>...</samp>” → “…”</li>
			<li>Accented letters title-casing properly in headings</li>
			<li>Blank line between DT &amp; DD no longer causes infinite loop</li>
			<li>Syntax language in pre fence can now contain numbers, e.g. “VB6”</li>
		</ul>
	</dd>
</dl>
<p>
	For previous history, see the <a href="/code/remarkable/change.log">changelog</a>
</p>


<h2 id="remarkable-why">Why ReMarkable?</h2>
<p>
	I have a lot of HTML. In writing and tweaking the content on this site, I found I was getting bogged down in a lot
	of HTML tags for relatively minor things, such as links, <a href="/code/using-abbr">abbreviations</a> and
	citations.
</p><p>
	Though I love writing in HTML I wanted to reduce this complexity and focus more on the content than the markup.
</p><p>
	The first place I turned to was
	<a href="http://daringfireball.net/projects/markdown/" rel="external">Markdown</a>, probably the most widely known
	plain-text formatter. John Gruber wrote Markdown for his site,
	<a href="http://daringfireball.net" rel="external">daringfireball.net</a> and to suit his way of writing articles.
</p><p>
	There were a number of shortcomings with Markdown when placed against my site:
</p>
<ul>
	<li>No support for abbreviations, citations and definition lists</li>
	<li>Perl. No hope I’d ever be able to customise it</li>
</ul>
<p>
	Working around these concerns of mine could have been possible by using another Markdown clone that would be easier
	for me to customise. A project called
	<a href="http://michelf.com/projects/php-markdown/" rel="external">PHPMarkdown</a> implements a Markdown parser in
	PHP, it also adds to the syntax, providing additions like abbreviations and definition lists.
</p><p>
	There’s one big problem with PHPMarkdown though. Its size. PHPMarkdown is almost 3’000 lines long. To include
	PHPMarkdown in my site would be like strapping an elephant to a flea and asking it to jump a canyon.
</p><p>
	Really then, what I knew I had to do was to write my own Markdown clone, in my own particular demeanour. I could
	cherry-pick the best syntax I wanted but ultimately make it as artful as Camen Design is itself.
</p>


<h2 id="remarkable-features">Features</h2>
<p>
	At a glance, compared to Markdown, ReMarkable has:
</p>
<dl>
	<dt id="remarkable-inline">More Inline Syntax:</dt>
	<dd>
		ReMarkable adds syntax for <samp>{abbr|abbreviations}</samp>, <samp>{{dfn|definitions}}</samp>,
		<samp>~citations~</samp>, <samp>((side text))</samp>, <samp>[insertions]</samp>,
		<samp>---deletions---</samp> and <samp>«inline quotations»</samp>.
	</dd>
	<dt id="remarkable-dl">Definition lists:</dt>
	<dd>
		<p>
			The <a href="http://michelf.com/projects/php-markdown/extra/#def-list" rel="external">PHPMarkdown
			syntax</a> doesn’t allow for optional descriptions where as the HTML spec, and ReMarkable,
			does.
		</p>
		
		<pre>:: Definition Term
	Description…

:: Definition Term 2

:: Definition Term 3
	Description…</pre>
		
		<p>
			You can see this structure put to good use in <a href="/blog/stop_writing_software">this
			article</a>.
		</p>
	</dd>
	<dt id="remarkable-hid">IDs in Headings:</dt>
	<dd>
		<p>
			An idea taken from PHPMarkdown for the benefit of writing a table of contents or others linking to
			specific parts of an article, headings can have an HTML ID like so:
		</p>
	
	<pre># Heading Level 1 # (#id)

Heading Level 2 (#id2)
======================
Heading Level 3 (#id3)
----------------------</pre>
	
	</dd>
	<dt id="title-case">Automatic Title Casing of Headings:</dt>
	<dd>
		Using <a href="/code/title-case">my PHP port</a> of David Gouch’s
		<a href="http://individed.com/code/to-title-case/" rel="external"><code>toTitleCase</code></a>, headings
		are automatically correctly Title Cased by ReMarkable
	</dd>
	<dt id="toc">Automatic Table of Contents:</dt>
	<dd>
		Using the special marker “<samp>&amp;__TOC__;</samp>” ReMarkable will generate a table of contents for
		each heading after the marker that has an ID.
	</dd>
	<dt id="remarkable-links">Automatic Marking-up of Links:</dt>
	<dd>
		<p>
			Links with absolute URLs are automatically marked up with <code>rel="external"</code>.
		</p><p>
			Hyperlinks directly to a file have the <code>type="mime/type"</code> attribute added
			automatically for the most common file types. ReMarkable has an easy to modify internal list of
			these types automatically recognised.
		</p><p>
			The benefit of this is that a) you should be doing this anyway, and b) you can use CSS mime-type
			icons <a href="/code/uth2_css3-hyperlinks">like this</a>.
		</p>
	</dd>
	<dt id="remarkable-li">Intelligent List Paragraphing:</dt>
	<dd>
		<p>
			ReMarkable intelligently adds <abbr title="paragraph"><code>&lt;p&gt;</code></abbr> tags to
			<abbr title="list"><code>&lt;li&gt;</code></abbr> items.<br />
			A normal list:
		</p>
		
		<pre>•	Item 1
•	Item 2
•	Item 3</pre>
		
		<p>
			Produces:
		</p>
		
		<pre><code>&lt;ul&gt;
	&lt;li&gt;Item 1&lt;/li&gt;
	&lt;li&gt;Item 2&lt;/li&gt;
	&lt;li&gt;Item 3&lt;/li&gt;
&lt;/ul&gt;</code></pre>
		
		<p>
			If any list item contains more than one paragraph, or any other block such as another list or
			blockquote, paragraphs are automatically added.
		</p>
		
		<pre>•	Item 1
•	Lorem ipsum dolor sit amet, consectetur adipisicing elit.
	
	sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
•	Item 3</pre>
		
		<p>
			Produces:
		</p>
		
		<pre><code>&lt;ul&gt;
	&lt;li&gt;Item 1&lt;/li&gt;
	&lt;li&gt;
		&lt;p&gt;
			Lorem ipsum dolor sit amet, consectetur adipisicing elit.
		&lt;/p&gt;&lt;p&gt;
			sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
		&lt;/p&gt;
	&lt;/li&gt;
	&lt;li&gt;Item 3&lt;/li&gt;
&lt;/ul&gt;</code></pre>
		
		<p>
			But, if you put blank lines between the list items:
		</p>
		
		<pre>•	Item 1

•	Item 2

•	Item 3</pre>
		
		<p>
			ReMarkable adds paragraph tags for all list items
		</p>
		
		<pre><code>&lt;ul&gt;
	&lt;li&gt;&lt;p&gt;Item 1&lt;/p&gt;&lt;/li&gt;
	&lt;li&gt;&lt;p&gt;Item 2&lt;/p&gt;&lt;/li&gt;
	&lt;li&gt;&lt;p&gt;Item 3&lt;/p&gt;&lt;/li&gt;
&lt;/ul&gt;</code></pre>
		
		<p>
			Lastly, if a list item contains no space between the opening text, and a list within the list
			item, ReMarkable does not add the first paragraph. Why? For a table of contents list:
		</p>
		
		<pre>1.	Features
	1.1.	More Inline Syntax:
	1.2.	Definition Lists:
	…</pre>
		
		<p>
			Produces:
		</p>
		
		<pre><code>&lt;ol&gt;
	&lt;li&gt;
		Features
		&lt;ol&gt;
			&lt;li&gt;More Inline Syntax:&lt;/li&gt;
			&lt;li&gt;Definition Lists:&lt;/li&gt;
		&lt;/ol&gt;
		…
	&lt;/li&gt;
&lt;/ol&gt;</code></pre>
		
		<p>
			Notice <q>Features</q> is not wrapped in a paragraph.<br />
			ReMarkable does all of these conversion cases using only <em>one</em> regex replace.
		</p>
	</dd>
	<dt id="remarkable-output">Human Readable Output:</dt>
	<dd>
		<p>
			In order for ReMarkable to be acceptable, it had to replace my hand-written HTML.<br />
			ReMarkable outputs clean and organised HTML and does perfect word wrapping so that when you
			<a href="/code/remarkable.html5">view-source</a> you don’t have to scroll sideways.
		</p><p>
			ReMarkable can also indent the whole output to your liking, so you can fit it into your blog
			template. <code>&lt;pre&gt;</code> blocks are intelligently unindented so that your code samples
			don’t break trying to fit ReMarkable output into your site design.
		</p>
	</dd>
</dl>


<h2 id="remarkable-code">Remarkable Code</h2>
<p>
	Whilst not on exact feature parity with PHPMarkdown, ReMarkable achieves its design with very compact code.
</p><p>
	PHPMarkdown is spread across 120 functions composing two classes.<br />
	ReMarkable is nearly 600 lines long in just one function (and heavily commented).
</p><p>
	Lists, definition lists and blockquotes are recursively converted (including all the conversion cases mentioned
	above) in two lines of code. Needless to say, the regex kills a kitten each time you run ReMarkable.
</p><p>
	<a href="/code/remarkable/remarkable.php">ReMarkable’s code</a> has been a real labour of love. I have tried to
	make sure it is well commented, but the tricks being used to reduce the amount of looping, and to achieve all that
	it does within one function can be difficult to understand. A future
	<q><a href="/code/uth1_is-png-32bit">Under</a> <a href="/code/uth2_css3-hyperlinks">the</a>
	<a href="/code/uth5_new-website-ish">Hood</a></q> article will do a more detailed breakdown of the PHP used.
</p>


<h2 id="remarkable-next">What’s Next?</h2>
<p>
	The goal with ReMarkable was to be able to publish my entire site’s contents. That has been achieved.
</p><p>
	Now ReMarkable is in your hands. I’m sure you’ll find a million bugs I never noticed. I don’t write articles
	the same way you do. Send bugs and suggestions to <a href="mailto:kroc@camendesign.com">kroc@camendesign.com</a>.
</p>


<h3 id="remarkable-planned">What’s Planned</h3>
<p>
	There are a number of shortcomings of ReMarkable that I’m aware of and will be tackling at various stages of the
	future (as Camen Design’s needs demand, really).
</p><p>
	Any suggestions for features, is always welcome. That said however, ReMarkable was not designed to ever be all
	things to all people. In accepting suggestions and fixes into my version of the code, these are ReMarkable’s
	priorities:
</p>
<dl>
	<dt>HTML5, UTF-8. No classes</dt>
	<dd>
		If you need every HTML tag to have a class or ID you need to learn <a href="/code/how_to_learn_html5">how
		to write better code</a>.
	</dd>
	<dt>Sloppy writing is not a fringe case</dt>
	<dd>
		<p>
			ReMarkable will never allow escaping of characters. That’s a cop out to avoid properly designing
			the syntax. Any weird text you’re writing that’s firing off ReMarkable syntax is more than
			likely a computer term or technical quote and should be wrapped in <code>`code`</code> spans.
		</p><p>
			If the bug can be solved by following the syntax documentation correctly, or by changing two or
			three letters in your source, then it’s not a bug.
		</p>
	</dd>
	<dt>Code is Art</dt>
	<dd>
		If I can’t maintain elegance and beauty in the code then it can’t be worth it.
	</dd>
</dl>
<p>
	Enjoy.
</p>
</section>
<!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -->
</article>
<footer>
	<nav><a href="http://forum.camendesign.com">‹ Discuss this in the Forum ›</a></nav>
		
	<a href="mailto:kroc@camendesign.com">kroc@camendesign.com</a>
	<nav>view-source:
		<a href="/code/remarkable.rem">Rem</a> •
		<a href="/code/remarkable.html">HTML</a> •
		<a href="/design/">CSS</a> •
		<a href="/.system/">PHP</a> •
		<a href="/.htaccess">.htaccess</a>
	</nav>
	<form method="get" action="https://duckduckgo.com">
		<input type="hidden" name="sites" value="camendesign.com" />
		<input type="search" name="q" placeholder="search…" />
		<input type="submit" value="Go" />
	</form>
</footer>
<!-- =================================================================================================== code is art === -->