Add include, substitution and admonition support reST markup

[jgm]

Hi!

It would be nice if Pandoc would have support for full reST markup which is
more powerful than e.g. markdown, and with the present suite of 'writers'
it would allow converting input to many output formats.



Sincerely,
Gour




Google Code Info:
Issue #: 130
Author: [email protected]
Created On: 2009-02-21T09:48:14.000Z
Closed On: 

[jgm]

The features that I've particularly missed: "include" and "admonition".

I still have to use rst2html.py for my documents that use these features.

#t

Google Code Info:
Author: [email protected]
Created On: 2009-04-17T15:38:42.000Z

[jgm]

I'm particularly missing the "class" directive, especially in conjunction with code
blocks. According to the ReST docs, you use it like this:

.. class:: special

This is a special paragraph.

For code blocks, you need to do this:

.. class:: python
..

::

def some_python_function():
# etc

Google Code Info:
Author: [email protected]
Created On: 2009-11-09T11:38:14.000Z

[jgm]

An alternative for nicer handling of code blocks would be the custom 'code-block'
directive that is commonly used. It is implemented by Sphinx, a popular tool for
documenting libraries, especially Python. See http://sphinx.pocoo.org/markup/
code.html. Syntax is much simpler than the above:

.. code-block:: python

def some_python_function():
# etc

Google Code Info:
Author: [email protected]
Created On: 2009-11-09T11:59:52.000Z

[valholl]

I would love full support for reStructuredText too.

One thing I'm missing is support for substitution definitions: http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#substitution-definitions with image and replace directives.

[EronHennessey]

Agreed with the above comments, and would like to refresh this issue.

I'd dearly love to see reStructuredText's .. include:: filename.rst directives honored (or at least some output that they've been ignored). This, to me, is one of the largest benefits of using reST instead of markdown.

I'm currently getting around this by using rst2html.py to convert the files to HTML, then using pandoc to convert it from HTML to markdown (for GitHub, etc.)... it's weird to have to use HTML as the intermediary format, but it works. ;)

Substitution support would be great, too.

[ramnathv]

Let me add another vote for this 👍

[mpickering]

To summarise, missing features are

• include
• substitution
• admonition

The latter two should be easy to implement. The first requires some more machinery I am currently thinking about.

[chiffa]

I would suggest that ..include:: is a critical part of the ReStructuredText and the reason I am working with it.

[timofurrer]

What's the state on the `.. include::`` directive?

[jgm]

.. include:: is not yet implemented.

Currently this would require adding a handleIncludes function like in the LaTeX reader, and modifying pandoc.hs to run this on the input before passing it to the (pure) LaTeX reader. This is pretty ugly, though. A cleaner solution would require #2930, which would allow pure readers to be run with IO (processing includes) or without it.

[jgm]

include is now implemented in the typeclass branch, which will eventually become pandoc 2.0.

It shouldn't be too hard to implement admonition and substitution as well.

[jgm]

We've got admonitions now.

[jgm]

And we've had substitutions for a long time. I think this issue can now finally be closed!

[mcepl]

include is now implemented in the typeclass branch, which will eventually become pandoc 2.0.

There is no typeclass branch in the current repo. Where can I find .. include:: honoring code for testing?

[mb21]

I think the typeclass branch has been merged into current master already...

[mcepl]

And does the release 1.19.2.1 contain it as well or do I have to build from the git checkout?

[iandol]

You can try the nightly build: https://github.com/pandoc-extras/pandoc-nightly/releases

[Gim6626]

Got pandoc v1.19.2.4, no "include" support. Since which version it was added?

[mb21]

Just get the newest pandoc from https://github.com/jgm/pandoc/releases

[saurabhnanda]

Two question regarding the include directive:

• Is is possible to include a function that resolves relative paths, else the directlve becomes brittle when (a) you're processing multiple RST documents from a deeply nested directory tree, or (b) moving files around.
• is it possible to use the include directive to include external code snippets such that pandoc recognizes them as code snippets and parses / renders them accordingly?

[jgm]

is it possible to use the include directive to include external code snippets such that pandoc recognizes them as code snippets and parses / renders them accordingly?

Can you do this in RST? If so, try the same syntax with pandoc and see if it works. IF not, we should support it, but open a new issue.

Is is possible to include a function that resolves relative paths,

I'm not sure what you mean here; relative paths should work, but pandoc interprets them relative to the working directory (or any --resource-paths).

[saurabhnanda]

@jgm continuing the conversation in two separate threads.