fletcher/MultiMarkdown-6
1
1
Fork 0
mirror of https://github.com/fletcher/MultiMarkdown-6.git synced 2024-10-04 10:37:08 +03:00
Code Issues Projects Releases Wiki Activity

version bump

Browse Source
This commit is contained in:
Fletcher T. Penney 2018-09-01 16:00:33 -04:00
parent ae0d673777
commit efaee1318e
12 changed files with 356 additions and 109 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
CMakeLists.txt
View File

@ -8,10 +8,10 @@ cmake_minimum_required (VERSION 2.6)
set (My_Project_Title "MultiMarkdown") set (My_Project_Title "MultiMarkdown")
set (My_Project_Description "Lightweight markup processor to produce HTML, LaTeX, and more.") set (My_Project_Description "Lightweight markup processor to produce HTML, LaTeX, and more.")
set (My_Project_Author "Fletcher T. Penney") set (My_Project_Author "Fletcher T. Penney")
set (My_Project_Revised_Date "2018-03-28") set (My_Project_Revised_Date "2018-09-01")
set (My_Project_Version_Major 6) set (My_Project_Version_Major 6)
set (My_Project_Version_Minor 3) set (My_Project_Version_Minor 4)
set (My_Project_Version_Patch 2) set (My_Project_Version_Patch 0)
set (My_Project_Version "${My_Project_Version_Major}.${My_Project_Version_Minor}.${My_Project_Version_Patch}") set (My_Project_Version "${My_Project_Version_Major}.${My_Project_Version_Minor}.${My_Project_Version_Patch}")

BIN
DevelopmentNotes/DevelopmentNotes.epub
View File

Binary file not shown.

193
DevelopmentNotes/DevelopmentNotes.fodt
View File

