diff --git a/CHANGELOG.md b/CHANGELOG.md --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,9 @@ +## MMark 0.0.5.0 + +* Documentation improvements. + +* Added a dummy `Show` instance for the `MMark` type. + ## MMark 0.0.4.3 * Compiles with `modern-uri-0.2.0.0` and later. diff --git a/README.md b/README.md --- a/README.md +++ b/README.md @@ -4,8 +4,8 @@ [![Hackage](https://img.shields.io/hackage/v/mmark.svg?style=flat)](https://hackage.haskell.org/package/mmark) [![Stackage Nightly](http://stackage.org/package/mmark/badge/nightly)](http://stackage.org/nightly/package/mmark) [![Stackage LTS](http://stackage.org/package/mmark/badge/lts)](http://stackage.org/lts/package/mmark) -[![Build Status](https://travis-ci.org/mrkkrp/mmark.svg?branch=master)](https://travis-ci.org/mrkkrp/mmark) -[![Coverage Status](https://coveralls.io/repos/mrkkrp/mmark/badge.svg?branch=master&service=github)](https://coveralls.io/github/mrkkrp/mmark?branch=master) +[![Build Status](https://travis-ci.org/mmark-md/mmark.svg?branch=master)](https://travis-ci.org/mmark-md/mmark) +[![Coverage Status](https://coveralls.io/repos/mmark-md/mmark/badge.svg?branch=master&service=github)](https://coveralls.io/github/mmark-md/mmark?branch=master) * [Quick start: MMark vs GitHub-flavored markdown](#quick-start-mmark-vs-github-flavored-markdown) * [MMark and Common Mark](#mmark-and-common-mark) @@ -13,6 +13,7 @@ * [Other differences](#other-differences) * [About MMark-specific extensions](#about-mmark-specific-extensions) * [Performance](#performance) +* [Related packages](#related-packages) * [Contribution](#contribution) * [License](#license) @@ -30,8 +31,7 @@ makes sense. * An extension system allowing to create extensions that alter parsed - markdown document in some way. Some of them are available in the - [`mmark-ext`](https://hackage.haskell.org/package/mmark-ext) package. + markdown document in some way. * A [`lucid`](https://hackage.haskell.org/package/lucid)-based render. @@ -47,8 +47,8 @@ 1. URIs are not automatically recognized, you must enclose them in `<` and `>`. -2. Block quotes require only one `>` and they continue as long as long the - inner content is indented. +2. Block quotes require only one `>` and they continue as long as the inner + content is indented. This is OK: @@ -268,11 +268,11 @@ Library | Parsing library | Execution time | Allocated | Max residency --------------------|---------------------|---------------:|------------:|-------------: -`cmark-0.5.6` | Custom C code | 311.8 μs | 228,440 | 9,608 -`mmark-0.0.4.2` | Megaparsec | 7.757 ms | 32,207,640 | 37,856 -`cheapskate-0.1.1` | Custom Haskell code | 10.22 ms | 44,686,272 | 799,200 -`markdown-0.1.16` † | Attoparsec | 13.51 ms | 69,261,816 | 699,656 -`pandoc-2.0.5` | Parsec | 36.01 ms | 141,868,840 | 1,471,080 +`cmark-0.5.6` | Custom C code | 316.1 μs | 228,440 | 9,608 +`mmark-0.0.4.3` | Megaparsec | 7.280 ms | 32,207,640 | 37,856 +`cheapskate-0.1.1` | Custom Haskell code | 10.30 ms | 44,686,272 | 799,200 +`markdown-0.1.16` † | Attoparsec | 13.58 ms | 69,261,816 | 699,656 +`pandoc-2.0.5` | Parsec | 36.04 ms | 141,868,840 | 1,471,080 *Results are ordered from fastest to slowest.* @@ -283,10 +283,19 @@ with a far simpler approach to parsing at the price that it's not really a valid markdown implementation. +## Related packages + +* [`mmark-ext`](https://hackage.haskell.org/package/mmark-ext) contains some + commonly useful MMark extensions. +* [`mmark-cli`](https://hackage.haskell.org/package/mmark-cli) is a command + line interface to MMark. +* [`flycheck-mmark`](https://github.com/mmark-md/flycheck-mmark) is a way to + check markdown documents against MMark parser interactively from Emacs. + ## Contribution Issues, bugs, and questions may be reported in [the GitHub issue tracker for -this project](https://github.com/mrkkrp/mmark/issues). +this project](https://github.com/mmark-md/mmark/issues). Pull requests are also welcome and will be reviewed quickly. diff --git a/Text/MMark.hs b/Text/MMark.hs --- a/Text/MMark.hs +++ b/Text/MMark.hs @@ -102,7 +102,7 @@ -- -- === Other modules of interest -- --- The "Text.MMark" module contains all the “core” functionality you may +-- The "Text.MMark" module contains all the “core” functionality one may -- need. However, one of the main selling points of MMark is that it's -- possible to write your own extensions which stay highly composable (if -- done right), so proliferation of third-party extensions is to be expected diff --git a/Text/MMark/Extension.hs b/Text/MMark/Extension.hs --- a/Text/MMark/Extension.hs +++ b/Text/MMark/Extension.hs @@ -14,12 +14,24 @@ -- > import Text.MMark.Extension (Bni, Block (..), Inline (..)) -- > import qualified Text.MMark.Extension as Ext -- --- === Details about extensions +-- === Philosophy of MMark extensions -- --- There are four kinds of extension-producing functions. They correspond --- internally to four functions that are applied to the parsed document in --- turn: +-- The extension system is guided by the following goals: -- +-- 1. Make it powerful, so users can write interesting extensions. +-- 2. Make it efficient, so every type of transformation is only applied +-- once and the number of traversals of the syntax tree stays +-- constant no matter how many extensions the user chooses to use and +-- how complex they are. +-- 3. Make it easy to write extensions that are very focused in what +-- they do and do not interfere with each other in weird and +-- unexpected ways. +-- +-- I ruled out allowing users to mess with AST directly pretty quickly +-- because it would be against the points 2 and 3. Instead, there are four +-- kinds of extension-producing functions. They correspond internally to +-- four functions that are applied to the parsed document in turn: +-- -- * 'blockTrans' is applied first, as it's quite general and can change -- block-level structure of document as well as inline-level -- structure. @@ -27,13 +39,39 @@ -- in the previous step. -- * 'inlineRender' is applied to every inline; this function produces -- HTML rendition of the inlines and we also preserve the original --- inline so 'blockRender' can look at it (sometimes it is useful). +-- inlines so 'blockRender' can look at it (see 'Ois'). -- * 'blockRender' is applied to every block to obtain HTML rendition of -- the whole document. -- -- When one combines different extensions, extensions of the same kind get -- fused together into a single function. This allows for faster processing --- in the end. +-- and constant number of traversals over AST in the end. +-- +-- One could note that the current design does not allow prepending or +-- appending new elements to the AST. This is a limitation by design because +-- we try to make the order in which extensions are applied not important +-- (it's not always possible, though). Thus, if we want to e.g. insert a +-- table of contents into a document, we need to do so by transforming an +-- already existing element, such as code block with a special info string +-- (this is how the extension works in the @mmark-ext@ package). +-- +-- Another limitation by design is that extensions cannot change how the +-- parser works. I find endless syntax-changing (or syntax-augmenting, if +-- you will) extensions (as implemented by Pandoc for example) ugly, because +-- they erode the core familiar markdown syntax and turn it into a +-- monstrosity. In MMark we choose a different path of re-purposing existing +-- markdown constructs, adding a special meaning to them in certain +-- situations. +-- +-- === Room for improvement +-- +-- One flaw of the current system is that it does not allow reporting +-- errors, so we have to silently fallback to some default behavior when we +-- can't apply an extension in a meaningful way. Such extension-produced +-- errors obviously should contain their positions in the original markdown +-- input, which would require us storing this information in AST in some +-- way. I'm not sure if the additional complexity (and possible performance +-- trade-offs) is really worth it, so it hasn't been implemented so far. {-# LANGUAGE RankNTypes #-} diff --git a/Text/MMark/Type.hs b/Text/MMark/Type.hs --- a/Text/MMark/Type.hs +++ b/Text/MMark/Type.hs @@ -58,10 +58,17 @@ instance NFData MMark where rnf MMark {..} = rnf mmarkYaml `seq` rnf mmarkBlocks --- | An extension. You can apply extensions with 'useExtension' and --- 'useExtensions' functions. The "Text.MMark.Extension" module provides --- tools for extension creation. +-- | Dummy instance. -- +-- @since 0.0.5.0 + +instance Show MMark where + show = const "MMark {..}" + +-- | An extension. You can apply extensions with 'Text.MMark.useExtension' +-- and 'Text.MMark.useExtensions' functions. The "Text.MMark.Extension" +-- module provides tools for writing your own extensions. +-- -- Note that 'Extension' is an instance of 'Semigroup' and 'Monoid', i.e. -- you can combine several extensions into one. Since the @('<>')@ operator -- is right-associative and 'mconcat' is a right fold under the hood, the @@ -217,8 +224,8 @@ -- | A wrapper for “originial inlines”. Source inlines are wrapped in this -- during rendering of inline components and then it's available to block -- render, but only for inspection. Altering of 'Ois' is not possible --- because the user cannot construct a value of the 'Ois' type, she can only --- inspect it with 'getOis'. +-- because the user cannot construct a value of the 'Ois' type, he\/she can +-- only inspect it with 'getOis'. newtype Ois = Ois (NonEmpty Inline) diff --git a/mmark.cabal b/mmark.cabal --- a/mmark.cabal +++ b/mmark.cabal @@ -1,13 +1,13 @@ name: mmark -version: 0.0.4.3 +version: 0.0.5.0 cabal-version: >= 1.18 tested-with: GHC==7.10.3, GHC==8.0.2, GHC==8.2.2 license: BSD3 license-file: LICENSE.md author: Mark Karpov maintainer: Mark Karpov -homepage: https://github.com/mrkkrp/mmark -bug-reports: https://github.com/mrkkrp/mmark/issues +homepage: https://github.com/mmark-md/mmark +bug-reports: https://github.com/mmark-md/mmark/issues category: Text synopsis: Strict markdown processor for writers build-type: Simple @@ -19,7 +19,7 @@ source-repository head type: git - location: https://github.com/mrkkrp/mmark.git + location: https://github.com/mmark-md/mmark.git flag dev description: Turn on development settings. @@ -100,7 +100,7 @@ hs-source-dirs: bench/speed type: exitcode-stdio-1.0 build-depends: base >= 4.8 && < 5.0 - , criterion >= 0.6.2.1 && < 1.3 + , criterion >= 0.6.2.1 && < 1.4 , mmark , text >= 0.2 && < 1.3 if flag(dev)