From: Fletcher T. Penney Date: Sat, 1 Sep 2018 20:00:33 +0000 (-0400) Subject: version bump X-Git-Tag: 6.4.0^2 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=efaee1318edf12e325e26f851e767591234ddd7c;p=multimarkdown version bump --- diff --git a/CMakeLists.txt b/CMakeLists.txt index 7ff61ad..a738a35 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -8,10 +8,10 @@ cmake_minimum_required (VERSION 2.6) 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-03-28") +set (My_Project_Revised_Date "2018-09-01") set (My_Project_Version_Major 6) -set (My_Project_Version_Minor 3) -set (My_Project_Version_Patch 2) +set (My_Project_Version_Minor 4) +set (My_Project_Version_Patch 0) set (My_Project_Version "${My_Project_Version_Major}.${My_Project_Version_Minor}.${My_Project_Version_Patch}") diff --git a/DevelopmentNotes/DevelopmentNotes.epub b/DevelopmentNotes/DevelopmentNotes.epub index 82fd304..c60fc7e 100644 Binary files a/DevelopmentNotes/DevelopmentNotes.epub and b/DevelopmentNotes/DevelopmentNotes.epub differ diff --git a/DevelopmentNotes/DevelopmentNotes.fodt b/DevelopmentNotes/DevelopmentNotes.fodt index d597347..a1be665 100644 --- a/DevelopmentNotes/DevelopmentNotes.fodt +++ b/DevelopmentNotes/DevelopmentNotes.fodt @@ -276,19 +276,19 @@ office:mimetype="application/vnd.oasis.opendocument.text"> MultiMarkdown v6 Development Notes Fletcher T. Penney - 2018-03-38 + 2018-09-01 dd2d8e76-dc2d-416d-9acd-5395d20871c2 -Introduction +Introduction 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 absolute “best” Markdown (MD) implementation for their needs – it is not required reading to understand how the software works. -Why a New Version? +Why a New Version? MultiMarkdown version 5 was released in November of 2015, but the codebase was essentially the same as that of v4 – and that was released in beta in April @@ -319,7 +319,7 @@ had been using First Attempt +First Attempt 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 @@ -449,7 +449,7 @@ don’t follow the rules above. I’ll continue to work on this.In the end, I scrapped this effort, but kept the lessons learned in the token pairing algorithm. -Second Attempt +Second Attempt I tried again this past Fall. This time, I approached the problem with lots of reading. Lots and lots of reading – tons of websites, computer science @@ -517,13 +517,13 @@ anyway, if not better. about how to create the grammar used. But so far, it has been able to handle everything I have thrown at it. -Optimization +Optimization One of my goals for MMD 6 was performance. So I’ve paid attention to speed along the way, and have tried to use a few tricks to keep things fast. Here are some things I’ve learned along the way. In no particular order: -Memory Allocation +Memory Allocation When parsing a long document, a lot of token structures are created. Each 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 where it matters. -Proper input buffering +Proper input buffering 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 @@ -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 measurable difference. -Output Buffering +Output Buffering I experimented with different approaches to creating the output after parsing. I tried printing directly to stdout, and even played with different buffering settings. None of those seemed to work well, and all were slower than using the d_string approach (formerly called GString in MMD 5). -Fast Searches +Fast Searches After getting basic Markdown functionality complete, I discovered during testing that the time required to parse a document grew exponentially as the @@ -583,7 +583,7 @@ a link (or footnote, etc.) by “name” rather than searching through a This allowed me to get MMD’s performance back to O(n), taking roughly twice as much time to process a document that is twice as long. -Efficient Utility Functions +Efficient Utility Functions It is frequently necessary when parsing Markdown to check what sort of character we are dealing with at a certain position – 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 improved performance, but don’t have the data to back it up. -Testing While Writing +Testing While Writing I developed several chunks of code in parallel while creating MMD 6. The vast majority of it was developed largely in a test-driven development approach. @@ -608,7 +608,7 @@ allowed me to ensure new features work properly and that old features aren’ broken. At this time, there are 29 text files in the test suite, and many more to come. -Other Lessons +Other Lessons Some things that didn’t do me any good…. @@ -626,7 +626,7 @@ automatically, there was no noticeable performance change, and I didn’t ha the tools to measure whether I could have improved memory usage at all. Not sure this would be worth the effort – much lower hanging fruit available. -Performance +Performance Basic tests show that currently MMD 6 takes about 20–25% longer the CommonMark 0.27.0 to process long files (e.g. 0.2 MB). However, it is around 5% faster @@ -667,9 +667,9 @@ more challenging and see whether they can be reworked to improve performance. -Testing +Testing -Test Suite +Test Suite 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 @@ -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 application with every release. -Fuzz Testing +Fuzz Testing I was not familiar with the concept of Fuzz Testing 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. Definitely a useful tool! -Unit Testing +Unit Testing 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. @@ -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 code or used during the development. -Dependencies/Libraries +Dependencies/Libraries MMD v6 has no external dependencies when compiling, aside from the standard libraries for C development (Except that it will use libcurl if available in @@ -760,9 +760,162 @@ 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: diff --git a/DevelopmentNotes/DevelopmentNotes.html b/DevelopmentNotes/DevelopmentNotes.html index f12b5f7..43cb5e0 100644 --- a/DevelopmentNotes/DevelopmentNotes.html +++ b/DevelopmentNotes/DevelopmentNotes.html @@ -4,19 +4,19 @@ MultiMarkdown v6 Development Notes - + -

