zim-wiki team mailing list archive

[hansbkk@xxxxxxxxx]

It seems possible that there are communications problems caused by the fact
that I'm cross-posting to both lists, so it might be best for anyone with
more specific questions or comments to continue the conversation by posting
directly.

FYR again here are the links to the relevant threads:

https://groups.google.com/forum/#!topic/pandoc-discuss/B0rIgV_CKto/discussion
https://groups.google.com/forum/#!topic/pandoc-discuss/ASTjSB_4gnM/discussion

On Wednesday, January 25, 2012 9:41:49 PM UTC+7, HansBKK wrote:
>
>
> On Wed, Jan 25, 2012 at 5:29 PM, Jaap Karssenberg <jaap.k...@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.
>
>
>
On Wednesday, January 25, 2012 9:41:49 PM UTC+7, HansBKK wrote:
>
>
> On Wed, Jan 25, 2012 at 5:29 PM, Jaap Karssenberg <jaap.k...@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.
>
>
>