Adding the highlight directive to the rST reader

Adding the highlight directive to the rST reader

[Lucas Escot]

[-- Attachment #1.1: Type: text/plain, Size: 1949 bytes --]

Hello everyone,

I just implemented the highlight directive 
<https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-highlight> 
to the pandoc rST reader.
This allows one to specify the default language to use when highlighting 
literal blocks.
It is especially useful when writing rST in a literate agda or literate 
haskell file, where it is undesirable to have to specify the language at 
every code block.

.. highlight:: haskell

From now on code will be highlighted as haskell::

  data Tree = Leaf | Node Tree Tree

An other exemple too show how terse using literal blocks becomes::

  main :: IO ()
  main = putStrLn "Hello World!"

We can change the language at any point in the document.

.. highlight:: python

So this block contains python code::

  def main():
    print("OK")

An we can still disable having a default language:

.. highlight::

This directive comes from the Sphinx extended rST (which argueably is one 
of the most popular use case of rST out here, see readthedocs.io),
this is why I am wondering *what is your stance on adding directives to the 
pandoc reader?* (which are not specified in the docutils reference)

My opinion is that such an addition is quite reasonable, and most people 
use rST with sphinx and are therefore accustomed with said directive 
already.

You can see my implementation here: https://github.com/flupe/pandoc

If you all agree it can be merged, what is the process? Should I create an 
issue mentionning the problem or just make a PR?

Best,
Lucas

-- 
You received this message because you are subscribed to the Google Groups "pandoc-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/9e025799-6d50-40a9-b8ab-a075437cb2b9%40googlegroups.com.

[-- Attachment #1.2: Type: text/html, Size: 7317 bytes --]

Re: Adding the highlight directive to the rST reader

[Lukas Atkinson]

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

From the perspective of a Pandoc user, adding more Sphinx extensions would
be extremely useful. Most RST documents seem to target Sphinx, and many of
the extensions are also really convenient.

However, this may be a case where it could help to control the Sphinx
extensions via Pandoc's extensions mechanism, e.g. '-f rst-sphinx' to get
the docutils behavior?

On Thu, 13 Feb 2020 at 10:30, Lucas Escot <lucas.escot-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:

> Hello everyone,
>
> I just implemented the highlight directive
> <https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-highlight>
> to the pandoc rST reader.
> This allows one to specify the default language to use when highlighting
> literal blocks.
> It is especially useful when writing rST in a literate agda or literate
> haskell file, where it is undesirable to have to specify the language at
> every code block.
>
> .. highlight:: haskell
>
> From now on code will be highlighted as haskell::
>
>   data Tree = Leaf | Node Tree Tree
>
> An other exemple too show how terse using literal blocks becomes::
>
>   main :: IO ()
>   main = putStrLn "Hello World!"
>
> We can change the language at any point in the document.
>
> .. highlight:: python
>
> So this block contains python code::
>
>   def main():
>     print("OK")
>
> An we can still disable having a default language:
>
> .. highlight::
>
> This directive comes from the Sphinx extended rST (which argueably is one
> of the most popular use case of rST out here, see readthedocs.io),
> this is why I am wondering *what is your stance on adding directives to
> the pandoc reader?* (which are not specified in the docutils reference)
>
> My opinion is that such an addition is quite reasonable, and most people
> use rST with sphinx and are therefore accustomed with said directive
> already.
>
> You can see my implementation here: https://github.com/flupe/pandoc
>
> If you all agree it can be merged, what is the process? Should I create an
> issue mentionning the problem or just make a PR?
>
> Best,
> Lucas
>
> --
> You received this message because you are subscribed to the Google Groups
> "pandoc-discuss" group.
> To unsubscribe from this group and stop receiving emails from it, send an
> email to pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
> To view this discussion on the web visit
> https://groups.google.com/d/msgid/pandoc-discuss/9e025799-6d50-40a9-b8ab-a075437cb2b9%40googlegroups.com
> <https://groups.google.com/d/msgid/pandoc-discuss/9e025799-6d50-40a9-b8ab-a075437cb2b9%40googlegroups.com?utm_medium=email&utm_source=footer>
> .
>

-- 
You received this message because you are subscribed to the Google Groups "pandoc-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/CAJTYOd3_psBu-hQtA0E43hozBu1-ZcM_up1Fh9ekTHMjV1c9dg%40mail.gmail.com.

[-- Attachment #2: Type: text/html, Size: 7329 bytes --]

Re: Adding the highlight directive to the rST reader

[Lucas Escot]

[-- Attachment #1.1: Type: text/plain, Size: 4000 bytes --]


>
> However, this may be a case where it could help to control the Sphinx 
> extensions via Pandoc's extensions mechanism, e.g. '-f rst-sphinx' to get 
> the docutils behavior?
>

That's a good idea! At first I was reluctant to add extensions for things 
that are specific to a single input format, but it seems there are already 
some language-specific extensions so this should not be a problem.

I am willing to try and implement the rest of them then. Here are the ones 
that I find relevant:

- note
- warning
- seealso?
- rubric
- hlist
- literal-include
- glossary?
- tabularcolumns?

And roles:

- term

Let me know if there is more I should know about.

Le jeudi 13 février 2020 11:37:20 UTC+1, latk a écrit :
>
> From the perspective of a Pandoc user, adding more Sphinx extensions would 
> be extremely useful. Most RST documents seem to target Sphinx, and many of 
> the extensions are also really convenient.
>
> However, this may be a case where it could help to control the Sphinx 
> extensions via Pandoc's extensions mechanism, e.g. '-f rst-sphinx' to get 
> the docutils behavior?
>
> On Thu, 13 Feb 2020 at 10:30, Lucas Escot <lucas...-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org 
> <javascript:>> wrote:
>
>> Hello everyone,
>>
>> I just implemented the highlight directive 
>> <https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-highlight> 
>> to the pandoc rST reader.
>> This allows one to specify the default language to use when highlighting 
>> literal blocks.
>> It is especially useful when writing rST in a literate agda or literate 
>> haskell file, where it is undesirable to have to specify the language at 
>> every code block.
>>
>> .. highlight:: haskell
>>
>> From now on code will be highlighted as haskell::
>>
>>   data Tree = Leaf | Node Tree Tree
>>
>> An other exemple too show how terse using literal blocks becomes::
>>
>>   main :: IO ()
>>   main = putStrLn "Hello World!"
>>
>> We can change the language at any point in the document.
>>
>> .. highlight:: python
>>
>> So this block contains python code::
>>
>>   def main():
>>     print("OK")
>>
>> An we can still disable having a default language:
>>
>> .. highlight::
>>
>> This directive comes from the Sphinx extended rST (which argueably is one 
>> of the most popular use case of rST out here, see readthedocs.io),
>> this is why I am wondering *what is your stance on adding directives to 
>> the pandoc reader?* (which are not specified in the docutils reference)
>>
>> My opinion is that such an addition is quite reasonable, and most people 
>> use rST with sphinx and are therefore accustomed with said directive 
>> already.
>>
>> You can see my implementation here: https://github.com/flupe/pandoc
>>
>> If you all agree it can be merged, what is the process? Should I create 
>> an issue mentionning the problem or just make a PR?
>>
>> Best,
>> Lucas
>>
>> -- 
>> You received this message because you are subscribed to the Google Groups 
>> "pandoc-discuss" group.
>> To unsubscribe from this group and stop receiving emails from it, send an 
>> email to pandoc-...-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org <javascript:>.
>> To view this discussion on the web visit 
>> https://groups.google.com/d/msgid/pandoc-discuss/9e025799-6d50-40a9-b8ab-a075437cb2b9%40googlegroups.com 
>> <https://groups.google.com/d/msgid/pandoc-discuss/9e025799-6d50-40a9-b8ab-a075437cb2b9%40googlegroups.com?utm_medium=email&utm_source=footer>
>> .
>>
>

-- 
You received this message because you are subscribed to the Google Groups "pandoc-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/ef12ef00-1ff4-4b45-81fc-c8bfb2262efe%40googlegroups.com.

[-- Attachment #1.2: Type: text/html, Size: 10421 bytes --]

Re: Adding the highlight directive to the rST reader

[John MacFarlane]

Yeah, even though it's a sphinx extension, I think I'd be
comfortable merging that. Does anyone disagree?  The procedure
would be to submit a PR.

Lucas Escot <lucas.escot-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> writes:

> Hello everyone,
>
> I just implemented the highlight directive 
> <https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-highlight> 
> to the pandoc rST reader.
> This allows one to specify the default language to use when highlighting 
> literal blocks.
> It is especially useful when writing rST in a literate agda or literate 
> haskell file, where it is undesirable to have to specify the language at 
> every code block.
>
> .. highlight:: haskell
>
> From now on code will be highlighted as haskell::
>
>   data Tree = Leaf | Node Tree Tree
>
> An other exemple too show how terse using literal blocks becomes::
>
>   main :: IO ()
>   main = putStrLn "Hello World!"
>
> We can change the language at any point in the document.
>
> .. highlight:: python
>
> So this block contains python code::
>
>   def main():
>     print("OK")
>
> An we can still disable having a default language:
>
> .. highlight::
>
> This directive comes from the Sphinx extended rST (which argueably is one 
> of the most popular use case of rST out here, see readthedocs.io),
> this is why I am wondering *what is your stance on adding directives to the 
> pandoc reader?* (which are not specified in the docutils reference)
>
> My opinion is that such an addition is quite reasonable, and most people 
> use rST with sphinx and are therefore accustomed with said directive 
> already.
>
> You can see my implementation here: https://github.com/flupe/pandoc
>
> If you all agree it can be merged, what is the process? Should I create an 
> issue mentionning the problem or just make a PR?
>
> Best,
> Lucas
>
> -- 
> You received this message because you are subscribed to the Google Groups "pandoc-discuss" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
> To view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/9e025799-6d50-40a9-b8ab-a075437cb2b9%40googlegroups.com.

Re: Adding the highlight directive to the rST reader

[Lucas Escot]

[-- Attachment #1.1: Type: text/plain, Size: 3218 bytes --]

Thank you very much for such a quick merge.

For the rest of Sphinx directives, should I go ahead and make an extension 
or would you feel comfortable having them under vanilla rST too?

Le jeudi 13 février 2020 17:29:36 UTC+1, John MacFarlane a écrit :
>
>
> Yeah, even though it's a sphinx extension, I think I'd be 
> comfortable merging that. Does anyone disagree?  The procedure 
> would be to submit a PR. 
>
> Lucas Escot <lucas...-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org <javascript:>> writes: 
>
> > Hello everyone, 
> > 
> > I just implemented the highlight directive 
> > <
> https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-highlight> 
>
> > to the pandoc rST reader. 
> > This allows one to specify the default language to use when highlighting 
> > literal blocks. 
> > It is especially useful when writing rST in a literate agda or literate 
> > haskell file, where it is undesirable to have to specify the language at 
> > every code block. 
> > 
> > .. highlight:: haskell 
> > 
> > From now on code will be highlighted as haskell:: 
> > 
> >   data Tree = Leaf | Node Tree Tree 
> > 
> > An other exemple too show how terse using literal blocks becomes:: 
> > 
> >   main :: IO () 
> >   main = putStrLn "Hello World!" 
> > 
> > We can change the language at any point in the document. 
> > 
> > .. highlight:: python 
> > 
> > So this block contains python code:: 
> > 
> >   def main(): 
> >     print("OK") 
> > 
> > An we can still disable having a default language: 
> > 
> > .. highlight:: 
> > 
> > This directive comes from the Sphinx extended rST (which argueably is 
> one 
> > of the most popular use case of rST out here, see readthedocs.io), 
> > this is why I am wondering *what is your stance on adding directives to 
> the 
> > pandoc reader?* (which are not specified in the docutils reference) 
> > 
> > My opinion is that such an addition is quite reasonable, and most people 
> > use rST with sphinx and are therefore accustomed with said directive 
> > already. 
> > 
> > You can see my implementation here: https://github.com/flupe/pandoc 
> > 
> > If you all agree it can be merged, what is the process? Should I create 
> an 
> > issue mentionning the problem or just make a PR? 
> > 
> > Best, 
> > Lucas 
> > 
> > -- 
> > You received this message because you are subscribed to the Google 
> Groups "pandoc-discuss" group. 
> > To unsubscribe from this group and stop receiving emails from it, send 
> an email to pandoc-...-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org <javascript:>. 
> > To view this discussion on the web visit 
> https://groups.google.com/d/msgid/pandoc-discuss/9e025799-6d50-40a9-b8ab-a075437cb2b9%40googlegroups.com. 
>
>

-- 
You received this message because you are subscribed to the Google Groups "pandoc-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/a6188c4b-d574-4fa3-b0ec-a5f1fd6e03f9%40googlegroups.com.

[-- Attachment #1.2: Type: text/html, Size: 6329 bytes --]

Re: Adding the highlight directive to the rST reader

[John MacFarlane]

I don't know what they all look like: can you link to a list?
Maybe it would be a good idea to add a sphinx extension.

Lucas Escot <lucas.escot-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> writes:

> Thank you very much for such a quick merge.
>
> For the rest of Sphinx directives, should I go ahead and make an extension 
> or would you feel comfortable having them under vanilla rST too?
>
> Le jeudi 13 février 2020 17:29:36 UTC+1, John MacFarlane a écrit :
>>
>>
>> Yeah, even though it's a sphinx extension, I think I'd be 
>> comfortable merging that. Does anyone disagree?  The procedure 
>> would be to submit a PR. 
>>
>> Lucas Escot <lucas...-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org <javascript:>> writes: 
>>
>> > Hello everyone, 
>> > 
>> > I just implemented the highlight directive 
>> > <
>> https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-highlight> 
>>
>> > to the pandoc rST reader. 
>> > This allows one to specify the default language to use when highlighting 
>> > literal blocks. 
>> > It is especially useful when writing rST in a literate agda or literate 
>> > haskell file, where it is undesirable to have to specify the language at 
>> > every code block. 
>> > 
>> > .. highlight:: haskell 
>> > 
>> > From now on code will be highlighted as haskell:: 
>> > 
>> >   data Tree = Leaf | Node Tree Tree 
>> > 
>> > An other exemple too show how terse using literal blocks becomes:: 
>> > 
>> >   main :: IO () 
>> >   main = putStrLn "Hello World!" 
>> > 
>> > We can change the language at any point in the document. 
>> > 
>> > .. highlight:: python 
>> > 
>> > So this block contains python code:: 
>> > 
>> >   def main(): 
>> >     print("OK") 
>> > 
>> > An we can still disable having a default language: 
>> > 
>> > .. highlight:: 
>> > 
>> > This directive comes from the Sphinx extended rST (which argueably is 
>> one 
>> > of the most popular use case of rST out here, see readthedocs.io), 
>> > this is why I am wondering *what is your stance on adding directives to 
>> the 
>> > pandoc reader?* (which are not specified in the docutils reference) 
>> > 
>> > My opinion is that such an addition is quite reasonable, and most people 
>> > use rST with sphinx and are therefore accustomed with said directive 
>> > already. 
>> > 
>> > You can see my implementation here: https://github.com/flupe/pandoc 
>> > 
>> > If you all agree it can be merged, what is the process? Should I create 
>> an 
>> > issue mentionning the problem or just make a PR? 
>> > 
>> > Best, 
>> > Lucas 
>> > 
>> > -- 
>> > You received this message because you are subscribed to the Google 
>> Groups "pandoc-discuss" group. 
>> > To unsubscribe from this group and stop receiving emails from it, send 
>> an email to pandoc-...-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org <javascript:>. 
>> > To view this discussion on the web visit 
>> https://groups.google.com/d/msgid/pandoc-discuss/9e025799-6d50-40a9-b8ab-a075437cb2b9%40googlegroups.com. 
>>
>>
>
> -- 
> You received this message because you are subscribed to the Google Groups "pandoc-discuss" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
> To view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/a6188c4b-d574-4fa3-b0ec-a5f1fd6e03f9%40googlegroups.com.

-- 
You received this message because you are subscribed to the Google Groups "pandoc-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/yh480kh7zskd1g.fsf%40johnmacfarlane.net.

Re: Adding the highlight directive to the rST reader

[Peter]

[-- Attachment #1.1: Type: text/plain, Size: 4445 bytes --]

I'm currently struggling with a Sphinx:MD conversion project due to 
Pandoc's lack of support for
these Sphinx-specific directives:

* :doc:
* :ref:
* :caption:

@Lucas have you made any progress with these things?

On Friday, 14 February 2020 at 17:41:17 UTC-5 John MacFarlane wrote:

>
> I don't know what they all look like: can you link to a list?
> Maybe it would be a good idea to add a sphinx extension.
>
> Lucas Escot <lucas...-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> writes:
>
> > Thank you very much for such a quick merge.
> >
> > For the rest of Sphinx directives, should I go ahead and make an 
> extension 
> > or would you feel comfortable having them under vanilla rST too?
> >
> > Le jeudi 13 février 2020 17:29:36 UTC+1, John MacFarlane a écrit :
> >>
> >>
> >> Yeah, even though it's a sphinx extension, I think I'd be 
> >> comfortable merging that. Does anyone disagree? The procedure 
> >> would be to submit a PR. 
> >>
> >> Lucas Escot <lucas...-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org <javascript:>> writes: 
> >>
> >> > Hello everyone, 
> >> > 
> >> > I just implemented the highlight directive 
> >> > <
> >> 
> https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-highlight> 
>
> >>
> >> > to the pandoc rST reader. 
> >> > This allows one to specify the default language to use when 
> highlighting 
> >> > literal blocks. 
> >> > It is especially useful when writing rST in a literate agda or 
> literate 
> >> > haskell file, where it is undesirable to have to specify the language 
> at 
> >> > every code block. 
> >> > 
> >> > .. highlight:: haskell 
> >> > 
> >> > From now on code will be highlighted as haskell:: 
> >> > 
> >> > data Tree = Leaf | Node Tree Tree 
> >> > 
> >> > An other exemple too show how terse using literal blocks becomes:: 
> >> > 
> >> > main :: IO () 
> >> > main = putStrLn "Hello World!" 
> >> > 
> >> > We can change the language at any point in the document. 
> >> > 
> >> > .. highlight:: python 
> >> > 
> >> > So this block contains python code:: 
> >> > 
> >> > def main(): 
> >> > print("OK") 
> >> > 
> >> > An we can still disable having a default language: 
> >> > 
> >> > .. highlight:: 
> >> > 
> >> > This directive comes from the Sphinx extended rST (which argueably is 
> >> one 
> >> > of the most popular use case of rST out here, see readthedocs.io), 
> >> > this is why I am wondering *what is your stance on adding directives 
> to 
> >> the 
> >> > pandoc reader?* (which are not specified in the docutils reference) 
> >> > 
> >> > My opinion is that such an addition is quite reasonable, and most 
> people 
> >> > use rST with sphinx and are therefore accustomed with said directive 
> >> > already. 
> >> > 
> >> > You can see my implementation here: https://github.com/flupe/pandoc 
> >> > 
> >> > If you all agree it can be merged, what is the process? Should I 
> create 
> >> an 
> >> > issue mentionning the problem or just make a PR? 
> >> > 
> >> > Best, 
> >> > Lucas 
> >> > 
> >> > -- 
> >> > You received this message because you are subscribed to the Google 
> >> Groups "pandoc-discuss" group. 
> >> > To unsubscribe from this group and stop receiving emails from it, 
> send 
> >> an email to pandoc-...-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org <javascript:>. 
> >> > To view this discussion on the web visit 
> >> 
> https://groups.google.com/d/msgid/pandoc-discuss/9e025799-6d50-40a9-b8ab-a075437cb2b9%40googlegroups.com. 
>
> >>
> >>
> >
> > -- 
> > You received this message because you are subscribed to the Google 
> Groups "pandoc-discuss" group.
> > To unsubscribe from this group and stop receiving emails from it, send 
> an email to pandoc-discus...-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
> > To view this discussion on the web visit 
> https://groups.google.com/d/msgid/pandoc-discuss/a6188c4b-d574-4fa3-b0ec-a5f1fd6e03f9%40googlegroups.com
> .
>

-- 
You received this message because you are subscribed to the Google Groups "pandoc-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/b8cf0188-b6e0-4c45-8dce-bd296356db27n%40googlegroups.com.

[-- Attachment #1.2: Type: text/html, Size: 7664 bytes --]