zim-wiki team mailing list archive

[HansBKK <hansbkk@xxxxxxxxx>]

On Wed, Jan 25, 2012 at 5:29 PM, Jaap Karssenberg 
<jaap.karssenberg@xxxxxxxxx> wrote:

> >> 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 
that below).

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 ?
>  
  
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.