1## About ## 2 3| | | 4| ---------- | ------------------------- | 5| Title: | libMultiMarkdown | 6| Author: | Fletcher T. Penney | 7| Date: | 2020-10-28 | 8| Copyright: | Copyright © 2016 - 2020 Fletcher T. Penney. | 9| Version: | 6.6.0 | 10 11master branch: [](https://travis-ci.org/fletcher/MultiMarkdown-6) 12develop branch: [](https://travis-ci.org/fletcher/MultiMarkdown-6) 13 14## An Announcement! ## 15 16MultiMarkdown v6 is finally here! If you want more information about 17testing, see `DevelopmentNotes`. 18 19If you want to more know about the differences from v5, see the `QuickStart` 20guide. 21 22 23## Obtaining MultiMarkdown ## 24 25You can download the latest installer for MacOS or Windows at Github: 26 27<https://github.com/fletcher/MultiMarkdown-6/releases> 28 29To build from source, download from Github. Then: 30 31 make release 32 (OR) 33 make debug 34 35 cd build 36 make 37 38You can optionally test using the test suite: 39 40 ctest 41 42 43### Xcode 44 45In order to use libMultiMarkdown in your Xcode project: 46 471. `cd` into the root of your Xcode project folder (where the `.xcodeproj` file 48 resides). 49 502. Add this project as a git submodule: 51 52 git submodule add https://github.com/fletcher/MultiMarkdown-6 MultiMarkdown-6 53 543. Compile: 55 56 cd MultiMarkdown-6 57 make xcode 58 594. Drag the `build-xcode/MultiMarkdown.xcodeproj` file to the root of your 60 Xcode project as a subproject. 61 625. Select the `MultiMarkdown` subproject, select the `libMultiMarkdown` target, 63 and in Build Phases > Copy Files select Products Directory from the 64 Destination popup menu. 65 666. Select your root project, select your target, add `libMultiMarkdown` under 67 Target Depencies and `libMultiMarkdown.framework/libMultiMarkdown` and 68 `libcurl.tdb` under Link Binary with Libraries. 69 70Warning: if you move the project on disk or update the MultiMarkdown source 71files, you need to rerun step 3 above. 72 73You can now `#import <libMultiMarkdown/libMultiMarkdown.h>`. To get you started, 74here is (untested) demonstration code that converts a `NSString` to HTML: 75 76 token_pool_init(); // needs to be done once per app lifecycle - PLEASE READ token.h!!!!!!!!!!! 77 78 NSString *input = @"Test *string* for **demonstration**."; 79 const char *cString = [input cStringUsingEncoding:NSUTF8StringEncoding]; 80 const char *mmd = mmd_string_convert(cString, EXT_SMART | EXT_NOTES | EXT_CRITIC | EXT_TRANSCLUDE, FORMAT_HTML, ENGLISH); 81 NSString *output = [[NSString alloc] initWithCString:mmd encoding:NSUTF8StringEncoding]; 82 83 // Cleanup 84 free(mmd); 85 token_pool_drain(); // again, PLEASE READ token.h!!!!!! 86 token_pool_free(); 87 88There are 3 main versions of the primary functions: 89 90* `mmd_string...`: start from source text in c string 91* `mmd_d_string...`: start from a DString (Useful if you already use DString's for your text) 92* `mmd_engine...`: useful when you are processing the same source multiple times 93 94The C string variants are as follows: 95 96 // Convert OPML string to MMD 97 DString * mmd_string_convert_opml_to_text(const char * source); 98 99 // Convert ITMZ string to MMD 100 DString * mmd_string_convert_itmz_to_text(const char * source); 101 102 // Convert MMD text to specified format, with specified extensions, and language 103 // Returned char * must be freed 104 char * mmd_string_convert(const char * source, unsigned long extensions, short format, short language); 105 106 // Convert MMD text to specified format using DString as a container for block of data 107 // and length of that block. Must be used for "complex" output formats such as EPUB. 108 // Returned DString * must be freed 109 DString * mmd_string_convert_to_data(const char * source, unsigned long extensions, short format, short language, const char * directory); 110 111 // Convert MMD text and write results to specified file -- used for "complex" output formats requiring 112 // multiple documents (e.g. EPUB) 113 void mmd_string_convert_to_file(const char * source, unsigned long extensions, short format, short language, const char * directory, const char * filepath); 114 115 // Does the text have metadata? 116 bool mmd_string_has_metadata(char * source, size_t * end); 117 118 // Return metadata keys, one per line 119 // Returned char * must be freed 120 char * mmd_string_metadata_keys(char * source); 121 122 // Extract desired metadata as string value 123 // Returned char * must be freed 124 char * mmd_string_metavalue_for_key(char * source, const char * key); 125 126 // Insert/replace metadata in string, returning new string 127 char * mmd_string_update_metavalue_for_key(const char * source, const char * key, const char * value); 128 129 // Grab list of all transcluded files, but we need to know directory to search, 130 // as well as the path to the file 131 // Returned stack needs to be freed 132 struct stack * mmd_string_transclusion_manifest(const char * source, const char * search_path, const char * source_path); 133 134The following enums can be used for the parameters `language`, `format` and `extensions`: 135 136 enum smart_quotes_language { 137 ENGLISH = 0, 138 DUTCH, 139 FRENCH, 140 GERMAN, 141 GERMANGUILL, 142 SPANISH, 143 SWEDISH, 144 }; 145 146 enum output_format { 147 FORMAT_HTML, 148 FORMAT_EPUB, 149 FORMAT_LATEX, 150 FORMAT_BEAMER, 151 FORMAT_MEMOIR, 152 FORMAT_FODT, 153 FORMAT_ODT, 154 FORMAT_TEXTBUNDLE, 155 FORMAT_TEXTBUNDLE_COMPRESSED, 156 FORMAT_OPML, 157 FORMAT_ITMZ, 158 FORMAT_MMD, 159 }; 160 161 enum parser_extensions { 162 EXT_COMPATIBILITY = 1 << 0, //!< Markdown compatibility mode 163 EXT_COMPLETE = 1 << 1, //!< Create complete document 164 EXT_SNIPPET = 1 << 2, //!< Create snippet only 165 EXT_SMART = 1 << 3, //!< Enable Smart quotes 166 EXT_NOTES = 1 << 4, //!< Enable Footnotes 167 EXT_NO_LABELS = 1 << 5, //!< Don't add anchors to headers, etc. 168 EXT_PROCESS_HTML = 1 << 6, //!< Process Markdown inside HTML 169 EXT_NO_METADATA = 1 << 7, //!< Don't parse Metadata 170 EXT_OBFUSCATE = 1 << 8, //!< Mask email addresses 171 EXT_CRITIC = 1 << 9, //!< Critic Markup Support 172 EXT_CRITIC_ACCEPT = 1 << 10, //!< Accept all proposed changes 173 EXT_CRITIC_REJECT = 1 << 11, //!< Reject all proposed changes 174 EXT_RANDOM_FOOT = 1 << 12, //!< Use random numbers for footnote links 175 EXT_TRANSCLUDE = 1 << 13, //!< Perform transclusion(s) 176 EXT_PARSE_OPML = 1 << 14, //!< Convert from OPML before processing source text 177 EXT_PARSE_ITMZ = 1 << 15, //!< Convert from ITMZ (iThoughts) before processing source text 178 EXT_RANDOM_LABELS = 1 << 16, //!< Use random numbers for header labels (unless manually defined) 179 EXT_FAKE = 1 << 31, //!< 31 is highest number allowed 180 }; 181 182 183## Differences in the MultiMarkdown Syntax ## 184 185MultiMarkdown v6 is mostly about making a better MMD parser, but it involves a 186few changes to the MultiMarkdown syntax itself. 187 1881. Setext headers can consist of more than one line to be included in the 189header: 190 191 This is 192 a header 193 ======== 194 1952. Whitespace is not allowed between the text brackets and label brackets in 196reference links, images, footnotes, etc. For example `[foo] [bar]` will no 197longer be the same as `[foo][bar]`. 198 1993. Link and image titles can be quoted with `'foo'`, `"foo"`, or `(foo)`. 200Link attributes can be used in both reference and inline links/images. 201 2024. HTML elements are handled slightly differently. There is no longer a 203`markdown="1"` feature. Instead, HTML elements that are on a line by 204themselves will open an HTML block that will cause the rest of the "paragraph" 205to be treated as HTML such that Markdown will not be parsed in side of it. 206HTML block-level tags are even "stronger" at starting an HTML block. It is 207not quite as complex as the approach used in CommonMark, but is similar under 208most circumstances. Leaving a blank line after the opening tag will allow 209MultiMarkdown parsing inside of the HTML block. 210 211 For example, this would not be parsed: 212 213 <div> 214 *foo* 215 </div> 216 217 But this would be: 218 219 <div> 220 221 *foo* 222 223 </div> 224 2255. "Malformed" reference link definitions are handled slightly differently. 226For example, the test suite file `Reference Footnotes.text` is parsed 227differently in compatibility mode than MMD-5. This started as a side-effect 228of the parsing algorithm, but I actually think it makes sense. This may or 229may not change in the future. 230 2316. Table captions in MMD-6 must come immediately *after* the table, not 232before it. 233 2347. Escaped linebreaks (`\` preceding a line break) will be interpreted as 235`<br />` (even in compatibility mode). This was previously an optional 236feature in MMD, but I don't see a problem with just making it default 237behavior. 238 2398. Escaped spaces (`\ `) will be interpreted as a non-breaking space, if the 240output format supports it. 241 2429. CriticMarkup, Abbreviations, Glossary Terms, and Citations are handled 243slightly differently. See the QuickStart guide for more information. 244 24510. Fenced code blocks can use leading/trailing "fences" of 3, 4, or 5 246backticks in length. That should be sufficient for complex documents without 247requiring a more complex parser. If there is no trailing fence, then the 248fenced block is considered to go through the end of the document. 249 25011. Emph and Strong parsing is conceptually the same, but the implementation 251is different. It is designed for speed, accuracy, and consistency. In 252general, it seems to handle edge cases much more reliably, but there are still 253a couple of situations that I would like to take into account, if possible. 254These are not situations that should occur often in "real life." 255 25612. EPUB 3 output is supported without need of any external tools. 257 25813. Internationalization support for HTML phrases, such as "see footnote". See 259[Github](https://github.com/fletcher/MultiMarkdown-6/issues/37) for more 260information. 261 262 263 264## License ## 265 266 The `MultiMarkdown 6` project is released under the MIT License.. 267 268 GLibFacade.c and GLibFacade.h are from the MultiMarkdown v4 project: 269 270 https://github.com/fletcher/MultiMarkdown-4/ 271 272 MMD 4 is released under both the MIT License and GPL. 273 274 275 CuTest is released under the zlib/libpng license. See CuTest.c for the 276 text of the license. 277 278 uthash library: 279 Copyright (c) 2005-2016, Troy D. Hanson 280 281 Licensed under Revised BSD license 282 283 miniz library: 284 Copyright 2013-2014 RAD Game Tools and Valve Software 285 Copyright 2010-2014 Rich Geldreich and Tenacious Software LLC 286 287 Licensed under the MIT license 288 289 argtable3 library: 290 Copyright (C) 1998-2001,2003-2011,2013 Stewart Heitmann 291 <sheitmann@users.sourceforge.net> 292 All rights reserved. 293 294 Licensed under the Revised BSD License 295 296 297 ## The MIT License ## 298 299 Permission is hereby granted, free of charge, to any person obtaining 300 a copy of this software and associated documentation files (the 301 "Software"), to deal in the Software without restriction, including 302 without limitation the rights to use, copy, modify, merge, publish, 303 distribute, sublicense, and/or sell copies of the Software, and to 304 permit persons to whom the Software is furnished to do so, subject to 305 the following conditions: 306 307 The above copyright notice and this permission notice shall be 308 included in all copies or substantial portions of the Software. 309 310 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 311 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 312 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. 313 IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY 314 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, 315 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE 316 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 317 318 319 ## Revised BSD License ## 320 321 Redistribution and use in source and binary forms, with or without 322 modification, are permitted provided that the following conditions are 323 met: 324 * Redistributions of source code must retain the above copyright 325 notice, this list of conditions and the following disclaimer. 326 * Redistributions in binary form must reproduce the above 327 copyright notice, this list of conditions and the following 328 disclaimer in the documentation and/or other materials provided 329 with the distribution. 330 * Neither the name of the <organization> nor the 331 names of its contributors may be used to endorse or promote 332 products derived from this software without specific prior 333 written permission. 334 335 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 336 "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 337 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 338 A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL <COPYRIGHT 339 HOLDER> BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 340 EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 341 PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES LOSS OF USE, DATA, OR 342 PROFITS OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 343 LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 344 NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 345 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 346 347
){kind=link}
){kind=link}