zim-wiki team mailing list archive
Mailing list archive
Re: Zim (personal desktop wiki) looking to possibly support "pandoc syntax"
On Wed, Jan 25, 2012 at 5:29 PM, Jaap Karssenberg
> >> meta-data header
> Consider this a zim specific wrapper around the actual content of the
> page. Just using email headers (rfc 822) with a few custom fields. Other
> media could use different wrapper to communicate the same meta-data.
Exactly - I was simply pointing out that to the extent this
meta-information is useful and similarly supported in one or more of the
target output formats, it should be converted along with the content - for
example, I believe EPUB has something similar. . ..
> Quick question - I was told before that markdown+extensions is the
> preferred format for pandoc. But now it sounds like you consider reST the
> default format. Which of the two should we focus on?
Back to my question why we are talking about reST/Spinx, and not Markdow
> with pandoc extensions.
It turns out now there are actually three choices for your "entry point"
syntax into Pandoc 8-)
- markdown + extensions
- a subset of standard reST (all the relevant bits)
- json syntax
John recommended reST based on the fact that Zim's a Python project. Pandoc
supports all the reST features with corresponding markdown+ elements, and
I'm confident that support would expand if needed in the future (more on
I'm sure if you'd prefer markdown+ that would also work perfectly well, but
note that reST is more of an "open standard" supported by the huge Python
dev-docs community, while Pandoc's extensions are specific to Pandoc.
I personally know very little about json (not being a programmer), but
apparently that would most reliably represent the internal/native pandoc
data structures; however its syntax isn't documented, so would require a
fair bit of experimentation with pandocs itself.
My long term goal is for zim to support multiple syntaxes to store it's
> data. Markdown is on my list for that feature, looks like I'll need
> extensions like the ones in pandoc to make all zim features work.
Note that however you get the data structured properly for Pandoc, you get
"for free" not only markdown/reST, but:
- HTML, textile/LaTeX (hence PDF), ConTeXt, S5, DocBook XML,
OpenDocumentXML, ODT, RTF, MediaWiki, Emacs org-mode, EPUB
and many more as well. The only reason Pandoc has added its own extensions
is to allow for features supported by these other target output formats but
not by the core markdown syntax, like:
- inline LaTeX math, tables, definition lists, superscripts and
subscripts, smart quotes and dashes, and footnotes.
I'm starting to feel like the amazing Ginsu knife salesman here - but wait!
there's more! 8-)
> My understanding is that I can generate markdown with extension and call
> pandoc to convert it to any of the formats supported by pandoc. This means
> some coding for me, but does not require any change in pandoc, correct ?
My (at this stage somewhat premature) point was that if you choose to
follow John's primary recommendation - to output standard reST/Sphinx path
rather than markdown+pandoc-specific-extensions, you now also have the
ability to use the standard Python docutils+Sphinx conversion tools for say
HTML and PDF (usually via LaTeX).
You may find that some Zim features (current or future) such as
hierarchical table of contents, cross-reference links, glossary terms,
topic-tagging and end-matter indexes, citation/biblio references could make
use - within that context - of some of the Sphinx extensions to reST that
aren't supported by Pandoc.
>From Zim's point of view, that's not an issue, you're not dependent on
Pandoc. However, from what I've seen of the rapid dev cycle around here, I
reckon it's very likely that John would in fact quickly enhance Pandoc's
support of the rest/Sphinx syntax - I'm no coder, but I've been frankly
amazed at the speed he's turned around what seem to me to be pretty
non-trivial feature requests posted to the pandoc list.
However this is more work then just export, because I need both export and
> import, and make sure all data from import is preserved in the internal
> model such that export reconstructs the import.
AFAICT you won't need to do your own import - just let Pandoc handle the
many-to-many complexity, including the changes constantly coming in various
output formats - you only need to track the one "entry point" syntax.
And by selecting reST/Sphinx as that syntax, you've still got the few
biggest mainstream output formats directly supported by the Python doc/devs
even if Pandocs were to disappear.
Seems like a slam-dunk to me 8-)
PS once again emphasizing that I'm a total noob to both projects, so to the
extent any of the above contains errors I hope those more knowledgeable
than me will jump in - obviously any comments welcome from anyone.