Pandoc and ConTeXt: Suggestions

Pandoc and ConTeXt: Suggestions

[Idris Samawi Hamid]

[-- Attachment #1: Type: text/plain, Size: 7461 bytes --]

Hi John,

Enclosed you will find a zip containing

test-context.txt  (a markdown test file)
test-context.tex  (output produced by Pandoc)
test-context2.txt (a modified file showing more ideal ConTeXt output).

In conjuction with odt2txt (which converts to markdown) Pandoc will be  
extremely useful in converting simple OOo-supported files to ConTeXt for  
advanced typography and typesetting. In the following comments I identify  
a few places where Pandoc could do things in a more ConTeXt-ish way.

Note also that ConTeXt and LaTeX have very different philosophies:  
Although one can make ConTeXt imitate LaTeX, that's not generally the most  
useful way to approach it.

Here we run Pandoc without the -s switch, so there is no preamble. In a  
separate report I will make suggestions on how we can improve the preamble  
to make it more ConTeXt-ish.

I am also cc'ing this to the ConTeXt list in case anyone has any  
suggestions on improving my comments or other thoughts.

I. Headings

There are two issues in the way pandoc translates headings into ConTeXt:

A. The heading-orders in markdown are not quite in sync with the context  
headings. In pandoc

#    => \section
##   => \subsection

etc.

This should be changed to

#    => \title
##   => \subject
###  => \subsubject
#### => \subsubsubject

See also I.B following.

B. Don't use

\chapter, \section, \subsection, \subsubsection;

Use instead

\title,   \subject, \subsubject, \subsubsubject

To explain: Markdown does not support explicit ordered headings:

Chapter 1: A Topic
Section 1: A Subtopic
Section 2: Another Subtopic

Chapter 2: Another Topic
Section 1: A Subtopic

Rather it supports simple headings:

A Topic
A Subtopic
Another Subtopic

Another Topic
A Subtopic

In ConTeXt we use \title, \subject, etc. for unordered headings.

II. Quotes

A. Inline quotes

For eg. “quotation using U201C and U201D” maybe you could translate that  
to \quotation{...} as well, though I guess “” are not part of markdown  
syntax so...

B. Block Quotes

There are three issues:

i) When run in fragment mode (no -s switch), all of your defined control  
sequences, like \start-stopblockquote and \start-\stopltxitem, still need  
to be placed in the preamble.

Note that \start-\stoptext can be nested. So you can place the entire  
fragment, including your definitions, within in a \start-\stoptext.

A -preamble switch would be useful to turn the preamble on and off.

ii) There is a \start-stopquotation command in ConTeXt already, but it has  
the odd feature that it adds doublequotes to the quote block (I'll ask  
Hans if he can add a setup option to remove them). Your definition is ok;  
I prefer (and in my own work typically use) something like

\definestartstop
   [blockquote]
   [before={\startnarrower[2*left,2*right]\blank[big]\noindenting},
     after={\stopnarrower\blank[big]}]

iii. There is a spurious blank line before \stopblockquote. Indeed, there  
are spurious spaces before the end of many of your \start-stop  
constructions, as well as missing blank spaces after those constructions.

III. Lists

The ConTeXt philosophy of lists calls for a different approach: No need  
for new, nonstandard constructions (like \startltxitem), no need for \sym;  
\start-stopitemize is very rich in options.

Also, using \start-stopitemize with options [...] is much better because  
what we want to be able to do is easily edit and configure the results of  
the pandoc transformation. So if I want to chage bullets to dashes I  
change \startitemize[1] to \startitemize[2].

For symbols, use the information in Section 10.6, Table 10.1, page 229 of  
cont-eni.pdf (the ConTeXt manual, available from  
http://www.pragma-ade.com/)

Also note: There should be a blank line after \stopitemize; it will not  
necessarily create a spurious line in the output. In the preamble the user  
can define its properties in \setupitemize. By default the following two  
itemizations will create the same output:

============
Here is some text
\startitemize
\item Hi!
\stopitemize
Here is some text

Here is some text

\startitemize
\item Hi!
\stopitemize

Here is some text
============

It is better to leave the blank space before and after the itemized group.

Some specific examples (see my modifictions to pandoc output in  
test-context-r.tex):

A. An unordered list:

\startitemize
\item One

\item Two

\item Three
\stopitemize

B. An ordered list with no paragraphs and no nesting:

\startitemize[n]
\item One

\item Two

\item Three
\stopitemize

C. An ordered list with paragraphs: NOTE THE USE OF \head HERE!

\startitemize
\head One

Here is a paragraph.

\head Two

And another.

\head Three

And yet another.

\stopitemize

Here is a post paragraph sentence (with a blank space after \stopitemize).

D. An ordered list with nesting and paragraphs:

The output seems buggy; I don't get level-2 paragraphs. Maybe my markdown  
syntax is wrong?

===================================
There's more in test-context-r.tex. Note that nested ordered list are  
defined for the document in the preamble, for example:

\setupitemize[1][symbol=n] [indentnext=no]
\setupitemize[2][symbol=A][indentnext=no]
\setupitemize[3][symbol=R][indentnext=no,after={\blank[small]}]

Level 1 will use Arabic numerals, level 2 will use capital letters, level  
3 will use roman numerals.

Normally a ConTeXt user wants to be keep the structure as general as  
possible so as to be able to typographically set the full document  
consistently. So there is no need to exacly mimic the settings of lists,  
etc; it's much more important to capture the structure as abstractly as  
possible.

IV. Emphasize and Bold

If we want to be really precise and do things the ConTeXt way, then we  
should define a new control sequence like

\STRONG

and then \let\STRONG=\bf

This will complement \em

Mixing the structural tag for emphasis with the formal tag \bf, as in

{\bf {\em bold italic}}

is strange in the TeX way of thinking. Better to have either

{\bf {\it bold italic}}

or

{\STRONG {\em bold italic}}

Bold italic is simply {\bi bold italic} btw.

A THOUGHT: Maybe the markdown community may want to consider using  
multiples of `*' for emphasis and using multiples of `_' for italic and  
bold. From a TeX/typographic point of view this is a huge distinction. But  
markdown has its own purpose so maybe the distinction is not so important  
there...

V. Footnotes

Pandoc output:

====================
This sentence contains a footnote\footnote{Footnote contents

}. This sentence contains no footnote.
====================

That blank space is really awful :-)

Ideal output:

====================
This sentence contains a footnote
	\footnote{Footnote contents}.
This sentence contains no footnote.
====================

There is no spurious space after the first line; \footnote gobbles it.

I hope this is useful and clear. Let me know what you think!

Best wishes
Idris

-- 
Professor Idris Samawi Hamid, Editor-in-Chief
International Journal of Shi`i Studies
Department of Philosophy
Colorado State University
Fort Collins, CO 80523

--
Using Opera's revolutionary e-mail client: http://www.opera.com/mail/

[-- Attachment #2: test-context.zip --]
[-- Type: application/zip, Size: 3243 bytes --]

[-- Attachment #3: Type: text/plain, Size: 487 bytes --]

___________________________________________________________________________________
If your question is of interest to others as well, please add an entry to the Wiki!

maillist : ntg-context@ntg.nl / http://www.ntg.nl/mailman/listinfo/ntg-context
webpage  : http://www.pragma-ade.nl / http://tex.aanhet.net
archive  : https://foundry.supelec.fr/projects/contextrev/
wiki     : http://contextgarden.net
___________________________________________________________________________________