Pandoc: Markua Writer

[mpickering]

http://markua.org/

Markup format based on CommonMark.

Used on LearnPub

[bpj]

@mpickering, do you intend to implement this as an extension to markdown or as its own writer?
I suppose a CommonMark writer will be needed eventually, posing the same question, no?

[mpickering]

I don't intend to implement it personally. It would probably be easier to implement it as an extension to the current markdown writer.

I think the current markdown writer will probably conform to CommonMark. As far as I could see, CommonMark was an effort to resolve ambiguous parses. If the markdown writer is careful to avoid such ambiguities then it should be fine.

[KurtPfeifle]

I think a markua _reader_ would also be required, since markua has defined
some of its own Markdown syntax extensions.
​

On Mon, Jan 12, 2015 at 1:42 PM, Benct Philip Jonsson <
[email protected]> wrote:

@mpickering https://github.com/mpickering, do you intend to implement
this as an extension to markdown or as its own writer?
I suppose a CommonMark writer will be needed eventually, posing the same
question, no?

—
Reply to this email directly or view it on GitHub
https://github.com/jgm/pandoc/issues/1871#issuecomment-69564329.

[mpickering]

I tag this as a writer extension as I envisage most authors will want to
write their boots in pandoc markdown and then convert to markua before
submitting.

On Mon, Jan 12, 2015 at 1:20 PM, KurtPfeifle [email protected]
wrote:

I think a markua _reader_ would also be required, since markua has defined
some of its own Markdown syntax extensions.
​

On Mon, Jan 12, 2015 at 1:42 PM, Benct Philip Jonsson <
[email protected]> wrote:

@mpickering https://github.com/mpickering, do you intend to implement
this as an extension to markdown or as its own writer?
I suppose a CommonMark writer will be needed eventually, posing the same
question, no?

—
Reply to this email directly or view it on GitHub
https://github.com/jgm/pandoc/issues/1871#issuecomment-69564329.

—
Reply to this email directly or view it on GitHub
https://github.com/jgm/pandoc/issues/1871#issuecomment-69568142.

[peterarmstrong]

As the lead author of Markua, once Markua is done it would be fantastic if there was a reader and a writer for it in pandoc. I expect Markua to be at 1.0 in Q3 this year, once we have a reference implementation of it in ES6 and support for it in Leanpub. (I want it to be tested by real-world usage before it's considered to be 1.0 quality.)

[hayd]

So to do this is the objective to write a reader as some kind of mish-mash (ahem, I mean according to the Markua spec) of Markdown and CommonMark? Hopefully, assuming there's nothing too novel/fancy it should be mostly be copy and pasting of those snippets from those files... :)

I'm guessing that the reader is more important that the writer here, CommonMark doesn't have a writer.

_Aside: It'd be really nice if there was a way to get an image as title page in pandoc (ala leanpub)._

[jgm]

+++ Andy Hayden [Jun 02 15 19:02 ]:

I'm guessing that the reader is more important that the writer here,
CommonMark doesn't have a writer.

Yes, it does.

[jgm]

+++ Andy Hayden [Jun 02 15 19:02 ]:

I'm guessing that the reader is more important that the writer here,
CommonMark doesn't have a writer.

I should add that, the way the CommonMark reader and writer
are currently implemented (by wrapping libcmark), it would
not be easy to extend them. A couple people are working on
Haskell parsers for CommonMark, which might solve that
problem. And really, it depends on the extensions you're
using. It's often possible to use _conventions_ within
standard CommonMark constructs that can be intercepted at
the AST level and handled even using stock CommonMark
parsers. That, I think, is usually a better approach than
ad-hoc extension syntaxes, and I would recommend that
Markua authors consider it. A huge advantage of it is that
your documents will be fully CommonMark compatible (they
will degrade gracefully when your special postprocessors
aren't there). An example of what I mean here:
http://talk.commonmark.org/t/what-could-a-spoiler-tag-extension-look-like/767/68?u=jgm

[peterarmstrong]

Markua is an open text format for writing books and documents which is very similar to Markdown, but which is not Markdown. (Markua isn't trying to be a competitor to CommonMark as a formally specified Markdown; Markua is trying to be Markua.)

The goals of Markua have evolved from when I first announced it, as I've been iterating on the spec. The stated goal of Markua is now "Markua is intended to be extremely simple and powerful. We want Markua to be the best way in the world to write everything from a short story or a novel to a computer programming book, user manual or doctoral thesis."

The spec (https://leanpub.com/markua/read) is more advanced than the Markua marketing site right now.

Specifically, there are meaningful incompatibilities with Markdown. These include:

• inline HTML is not supported
• single newlines are interpreted differently
• trailing spaces at the end of lines are ignored (the two space trick is gone)
• There is only one type of bulleted list delimiter, the asterisk (*).
• In a numbered list, the number that begins the list is the number that begins the list in the output (as opposed to the output always starting with 1).
• In a numbered list, numbers must be consecutive. You're not allowed to start every entry with 1..
• There's no support for indented code blocks.

So, chances are a Markua reader and writer would be best done as a copy-paste-modify of a Markdown or CommonMark one.

Scott and I are both terrible Haskell programmers, so we're not capable of doing this in a timely manner, or we'd ship one. (We're so bad at Haskell that we use Kramdown not pandoc in Leanpub.) What we are doing is producing a test harness which any Markua implementation (including the open source ES6 one) needs to pass, etc.

Once Markua is at 1.0, I'd be thrilled if pandoc supported it. We'll happily work with people to help make this happen. (I am also fine with someone starting work before Markua is at 1.0, but I reserve the right to make breaking changes -- so you probably should wait :)

If you have any questions, please email me at [email protected]. I'll be in touch when Markua gets to 1.0...

Thanks!
Peter

[hayd]

In a numbered list, the number that begins the list is the number that begins the list in the output (as opposed to the output always starting with 1).

This is part of the commonmark spec (there's a start attribute).

Except for

In a numbered list, numbers must be consecutive. You're not allowed to start every entry with 1..

The rest look like they should all already be available in some sense (like you can turn things off e.g. the bullets) in Pandoc IIUC.

---

The other solution which may be easier if tweaking Markdown.hs is not possible, is you write a converter from Markua to CommonMark (escape html, \ escape some bullets and indented code, if bullet numbers aren't consecutive add newline between them - that kind of thing.)