Re: [Docutils-users] RST cross referencing not working in code highlighting

[David G. <go...@py...>]

On Thu, May 21, 2015 at 4:34 AM, Masood Azizi <ma...@gt...> wrote:
> Hello,
>
> I use docutils in order to produce documents via rst file.
>
> In my document, I need to add and highlight some source code. Also I use
> cross referencing to make some keywords (section names) hyperlink to the
> respective section. So, simply append an underline to the end of the word,
> e.g mysection_ which refers to:
>
> mysection
> ---------
>
> Some text...
>
> The problem occurs when I use the format of code highlighting. That is, if I
> use .. code:: C and then a block of C code, cross referencing in the source
> code does not work:
>
> .. code:: C
>
>     #include "example.h"
>     int main()
>     {
>         printf("My Section is:");
>         mysection_();
>         return 0;
>     }
>
> So, how can I have both code highlighting and cross referencing?

I believe the answer is: you cannot have both.

The "code" directive parses its content (a code block) via the
Pygments library, which doesn't understand reStructuredText. Pygments
only understands code, in one language at a time. So the trailing
underscore in "mysection_" is just seen as part of the identifier.
Which is perfectly valid; "mysection_" is a legal Python identifier,
as is "_this" and even "_".

You can get a literal block with inline markup, such as hyperlink
references, using the "parsed-literal" directive. It doesn't do code
highlighting though. And "care must be taken with the text, because
inline markup is recognized and there is no protection from parsing".
See http://docutils.sourceforge.net/docs/ref/rst/directives.html#parsed-literal-block

You have to choose one or the other. If you choose code highlighting,
a workaround is to include the hyperlink references outside of the
code block, in explanatory text (e.g. "see mysection_ ...").

-- David Goodger

> Thank you in advance,
>
> Masood
>
>
> PS. I am not a subscribed user.