Introduction

+

Introduction

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 absolute “best” Markdown (MD) implementation for their needs – it is not required reading to understand how the software works.

-

Why a New Version?

+

Why a New Version?

MultiMarkdown version 5 was released in November of 2015, but the codebase was essentially the same as that of v4 – and that was released in beta in April @@ -43,7 +43,7 @@ had been using greg to compile th into parser code. It worked well overall, but lacked some features I needed, requiring a lot of workarounds.)

-

First Attempt

+

First Attempt

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 @@ -137,7 +137,7 @@ don’t follow the rules above. I’ll continue to work on this.

In the end, I scrapped this effort, but kept the lessons learned in the token pairing algorithm.

-

Second Attempt

+

Second Attempt

I tried again this past Fall. This time, I approached the problem with lots of reading. Lots and lots of reading – tons of websites, computer science @@ -195,13 +195,13 @@ anyway, if not better.

about how to create the grammar used. But so far, it has been able to handle everything I have thrown at it.

-

Optimization

+

Optimization

One of my goals for MMD 6 was performance. So I’ve paid attention to speed along the way, and have tried to use a few tricks to keep things fast. Here are some things I’ve learned along the way. In no particular order:

-

Memory Allocation

+

Memory Allocation

When parsing a long document, a lot of token structures are created. Each 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 where it matters.

-

Proper input buffering

+

Proper input buffering

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 @@ -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 measurable difference.

-

Output Buffering

+

Output Buffering

I experimented with different approaches to creating the output after parsing. I tried printing directly to stdout, and even played with different buffering settings. None of those seemed to work well, and all were slower than using the d_string approach (formerly called GString in MMD 5).

-

Fast Searches

+

Fast Searches

After getting basic Markdown functionality complete, I discovered during testing that the time required to parse a document grew exponentially as the @@ -261,7 +261,7 @@ a link (or footnote, etc.) by “name” rather than searching through a This allowed me to get MMD’s performance back to O(n), taking roughly twice as much time to process a document that is twice as long.

-

Efficient Utility Functions

+

Efficient Utility Functions

It is frequently necessary when parsing Markdown to check what sort of character we are dealing with at a certain position – 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 improved performance, but don’t have the data to back it up.

-

Testing While Writing

+

Testing While Writing

I developed several chunks of code in parallel while creating MMD 6. The vast majority of it was developed largely in a test-driven development approach. @@ -286,7 +286,7 @@ allowed me to ensure new features work properly and that old features aren’ broken. At this time, there are 29 text files in the test suite, and many more to come.

