[ocaml-infra] markdown in "pure" OCaml

[Christophe TROESTLER]

On Thu, 8 Aug 2013 14:14:08 +0200, Amir Chaudhry wrote:
>
> Christophe, is your example referring to things like the 99 problem 
> s page [1, 2], where there are problems posed and clicking a button 
>  reveals the solution.  I'm not clear why this would be relevant to 
>  the Markdown implementation as html in the markdown file should be 
>  fine.
> [1] page: http://ocaml.org/tutorials/99problems.html

The 99 problems page is what I was indeed thinking of.  Of course one 
 can always resort to HTML in case of need but I think that one shoul 
d take opportunity of the "port" of the page to Markdown to do someth 
ing better.  In particular, the text should be closer to the intended 
 semantics if possible, e.g., say

     @Question
     ...
     @Solution
     ...
     @Examples
     ...
     @end

possibly with a line "@use Questions" at the beginning of the file if 
 it is deemed desirable to announce explicitly the active extensions  
for a given page.  I think such an extension mechanism is desirable¹⁻ 
²⁻³ because it uses the principle of least surprise (syntax wise): on 
ce you read the documentation of the markdown parser, you know what c 
onstructs refer to outside code.  Otherwise, one may always preproces 
s Markdown files (adding HTML) before passing them to the parser but  
several incompatible extensions may appear (I'll certainly develop on 
e for ocaml.org).

Note that such an extension mechanism may also solve the specificatio 
n of metadata at the beginning of the file (such as "@use template ma 
in").

The possibility of adapting the output of standard elements would als 
o be desirable.  What if you want to add an anchor to each paragraph  
or add some JavaScript around each code block?

My 0.02€,
C.


¹ https://pypi.python.org/pypi/markdown-macros
² http://kirbysayshi.com/2012/09/17/putting-macros-into-markdown.html
³ http://pythonhosted.org/Markdown/extensions/api.html