A Nim source program has the doc comment:
##Look at `doAnAction,string`_ or else punt.
in an attempt to link to the procedure:
proc doAnAction(somearg:string) = etc.etc.
However the html page changes the link's href to:
"#doanaction-string"
instead of the href:
"#doAnAction,string"
used by the html page's toc and by the anchor for the section giving doAnAction's declaration.
How does one create the correct link in the doc comment?
I think it's
`doAnAction,string`:idx:
Since the problem might have been caused by material elsewhere, I have made a small example that shows the same problem:
type
Person* = ref object
## Please look at `doSomeAct,string`_ and try it.
##
## Spacing down
##
## Spacing down
##
## Spacing down
##
## Spacing down
##
## Spacing down
##
## Spacing down
##
## Spacing down
name:string
age:int
proc doSomeAct*(arg:string):Person =
result.name = arg
result.age = 101
proc doAnother*(arg:Person) =
echo "the age=",arg.age
echo "named:",doSomeAct("fooey").name
I tried :idx: instead of the underscore - but that did not even yield a link.
The "Spacing down" lines are to demonstrate that clicking the "Please look at" link does NOT jump down to that section.
Well, I did find a work-around.
Instead of the link `doSomeAct,string`_
Use the link 'doSomeAct <#doSomeAct,string>`_
And since I cannot find documentation of that, it may not be stable.
But that is really UGLY.
I tried to demo some of the interpreted text role effects found in using nim's rst2html
nim rst2html sample.rst
Here is the sample.rst
.. contents::
Sample Interpreted Text Roles
=============================
Ordinary reference `Subheading A`_
gives ``<a class="reference external" href="#subheading-a">``
Note that according to the TOC, the href should be ``"#a-major-heading-subheading-a">``
Use id role `Subheading A`:id:
gives ``<span class="id">Subheading A</span>``
Use id argument `Subheading A`:id-abc:
gives ``<cite>Subheading A</cite>:id-abc:``
Use idx role `Subheading A`:idx:
gives ``<span id="subheading-a_1">Subheading A</span>``
Use idw role `Subheading A`:idw:
gives ``<span class="idw">Subheading A</span>``
A Major Heading
===============
Highly important stuffA
Subheading A
------------
Detailed stuff
Are the docutils directives and interpreted text roles as actually implemented in nim documented anywhere? The above shows behavior I did not find in [http://docutils.sourceforge.net/docs/ref/rst/roles.html]
If I could just get the correct Subheading A href to show, I would be very happy.