set (My_Project_Title "MultiMarkdown")
set (My_Project_Description "Lightweight markup processor to produce HTML, LaTeX, and more.")
set (My_Project_Author "Fletcher T. Penney")
-set (My_Project_Revised_Date "2018-02-05")
+set (My_Project_Revised_Date "2018-03-27")
set (My_Project_Version_Major 6)
set (My_Project_Version_Minor 3)
-set (My_Project_Version_Patch 0)
+set (My_Project_Version_Patch 1)
set (My_Project_Version "${My_Project_Version_Major}.${My_Project_Version_Minor}.${My_Project_Version_Patch}")
<text:p text:style-name="TOC_Item"><text:a xlink:type="simple" xlink:href="#tableofcontents" text:style-name="Index_20_Link" text:visited-style-name="Index_20_Link">Table of Contents <text:tab/>1</text:a></text:p>
<text:p text:style-name="TOC_Item"><text:a xlink:type="simple" xlink:href="#tables" text:style-name="Index_20_Link" text:visited-style-name="Index_20_Link">Tables <text:tab/>1</text:a></text:p>
<text:p text:style-name="TOC_Item"><text:a xlink:type="simple" xlink:href="#transclusion" text:style-name="Index_20_Link" text:visited-style-name="Index_20_Link">Transclusion <text:tab/>1</text:a></text:p>
+<text:p text:style-name="TOC_Item"><text:a xlink:type="simple" xlink:href="#developernotes" text:style-name="Index_20_Link" text:visited-style-name="Index_20_Link">Developer Notes <text:tab/>1</text:a></text:p>
+<text:p text:style-name="TOC_Item"><text:a xlink:type="simple" xlink:href="#objectpools" text:style-name="Index_20_Link" text:visited-style-name="Index_20_Link">Object Pools <text:tab/>1</text:a></text:p>
+<text:p text:style-name="TOC_Item"><text:a xlink:type="simple" xlink:href="#htmlbooleanattributes" text:style-name="Index_20_Link" text:visited-style-name="Index_20_Link">HTML Boolean Attributes <text:tab/>1</text:a></text:p>
<text:p text:style-name="TOC_Item"><text:a xlink:type="simple" xlink:href="#futuresteps" text:style-name="Index_20_Link" text:visited-style-name="Index_20_Link">Future Steps <text:tab/>1</text:a></text:p>
</text:index-body>
</text:table-of-content>
This can be useful when a particular file can either be a standalone document,
or a chapter inside a larger document.</text:p>
+<text:h text:outline-level="3"><text:bookmark text:name="developernotes"/>Developer Notes </text:h>
+
+<text:p text:style-name="Standard">If you’re using MMD as a library in another application, there are a few
+things to be aware of.</text:p>
+
+<text:h text:outline-level="4"><text:bookmark text:name="objectpools"/>Object Pools </text:h>
+
+<text:p text:style-name="Standard">To improve performance, MMD has the option to allocate the memory for the
+tokens used in parsing in large chunks (“object pools”). Allocating a single
+large chunk of memory is more efficient than allocating many smaller chunks.
+However, this does complicate memory management.</text:p>
+
+<text:p text:style-name="Standard">By default <text:span text:style-name="Source_20_Text">token.h</text:span> defines <text:span text:style-name="Source_20_Text">kUseObjectPool</text:span> which enables this performance
+improvement. This does require more caution with the way that memory is
+managed. (See <text:span text:style-name="Source_20_Text">main.c</text:span> for an example of how the object pool is allocated and
+drained.) I recommend disabling object pools unless you really understand C
+memory management, and understand MultiMarkdown’s program flow. Failure to
+properly manage the object pool can lead to massive memory leaks, freeing
+memory before that is still in use, or other potential problems.</text:p>
+
+<text:h text:outline-level="4"><text:bookmark text:name="htmlbooleanattributes"/>HTML Boolean Attributes </text:h>
+
+<text:p text:style-name="Standard">Most HTML attributes are of the key-value type (e.g. <text:span text:style-name="Source_20_Text">key="value"</text:span>). But some
+less frequently used attributes are boolean attributes (e.g. <text:span text:style-name="Source_20_Text"><video<text:line-break/>controls></text:span>). Properly distinguishing HTML from other uses of the <text:span text:style-name="Source_20_Text"><</text:span>
+character requires matching both types under certain circumstances.</text:p>
+
+<text:p text:style-name="Standard">There are some trade-offs to be made:</text:p>
+
+<text:list text:style-name="L1">
+<text:list-item>
+<text:p text:style-name="Standard">Performance when compiling MultiMarkdown</text:p></text:list-item>
+
+<text:list-item>
+<text:p text:style-name="Standard">Performance when processing parts of documents that are <text:span text:style-name="MMD-Italic">not</text:span> HTML</text:p></text:list-item>
+
+<text:list-item>
+<text:p text:style-name="Standard">Accuracy when matching HTML</text:p></text:list-item>
+
+</text:list>
+
+<text:p text:style-name="Standard">So far, there seem to be four main approaches:</text:p>
+
+<text:list text:style-name="L1">
+<text:list-item>
+<text:p text:style-name="Standard">Ignore boolean attributes – this is how MMD-6 started. This is fast, but
+not accurate for some users. Several users found issues with the <text:span text:style-name="Source_20_Text"><video></text:span> tag
+when MMD was used in HTML heavy documents.</text:p></text:list-item>
+
+<text:list-item>
+<text:p text:style-name="Standard">Use regexp to match all boolean attributes. This is fast to compile, but
+adds roughly 5–8% processing time (probably due to false positive HTML
+matches). This <text:span text:style-name="MMD-Italic">may</text:span> cause some text to be classified as HTML when it
+shouldn’t.</text:p></text:list-item>
+
+<text:list-item>
+<text:p text:style-name="Standard">Explicitly match all possible boolean attributes – This would presumably be
+relatively fast when processing (due to the nature of re2c lexers), but it may
+be prohibitively slow to compile for some users. As someone who compiles MMD
+frequently, it is too slow to compile be useful for me during development.</text:p></text:list-item>
+
+<text:list-item>
+<text:p text:style-name="Standard">Use a hand-curated list of boolean attributes that are most commonly used –
+this does not incur much of a performance hit when parsing, and compiles
+faster than the complete list of all boolean attributes. For now, this is the
+option I have chosen as default for MMD – it seems to be a reasonable trade-
+off. I will continue to research additional options.</text:p></text:list-item>
+
+</text:list>
+
<text:h text:outline-level="3"><text:bookmark text:name="futuresteps"/>Future Steps </text:h>
<text:p text:style-name="Standard">Some features I plan to implement at some point:</text:p>
<li><a href="#transclusion">Transclusion </a></li>
</ul>
</li>
+<li><a href="#developernotes">Developer Notes </a>
+<ul>
+<li><a href="#objectpools">Object Pools </a></li>
+<li><a href="#htmlbooleanattributes">HTML Boolean Attributes </a></li>
+</ul>
+</li>
<li><a href="#futuresteps">Future Steps </a></li>
</ul>
</div>
This can be useful when a particular file can either be a standalone document,
or a chapter inside a larger document.</p>
+<h3 id="developernotes">Developer Notes </h3>
+
+<p>If you’re using <abbr title="MultiMarkdown">MMD</abbr> as a library in another application, there are a few
+things to be aware of.</p>
+
+<h4 id="objectpools">Object Pools </h4>
+
+<p>To improve performance, <abbr title="MultiMarkdown">MMD</abbr> has the option to allocate the memory for the
+tokens used in parsing in large chunks (“object pools”). Allocating a single
+large chunk of memory is more efficient than allocating many smaller chunks.
+However, this does complicate memory management.</p>
+
+<p>By default <code>token.h</code> defines <code>kUseObjectPool</code> which enables this performance
+improvement. This does require more caution with the way that memory is
+managed. (See <code>main.c</code> for an example of how the object pool is allocated and
+drained.) I recommend disabling object pools unless you really understand C
+memory management, and understand MultiMarkdown’s program flow. Failure to
+properly manage the object pool can lead to massive memory leaks, freeing
+memory before that is still in use, or other potential problems.</p>
+
+<h4 id="htmlbooleanattributes">HTML Boolean Attributes </h4>
+
+<p>Most HTML attributes are of the key-value type (e.g. <code>key="value"</code>). But some
+less frequently used attributes are boolean attributes (e.g. <code><video
+controls></code>). Properly distinguishing HTML from other uses of the <code><</code>
+character requires matching both types under certain circumstances.</p>
+
+<p>There are some trade-offs to be made:</p>
+
+<ul>
+<li><p>Performance when compiling MultiMarkdown</p></li>
+<li><p>Performance when processing parts of documents that are <em>not</em> HTML</p></li>
+<li><p>Accuracy when matching HTML</p></li>
+</ul>
+
+<p>So far, there seem to be four main approaches:</p>
+
+<ul>
+<li><p>Ignore boolean attributes – this is how <abbr title="MultiMarkdown">MMD</abbr>-6 started. This is fast, but
+not accurate for some users. Several users found issues with the <code><video></code> tag
+when <abbr title="MultiMarkdown">MMD</abbr> was used in HTML heavy documents.</p></li>
+<li><p>Use regexp to match all boolean attributes. This is fast to compile, but
+adds roughly 5–8% processing time (probably due to false positive HTML
+matches). This <em>may</em> cause some text to be classified as HTML when it
+shouldn’t.</p></li>
+<li><p>Explicitly match all possible boolean attributes – This would presumably be
+relatively fast when processing (due to the nature of re2c lexers), but it may
+be prohibitively slow to compile for some users. As someone who compiles <abbr title="MultiMarkdown">MMD</abbr>
+frequently, it is too slow to compile be useful for me during development.</p></li>
+<li><p>Use a hand-curated list of boolean attributes that are most commonly used –
+this does not incur much of a performance hit when parsing, and compiles
+faster than the complete list of all boolean attributes. For now, this is the
+option I have chosen as default for <abbr title="MultiMarkdown">MMD</abbr> – it seems to be a reasonable trade-
+off. I will continue to research additional options.</p></li>
+</ul>
+
<h3 id="futuresteps">Future Steps </h3>
<p>Some features I plan to implement at some point:</p>
| ---------- | ------------------------- |
| Title: | MultiMarkdown |
| Author: | Fletcher T. Penney |
-| Date: | 2018-02-05 |
+| Date: | 2018-03-27 |
| Copyright: | Copyright © 2016 - 2018 Fletcher T. Penney. |
-| Version: | 6.3.0 |
+| Version: | 6.3.1 |
master branch: [](https://travis-ci.org/fletcher/MultiMarkdown-6)
develop branch: [](https://travis-ci.org/fletcher/MultiMarkdown-6)
projects / multimarkdown / commitdiff