At http://software-carpentry.org/blog/2014/10/pandoc-and-gh-pages.html Greg wrote:
Here's a summary of the forces we need to balance:
1. People should be able to write lessons in Markdown. We choose Markdown
rather than LaTeX or HTML because it's easier to read, diff, and merge;
we
choose it rather than AsciiDoc or reStructuredText (reST) because
it's much better known.
Either Jekyll/Kramdown as Pandoc match this requirement.
2. People should be able to preview their lessons locally before
publishing them, both to avoid embarrassment and because many
people compose offline.
Again, either Jekyll as Pandoc match this requirement.
3. Lessons should be easy to write and read. We shouldn't require
people to put div's and other bits of HTML in their Markdown.
Pandoc allows third party filters.
4. It should be easy to add machine-comprehensible structure
to lessons.
This means using HTML tags properly, i.e. <blockquote> only for quotes
and not to very box that we want just because we don't want to have
<div>, <section>, <aside>, ... in the Markdown file.
We want to be able to build tools to extract
lesson titles, count challenge exercises, etc., all of
which requires machine-comprehensible source.
Pandoc can export its AST as JSON which means that we can process
the lessons with any language that we want (as long as the language has
a JSON parser).
This is in tension with the point above:
everything we do to make lessons more readable to computers
means extra work or less readbility for people.
I think that we ours currently workflow we accomplish a good balance.
5. We should use only off-the-shelf tools. We don't want
to have to build, document, and maintain custom plugins
for formatting tools. We do want to use GitHub's gh-pages magic.
Pandoc isn't off-the-shelf tool for what we want
and it isn't supported by GitHub Pages.
6. The workflow for creating and publishing lessons
should be authentic, i.e., the way people write and
publish lessons should be a way they might use to
write and publish research papers.
I want to have real data for this but I don't have.
What I know is that
(1) RStudio users have Pandoc off-the-shelf,
and are using it,
(2) IPython/Jupyter Notebook users are using Jinja2
that is something that we will not considere using,
and (3) despite many people hate DOCX and ODT
many publishers still require it,
Pandoc can convert Markdown to DOCX/ODT
but Kramdown can't.
Trying to be rational here,
Pandoc only loses in the GitHub Pages magic
so we should stay it it and replace GitHub Pages
for the lessons with another solution.
If people really want to back to Jekyll
just because of GitHub I'm OK with it.
Cheers,
Raniere
signature.asc
Description: Digital signature
_______________________________________________ Discuss mailing list [email protected] http://lists.software-carpentry.org/mailman/listinfo/discuss_lists.software-carpentry.org