@ -276,19 +276,19 @@ office:mimetype="application/vnd.oasis.opendocument.text">
<office:meta> <office:meta>
<dc:title>MultiMarkdown v6 Development Notes</dc:title> <dc:title>MultiMarkdown v6 Development Notes</dc:title>
<dc:creator>Fletcher T. Penney</dc:creator> <dc:creator>Fletcher T. Penney</dc:creator>
<meta:user-defined meta:name="date">2018-03-38</meta:user-defined> <meta:user-defined meta:name="date">2018-09-01</meta:user-defined>
<meta:user-defined meta:name="uuid">dd2d8e76-dc2d-416d-9acd-5395d20871c2</meta:user-defined> <meta:user-defined meta:name="uuid">dd2d8e76-dc2d-416d-9acd-5395d20871c2</meta:user-defined>
</office:meta> </office:meta>
<office:body> <office:body>
<office:text> <office:text>
<text:h text:outline-level="3"><text:bookmark text:name="introduction"/>Introduction </text:h> <text:h text:outline-level="3"><text:bookmark text:name="introduction"/>Introduction</text:h>
<text:p text:style-name="Standard">This document includes some notes on the development of MultiMarkdown (MMD) v6. Most of it <text:p text:style-name="Standard">This document includes some notes on the development of MultiMarkdown (MMD) v6. Most of it
will be interesting only to other developers or those needing to choose the will be interesting only to other developers or those needing to choose the
absolute &#8220;best&#8221; Markdown (MD) implementation for their needs &#8211; it is not required absolute &#8220;best&#8221; Markdown (MD) implementation for their needs &#8211; it is not required
reading to understand how the software works.</text:p> reading to understand how the software works.</text:p>
<text:h text:outline-level="4"><text:bookmark text:name="whyanewversion"/>Why a New Version? </text:h> <text:h text:outline-level="4"><text:bookmark text:name="whyanewversion"/>Why a New Version?</text:h>
<text:p text:style-name="Standard">MultiMarkdown version 5 was released in November of 2015, but the codebase was <text:p text:style-name="Standard">MultiMarkdown version 5 was released in November of 2015, but the codebase was
essentially the same as that of v4 &#8211; and that was released in beta in April essentially the same as that of v4 &#8211; and that was released in beta in April
@ -319,7 +319,7 @@ had been using <text:a xlink:type="simple" xlink:href="https://github.com/ooc-la
into parser code. It worked well overall, but lacked some features I needed, into parser code. It worked well overall, but lacked some features I needed,
requiring a lot of workarounds.)</text:p> requiring a lot of workarounds.)</text:p>
<text:h text:outline-level="3"><text:bookmark text:name="firstattempt"/>First Attempt </text:h> <text:h text:outline-level="3"><text:bookmark text:name="firstattempt"/>First Attempt</text:h>
<text:p text:style-name="Standard">My first attempt started by hand-crafting a parser that scanned through the <text:p text:style-name="Standard">My first attempt started by hand-crafting a parser that scanned through the
document a line at a time, deciding what to do with each line as it found document a line at a time, deciding what to do with each line as it found
@ -449,7 +449,7 @@ don&#8217;t follow the rules above. I&#8217;ll continue to work on this.</text:p
<text:p text:style-name="Standard">In the end, I scrapped this effort, but kept the lessons learned in the token <text:p text:style-name="Standard">In the end, I scrapped this effort, but kept the lessons learned in the token
pairing algorithm.</text:p> pairing algorithm.</text:p>
<text:h text:outline-level="3"><text:bookmark text:name="secondattempt"/>Second Attempt </text:h> <text:h text:outline-level="3"><text:bookmark text:name="secondattempt"/>Second Attempt</text:h>
<text:p text:style-name="Standard">I tried again this past Fall. This time, I approached the problem with lots <text:p text:style-name="Standard">I tried again this past Fall. This time, I approached the problem with lots
of reading. <text:span text:style-name="MMD-Italic">Lots and lots</text:span> of reading &#8211; tons of websites, computer science of reading. <text:span text:style-name="MMD-Italic">Lots and lots</text:span> of reading &#8211; tons of websites, computer science
@ -517,13 +517,13 @@ anyway, if not better.</text:p>
about how to create the grammar used. But so far, it has been able to handle about how to create the grammar used. But so far, it has been able to handle
everything I have thrown at it.</text:p> everything I have thrown at it.</text:p>
<text:h text:outline-level="3"><text:bookmark text:name="optimization"/>Optimization </text:h> <text:h text:outline-level="3"><text:bookmark text:name="optimization"/>Optimization</text:h>
<text:p text:style-name="Standard">One of my goals for MMD 6 was performance. So I&#8217;ve paid attention to speed <text:p text:style-name="Standard">One of my goals for MMD 6 was performance. So I&#8217;ve paid attention to speed
along the way, and have tried to use a few tricks to keep things fast. Here along the way, and have tried to use a few tricks to keep things fast. Here
are some things I&#8217;ve learned along the way. In no particular order:</text:p> are some things I&#8217;ve learned along the way. In no particular order:</text:p>
<text:h text:outline-level="4"><text:bookmark text:name="memoryallocation"/>Memory Allocation </text:h> <text:h text:outline-level="4"><text:bookmark text:name="memoryallocation"/>Memory Allocation</text:h>
<text:p text:style-name="Standard">When parsing a long document, a <text:span text:style-name="MMD-Italic">lot</text:span> of token structures are created. Each <text:p text:style-name="Standard">When parsing a long document, a <text:span text:style-name="MMD-Italic">lot</text:span> of token structures are created. Each
one requires a small bit of memory to be allocated. In aggregate, that time one requires a small bit of memory to be allocated. In aggregate, that time
@ -552,7 +552,7 @@ reduces the number of tokens that need to be processed later on. The only
downside is remember to check for a single space character in a few instances downside is remember to check for a single space character in a few instances
where it matters.</text:p> where it matters.</text:p>
<text:h text:outline-level="4"><text:bookmark text:name="properinputbuffering"/>Proper input buffering </text:h> <text:h text:outline-level="4"><text:bookmark text:name="properinputbuffering"/>Proper input buffering</text:h>
<text:p text:style-name="Standard">When I first began last spring, I was amazed to see how much time was being <text:p text:style-name="Standard">When I first began last spring, I was amazed to see how much time was being
spent by MultiMarkdown simply reading the input file. Then I discovered it spent by MultiMarkdown simply reading the input file. Then I discovered it
@ -561,14 +561,14 @@ buffered read approach and the time to read the file went to almost nothing. I
experimented with different buffer sizes, but they did not seem to make a experimented with different buffer sizes, but they did not seem to make a
measurable difference.</text:p> measurable difference.</text:p>
<text:h text:outline-level="4"><text:bookmark text:name="outputbuffering"/>Output Buffering </text:h> <text:h text:outline-level="4"><text:bookmark text:name="outputbuffering"/>Output Buffering</text:h>
<text:p text:style-name="Standard">I experimented with different approaches to creating the output after parsing. <text:p text:style-name="Standard">I experimented with different approaches to creating the output after parsing.
I tried printing directly to <text:span text:style-name="Source_20_Text">stdout</text:span>, and even played with different I tried printing directly to <text:span text:style-name="Source_20_Text">stdout</text:span>, and even played with different
buffering settings. None of those seemed to work well, and all were slower buffering settings. None of those seemed to work well, and all were slower
than using the <text:span text:style-name="Source_20_Text">d_string</text:span> approach (formerly called <text:span text:style-name="Source_20_Text">GString</text:span> in MMD 5).</text:p> than using the <text:span text:style-name="Source_20_Text">d_string</text:span> approach (formerly called <text:span text:style-name="Source_20_Text">GString</text:span> in MMD 5).</text:p>
<text:h text:outline-level="4"><text:bookmark text:name="fastsearches"/>Fast Searches </text:h> <text:h text:outline-level="4"><text:bookmark text:name="fastsearches"/>Fast Searches</text:h>
<text:p text:style-name="Standard">After getting basic Markdown functionality complete, I discovered during <text:p text:style-name="Standard">After getting basic Markdown functionality complete, I discovered during
testing that the time required to parse a document grew exponentially as the testing that the time required to parse a document grew exponentially as the
@ -583,7 +583,7 @@ a link (or footnote, etc.) by &#8220;name&#8221; rather than searching through a
This allowed me to get MMD&#8217;s performance back to O(n), taking roughly twice as This allowed me to get MMD&#8217;s performance back to O(n), taking roughly twice as
much time to process a document that is twice as long.</text:p> much time to process a document that is twice as long.</text:p>
<text:h text:outline-level="4"><text:bookmark text:name="efficientutilityfunctions"/>Efficient Utility Functions </text:h> <text:h text:outline-level="4"><text:bookmark text:name="efficientutilityfunctions"/>Efficient Utility Functions</text:h>
<text:p text:style-name="Standard">It is frequently necessary when parsing Markdown to check what sort of <text:p text:style-name="Standard">It is frequently necessary when parsing Markdown to check what sort of
character we are dealing with at a certain position &#8211; a letter, whitespace, character we are dealing with at a certain position &#8211; a letter, whitespace,
@ -594,7 +594,7 @@ programming time, and saved time tracking down bugs from handling things
slightly differently under different circumstances. I also suspect it slightly differently under different circumstances. I also suspect it
improved performance, but don&#8217;t have the data to back it up.</text:p> improved performance, but don&#8217;t have the data to back it up.</text:p>
<text:h text:outline-level="4"><text:bookmark text:name="testingwhilewriting"/>Testing While Writing </text:h> <text:h text:outline-level="4"><text:bookmark text:name="testingwhilewriting"/>Testing While Writing</text:h>
<text:p text:style-name="Standard">I developed several chunks of code in parallel while creating MMD 6. The vast <text:p text:style-name="Standard">I developed several chunks of code in parallel while creating MMD 6. The vast
majority of it was developed largely in a <text:a xlink:type="simple" xlink:href="https://en.wikipedia.org/wiki/Test-driven_development">test-driven development</text:a> approach. majority of it was developed largely in a <text:a xlink:type="simple" xlink:href="https://en.wikipedia.org/wiki/Test-driven_development">test-driven development</text:a> approach.
@ -608,7 +608,7 @@ allowed me to ensure new features work properly and that old features aren&#8217
broken. At this time, there are 29 text files in the test suite, and many broken. At this time, there are 29 text files in the test suite, and many
more to come.</text:p> more to come.</text:p>
<text:h text:outline-level="4"><text:bookmark text:name="otherlessons"/>Other Lessons </text:h> <text:h text:outline-level="4"><text:bookmark text:name="otherlessons"/>Other Lessons</text:h>
<text:p text:style-name="Standard">Some things that didn&#8217;t do me any good&#8230;.</text:p> <text:p text:style-name="Standard">Some things that didn&#8217;t do me any good&#8230;.</text:p>
@ -626,7 +626,7 @@ automatically, there was no noticeable performance change, and I didn&#8217;t ha
the tools to measure whether I could have improved memory usage at all. Not the tools to measure whether I could have improved memory usage at all. Not
sure this would be worth the effort &#8211; much lower hanging fruit available.</text:p> sure this would be worth the effort &#8211; much lower hanging fruit available.</text:p>
<text:h text:outline-level="3"><text:bookmark text:name="performance"/>Performance </text:h> <text:h text:outline-level="3"><text:bookmark text:name="performance"/>Performance</text:h>
<text:p text:style-name="Standard">Basic tests show that currently MMD 6 takes about 20&#8211;25% longer the CommonMark <text:p text:style-name="Standard">Basic tests show that currently MMD 6 takes about 20&#8211;25% longer the CommonMark
0.27.0 to process long files (e.g. 0.2 MB). However, it is around 5% <text:span text:style-name="MMD-Italic">faster</text:span> 0.27.0 to process long files (e.g. 0.2 MB). However, it is around 5% <text:span text:style-name="MMD-Italic">faster</text:span>
@ -667,9 +667,9 @@ more challenging and see whether they can be reworked to improve performance.</t
I&#8217;m sure there&#8217;s still a lot of room for further improvement to be made. I&#8217;m sure there&#8217;s still a lot of room for further improvement to be made.
Suggestions welcome!</text:p> Suggestions welcome!</text:p>
<text:h text:outline-level="3"><text:bookmark text:name="testing"/>Testing </text:h> <text:h text:outline-level="3"><text:bookmark text:name="testing"/>Testing</text:h>
<text:h text:outline-level="4"><text:bookmark text:name="testsuite"/>Test Suite </text:h> <text:h text:outline-level="4"><text:bookmark text:name="testsuite"/>Test Suite</text:h>
<text:p text:style-name="Standard">The development of MMD v6 was heavily, but not absolutely, influenced by the <text:p text:style-name="Standard">The development of MMD v6 was heavily, but not absolutely, influenced by the
philosophy of test-driven development. While coding, I made use of test philosophy of test-driven development. While coding, I made use of test
@ -682,7 +682,7 @@ documents that will continue to be updated as new bugs and edge cases are
identified. This helps make proper integration testing of the entire identified. This helps make proper integration testing of the entire
application with every release.</text:p> application with every release.</text:p>
<text:h text:outline-level="4"><text:bookmark text:name="fuzztesting"/>Fuzz Testing </text:h> <text:h text:outline-level="4"><text:bookmark text:name="fuzztesting"/>Fuzz Testing</text:h>
<text:p text:style-name="Standard">I was not familiar with the concept of <text:p text:style-name="Standard">I was not familiar with the concept of
<text:a xlink:type="simple" xlink:href="https://en.wikipedia.org/wiki/Fuzzing">Fuzz Testing</text:a> until a user mentioned <text:a xlink:type="simple" xlink:href="https://en.wikipedia.org/wiki/Fuzzing">Fuzz Testing</text:a> until a user mentioned
@ -710,7 +710,7 @@ versions. Do this over and over and over, and some interesting edge cases are
sometimes identified. I have found some interesting edge cases this way. sometimes identified. I have found some interesting edge cases this way.
Definitely a useful tool!</text:p> Definitely a useful tool!</text:p>
<text:h text:outline-level="4"><text:bookmark text:name="unittesting"/>Unit Testing </text:h> <text:h text:outline-level="4"><text:bookmark text:name="unittesting"/>Unit Testing</text:h>
<text:p text:style-name="Standard">Some of the original development was done with unit testing in some other <text:p text:style-name="Standard">Some of the original development was done with unit testing in some other
tools I developed. This code formed the basis of a few parts of MMD. tools I developed. This code formed the basis of a few parts of MMD.
@ -718,7 +718,7 @@ Otherwise, it was hard to see how to really create very good unit tests for
the development of MMD. So there is really not much unit testing built into the development of MMD. So there is really not much unit testing built into
the code or used during the development.</text:p> the code or used during the development.</text:p>
<text:h text:outline-level="3"><text:bookmark text:name="dependencieslibraries"/>Dependencies/Libraries </text:h> <text:h text:outline-level="3"><text:bookmark text:name="dependencieslibraries"/>Dependencies/Libraries</text:h>
<text:p text:style-name="Standard">MMD v6 has no external dependencies when compiling, aside from the standard <text:p text:style-name="Standard">MMD v6 has no external dependencies when compiling, aside from the standard
libraries for C development (Except that it will use <text:span text:style-name="Source_20_Text">libcurl</text:span> if available in libraries for C development (Except that it will use <text:span text:style-name="Source_20_Text">libcurl</text:span> if available in
@ -760,9 +760,162 @@ TextBundle/TextPack, OpenDocument, etc.</text:p></text:list-item>
</text:list> </text:list>
<text:h text:outline-level="3"><text:bookmark text:name="changelog"/>Changelog </text:h> <text:h text:outline-level="3"><text:bookmark text:name="changelog"/>Changelog</text:h>
<text:list text:style-name="L1"> <text:list text:style-name="L1">
<text:list-item>
<text:p text:style-name="Standard">2018&#8211;09&#8211;01 - v 6.4.0:</text:p>
<text:list text:style-name="L1">
<text:list-item>
<text:p text:style-name="P1">
ADDED: Add ODF Header metadata and fix issue with LaTeX Header metadata</text:p></text:list-item>
<text:list-item>
<text:p text:style-name="P1">
ADDED: Add additional tests for special characters</text:p></text:list-item>
<text:list-item>
<text:p text:style-name="P1">
ADDED: Add initial OPML export support (address #9)</text:p></text:list-item>
<text:list-item>
<text:p text:style-name="P1">
ADDED: Add opml option to read for MultiMarkdown OPML files</text:p></text:list-item>
<text:list-item>
<text:p text:style-name="P1">
Add missing Latex support files</text:p></text:list-item>
<text:list-item>
<text:p text:style-name="P1">
Avoid potential error with stack_free</text:p></text:list-item>
<text:list-item>
<text:p text:style-name="P1">
CHANGED: Remove unnecessary code</text:p></text:list-item>
<text:list-item>
<text:p text:style-name="P1">
FIXED: Allow caption without trailing newline at end of document</text:p></text:list-item>
<text:list-item>
<text:p text:style-name="P1">
FIXED: Escape square brackets, e.g. &#8216;{[foo]}&#8217; (addresses #128 and #129)</text:p></text:list-item>
<text:list-item>
<text:p text:style-name="P1">
FIXED: Fix escpaing of % character in LaTeX code spans and blocks</text:p></text:list-item>
<text:list-item>
<text:p text:style-name="P1">
FIXED: Fix html comments inside code blocks (fixes #118)</text:p></text:list-item>
<text:list-item>
<text:p text:style-name="P1">
FIXED: Fix issue where <text:span text:style-name="Source_20_Text">~</text:span> is mistakenly interpreted as fence delimiter</text:p></text:list-item>
<text:list-item>
<text:p text:style-name="P1">
FIXED: Fix issue with BOM and files &gt; 4k</text:p></text:list-item>
<text:list-item>
<text:p text:style-name="P1">
FIXED: Fix issue with dollar math delimiters inside code (fixes #134)</text:p></text:list-item>
<text:list-item>
<text:p text:style-name="P1">
FIXED: Fix token length in OPML</text:p></text:list-item>
<text:list-item>
<text:p text:style-name="P1">
FIXED: Improve OPML export; add OPML tests</text:p></text:list-item>
<text:list-item>
<text:p text:style-name="P1">
FIXED: Normalize line spacing in CriticMarkup notes in LaTeX (fixes #120)</text:p></text:list-item>
<text:list-item>
<text:p text:style-name="P1">
FIXED: Preserve tabs following leading hashes in code blocks</text:p></text:list-item>
<text:list-item>
<text:p text:style-name="P1">
FIXED: Prevent potential null dereference</text:p></text:list-item>
<text:list-item>
<text:p text:style-name="P1">
FIXED: Remove lock file</text:p></text:list-item>
<text:list-item>
<text:p text:style-name="P1">
FIXED: Trim single remaining whitespace when exporting headers</text:p></text:list-item>
<text:list-item>
<text:p text:style-name="P1">
FIXED: Trim trailing newlines in definition blocks</text:p></text:list-item>
<text:list-item>
<text:p text:style-name="P1">
FIXED: Use Setext headers when necessary to convert from OPML to text (fixes #138)</text:p></text:list-item>
<text:list-item>
<text:p text:style-name="P1">
FIXED: Use \ul instead of \underline when soul package is in use (fixes #121)</text:p></text:list-item>
<text:list-item>
<text:p text:style-name="P1">
Merge pull request #132 from jlargentaye/develop</text:p></text:list-item>
<text:list-item>
<text:p text:style-name="P1">
UPDATE: Clarify DevelopmentNotes re: libcurl</text:p></text:list-item>
<text:list-item>
<text:p text:style-name="P1">
UPDATE: Clarify README re: libcurl</text:p></text:list-item>
<text:list-item>
<text:p text:style-name="P1">
UPDATED: &#8216;\item{}&#8217; no longer needed since square brackets escaped on their own</text:p></text:list-item>
<text:list-item>
<text:p text:style-name="P1">
UPDATED: Add 6.3.1 release notes</text:p></text:list-item>
<text:list-item>
<text:p text:style-name="P1">
UPDATED: Add allowfullscreen to list of boolean HTML attributes</text:p></text:list-item>
<text:list-item>
<text:p text:style-name="P1">
UPDATED: Add more BibTeX test cases</text:p></text:list-item>
<text:list-item>
<text:p text:style-name="P1">
UPDATED: Adjust metadata for test files</text:p></text:list-item>
<text:list-item>
<text:p text:style-name="P1">
UPDATED: Allow '' to preserve line break in metadata. (Addresses #86)</text:p></text:list-item>
<text:list-item>
<text:p text:style-name="P1">
UPDATED: Apply astyle</text:p></text:list-item>
<text:list-item>
<text:p text:style-name="P1">
UPDATED: Fix whitespace with boolean HTML attributes</text:p></text:list-item>
<text:list-item>
<text:p text:style-name="P1">
UPDATED: Ignore escaped space at end of code span</text:p></text:list-item>
<text:list-item>
<text:p text:style-name="Standard">UPDATED: Test % escaping in URLs</text:p></text:list-item>
</text:list></text:list-item>
<text:list-item> <text:list-item>
<text:p text:style-name="Standard">2018&#8211;03&#8211;28 - v 6.3.2:</text:p> <text:p text:style-name="Standard">2018&#8211;03&#8211;28 - v 6.3.2:</text:p>

81
DevelopmentNotes/DevelopmentNotes.html
View File

@ -4,19 +4,19 @@
<meta charset="utf-8"/> <meta charset="utf-8"/>
<title>MultiMarkdown v6 Development Notes</title> <title>MultiMarkdown v6 Development Notes</title>
<meta name="author" content="Fletcher T. Penney"/> <meta name="author" content="Fletcher T. Penney"/>
<meta name="date" content="2018-03-38"/> <meta name="date" content="2018-09-01"/>
<meta name="uuid" content="dd2d8e76-dc2d-416d-9acd-5395d20871c2"/> <meta name="uuid" content="dd2d8e76-dc2d-416d-9acd-5395d20871c2"/>
</head> </head>
<body> <body>
<h3 id="introduction">Introduction </h3> <h3 id="introduction">Introduction</h3>
<p>This document includes some notes on the development of MultiMarkdown (<abbr title="MultiMarkdown">MMD</abbr>) v6. Most of it <p>This document includes some notes on the development of MultiMarkdown (<abbr title="MultiMarkdown">MMD</abbr>) v6. Most of it
will be interesting only to other developers or those needing to choose the will be interesting only to other developers or those needing to choose the
absolute &#8220;best&#8221; Markdown (<abbr title="Markdown">MD</abbr>) implementation for their needs &#8211; it is not required absolute &#8220;best&#8221; Markdown (<abbr title="Markdown">MD</abbr>) implementation for their needs &#8211; it is not required
reading to understand how the software works.</p> reading to understand how the software works.</p>
<h4 id="whyanewversion">Why a New Version? </h4> <h4 id="whyanewversion">Why a New Version?</h4>
<p>MultiMarkdown version 5 was released in November of 2015, but the codebase was <p>MultiMarkdown version 5 was released in November of 2015, but the codebase was
essentially the same as that of v4 &#8211; and that was released in beta in April essentially the same as that of v4 &#8211; and that was released in beta in April
@ -43,7 +43,7 @@ had been using <a href="https://github.com/ooc-lang/greg">greg</a> to compile th
into parser code. It worked well overall, but lacked some features I needed, into parser code. It worked well overall, but lacked some features I needed,
requiring a lot of workarounds.)</p> requiring a lot of workarounds.)</p>
<h3 id="firstattempt">First Attempt </h3> <h3 id="firstattempt">First Attempt</h3>
<p>My first attempt started by hand-crafting a parser that scanned through the <p>My first attempt started by hand-crafting a parser that scanned through the
document a line at a time, deciding what to do with each line as it found document a line at a time, deciding what to do with each line as it found
@ -137,7 +137,7 @@ don&#8217;t follow the rules above. I&#8217;ll continue to work on this.</p>
<p>In the end, I scrapped this effort, but kept the lessons learned in the token <p>In the end, I scrapped this effort, but kept the lessons learned in the token
pairing algorithm.</p> pairing algorithm.</p>
<h3 id="secondattempt">Second Attempt </h3> <h3 id="secondattempt">Second Attempt</h3>
<p>I tried again this past Fall. This time, I approached the problem with lots <p>I tried again this past Fall. This time, I approached the problem with lots
of reading. <em>Lots and lots</em> of reading &#8211; tons of websites, computer science of reading. <em>Lots and lots</em> of reading &#8211; tons of websites, computer science
@ -195,13 +195,13 @@ anyway, if not better.</p>
about how to create the grammar used. But so far, it has been able to handle about how to create the grammar used. But so far, it has been able to handle
everything I have thrown at it.</p> everything I have thrown at it.</p>
<h3 id="optimization">Optimization </h3> <h3 id="optimization">Optimization</h3>
<p>One of my goals for <abbr title="MultiMarkdown">MMD</abbr> 6 was performance. So I&#8217;ve paid attention to speed <p>One of my goals for <abbr title="MultiMarkdown">MMD</abbr> 6 was performance. So I&#8217;ve paid attention to speed
along the way, and have tried to use a few tricks to keep things fast. Here along the way, and have tried to use a few tricks to keep things fast. Here
are some things I&#8217;ve learned along the way. In no particular order:</p> are some things I&#8217;ve learned along the way. In no particular order:</p>
<h4 id="memoryallocation">Memory Allocation </h4> <h4 id="memoryallocation">Memory Allocation</h4>
<p>When parsing a long document, a <em>lot</em> of token structures are created. Each <p>When parsing a long document, a <em>lot</em> of token structures are created. Each
one requires a small bit of memory to be allocated. In aggregate, that time one requires a small bit of memory to be allocated. In aggregate, that time
@ -230,7 +230,7 @@ reduces the number of tokens that need to be processed later on. The only
downside is remember to check for a single space character in a few instances downside is remember to check for a single space character in a few instances
where it matters.</p> where it matters.</p>
<h4 id="properinputbuffering">Proper input buffering </h4> <h4 id="properinputbuffering">Proper input buffering</h4>
<p>When I first began last spring, I was amazed to see how much time was being <p>When I first began last spring, I was amazed to see how much time was being
spent by MultiMarkdown simply reading the input file. Then I discovered it spent by MultiMarkdown simply reading the input file. Then I discovered it
@ -239,14 +239,14 @@ buffered read approach and the time to read the file went to almost nothing. I
experimented with different buffer sizes, but they did not seem to make a experimented with different buffer sizes, but they did not seem to make a
measurable difference.</p> measurable difference.</p>
<h4 id="outputbuffering">Output Buffering </h4> <h4 id="outputbuffering">Output Buffering</h4>
<p>I experimented with different approaches to creating the output after parsing. <p>I experimented with different approaches to creating the output after parsing.
I tried printing directly to <code>stdout</code>, and even played with different I tried printing directly to <code>stdout</code>, and even played with different
buffering settings. None of those seemed to work well, and all were slower buffering settings. None of those seemed to work well, and all were slower
than using the <code>d_string</code> approach (formerly called <code>GString</code> in MMD 5).</p> than using the <code>d_string</code> approach (formerly called <code>GString</code> in MMD 5).</p>
<h4 id="fastsearches">Fast Searches </h4> <h4 id="fastsearches">Fast Searches</h4>
<p>After getting basic Markdown functionality complete, I discovered during <p>After getting basic Markdown functionality complete, I discovered during
testing that the time required to parse a document grew exponentially as the testing that the time required to parse a document grew exponentially as the
@ -261,7 +261,7 @@ a link (or footnote, etc.) by &#8220;name&#8221; rather than searching through a
This allowed me to get <abbr title="MultiMarkdown">MMD</abbr>&#8217;s performance back to O(n), taking roughly twice as This allowed me to get <abbr title="MultiMarkdown">MMD</abbr>&#8217;s performance back to O(n), taking roughly twice as
much time to process a document that is twice as long.</p> much time to process a document that is twice as long.</p>
<h4 id="efficientutilityfunctions">Efficient Utility Functions </h4> <h4 id="efficientutilityfunctions">Efficient Utility Functions</h4>
<p>It is frequently necessary when parsing Markdown to check what sort of <p>It is frequently necessary when parsing Markdown to check what sort of
character we are dealing with at a certain position &#8211; a letter, whitespace, character we are dealing with at a certain position &#8211; a letter, whitespace,
@ -272,7 +272,7 @@ programming time, and saved time tracking down bugs from handling things
slightly differently under different circumstances. I also suspect it slightly differently under different circumstances. I also suspect it
improved performance, but don&#8217;t have the data to back it up.</p> improved performance, but don&#8217;t have the data to back it up.</p>
<h4 id="testingwhilewriting">Testing While Writing </h4> <h4 id="testingwhilewriting">Testing While Writing</h4>
<p>I developed several chunks of code in parallel while creating <abbr title="MultiMarkdown">MMD</abbr> 6. The vast <p>I developed several chunks of code in parallel while creating <abbr title="MultiMarkdown">MMD</abbr> 6. The vast
majority of it was developed largely in a <a href="https://en.wikipedia.org/wiki/Test-driven_development">test-driven development</a> approach. majority of it was developed largely in a <a href="https://en.wikipedia.org/wiki/Test-driven_development">test-driven development</a> approach.
@ -286,7 +286,7 @@ allowed me to ensure new features work properly and that old features aren&#8217
broken. At this time, there are 29 text files in the test suite, and many broken. At this time, there are 29 text files in the test suite, and many
more to come.</p> more to come.</p>
<h4 id="otherlessons">Other Lessons </h4> <h4 id="otherlessons">Other Lessons</h4>
<p>Some things that didn&#8217;t do me any good&#8230;.</p> <p>Some things that didn&#8217;t do me any good&#8230;.</p>
@ -304,7 +304,7 @@ automatically, there was no noticeable performance change, and I didn&#8217;t ha
the tools to measure whether I could have improved memory usage at all. Not the tools to measure whether I could have improved memory usage at all. Not
sure this would be worth the effort &#8211; much lower hanging fruit available.</p> sure this would be worth the effort &#8211; much lower hanging fruit available.</p>
<h3 id="performance">Performance </h3> <h3 id="performance">Performance</h3>
<p>Basic tests show that currently <abbr title="MultiMarkdown">MMD</abbr> 6 takes about 20&#8211;25% longer the CommonMark <p>Basic tests show that currently <abbr title="MultiMarkdown">MMD</abbr> 6 takes about 20&#8211;25% longer the CommonMark
0.27.0 to process long files (e.g. 0.2 MB). However, it is around 5% <em>faster</em> 0.27.0 to process long files (e.g. 0.2 MB). However, it is around 5% <em>faster</em>
@ -345,9 +345,9 @@ more challenging and see whether they can be reworked to improve performance.</p
I&#8217;m sure there&#8217;s still a lot of room for further improvement to be made. I&#8217;m sure there&#8217;s still a lot of room for further improvement to be made.
Suggestions welcome!</p> Suggestions welcome!</p>
<h3 id="testing">Testing </h3> <h3 id="testing">Testing</h3>
<h4 id="testsuite">Test Suite </h4> <h4 id="testsuite">Test Suite</h4>
<p>The development of <abbr title="MultiMarkdown">MMD</abbr> v6 was heavily, but not absolutely, influenced by the <p>The development of <abbr title="MultiMarkdown">MMD</abbr> v6 was heavily, but not absolutely, influenced by the
philosophy of test-driven development. While coding, I made use of test philosophy of test-driven development. While coding, I made use of test
@ -360,7 +360,7 @@ documents that will continue to be updated as new bugs and edge cases are
identified. This helps make proper integration testing of the entire identified. This helps make proper integration testing of the entire
application with every release.</p> application with every release.</p>
<h4 id="fuzztesting">Fuzz Testing </h4> <h4 id="fuzztesting">Fuzz Testing</h4>
<p>I was not familiar with the concept of <p>I was not familiar with the concept of
<a href="https://en.wikipedia.org/wiki/Fuzzing">Fuzz Testing</a> until a user mentioned <a href="https://en.wikipedia.org/wiki/Fuzzing">Fuzz Testing</a> until a user mentioned
@ -388,7 +388,7 @@ versions. Do this over and over and over, and some interesting edge cases are
sometimes identified. I have found some interesting edge cases this way. sometimes identified. I have found some interesting edge cases this way.
Definitely a useful tool!</p> Definitely a useful tool!</p>
<h4 id="unittesting">Unit Testing </h4> <h4 id="unittesting">Unit Testing</h4>
<p>Some of the original development was done with unit testing in some other <p>Some of the original development was done with unit testing in some other
tools I developed. This code formed the basis of a few parts of <abbr title="MultiMarkdown">MMD</abbr>. tools I developed. This code formed the basis of a few parts of <abbr title="MultiMarkdown">MMD</abbr>.
@ -396,7 +396,7 @@ Otherwise, it was hard to see how to really create very good unit tests for
the development of <abbr title="MultiMarkdown">MMD</abbr>. So there is really not much unit testing built into the development of <abbr title="MultiMarkdown">MMD</abbr>. So there is really not much unit testing built into
the code or used during the development.</p> the code or used during the development.</p>
<h3 id="dependencieslibraries">Dependencies/Libraries </h3> <h3 id="dependencieslibraries">Dependencies/Libraries</h3>
<p><abbr title="MultiMarkdown">MMD</abbr> v6 has no external dependencies when compiling, aside from the standard <p><abbr title="MultiMarkdown">MMD</abbr> v6 has no external dependencies when compiling, aside from the standard
libraries for C development (Except that it will use <code>libcurl</code> if available in libraries for C development (Except that it will use <code>libcurl</code> if available in
@ -430,9 +430,50 @@ order to embed them in packaged file formats, e.g. EPUB 3,
TextBundle/TextPack, OpenDocument, etc.</p></li> TextBundle/TextPack, OpenDocument, etc.</p></li>
</ul> </ul>
<h3 id="changelog">Changelog </h3> <h3 id="changelog">Changelog</h3>
<ul> <ul>
<li><p>2018&#8211;09&#8211;01 - v 6.4.0:</p>
<ul>
<li>ADDED: Add ODF Header metadata and fix issue with LaTeX Header metadata</li>
<li>ADDED: Add additional tests for special characters</li>
<li>ADDED: Add initial OPML export support (address #9)</li>
<li>ADDED: Add opml option to read for MultiMarkdown OPML files</li>
<li>Add missing Latex support files</li>
<li>Avoid potential error with stack_free</li>
<li>CHANGED: Remove unnecessary code</li>
<li>FIXED: Allow caption without trailing newline at end of document</li>
<li>FIXED: Escape square brackets, e.g. &#8216;{[foo]}&#8217; (addresses #128 and #129)</li>
<li>FIXED: Fix escpaing of % character in LaTeX code spans and blocks</li>
<li>FIXED: Fix html comments inside code blocks (fixes #118)</li>
<li>FIXED: Fix issue where <code>~</code> is mistakenly interpreted as fence delimiter</li>
<li>FIXED: Fix issue with BOM and files &gt; 4k</li>
<li>FIXED: Fix issue with dollar math delimiters inside code (fixes #134)</li>
<li>FIXED: Fix token length in OPML</li>
<li>FIXED: Improve OPML export; add OPML tests</li>
<li>FIXED: Normalize line spacing in CriticMarkup notes in LaTeX (fixes #120)</li>
<li>FIXED: Preserve tabs following leading hashes in code blocks</li>
<li>FIXED: Prevent potential null dereference</li>
<li>FIXED: Remove lock file</li>
<li>FIXED: Trim single remaining whitespace when exporting headers</li>
<li>FIXED: Trim trailing newlines in definition blocks</li>
<li>FIXED: Use Setext headers when necessary to convert from OPML to text (fixes #138)</li>
<li>FIXED: Use \ul instead of \underline when soul package is in use (fixes #121)</li>
<li>Merge pull request #132 from jlargentaye/develop</li>
<li>UPDATE: Clarify DevelopmentNotes re: libcurl</li>
<li>UPDATE: Clarify README re: libcurl</li>
<li>UPDATED: &#8216;\item{}&#8217; no longer needed since square brackets escaped on their own</li>
<li>UPDATED: Add 6.3.1 release notes</li>
<li>UPDATED: Add allowfullscreen to list of boolean HTML attributes</li>
<li>UPDATED: Add more BibTeX test cases</li>
<li>UPDATED: Adjust metadata for test files</li>
<li>UPDATED: Allow '' to preserve line break in metadata. (Addresses #86)</li>
<li>UPDATED: Apply astyle</li>
<li>UPDATED: Fix whitespace with boolean HTML attributes</li>
<li>UPDATED: Ignore escaped space at end of code span</li>
<li>UPDATED: Test % escaping in URLs</li>
</ul></li>
<li><p>2018&#8211;03&#8211;28 - v 6.3.2:</p> <li><p>2018&#8211;03&#8211;28 - v 6.3.2:</p>
<ul> <ul>

BIN
DevelopmentNotes/DevelopmentNotes.pdf
View File

Binary file not shown.

43
DevelopmentNotes/DevelopmentNotes.txt
View File

@ -1,6 +1,6 @@
Title: MultiMarkdown v6 Development Notes Title: MultiMarkdown v6 Development Notes
Author: Fletcher T. Penney Author: Fletcher T. Penney
Date: 2018-03-38 Date: 2018-09-01
LaTeX Config: tufte-handout LaTeX Config: tufte-handout
Base Header Level: 3 Base Header Level: 3
uuid: dd2d8e76-dc2d-416d-9acd-5395d20871c2 uuid: dd2d8e76-dc2d-416d-9acd-5395d20871c2
@ -472,6 +472,47 @@ TextBundle/TextPack, OpenDocument, etc.
# Changelog # # Changelog #
* 2018-09-01 - v 6.4.0:
* ADDED: Add ODF Header metadata and fix issue with LaTeX Header metadata
* ADDED: Add additional tests for special characters
* ADDED: Add initial OPML export support (address #9)
* ADDED: Add opml option to read for MultiMarkdown OPML files
* Add missing Latex support files
* Avoid potential error with stack_free
* CHANGED: Remove unnecessary code
* FIXED: Allow caption without trailing newline at end of document
* FIXED: Escape square brackets, e.g. '{[foo]}' (addresses #128 and #129)
* FIXED: Fix escpaing of % character in LaTeX code spans and blocks
* FIXED: Fix html comments inside code blocks (fixes #118)
* FIXED: Fix issue where `~` is mistakenly interpreted as fence delimiter
* FIXED: Fix issue with BOM and files > 4k
* FIXED: Fix issue with dollar math delimiters inside code (fixes #134)
* FIXED: Fix token length in OPML
* FIXED: Improve OPML export; add OPML tests
* FIXED: Normalize line spacing in CriticMarkup notes in LaTeX (fixes #120)
* FIXED: Preserve tabs following leading hashes in code blocks
* FIXED: Prevent potential null dereference
* FIXED: Remove lock file
* FIXED: Trim single remaining whitespace when exporting headers
* FIXED: Trim trailing newlines in definition blocks
* FIXED: Use Setext headers when necessary to convert from OPML to text (fixes #138)
* FIXED: Use \ul instead of \underline when soul package is in use (fixes #121)
* Merge pull request #132 from jlargentaye/develop
* UPDATE: Clarify DevelopmentNotes re: libcurl
* UPDATE: Clarify README re: libcurl
* UPDATED: '\item{}' no longer needed since square brackets escaped on their own
* UPDATED: Add 6.3.1 release notes
* UPDATED: Add allowfullscreen to list of boolean HTML attributes
* UPDATED: Add more BibTeX test cases
* UPDATED: Adjust metadata for test files
* UPDATED: Allow '\' to preserve line break in metadata. (Addresses #86)
* UPDATED: Apply astyle
* UPDATED: Fix whitespace with boolean HTML attributes
* UPDATED: Ignore escaped space at end of code span
* UPDATED: Test % escaping in URLs
* 2018-03-28 - v 6.3.2: * 2018-03-28 - v 6.3.2:
* UPDATED: Update documentation * UPDATED: Update documentation

BIN
QuickStart/QuickStart.epub
View File

Binary file not shown.

64
QuickStart/QuickStart.fodt
View File

@ -276,7 +276,7 @@ office:mimetype="application/vnd.oasis.opendocument.text">
<office:meta> <office:meta>
<dc:title>MultiMarkdown v6 Quick Start Guide</dc:title> <dc:title>MultiMarkdown v6 Quick Start Guide</dc:title>
<dc:creator>Fletcher T. Penney</dc:creator> <dc:creator>Fletcher T. Penney</dc:creator>
<meta:user-defined meta:name="version">6.3.2</meta:user-defined> <meta:user-defined meta:name="version">6.4.0</meta:user-defined>
<meta:user-defined meta:name="uuid">0d6313fa-9135-477e-9c14-7d62c1977833</meta:user-defined> <meta:user-defined meta:name="uuid">0d6313fa-9135-477e-9c14-7d62c1977833</meta:user-defined>
</office:meta> </office:meta>
<office:body> <office:body>
@ -319,15 +319,15 @@ office:mimetype="application/vnd.oasis.opendocument.text">
</text:table-of-content> </text:table-of-content>
<text:h text:outline-level="3"><text:bookmark text:name="introduction"/>Introduction </text:h> <text:h text:outline-level="3"><text:bookmark text:name="introduction"/>Introduction</text:h>
<text:p text:style-name="Standard">Version: 6.3.2</text:p> <text:p text:style-name="Standard">Version: 6.4.0</text:p>
<text:p text:style-name="Standard">This document serves as a description of MultiMarkdown (MMD) v6, as well as a sample <text:p text:style-name="Standard">This document serves as a description of MultiMarkdown (MMD) v6, as well as a sample
document to demonstrate the various features. Specifically, differences from document to demonstrate the various features. Specifically, differences from
MMD v5 will be pointed out.</text:p> MMD v5 will be pointed out.</text:p>
<text:h text:outline-level="3"><text:bookmark text:name="performance"/>Performance </text:h> <text:h text:outline-level="3"><text:bookmark text:name="performance"/>Performance</text:h>
<text:p text:style-name="Standard">A big motivating factor leading to the development of MMD v6 was <text:p text:style-name="Standard">A big motivating factor leading to the development of MMD v6 was
performance. When MMD first migrated from Perl to C (based on <text:a xlink:type="simple" xlink:href="https://github.com/jgm/peg-markdown">peg- performance. When MMD first migrated from Perl to C (based on <text:a xlink:type="simple" xlink:href="https://github.com/jgm/peg-markdown">peg-
@ -407,7 +407,7 @@ files, the additional features of MMD compared with Markdown in addition to
the increased legibility of the source code of MMD (in my biased opinion the increased legibility of the source code of MMD (in my biased opinion
anyway) make this project worthwhile.</text:p> anyway) make this project worthwhile.</text:p>
<text:h text:outline-level="3"><text:bookmark text:name="parsetree"/>Parse Tree </text:h> <text:h text:outline-level="3"><text:bookmark text:name="parsetree"/>Parse Tree</text:h>
<text:p text:style-name="Standard">MMD v6 performs its parsing in the following steps:</text:p> <text:p text:style-name="Standard">MMD v6 performs its parsing in the following steps:</text:p>
@ -450,9 +450,9 @@ libMultiMarkdown is to be used in a multithreaded program, a separate
slightly more abstracted <text:span text:style-name="Source_20_Text">mmd_convert_string()</text:span> function that handles creating slightly more abstracted <text:span text:style-name="Source_20_Text">mmd_convert_string()</text:span> function that handles creating
and destroying the <text:span text:style-name="Source_20_Text">mmd_engine</text:span> automatically.</text:p> and destroying the <text:span text:style-name="Source_20_Text">mmd_engine</text:span> automatically.</text:p>
<text:h text:outline-level="3"><text:bookmark text:name="features"/>Features </text:h> <text:h text:outline-level="3"><text:bookmark text:name="features"/>Features</text:h>
<text:h text:outline-level="4"><text:bookmark text:name="abbreviationsoracronyms"/>Abbreviations (Or Acronyms) </text:h> <text:h text:outline-level="4"><text:bookmark text:name="abbreviationsoracronyms"/>Abbreviations (Or Acronyms)</text:h>
<text:p text:style-name="Standard">This file includes the use of MMD as an abbreviation for MultiMarkdown. The <text:p text:style-name="Standard">This file includes the use of MMD as an abbreviation for MultiMarkdown. The
abbreviation will be expanded on the first use, and the shortened form will be abbreviation will be expanded on the first use, and the shortened form will be
@ -472,7 +472,7 @@ this case, the abbreviation is limited to a more basic character set which
includes letters, numbers, periods, and hyphens, but not much else. For more includes letters, numbers, periods, and hyphens, but not much else. For more
complex abbreviations, you must explicitly mark uses of the abbreviation.</text:p> complex abbreviations, you must explicitly mark uses of the abbreviation.</text:p>
<text:h text:outline-level="4"><text:bookmark text:name="citations"/>Citations </text:h> <text:h text:outline-level="4"><text:bookmark text:name="citations"/>Citations</text:h>
<text:p text:style-name="Standard">Citations can be specified using an inline syntax, just like inline footnotes. <text:p text:style-name="Standard">Citations can be specified using an inline syntax, just like inline footnotes.
If you wish to use BibTeX, then configure the <text:span text:style-name="Source_20_Text">bibtex</text:span> metadata (required) and If you wish to use BibTeX, then configure the <text:span text:style-name="Source_20_Text">bibtex</text:span> metadata (required) and
@ -481,7 +481,7 @@ the <text:span text:style-name="Source_20_Text">biblio style</text:span> metadat
<text:p text:style-name="Standard">The HTML output for citations now uses parentheses instead of brackets, e.g. <text:p text:style-name="Standard">The HTML output for citations now uses parentheses instead of brackets, e.g.
<text:span text:style-name="Source_20_Text">(1)</text:span> instead of <text:span text:style-name="Source_20_Text">[1]</text:span>.</text:p> <text:span text:style-name="Source_20_Text">(1)</text:span> instead of <text:span text:style-name="Source_20_Text">[1]</text:span>.</text:p>
<text:h text:outline-level="4"><text:bookmark text:name="criticmarkup"/>CriticMarkup </text:h> <text:h text:outline-level="4"><text:bookmark text:name="criticmarkup"/>CriticMarkup</text:h>
<text:p text:style-name="Standard">MMD v6 has improved support for <text:a xlink:type="simple" xlink:href="http://criticmarkup.com/">CriticMarkup</text:a>, both in terms of parsing, and <text:p text:style-name="Standard">MMD v6 has improved support for <text:a xlink:type="simple" xlink:href="http://criticmarkup.com/">CriticMarkup</text:a>, both in terms of parsing, and
in terms of support for each output format. You can <text:span text:style-name="Underline">insert text</text:span>, in terms of support for each output format. You can <text:span text:style-name="Underline">insert text</text:span>,
@ -498,7 +498,7 @@ these two options, then CriticMarkup that spans a blank line is not recogniz</te
<text:p text:style-name="Standard">T <text:p text:style-name="Standard">T
formats).</text:p> formats).</text:p>
<text:h text:outline-level="4"><text:bookmark text:name="embeddedimages"/>Embedded Images </text:h> <text:h text:outline-level="4"><text:bookmark text:name="embeddedimages"/>Embedded Images</text:h>
<text:p text:style-name="Standard">Supported export formats (<text:span text:style-name="Source_20_Text">odt</text:span>, <text:span text:style-name="Source_20_Text">epub</text:span>, <text:span text:style-name="Source_20_Text">bundle</text:span>, <text:span text:style-name="Source_20_Text">bundlezip</text:span>) include <text:p text:style-name="Standard">Supported export formats (<text:span text:style-name="Source_20_Text">odt</text:span>, <text:span text:style-name="Source_20_Text">epub</text:span>, <text:span text:style-name="Source_20_Text">bundle</text:span>, <text:span text:style-name="Source_20_Text">bundlezip</text:span>) include
images inside the export document:</text:p> images inside the export document:</text:p>
@ -517,13 +517,13 @@ properly installed when MMD is compiled. This is true f</text:p></text:list-item
<text:p text:style-name="Standard">ed <text:p text:style-name="Standard">ed
as such. I working on options for this for the future.</text:p> as such. I working on options for this for the future.</text:p>
<text:h text:outline-level="4"><text:bookmark text:name="emphandstrong"/>Emph and Strong </text:h> <text:h text:outline-level="4"><text:bookmark text:name="emphandstrong"/>Emph and Strong</text:h>
<text:p text:style-name="Standard">The basics of emphasis and strong emphasis are unchanged, but the parsing <text:p text:style-name="Standard">The basics of emphasis and strong emphasis are unchanged, but the parsing
engine has been improved to be more accurate, particularly in various edge engine has been improved to be more accurate, particularly in various edge
cases where proper parsing can be difficult.</text:p> cases where proper parsing can be difficult.</text:p>
<text:h text:outline-level="4"><text:bookmark text:name="epub3support"/>EPUB 3 Support </text:h> <text:h text:outline-level="4"><text:bookmark text:name="epub3support"/>EPUB 3 Support</text:h>
<text:p text:style-name="Standard">MMD v6 now provides support for direct creation of <text:a xlink:type="simple" xlink:href="https://en.wikipedia.org/wiki/EPUB">EPUB 3</text:a> files. Previously <text:p text:style-name="Standard">MMD v6 now provides support for direct creation of <text:a xlink:type="simple" xlink:href="https://en.wikipedia.org/wiki/EPUB">EPUB 3</text:a> files. Previously
a separate tool was required to create EPUB files from MMD. It&#8217;s now built- a separate tool was required to create EPUB files from MMD. It&#8217;s now built-
@ -546,7 +546,7 @@ document formats you need. Same goes for Amazon&#8217;s ebook formats &#8211; th
run in batch mode (using the <text:span text:style-name="Source_20_Text">-b\--batch</text:span> options). Otherwise, it simply run in batch mode (using the <text:span text:style-name="Source_20_Text">-b\--batch</text:span> options). Otherwise, it simply
outputs the HTML 5 file that would serve as the primary content for the EPUB.</text:p> outputs the HTML 5 file that would serve as the primary content for the EPUB.</text:p>
<text:h text:outline-level="4"><text:bookmark text:name="fencedcodeblocks"/>Fenced Code Blocks </text:h> <text:h text:outline-level="4"><text:bookmark text:name="fencedcodeblocks"/>Fenced Code Blocks</text:h>
<text:p text:style-name="Standard">Fenced code blocks are fundamentally the same as MMD v5, except:</text:p> <text:p text:style-name="Standard">Fenced code blocks are fundamentally the same as MMD v5, except:</text:p>
@ -562,12 +562,12 @@ considered to be part of the code block.</text:p></text:list-item>
</text:list> </text:list>
<text:h text:outline-level="4"><text:bookmark text:name="footnotes"/>Footnotes </text:h> <text:h text:outline-level="4"><text:bookmark text:name="footnotes"/>Footnotes</text:h>
<text:p text:style-name="Standard">The HTML output for footnotes now uses superscripts instead of brackets, e.g. <text:p text:style-name="Standard">The HTML output for footnotes now uses superscripts instead of brackets, e.g.
<text:span text:style-name="Source_20_Text">&lt;sup&gt;1&lt;/sup&gt;</text:span> instead of <text:span text:style-name="Source_20_Text">[1]</text:span>.</text:p> <text:span text:style-name="Source_20_Text">&lt;sup&gt;1&lt;/sup&gt;</text:span> instead of <text:span text:style-name="Source_20_Text">[1]</text:span>.</text:p>
<text:h text:outline-level="4"><text:bookmark text:name="glossaryterms"/>Glossary Terms </text:h> <text:h text:outline-level="4"><text:bookmark text:name="glossaryterms"/>Glossary Terms</text:h>
<text:p text:style-name="Standard">If there are terms in your document you wish to define in a glossary<text:note text:id="gn3" text:note-class="glossary"><text:note-body><text:p text:style-name="Footnote">The <text:p text:style-name="Standard">If there are terms in your document you wish to define in a glossary<text:note text:id="gn3" text:note-class="glossary"><text:note-body><text:p text:style-name="Footnote">The
glossary collects information about important terms used in your document</text:p></text:note-body></text:note> at glossary collects information about important terms used in your document</text:p></text:note-body></text:note> at
@ -587,7 +587,7 @@ case, the term is limited to a more basic character set which includes
letters, numbers, periods, and hyphens, but not much else. For more complex letters, numbers, periods, and hyphens, but not much else. For more complex
glossary terms, you must explicitly mark uses of the term.</text:p> glossary terms, you must explicitly mark uses of the term.</text:p>
<text:h text:outline-level="4"><text:bookmark text:name="htmlcomments"/>HTML Comments </text:h> <text:h text:outline-level="4"><text:bookmark text:name="htmlcomments"/>HTML Comments</text:h>
<text:p text:style-name="Standard">Previously, HTML Comments were used by MultiMarkdown to include raw text for <text:p text:style-name="Standard">Previously, HTML Comments were used by MultiMarkdown to include raw text for
inclusion in the output file. This was useful, but limited, as it could only inclusion in the output file. This was useful, but limited, as it could only
@ -599,12 +599,12 @@ format since they would cause errors.</text:p>
<text:p text:style-name="Standard">Take a look at the <text:span text:style-name="Source_20_Text">HTML Comments.text</text:span> file in the test suite for a better <text:p text:style-name="Standard">Take a look at the <text:span text:style-name="Source_20_Text">HTML Comments.text</text:span> file in the test suite for a better
understanding of comment blocks vs comment spans, and how they are parsed.</text:p> understanding of comment blocks vs comment spans, and how they are parsed.</text:p>
<text:h text:outline-level="4"><text:bookmark text:name="internationalization"/>Internationalization </text:h> <text:h text:outline-level="4"><text:bookmark text:name="internationalization"/>Internationalization</text:h>
<text:p text:style-name="Standard">MMD v6 includes support for substituting certain text phrases in other <text:p text:style-name="Standard">MMD v6 includes support for substituting certain text phrases in other
languages. This only affects the HTML format.</text:p> languages. This only affects the HTML format.</text:p>
<text:h text:outline-level="4"><text:bookmark text:name="latexchanges"/>LaTeX Changes </text:h> <text:h text:outline-level="4"><text:bookmark text:name="latexchanges"/>LaTeX Changes</text:h>
<text:p text:style-name="Standard">LaTeX support is slightly different than in prior versions of MMD. It is <text:p text:style-name="Standard">LaTeX support is slightly different than in prior versions of MMD. It is
designed to be a bit more consistent, and easier for basic use.</text:p> designed to be a bit more consistent, and easier for basic use.</text:p>
@ -695,7 +695,7 @@ the following <text:span text:style-name="Source_20_Text">latex config</text:spa
location for your system. I would like to make this easier, but haven&#8217;t found location for your system. I would like to make this easier, but haven&#8217;t found
the best configuration yet.</text:p> the best configuration yet.</text:p>
<text:h text:outline-level="4"><text:bookmark text:name="metadata"/>Metadata </text:h> <text:h text:outline-level="4"><text:bookmark text:name="metadata"/>Metadata</text:h>
<text:p text:style-name="Standard">Metadata in MMD v6 includes new support for LaTeX &#8211; the <text:span text:style-name="Source_20_Text">latex config</text:span> key <text:p text:style-name="Standard">Metadata in MMD v6 includes new support for LaTeX &#8211; the <text:span text:style-name="Source_20_Text">latex config</text:span> key
allows you to automatically setup of multiple <text:span text:style-name="Source_20_Text">latex include</text:span> files at once. allows you to automatically setup of multiple <text:span text:style-name="Source_20_Text">latex include</text:span> files at once.
@ -727,7 +727,7 @@ use the transclusion functionality:</text:p>
<text:p text:style-name="Preformatted Text">Title:<text:tab/>Some Title<text:line-break/>MMD Header:<text:tab/>This is *MMD* text.<text:line-break/>MMD Footer:<text:tab/>{{footer.txt}}<text:line-break/></text:p> <text:p text:style-name="Preformatted Text">Title:<text:tab/>Some Title<text:line-break/>MMD Header:<text:tab/>This is *MMD* text.<text:line-break/>MMD Footer:<text:tab/>{{footer.txt}}<text:line-break/></text:p>
<text:h text:outline-level="4"><text:bookmark text:name="outputformats"/>Output Formats </text:h> <text:h text:outline-level="4"><text:bookmark text:name="outputformats"/>Output Formats</text:h>
<text:p text:style-name="Standard">MultiMarkdown 6 supports the following output formats, using the <text:span text:style-name="Source_20_Text">-t</text:span> <text:p text:style-name="Standard">MultiMarkdown 6 supports the following output formats, using the <text:span text:style-name="Source_20_Text">-t</text:span>
command-line argument:</text:p> command-line argument:</text:p>
@ -772,11 +772,15 @@ package is compressed to a single zip file (similar to EPUB and ODor macOS build
</text:list> </text:list>
<text:h text:outline-level="4"><text:bookmark text:name="rawsource"/>Raw Source </text:h> <text:h text:outline-level="4"><text:bookmark text:name="rawsource"/>Raw Source</text:h>
<text:p text:style-name="Standard">In older versions of MultiMarkdown you could use an HTML comment to pass raw LaTeX or other content to the final document. This worked reasonably well, but was limited and didn&#8217;t work well when exporting to multiple formats. It was time for something new.</text:p> <text:p text:style-name="Standard">In older versions of MultiMarkdown you could use an HTML comment to pass raw
LaTeX or other content to the final document. This worked reasonably well,
but was limited and didn&#8217;t work well when exporting to multiple formats. It
was time for something new.</text:p>
<text:p text:style-name="Standard">MMD v6 offers a new feature to handle this. Code spans and code blocks can be flagged as representing raw source:</text:p> <text:p text:style-name="Standard">MMD v6 offers a new feature to handle this. Code spans and code blocks can
be flagged as representing raw source:</text:p>
<text:p text:style-name="Preformatted Text">foo `*bar*`{=html}<text:line-break/><text:line-break/>```{=latex}<text:line-break/>*foo*<text:line-break/>```<text:line-break/></text:p> <text:p text:style-name="Preformatted Text">foo `*bar*`{=html}<text:line-break/><text:line-break/>```{=latex}<text:line-break/>*foo*<text:line-break/>```<text:line-break/></text:p>
@ -806,19 +810,19 @@ package is compressed to a single zip file (similar to EPUB and ODor macOS build
</text:list> </text:list>
<text:h text:outline-level="4"><text:bookmark text:name="tableofcontents"/>Table of Contents </text:h> <text:h text:outline-level="4"><text:bookmark text:name="tableofcontents"/>Table of Contents</text:h>
<text:p text:style-name="Standard">By placing <text:span text:style-name="Source_20_Text">{{TOC}}</text:span> in your document, you can insert an automatically <text:p text:style-name="Standard">By placing <text:span text:style-name="Source_20_Text">{{TOC}}</text:span> in your document, you can insert an automatically
generated Table of Contents in your document. As of MMD v6, the native generated Table of Contents in your document. As of MMD v6, the native
Table of Contents functionality is used when exporting to LaTeX or Table of Contents functionality is used when exporting to LaTeX or
OpenDocument formats.</text:p> OpenDocument formats.</text:p>
<text:h text:outline-level="4"><text:bookmark text:name="tables"/>Tables </text:h> <text:h text:outline-level="4"><text:bookmark text:name="tables"/>Tables</text:h>
<text:p text:style-name="Standard">Tables in MultiMarkdown-6 work basically the same as before, but a caption, if <text:p text:style-name="Standard">Tables in MultiMarkdown-6 work basically the same as before, but a caption, if
present, must come <text:span text:style-name="MMD-Italic">after</text:span> the body of the table, not <text:span text:style-name="MMD-Italic">before</text:span>.</text:p> present, must come <text:span text:style-name="MMD-Italic">after</text:span> the body of the table, not <text:span text:style-name="MMD-Italic">before</text:span>.</text:p>
<text:h text:outline-level="4"><text:bookmark text:name="transclusion"/>Transclusion </text:h> <text:h text:outline-level="4"><text:bookmark text:name="transclusion"/>Transclusion</text:h>
<text:p text:style-name="Standard">File transclusion works basically the same way &#8211; <text:span text:style-name="Source_20_Text">{{file}}</text:span> is used to <text:p text:style-name="Standard">File transclusion works basically the same way &#8211; <text:span text:style-name="Source_20_Text">{{file}}</text:span> is used to
indicate a file that needs to be transcluded. <text:span text:style-name="Source_20_Text">{{file.*}}</text:span> allows for indicate a file that needs to be transcluded. <text:span text:style-name="Source_20_Text">{{file.*}}</text:span> allows for
@ -905,12 +909,12 @@ whether a file is being processed by itself or as part of a &#8220;parent&#8221;
This can be useful when a particular file can either be a standalone document, This can be useful when a particular file can either be a standalone document,
or a chapter inside a larger document.</text:p> 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:h text:outline-level="3"><text:bookmark text:name="developernotes"/>Developer Notes</text:h>
<text:p text:style-name="Standard">If you&#8217;re using MMD as a library in another application, there are a few <text:p text:style-name="Standard">If you&#8217;re using MMD as a library in another application, there are a few
things to be aware of.</text:p> things to be aware of.</text:p>
<text:h text:outline-level="4"><text:bookmark text:name="objectpools"/>Object Pools </text:h> <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 <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 (&#8220;object pools&#8221;). Allocating a single tokens used in parsing in large chunks (&#8220;object pools&#8221;). Allocating a single
@ -925,7 +929,7 @@ memory management, and understand MultiMarkdown&#8217;s program flow. Failure to
properly manage the object pool can lead to massive memory leaks, freeing 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> 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: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=&quot;value&quot;</text:span>). But some <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=&quot;value&quot;</text:span>). But some
less frequently used attributes are boolean attributes (e.g. <text:span text:style-name="Source_20_Text">&lt;video<text:line-break/>controls&gt;</text:span>). Properly distinguishing HTML from other uses of the <text:span text:style-name="Source_20_Text">&lt;</text:span> less frequently used attributes are boolean attributes (e.g. <text:span text:style-name="Source_20_Text">&lt;video<text:line-break/>controls&gt;</text:span>). Properly distinguishing HTML from other uses of the <text:span text:style-name="Source_20_Text">&lt;</text:span>
@ -974,7 +978,7 @@ off. I will continue to research additional options.</text:p></text:list-item>
</text:list> </text:list>
<text:h text:outline-level="3"><text:bookmark text:name="futuresteps"/>Future Steps </text:h> <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> <text:p text:style-name="Standard">Some features I plan to implement at some point:</text:p>

64
QuickStart/QuickStart.html
View File

@ -4,7 +4,7 @@
<meta charset="utf-8"/> <meta charset="utf-8"/>
<title>MultiMarkdown v6 Quick Start Guide</title> <title>MultiMarkdown v6 Quick Start Guide</title>
<meta name="author" content="Fletcher T. Penney"/> <meta name="author" content="Fletcher T. Penney"/>
<meta name="version" content="6.3.2"/> <meta name="version" content="6.4.0"/>
<meta name="uuid" content="0d6313fa-9135-477e-9c14-7d62c1977833"/> <meta name="uuid" content="0d6313fa-9135-477e-9c14-7d62c1977833"/>
</head> </head>
<body> <body>
@ -47,15 +47,15 @@
</ul> </ul>
</div> </div>
<h3 id="introduction">Introduction </h3> <h3 id="introduction">Introduction</h3>
<p>Version: 6.3.2</p> <p>Version: 6.4.0</p>
<p>This document serves as a description of MultiMarkdown (<abbr title="MultiMarkdown">MMD</abbr>) v6, as well as a sample <p>This document serves as a description of MultiMarkdown (<abbr title="MultiMarkdown">MMD</abbr>) v6, as well as a sample
document to demonstrate the various features. Specifically, differences from document to demonstrate the various features. Specifically, differences from
<abbr title="MultiMarkdown">MMD</abbr> v5 will be pointed out.</p> <abbr title="MultiMarkdown">MMD</abbr> v5 will be pointed out.</p>
<h3 id="performance">Performance </h3> <h3 id="performance">Performance</h3>
<p>A big motivating factor leading to the development of <abbr title="MultiMarkdown">MMD</abbr> v6 was <p>A big motivating factor leading to the development of <abbr title="MultiMarkdown">MMD</abbr> v6 was
performance. When <abbr title="MultiMarkdown">MMD</abbr> first migrated from Perl to C (based on <a href="https://github.com/jgm/peg-markdown">peg- performance. When <abbr title="MultiMarkdown">MMD</abbr> first migrated from Perl to C (based on <a href="https://github.com/jgm/peg-markdown">peg-
@ -131,7 +131,7 @@ files, the additional features of <abbr title="MultiMarkdown">MMD</abbr> compare
the increased legibility of the source code of <abbr title="MultiMarkdown">MMD</abbr> (in my biased opinion the increased legibility of the source code of <abbr title="MultiMarkdown">MMD</abbr> (in my biased opinion
anyway) make this project worthwhile.</p> anyway) make this project worthwhile.</p>
<h3 id="parsetree">Parse Tree </h3> <h3 id="parsetree">Parse Tree</h3>
<p><abbr title="MultiMarkdown">MMD</abbr> v6 performs its parsing in the following steps:</p> <p><abbr title="MultiMarkdown">MMD</abbr> v6 performs its parsing in the following steps:</p>
@ -162,9 +162,9 @@ libMultiMarkdown is to be used in a multithreaded program, a separate
slightly more abstracted <code>mmd_convert_string()</code> function that handles creating slightly more abstracted <code>mmd_convert_string()</code> function that handles creating
and destroying the <code>mmd_engine</code> automatically.</p> and destroying the <code>mmd_engine</code> automatically.</p>
<h3 id="features">Features </h3> <h3 id="features">Features</h3>
<h4 id="abbreviationsoracronyms">Abbreviations (Or Acronyms) </h4> <h4 id="abbreviationsoracronyms">Abbreviations (Or Acronyms)</h4>
<p>This file includes the use of <abbr title="MultiMarkdown">MMD</abbr> as an abbreviation for MultiMarkdown. The <p>This file includes the use of <abbr title="MultiMarkdown">MMD</abbr> as an abbreviation for MultiMarkdown. The
abbreviation will be expanded on the first use, and the shortened form will be abbreviation will be expanded on the first use, and the shortened form will be
@ -187,7 +187,7 @@ this case, the abbreviation is limited to a more basic character set which
includes letters, numbers, periods, and hyphens, but not much else. For more includes letters, numbers, periods, and hyphens, but not much else. For more
complex abbreviations, you must explicitly mark uses of the abbreviation.</p> complex abbreviations, you must explicitly mark uses of the abbreviation.</p>
<h4 id="citations">Citations </h4> <h4 id="citations">Citations</h4>
<p>Citations can be specified using an inline syntax, just like inline footnotes. <p>Citations can be specified using an inline syntax, just like inline footnotes.
If you wish to use BibTeX, then configure the <code>bibtex</code> metadata (required) and If you wish to use BibTeX, then configure the <code>bibtex</code> metadata (required) and
@ -196,7 +196,7 @@ the <code>biblio style</code> metadata (optional).</p>
<p>The HTML output for citations now uses parentheses instead of brackets, e.g. <p>The HTML output for citations now uses parentheses instead of brackets, e.g.
<code>(1)</code> instead of <code>[1]</code>.</p> <code>(1)</code> instead of <code>[1]</code>.</p>
<h4 id="criticmarkup">CriticMarkup </h4> <h4 id="criticmarkup">CriticMarkup</h4>
<p><abbr title="MultiMarkdown">MMD</abbr> v6 has improved support for <a href="http://criticmarkup.com/">CriticMarkup</a>, both in terms of parsing, and <p><abbr title="MultiMarkdown">MMD</abbr> v6 has improved support for <a href="http://criticmarkup.com/">CriticMarkup</a>, both in terms of parsing, and
in terms of support for each output format. You can <ins>insert text</ins>, in terms of support for each output format. You can <ins>insert text</ins>,
@ -213,7 +213,7 @@ these two options, then CriticMarkup that spans a blank line is not recogniz</p>
<p>T <p>T
formats).</p> formats).</p>
<h4 id="embeddedimages">Embedded Images </h4> <h4 id="embeddedimages">Embedded Images</h4>
<p>Supported export formats (<code>odt</code>, <code>epub</code>, <code>bundle</code>, <code>bundlezip</code>) include <p>Supported export formats (<code>odt</code>, <code>epub</code>, <code>bundle</code>, <code>bundlezip</code>) include
images inside the export document:</p> images inside the export document:</p>
@ -227,13 +227,13 @@ properly installed when <abbr title="MultiMarkdown">MMD</abbr> is compiled. This
<p>ed <p>ed
as such. I working on options for this for the future.</p> as such. I working on options for this for the future.</p>
<h4 id="emphandstrong">Emph and Strong </h4> <h4 id="emphandstrong">Emph and Strong</h4>
<p>The basics of emphasis and strong emphasis are unchanged, but the parsing <p>The basics of emphasis and strong emphasis are unchanged, but the parsing
engine has been improved to be more accurate, particularly in various edge engine has been improved to be more accurate, particularly in various edge
cases where proper parsing can be difficult.</p> cases where proper parsing can be difficult.</p>
<h4 id="epub3support">EPUB 3 Support </h4> <h4 id="epub3support">EPUB 3 Support</h4>
<p><abbr title="MultiMarkdown">MMD</abbr> v6 now provides support for direct creation of <a href="https://en.wikipedia.org/wiki/EPUB">EPUB 3</a> files. Previously <p><abbr title="MultiMarkdown">MMD</abbr> v6 now provides support for direct creation of <a href="https://en.wikipedia.org/wiki/EPUB">EPUB 3</a> files. Previously
a separate tool was required to create EPUB files from <abbr title="MultiMarkdown">MMD</abbr>. It&#8217;s now built- a separate tool was required to create EPUB files from <abbr title="MultiMarkdown">MMD</abbr>. It&#8217;s now built-
@ -256,7 +256,7 @@ document formats you need. Same goes for Amazon&#8217;s ebook formats &#8211; th
run in batch mode (using the <code>-b\--batch</code> options). Otherwise, it simply run in batch mode (using the <code>-b\--batch</code> options). Otherwise, it simply
outputs the HTML 5 file that would serve as the primary content for the EPUB.</p> outputs the HTML 5 file that would serve as the primary content for the EPUB.</p>
<h4 id="fencedcodeblocks">Fenced Code Blocks </h4> <h4 id="fencedcodeblocks">Fenced Code Blocks</h4>
<p>Fenced code blocks are fundamentally the same as <abbr title="MultiMarkdown">MMD</abbr> v5, except:</p> <p>Fenced code blocks are fundamentally the same as <abbr title="MultiMarkdown">MMD</abbr> v5, except:</p>
@ -268,12 +268,12 @@ complex parser.</p></li>
considered to be part of the code block.</p></li> considered to be part of the code block.</p></li>
</ol> </ol>
<h4 id="footnotes">Footnotes </h4> <h4 id="footnotes">Footnotes</h4>
<p>The HTML output for footnotes now uses superscripts instead of brackets, e.g. <p>The HTML output for footnotes now uses superscripts instead of brackets, e.g.
<code>&lt;sup&gt;1&lt;/sup&gt;</code> instead of <code>[1]</code>.</p> <code>&lt;sup&gt;1&lt;/sup&gt;</code> instead of <code>[1]</code>.</p>
<h4 id="glossaryterms">Glossary Terms </h4> <h4 id="glossaryterms">Glossary Terms</h4>
<p>If there are terms in your document you wish to define in a <a href="#gn:3" id="gnref:3" title="see glossary" class="glossary">glossary</a> at <p>If there are terms in your document you wish to define in a <a href="#gn:3" id="gnref:3" title="see glossary" class="glossary">glossary</a> at
the end of your document, you can define them using the glossary syntax.</p> the end of your document, you can define them using the glossary syntax.</p>
@ -299,7 +299,7 @@ case, the term is limited to a more basic character set which includes
letters, numbers, periods, and hyphens, but not much else. For more complex letters, numbers, periods, and hyphens, but not much else. For more complex
glossary terms, you must explicitly mark uses of the term.</p> glossary terms, you must explicitly mark uses of the term.</p>
<h4 id="htmlcomments">HTML Comments </h4> <h4 id="htmlcomments">HTML Comments</h4>
<p>Previously, HTML Comments were used by MultiMarkdown to include raw text for <p>Previously, HTML Comments were used by MultiMarkdown to include raw text for
inclusion in the output file. This was useful, but limited, as it could only inclusion in the output file. This was useful, but limited, as it could only
@ -311,12 +311,12 @@ format since they would cause errors.</p>
<p>Take a look at the <code>HTML Comments.text</code> file in the test suite for a better <p>Take a look at the <code>HTML Comments.text</code> file in the test suite for a better
understanding of comment blocks vs comment spans, and how they are parsed.</p> understanding of comment blocks vs comment spans, and how they are parsed.</p>
<h4 id="internationalization">Internationalization </h4> <h4 id="internationalization">Internationalization</h4>
<p><abbr title="MultiMarkdown">MMD</abbr> v6 includes support for substituting certain text phrases in other <p><abbr title="MultiMarkdown">MMD</abbr> v6 includes support for substituting certain text phrases in other
languages. This only affects the HTML format.</p> languages. This only affects the HTML format.</p>
<h4 id="latexchanges">LaTeX Changes </h4> <h4 id="latexchanges">LaTeX Changes</h4>
<p>LaTeX support is slightly different than in prior versions of <abbr title="MultiMarkdown">MMD</abbr>. It is <p>LaTeX support is slightly different than in prior versions of <abbr title="MultiMarkdown">MMD</abbr>. It is
designed to be a bit more consistent, and easier for basic use.</p> designed to be a bit more consistent, and easier for basic use.</p>
@ -384,7 +384,7 @@ the following <code>latex config</code> values by default:</p>
location for your system. I would like to make this easier, but haven&#8217;t found location for your system. I would like to make this easier, but haven&#8217;t found
the best configuration yet.</p> the best configuration yet.</p>
<h4 id="metadata">Metadata </h4> <h4 id="metadata">Metadata</h4>
<p>Metadata in <abbr title="MultiMarkdown">MMD</abbr> v6 includes new support for LaTeX &#8211; the <code>latex config</code> key <p>Metadata in <abbr title="MultiMarkdown">MMD</abbr> v6 includes new support for LaTeX &#8211; the <code>latex config</code> key
allows you to automatically setup of multiple <code>latex include</code> files at once. allows you to automatically setup of multiple <code>latex include</code> files at once.
@ -416,7 +416,7 @@ MMD Header: This is *MMD* text.
MMD Footer: {{footer.txt}} MMD Footer: {{footer.txt}}
</code></pre> </code></pre>
<h4 id="outputformats">Output Formats </h4> <h4 id="outputformats">Output Formats</h4>
<p>MultiMarkdown 6 supports the following output formats, using the <code>-t</code> <p>MultiMarkdown 6 supports the following output formats, using the <code>-t</code>
command-line argument:</p> command-line argument:</p>
@ -442,11 +442,15 @@ and images between applications (on any OS, but especially on iOS)</li>
package is compressed to a single zip file (similar to EPUB and ODor macOS builds.</li> package is compressed to a single zip file (similar to EPUB and ODor macOS builds.</li>
</ul> </ul>
<h4 id="rawsource">Raw Source </h4> <h4 id="rawsource">Raw Source</h4>
<p>In older versions of MultiMarkdown you could use an HTML comment to pass raw LaTeX or other content to the final document. This worked reasonably well, but was limited and didn&#8217;t work well when exporting to multiple formats. It was time for something new.</p> <p>In older versions of MultiMarkdown you could use an HTML comment to pass raw
LaTeX or other content to the final document. This worked reasonably well,
but was limited and didn&#8217;t work well when exporting to multiple formats. It
was time for something new.</p>
<p><abbr title="MultiMarkdown">MMD</abbr> v6 offers a new feature to handle this. Code spans and code blocks can be flagged as representing raw source:</p> <p><abbr title="MultiMarkdown">MMD</abbr> v6 offers a new feature to handle this. Code spans and code blocks can
be flagged as representing raw source:</p>
<pre><code>foo `*bar*`{=html} <pre><code>foo `*bar*`{=html}
@ -467,19 +471,19 @@ package is compressed to a single zip file (similar to EPUB and ODor macOS build
<li><code>*</code> &#8211; wildcard matches any output format</li> <li><code>*</code> &#8211; wildcard matches any output format</li>
</ul> </ul>
<h4 id="tableofcontents">Table of Contents </h4> <h4 id="tableofcontents">Table of Contents</h4>
<p>By placing <code>{{TOC}}</code> in your document, you can insert an automatically <p>By placing <code>{{TOC}}</code> in your document, you can insert an automatically
generated Table of Contents in your document. As of <abbr title="MultiMarkdown">MMD</abbr> v6, the native generated Table of Contents in your document. As of <abbr title="MultiMarkdown">MMD</abbr> v6, the native
Table of Contents functionality is used when exporting to LaTeX or Table of Contents functionality is used when exporting to LaTeX or
OpenDocument formats.</p> OpenDocument formats.</p>
<h4 id="tables">Tables </h4> <h4 id="tables">Tables</h4>
<p>Tables in MultiMarkdown-6 work basically the same as before, but a caption, if <p>Tables in MultiMarkdown-6 work basically the same as before, but a caption, if
present, must come <em>after</em> the body of the table, not <em>before</em>.</p> present, must come <em>after</em> the body of the table, not <em>before</em>.</p>
<h4 id="transclusion">Transclusion </h4> <h4 id="transclusion">Transclusion</h4>
<p>File transclusion works basically the same way &#8211; <code>{{file}}</code> is used to <p>File transclusion works basically the same way &#8211; <code>{{file}}</code> is used to
indicate a file that needs to be transcluded. <code>{{file.*}}</code> allows for indicate a file that needs to be transcluded. <code>{{file.*}}</code> allows for
@ -549,12 +553,12 @@ whether a file is being processed by itself or as part of a &#8220;parent&#8221;
This can be useful when a particular file can either be a standalone document, This can be useful when a particular file can either be a standalone document,
or a chapter inside a larger document.</p> or a chapter inside a larger document.</p>
<h3 id="developernotes">Developer Notes </h3> <h3 id="developernotes">Developer Notes</h3>
<p>If you&#8217;re using <abbr title="MultiMarkdown">MMD</abbr> as a library in another application, there are a few <p>If you&#8217;re using <abbr title="MultiMarkdown">MMD</abbr> as a library in another application, there are a few
things to be aware of.</p> things to be aware of.</p>
<h4 id="objectpools">Object Pools </h4> <h4 id="objectpools">Object Pools</h4>
<p>To improve performance, <abbr title="MultiMarkdown">MMD</abbr> has the option to allocate the memory for the <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 (&#8220;object pools&#8221;). Allocating a single tokens used in parsing in large chunks (&#8220;object pools&#8221;). Allocating a single
@ -569,7 +573,7 @@ memory management, and understand MultiMarkdown&#8217;s program flow. Failure to
properly manage the object pool can lead to massive memory leaks, freeing properly manage the object pool can lead to massive memory leaks, freeing
memory before that is still in use, or other potential problems.</p> memory before that is still in use, or other potential problems.</p>
<h4 id="htmlbooleanattributes">HTML Boolean Attributes </h4> <h4 id="htmlbooleanattributes">HTML Boolean Attributes</h4>
<p>Most HTML attributes are of the key-value type (e.g. <code>key=&quot;value&quot;</code>). But some <p>Most HTML attributes are of the key-value type (e.g. <code>key=&quot;value&quot;</code>). But some
less frequently used attributes are boolean attributes (e.g. <code>&lt;video less frequently used attributes are boolean attributes (e.g. <code>&lt;video
@ -605,7 +609,7 @@ option I have chosen as default for <abbr title="MultiMarkdown">MMD</abbr> &#821
off. I will continue to research additional options.</p></li> off. I will continue to research additional options.</p></li>
</ul> </ul>
<h3 id="futuresteps">Future Steps </h3> <h3 id="futuresteps">Future Steps</h3>
<p>Some features I plan to implement at some point:</p> <p>Some features I plan to implement at some point:</p>

BIN
QuickStart/QuickStart.pdf
View File

Binary file not shown.

10
QuickStart/QuickStart.txt
View File

@ -1,6 +1,6 @@
Title: MultiMarkdown v6 Quick Start Guide Title: MultiMarkdown v6 Quick Start Guide
Author: Fletcher T. Penney Author: Fletcher T. Penney
Version: 6.3.2 Version: 6.4.0
LaTeX Config: tufte-handout LaTeX Config: tufte-handout
Base Header Level: 3 Base Header Level: 3
uuid: 0d6313fa-9135-477e-9c14-7d62c1977833 uuid: 0d6313fa-9135-477e-9c14-7d62c1977833
@ -416,9 +416,13 @@ package is compressed to a single zip file (similar to EPUB and ODor macOS build
## Raw Source ## ## Raw Source ##
In older versions of MultiMarkdown you could use an HTML comment to pass raw LaTeX or other content to the final document. This worked reasonably well, but was limited and didn't work well when exporting to multiple formats. It was time for something new. In older versions of MultiMarkdown you could use an HTML comment to pass raw
LaTeX or other content to the final document. This worked reasonably well,
but was limited and didn't work well when exporting to multiple formats. It
was time for something new.
MMD v6 offers a new feature to handle this. Code spans and code blocks can be flagged as representing raw source: MMD v6 offers a new feature to handle this. Code spans and code blocks can
be flagged as representing raw source:
foo `*bar*`{=html} foo `*bar*`{=html}

4
README.md
View File

@ -4,9 +4,9 @@
| ---------- | ------------------------- | | ---------- | ------------------------- |
| Title: | MultiMarkdown | | Title: | MultiMarkdown |
| Author: | Fletcher T. Penney | | Author: | Fletcher T. Penney |
| Date: | 2018-03-28 | | Date: | 2018-09-01 |
| Copyright: | Copyright © 2016 - 2018 Fletcher T. Penney. | | Copyright: | Copyright © 2016 - 2018 Fletcher T. Penney. |
| Version: | 6.3.2 | | Version: | 6.4.0 |
master branch: [![Build Status](https://travis-ci.org/fletcher/MultiMarkdown-6.svg?branch=master)](https://travis-ci.org/fletcher/MultiMarkdown-6) master branch: [![Build Status](https://travis-ci.org/fletcher/MultiMarkdown-6.svg?branch=master)](https://travis-ci.org/fletcher/MultiMarkdown-6)
develop branch: [![Build Status](https://travis-ci.org/fletcher/MultiMarkdown-6.svg?branch=develop)](https://travis-ci.org/fletcher/MultiMarkdown-6) develop branch: [![Build Status](https://travis-ci.org/fletcher/MultiMarkdown-6.svg?branch=develop)](https://travis-ci.org/fletcher/MultiMarkdown-6)