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

[Masood Azizi]

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/?


Thank you in advance,

Masood


PS. I am not a subscribed user.

[David Goodger]

Post by Masood Azizi
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,
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:: 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

Post by Masood Azizi
Thank you in advance,
Masood
PS. I am not a subscribed user.

------------------------------------------------------------------------------
One dashboard for servers and applications across Physical-Virtual-Cloud
Widest out-of-the-box monitoring support with 50+ applications
Performance metrics, stats and reports that give you Actionable Insights
Deep dive visibility with transaction tracing using APM Insight.
http://ad.doubleclick.net/ddm/clk/290420510;117567292;y
_______________________________________________
Docutils-users mailing list
Docutils-***@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/docutils-users

Please use "Reply All" to reply to the list.