-

Other Lessons

+

Other Lessons

Some things that didn’t do me any good….

@@ -304,7 +304,7 @@ automatically, there was no noticeable performance change, and I didn’t ha the tools to measure whether I could have improved memory usage at all. Not sure this would be worth the effort – much lower hanging fruit available.

-

Performance

+

Performance

Basic tests show that currently MMD 6 takes about 20–25% longer the CommonMark 0.27.0 to process long files (e.g. 0.2 MB). However, it is around 5% faster @@ -345,9 +345,9 @@ more challenging and see whether they can be reworked to improve performance.

-

Testing

+

Testing

-

Test Suite

+

Test Suite

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 @@ -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 application with every release.

-

Fuzz Testing

+

Fuzz Testing

I was not familiar with the concept of Fuzz Testing 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. Definitely a useful tool!

-

Unit Testing

+

Unit Testing

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. @@ -396,7 +396,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 code or used during the development.

-

Dependencies/Libraries

+

Dependencies/Libraries

MMD v6 has no external dependencies when compiling, aside from the standard libraries for C development (Except that it will use libcurl if available in @@ -430,9 +430,50 @@ order to embed them in packaged file formats, e.g. EPUB 3, 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:

        diff --git a/DevelopmentNotes/DevelopmentNotes.pdf b/DevelopmentNotes/DevelopmentNotes.pdf index 0ecf1e4..bf637e9 100644 Binary files a/DevelopmentNotes/DevelopmentNotes.pdf and b/DevelopmentNotes/DevelopmentNotes.pdf differ diff --git a/DevelopmentNotes/DevelopmentNotes.txt b/DevelopmentNotes/DevelopmentNotes.txt index 43be8f8..64e6414 100644 --- a/DevelopmentNotes/DevelopmentNotes.txt +++ b/DevelopmentNotes/DevelopmentNotes.txt @@ -1,6 +1,6 @@ Title: MultiMarkdown v6 Development Notes Author: Fletcher T. Penney -Date: 2018-03-38 +Date: 2018-09-01 LaTeX Config: tufte-handout Base Header Level: 3 uuid: dd2d8e76-dc2d-416d-9acd-5395d20871c2 @@ -472,6 +472,47 @@ TextBundle/TextPack, OpenDocument, etc. # 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: * UPDATED: Update documentation diff --git a/QuickStart/QuickStart.epub b/QuickStart/QuickStart.epub index 4ac65de..72b0489 100644 Binary files a/QuickStart/QuickStart.epub and b/QuickStart/QuickStart.epub differ diff --git a/QuickStart/QuickStart.fodt b/QuickStart/QuickStart.fodt index 1615192..0d9da23 100644 --- a/QuickStart/QuickStart.fodt +++ b/QuickStart/QuickStart.fodt @@ -276,7 +276,7 @@ office:mimetype="application/vnd.oasis.opendocument.text"> MultiMarkdown v6 Quick Start Guide Fletcher T. Penney - 6.3.2 + 6.4.0 0d6313fa-9135-477e-9c14-7d62c1977833 @@ -319,15 +319,15 @@ office:mimetype="application/vnd.oasis.opendocument.text"> -Introduction +Introduction -Version: 6.3.2 +Version: 6.4.0 This document serves as a description of MultiMarkdown (MMD) v6, as well as a sample document to demonstrate the various features. Specifically, differences from MMD v5 will be pointed out. -Performance +Performance A big motivating factor leading to the development of MMD v6 was performance. When MMD first migrated from Perl to C (based on 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 anyway) make this project worthwhile. -Parse Tree +Parse Tree MMD v6 performs its parsing in the following steps: @@ -450,9 +450,9 @@ libMultiMarkdown is to be used in a multithreaded program, a separate slightly more abstracted mmd_convert_string() function that handles creating and destroying the mmd_engine automatically. -Features +Features -Abbreviations (Or Acronyms) +Abbreviations (Or Acronyms) 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 @@ -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 complex abbreviations, you must explicitly mark uses of the abbreviation. -Citations +Citations Citations can be specified using an inline syntax, just like inline footnotes. If you wish to use BibTeX, then configure the bibtex metadata (required) and @@ -481,7 +481,7 @@ the biblio style metadat The HTML output for citations now uses parentheses instead of brackets, e.g. (1) instead of [1]. -CriticMarkup +CriticMarkup MMD v6 has improved support for CriticMarkup, both in terms of parsing, and in terms of support for each output format. You can insert text, @@ -498,7 +498,7 @@ these two options, then CriticMarkup that spans a blank line is not recognizT formats). -Embedded Images +Embedded Images Supported export formats (odt, epub, bundle, bundlezip) include images inside the export document: @@ -517,13 +517,13 @@ properly installed when MMD is compiled. This is true fed as such. I working on options for this for the future. -Emph and Strong +Emph and Strong The basics of emphasis and strong emphasis are unchanged, but the parsing engine has been improved to be more accurate, particularly in various edge cases where proper parsing can be difficult. -EPUB 3 Support +EPUB 3 Support MMD v6 now provides support for direct creation of EPUB 3 files. Previously a separate tool was required to create EPUB files from MMD. It’s now built- @@ -546,7 +546,7 @@ document formats you need. Same goes for Amazon’s ebook formats – th run in batch mode (using the -b\--batch options). Otherwise, it simply outputs the HTML 5 file that would serve as the primary content for the EPUB. -Fenced Code Blocks +Fenced Code Blocks Fenced code blocks are fundamentally the same as MMD v5, except: @@ -562,12 +562,12 @@ considered to be part of the code block. -Footnotes +Footnotes The HTML output for footnotes now uses superscripts instead of brackets, e.g. <sup>1</sup> instead of [1]. -Glossary Terms +Glossary Terms If there are terms in your document you wish to define in a glossaryThe glossary collects information about important terms used in your document 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 glossary terms, you must explicitly mark uses of the term. -HTML Comments +HTML Comments 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 @@ -599,12 +599,12 @@ format since they would cause errors. Take a look at the HTML Comments.text file in the test suite for a better understanding of comment blocks vs comment spans, and how they are parsed. -Internationalization +Internationalization MMD v6 includes support for substituting certain text phrases in other languages. This only affects the HTML format. -LaTeX Changes +LaTeX Changes 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. @@ -695,7 +695,7 @@ the following latex config -Metadata +Metadata Metadata in MMD v6 includes new support for LaTeX – the latex config key allows you to automatically setup of multiple latex include files at once. @@ -727,7 +727,7 @@ use the transclusion functionality: Title:Some TitleMMD Header:This is *MMD* text.MMD Footer:{{footer.txt}} -Output Formats +Output Formats MultiMarkdown 6 supports the following output formats, using the -t command-line argument: @@ -772,11 +772,15 @@ 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}```{=latex}*foo*``` @@ -806,19 +810,19 @@ package is compressed to a single zip file (similar to EPUB and ODor macOS build -Table of Contents +Table of Contents By placing {{TOC}} in your document, you can insert an automatically generated Table of Contents in your document. As of MMD v6, the native Table of Contents functionality is used when exporting to LaTeX or OpenDocument formats. -Tables +Tables Tables in MultiMarkdown-6 work basically the same as before, but a caption, if present, must come after the body of the table, not before. -Transclusion +Transclusion File transclusion works basically the same way – {{file}} is used to indicate a file that needs to be transcluded. {{file.*}} allows for @@ -905,12 +909,12 @@ whether a file is being processed by itself or as part of a “parent” This can be useful when a particular file can either be a standalone document, or a chapter inside a larger document. -Developer Notes +Developer Notes If you’re using MMD as a library in another application, there are a few things to be aware of. -Object Pools +Object Pools 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 @@ -925,7 +929,7 @@ 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. -HTML Boolean Attributes +HTML Boolean Attributes Most HTML attributes are of the key-value type (e.g. key="value"). But some less frequently used attributes are boolean attributes (e.g. <videocontrols>). Properly distinguishing HTML from other uses of the < @@ -974,7 +978,7 @@ off. I will continue to research additional options. -Future Steps +Future Steps Some features I plan to implement at some point: diff --git a/QuickStart/QuickStart.html b/QuickStart/QuickStart.html index 7bad18f..2a55763 100644 --- a/QuickStart/QuickStart.html +++ b/QuickStart/QuickStart.html @@ -4,7 +4,7 @@ MultiMarkdown v6 Quick Start Guide - + @@ -47,15 +47,15 @@
      -

      Introduction

      +

      Introduction

      -

      Version: 6.3.2

      +

      Version: 6.4.0

      This document serves as a description of MultiMarkdown (MMD) v6, as well as a sample document to demonstrate the various features. Specifically, differences from MMD v5 will be pointed out.

      -

      Performance

      +

      Performance

      A big motivating factor leading to the development of MMD v6 was performance. When MMD first migrated from Perl to C (based on peg- @@ -131,7 +131,7 @@ files, the additional features of MMD compare the increased legibility of the source code of MMD (in my biased opinion anyway) make this project worthwhile.

      -

      Parse Tree

      +

      Parse Tree

      MMD v6 performs its parsing in the following steps:

      @@ -162,9 +162,9 @@ libMultiMarkdown is to be used in a multithreaded program, a separate slightly more abstracted mmd_convert_string() function that handles creating and destroying the mmd_engine automatically.

      -

      Features

      +

      Features

      -

      Abbreviations (Or Acronyms)

      +

      Abbreviations (Or Acronyms)

      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 @@ -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 complex abbreviations, you must explicitly mark uses of the abbreviation.

      -

      Citations

      +

      Citations

      Citations can be specified using an inline syntax, just like inline footnotes. If you wish to use BibTeX, then configure the bibtex metadata (required) and @@ -196,7 +196,7 @@ the biblio style metadata (optional).

      The HTML output for citations now uses parentheses instead of brackets, e.g. (1) instead of [1].

      -

      CriticMarkup

      +

      CriticMarkup

      MMD v6 has improved support for CriticMarkup, both in terms of parsing, and in terms of support for each output format. You can insert text, @@ -213,7 +213,7 @@ these two options, then CriticMarkup that spans a blank line is not recogniz

      T formats).

      -

      Embedded Images

      +

      Embedded Images

      Supported export formats (odt, epub, bundle, bundlezip) include images inside the export document:

      @@ -227,13 +227,13 @@ properly installed when MMD is compiled. This

      ed as such. I working on options for this for the future.

      -

      Emph and Strong

      +

      Emph and Strong

      The basics of emphasis and strong emphasis are unchanged, but the parsing engine has been improved to be more accurate, particularly in various edge cases where proper parsing can be difficult.

      -

      EPUB 3 Support

      +

      EPUB 3 Support

      MMD v6 now provides support for direct creation of EPUB 3 files. Previously a separate tool was required to create EPUB files from MMD. It’s now built- @@ -256,7 +256,7 @@ document formats you need. Same goes for Amazon’s ebook formats – th run in batch mode (using the -b\--batch options). Otherwise, it simply outputs the HTML 5 file that would serve as the primary content for the EPUB.

      -

      Fenced Code Blocks

      +

      Fenced Code Blocks

      Fenced code blocks are fundamentally the same as MMD v5, except:

      @@ -268,12 +268,12 @@ complex parser.

      • considered to be part of the code block.

      -

      Footnotes

      +

      Footnotes

      The HTML output for footnotes now uses superscripts instead of brackets, e.g. <sup>1</sup> instead of [1].

      -

      Glossary Terms

      +

      Glossary Terms

      If there are terms in your document you wish to define in a glossary at the end of your document, you can define them using the glossary syntax.

      @@ -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 glossary terms, you must explicitly mark uses of the term.

      -

      HTML Comments

      +

      HTML Comments

      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 @@ -311,12 +311,12 @@ format since they would cause errors.

      Take a look at the HTML Comments.text file in the test suite for a better understanding of comment blocks vs comment spans, and how they are parsed.

      -

      Internationalization

      +

      Internationalization

      MMD v6 includes support for substituting certain text phrases in other languages. This only affects the HTML format.

      -

      LaTeX Changes

      +

      LaTeX Changes

      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.

      @@ -384,7 +384,7 @@ the following latex config values by default:

      location for your system. I would like to make this easier, but haven’t found the best configuration yet.

      -

      Metadata

      +

      Metadata

      Metadata in MMD v6 includes new support for LaTeX – the latex config key allows you to automatically setup of multiple latex include files at once. @@ -416,7 +416,7 @@ MMD Header: This is *MMD* text. MMD Footer: {{footer.txt}} -

      Output Formats

      +

      Output Formats

      MultiMarkdown 6 supports the following output formats, using the -t command-line argument:

      @@ -442,11 +442,15 @@ and images between applications (on any OS, but especially on iOS) package is compressed to a single zip file (similar to EPUB and ODor macOS builds.
    -

    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}
 
@@ -467,19 +471,19 @@ package is compressed to a single zip file (similar to EPUB and ODor macOS build
 
  • * – wildcard matches any output format
    •
-

Table of Contents

+

Table of Contents

By placing {{TOC}} in your document, you can insert an automatically generated Table of Contents in your document. As of MMD v6, the native Table of Contents functionality is used when exporting to LaTeX or OpenDocument formats.

-

Tables

+

Tables

Tables in MultiMarkdown-6 work basically the same as before, but a caption, if present, must come after the body of the table, not before.

-

Transclusion

+

Transclusion

File transclusion works basically the same way – {{file}} is used to indicate a file that needs to be transcluded. {{file.*}} allows for @@ -549,12 +553,12 @@ whether a file is being processed by itself or as part of a “parent” This can be useful when a particular file can either be a standalone document, or a chapter inside a larger document.

-

Developer Notes

+

Developer Notes

If you’re using MMD as a library in another application, there are a few things to be aware of.

-

Object Pools

+

Object Pools

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 @@ -569,7 +573,7 @@ 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.

-

HTML Boolean Attributes

+

HTML Boolean Attributes

Most HTML attributes are of the key-value type (e.g. key="value"). But some less frequently used attributes are boolean attributes (e.g. <video @@ -605,7 +609,7 @@ option I have chosen as default for MMD ̵ off. I will continue to research additional options.

-

Future Steps

+

Future Steps

Some features I plan to implement at some point:

diff --git a/QuickStart/QuickStart.pdf b/QuickStart/QuickStart.pdf index 7639cdb..3b3ff11 100644 Binary files a/QuickStart/QuickStart.pdf and b/QuickStart/QuickStart.pdf differ diff --git a/QuickStart/QuickStart.txt b/QuickStart/QuickStart.txt index 84bff0f..08a04bf 100644 --- a/QuickStart/QuickStart.txt +++ b/QuickStart/QuickStart.txt @@ -1,6 +1,6 @@ Title: MultiMarkdown v6 Quick Start Guide Author: Fletcher T. Penney -Version: 6.3.2 +Version: 6.4.0 LaTeX Config: tufte-handout Base Header Level: 3 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 ## -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} diff --git a/README.md b/README.md index b787ca8..d27d8a5 100644 --- a/README.md +++ b/README.md @@ -4,9 +4,9 @@ | ---------- | ------------------------- | | Title: | MultiMarkdown | | Author: | Fletcher T. Penney | -| Date: | 2018-03-28 | +| Date: | 2018-09-01 | | 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) develop branch: [![Build Status](https://travis-ci.org/fletcher/MultiMarkdown-6.svg?branch=develop)](https://travis-ci.org/fletcher/MultiMarkdown-6)