From: Fletcher T. Penney Date: Wed, 28 Mar 2018 01:23:35 +0000 (-0400) Subject: version bump X-Git-Tag: 6.3.1^2 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=715c106d28cf79396c1efc0928ceb7818edb67bd;p=multimarkdown version bump --- diff --git a/CMakeLists.txt b/CMakeLists.txt index 0d650bd..f46e018 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-02-05") +set (My_Project_Revised_Date "2018-03-27") set (My_Project_Version_Major 6) set (My_Project_Version_Minor 3) -set (My_Project_Version_Patch 0) +set (My_Project_Version_Patch 1) set (My_Project_Version "${My_Project_Version_Major}.${My_Project_Version_Minor}.${My_Project_Version_Patch}") diff --git a/QuickStart/QuickStart.epub b/QuickStart/QuickStart.epub index 6534f83..e28607b 100644 Binary files a/QuickStart/QuickStart.epub and b/QuickStart/QuickStart.epub differ diff --git a/QuickStart/QuickStart.fodt b/QuickStart/QuickStart.fodt index b3a30e3..9e2b790 100644 --- a/QuickStart/QuickStart.fodt +++ b/QuickStart/QuickStart.fodt @@ -311,6 +311,9 @@ office:mimetype="application/vnd.oasis.opendocument.text"> Table of Contents 1 Tables 1 Transclusion 1 +Developer Notes 1 +Object Pools 1 +HTML Boolean Attributes 1 Future Steps 1 @@ -902,6 +905,75 @@ 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 + +If you’re using MMD as a library in another application, there are a few +things to be aware of. + +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 +large chunk of memory is more efficient than allocating many smaller chunks. +However, this does complicate memory management. + +By default token.h defines kUseObjectPool which enables this performance +improvement. This does require more caution with the way that memory is +managed. (See main.c for an example of how the object pool is allocated and +drained.) I recommend disabling object pools unless you really understand C +memory management, and understand MultiMarkdown’s program flow. Failure to +properly manage the object pool can lead to massive memory leaks, freeing +memory before that is still in use, or other potential problems. + +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 < +character requires matching both types under certain circumstances. + +There are some trade-offs to be made: + + + +Performance when compiling MultiMarkdown + + +Performance when processing parts of documents that are not HTML + + +Accuracy when matching HTML + + + +So far, there seem to be four main approaches: + + + +Ignore boolean attributes – this is how MMD-6 started. This is fast, but +not accurate for some users. Several users found issues with the <video> tag +when MMD was used in HTML heavy documents. + + +Use regexp to match all boolean attributes. This is fast to compile, but +adds roughly 5–8% processing time (probably due to false positive HTML +matches). This may cause some text to be classified as HTML when it +shouldn’t. + + +Explicitly match all possible boolean attributes – This would presumably be +relatively fast when processing (due to the nature of re2c lexers), but it may +be prohibitively slow to compile for some users. As someone who compiles MMD +frequently, it is too slow to compile be useful for me during development. + + +Use a hand-curated list of boolean attributes that are most commonly used – +this does not incur much of a performance hit when parsing, and compiles +faster than the complete list of all boolean attributes. For now, this is the +option I have chosen as default for MMD – it seems to be a reasonable trade- +off. I will continue to research additional options. + + + Future Steps Some features I plan to implement at some point: diff --git a/QuickStart/QuickStart.html b/QuickStart/QuickStart.html index 765a9ef..8490466 100644 --- a/QuickStart/QuickStart.html +++ b/QuickStart/QuickStart.html @@ -37,6 +37,12 @@
  • Transclusion
    • +
  • Developer Notes + +
  • Future Steps
    • @@ -543,6 +549,62 @@ 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

    + +

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

    + +

    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 +large chunk of memory is more efficient than allocating many smaller chunks. +However, this does complicate memory management.

    + +

    By default token.h defines kUseObjectPool which enables this performance +improvement. This does require more caution with the way that memory is +managed. (See main.c for an example of how the object pool is allocated and +drained.) I recommend disabling object pools unless you really understand C +memory management, and understand MultiMarkdown’s program flow. Failure to +properly manage the object pool can lead to massive memory leaks, freeing +memory before that is still in use, or other potential problems.

    + +

    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 +controls>). Properly distinguishing HTML from other uses of the < +character requires matching both types under certain circumstances.

    + +

    There are some trade-offs to be made:

    + + + +

    So far, there seem to be four main approaches:

    + + +

    Future Steps

    Some features I plan to implement at some point:

    diff --git a/QuickStart/QuickStart.pdf b/QuickStart/QuickStart.pdf index 16e3ccf..94f9298 100644 Binary files a/QuickStart/QuickStart.pdf and b/QuickStart/QuickStart.pdf differ diff --git a/README.md b/README.md index 4d459cd..f473091 100644 --- a/README.md +++ b/README.md @@ -4,9 +4,9 @@ | ---------- | ------------------------- | | Title: | MultiMarkdown | | Author: | Fletcher T. Penney | -| Date: | 2018-02-05 | +| Date: | 2018-03-27 | | Copyright: | Copyright © 2016 - 2018 Fletcher T. Penney. | -| Version: | 6.3.0 | +| Version: | 6.3.1 | master branch: [![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)