HTML Export of Links to Source Blocks seems broken

HTML Export of Links to Source Blocks seems broken

[timor]

Hello,

considering the following example:

--------------------------------------
#+NAME: test_fun
#+BEGIN_SRC js
function test_fun() {

}
#+END_SRC

Link to [[test_fun]]

#+NAME: another_test_fun
#+BEGIN_SRC js
function another_test_fun() {

}
#+END_SRC

Link to [[another_test_fun]]
-----------------------------------------

the exported html code creates to <a> tags, like this:

------------------------------------
Link to <a href="#orgsrcblock1">1</a>
------------------------------------

and this:

------------------------------------
Link to <a href="#orgsrcblock2">1</a>
------------------------------------

Is that behavior desired?

I would expect the link text to actually spell "test_fun" and
"another_test_fun" in this case, since those are the names of the
source blocks.

As a workaround, is there anywhere in the exporter that I could hook
into to change the link text myself?

(org version 8.3.4)

Regads,
timor

Re: HTML Export of Links to Source Blocks seems broken

[Nicolas Goaziou]

Hello,

timor <timor.dd@gmail.com> writes:

> considering the following example:
>
> --------------------------------------
> #+NAME: test_fun
> #+BEGIN_SRC js
> function test_fun() {
>
> } #+END_SRC
>
> Link to [[test_fun]]
>
> #+NAME: another_test_fun
> #+BEGIN_SRC js
> function another_test_fun() {
>
> }
> #+END_SRC
>
> Link to [[another_test_fun]]
> -----------------------------------------
>
> the exported html code creates to <a> tags, like this:
>
> ------------------------------------
> Link to <a href="#orgsrcblock1">1</a>
> ------------------------------------
>
> and this:
>
> ------------------------------------
> Link to <a href="#orgsrcblock2">1</a>
> ------------------------------------
>
> Is that behavior desired?

Yes, it is. Those are internals targets. Org handles them, well,
internally.

> I would expect the link text to actually spell "test_fun" and
> "another_test_fun" in this case, since those are the names of the
> source blocks.

This is a reasonable expectation only if you are a bit careful about the
value of the NAME keyword. See `org-latex-prefer-user-labels' for more
information.

> As a workaround, is there anywhere in the exporter that I could hook
> into to change the link text myself?

There is no equivalent to `org-latex-prefer-user-labels' in HTML export
back-end at the moment. Though, patches to add one are welcome since
this is a quite frequent request.


Regards,

-- 
Nicolas Goaziou

Re: HTML Export of Links to Source Blocks seems broken

[timor]

Hello Nicolas,

2016-06-17 9:51 GMT+02:00 Nicolas Goaziou <mail@nicolasgoaziou.fr>:
>> the exported html code creates to <a> tags, like this:
>>
>> ------------------------------------
>> Link to <a href="#orgsrcblock1">1</a>
>> ------------------------------------
>>
>> and this:
>>
>> ------------------------------------
>> Link to <a href="#orgsrcblock2">1</a>
>> ------------------------------------
>>
>> Is that behavior desired?
>
> Yes, it is. Those are internals targets. Org handles them, well,
> internally.
Why is the link text set to "1" in both cases?

>> I would expect the link text to actually spell "test_fun" and
>> "another_test_fun" in this case, since those are the names of the
>> source blocks.
>
> This is a reasonable expectation only if you are a bit careful about the
> value of the NAME keyword. See `org-latex-prefer-user-labels' for more
> information.

Thanks for the pointer.  I tried to see the effect of that variable,
but I noticed that for latex export, a \ref{orgsrcblock1} tag is
created, although the listing in the exported latex code does not
provide a "target" to link to at all.  This is probably unrelated to
my original problem, but keeps me from understanding how the mechanism
around `org-latex-prefer-user-labels` works. (maybe related:
http://emacs.stackexchange.com/questions/20947/how-to-reference-source-blocks-in-org-text)

>> As a workaround, is there anywhere in the exporter that I could hook
>> into to change the link text myself?
>
> There is no equivalent to `org-latex-prefer-user-labels' in HTML export
> back-end at the moment. Though, patches to add one are welcome since
> this is a quite frequent request.

I was more thinking along the lines of treating internal links to
named blocks in the same way that external links in HTML export are
treated:
For [[http://some/url]], the link text is simply set to the target,
the target being the external web page.
For [[some_named_block]] the link text should then also be the name of
the target, in that case the target being the source block.

I tried to debug what happens during html export, and traced the link
resolution to `org-html-link`, with the link type being "fuzzy".
Then, it correctly identifies the link target(via
`org-export-resolve-fuzzy-link`), but for some reason seems to do some
form of generic numbering for the link text.

I would probably add a case for (org-element-type destination) being
"src-block", and then use the :name property of the link destination
as link text. Does that route make sense?

Regards,
timor

Re: HTML Export of Links to Source Blocks seems broken

[Nicolas Goaziou]

Hello,

timor <timor.dd@gmail.com> writes:

> Why is the link text set to "1" in both cases?

This is just a nonsensical number because Org does not know what to
number. If you want to number source blocks, you need to add a caption
to them.

> Thanks for the pointer.  I tried to see the effect of that variable,
> but I noticed that for latex export, a \ref{orgsrcblock1} tag is
> created, although the listing in the exported latex code does not
> provide a "target" to link to at all.

If `org-latex-prefer-user-labels' is non-nil, no \ref{orgsrcblock1} is
created.

> I was more thinking along the lines of treating internal links to
> named blocks in the same way that external links in HTML export are
> treated:
> For [[http://some/url]], the link text is simply set to the target,
> the target being the external web page.
> For [[some_named_block]] the link text should then also be the name of
> the target, in that case the target being the source block.

I think the way to go is to create an equivalent to
`org-latex-prefer-user-labels' and to turn it off by default.

It boils down to creating a wrapper around `org-export-get-reference',
e.g. `org-html--reference' and replace it in the file.

It should also be tested when cross-referencing data in a published
project.

Regards,

-- 
Nicolas Goaziou

Re: HTML Export of Links to Source Blocks seems broken

[timor]

Ok, if I understand you correctly, implementing the mechanism akin to
the latex one, setting a new variable `org-html-prefer-user-labels` would
change the relevant exported HTML for the following piece of org:

----------------------
#+NAME: test_fun
#+BEGIN_SRC js :exports code
function test_fun() {

}
#+END_SRC

Link to [[test_fun]]

#+CAPTION: Caption of Another Test Fun
#+NAME: another_test_fun
#+BEGIN_SRC js
function another_test_fun() {

}
#+END_SRC

Link to [[another_test_fun]]
-----------------------

from

#+BEGIN_EXAMPLE html

  <pre class="src src-js" id="orgsrcblock1">
  ...
  </pre>

  <pre class="src src-js" id="orgsrcblock2">
  ...
  </pre>

  Link to <a href="#orgsrcblock1">1</a>

  Link to <a href="#orgsrcblock2">1</a>

#+END_EXAMPLE

to

#+BEGIN_EXAMPLE html

  <pre class="src src-js" id="test_fun">
  ...
  </pre>

  <pre class="src src-js" id="another_test_fun">
  ...
  </pre>

  Link to <a href="#test_fun">1</a>

  Link to <a href="#another_test_fun">1</a>

#+END_EXAMPLE

Looking at `org-html-link`, `org-export-get-reference` is only called
to get the _internal_ reference.  That works perfectly fine already, and I am
quite happy with the way org mode generates labels/ids for the exported
code.  That should, however, have no influence of the link description
(called `desc` in the code in `org-html-link`), which is the thing
that I actually want to change?

In summary, my exported output is supposed to look like that:

#+BEGIN_EXAMPLE html

  <pre class="src src-js" id="orgsrcblock1">
  ...
  </pre>

  <pre class="src src-js" id="orgsrcblock2">
  ...
  </pre>

  Link to <a href="#orgsrcblock1">test_fun</a>

  Link to <a href="#orgsrcblock2">another_test_fun</a>

#+END_EXAMPLE

Regards,
timor

2016-06-17 13:56 GMT+02:00 Nicolas Goaziou <mail@nicolasgoaziou.fr>:
> Hello,
>
> timor <timor.dd@gmail.com> writes:
>
>> Why is the link text set to "1" in both cases?
>
> This is just a nonsensical number because Org does not know what to
> number. If you want to number source blocks, you need to add a caption
> to them.
>
>> Thanks for the pointer.  I tried to see the effect of that variable,
>> but I noticed that for latex export, a \ref{orgsrcblock1} tag is
>> created, although the listing in the exported latex code does not
>> provide a "target" to link to at all.
>
> If `org-latex-prefer-user-labels' is non-nil, no \ref{orgsrcblock1} is
> created.
>
>> I was more thinking along the lines of treating internal links to
>> named blocks in the same way that external links in HTML export are
>> treated:
>> For [[http://some/url]], the link text is simply set to the target,
>> the target being the external web page.
>> For [[some_named_block]] the link text should then also be the name of
>> the target, in that case the target being the source block.
>
> I think the way to go is to create an equivalent to
> `org-latex-prefer-user-labels' and to turn it off by default.
>
> It boils down to creating a wrapper around `org-export-get-reference',
> e.g. `org-html--reference' and replace it in the file.
>
> It should also be tested when cross-referencing data in a published
> project.
>
> Regards,
>
> --
> Nicolas Goaziou

Re: HTML Export of Links to Source Blocks seems broken

[Nicolas Goaziou]

Hello,

timor <timor.dd@gmail.com> writes:

> Ok, if I understand you correctly, implementing the mechanism akin to
> the latex one, setting a new variable `org-html-prefer-user-labels` would
> change the relevant exported HTML for the following piece of org:
>
> ----------------------
> #+NAME: test_fun
> #+BEGIN_SRC js :exports code
> function test_fun() {
>
> } #+END_SRC
>
> Link to [[test_fun]]
>
> #+CAPTION: Caption of Another Test Fun
> #+NAME: another_test_fun
> #+BEGIN_SRC js
> function another_test_fun() {
>
> }
> #+END_SRC
>
> Link to [[another_test_fun]] -----------------------
>
> from
>
> #+BEGIN_EXAMPLE html
>
>   <pre class="src src-js" id="orgsrcblock1">
>   ...
>   </pre>
>
>   <pre class="src src-js" id="orgsrcblock2">
>   ...
>   </pre>
>
>   Link to <a href="#orgsrcblock1">1</a>
>
>   Link to <a href="#orgsrcblock2">1</a>
>
> #+END_EXAMPLE
>
> to
>
> #+BEGIN_EXAMPLE html
>
>   <pre class="src src-js" id="test_fun">
>   ...
>   </pre>
>
>   <pre class="src src-js" id="another_test_fun">
>   ...
>   </pre>
>
>   Link to <a href="#test_fun">1</a>
>
>   Link to <a href="#another_test_fun">1</a>
>
> #+END_EXAMPLE

Correct.

> Looking at `org-html-link`, `org-export-get-reference` is only called
> to get the _internal_ reference.  That works perfectly fine already, and I am
> quite happy with the way org mode generates labels/ids for the exported
> code.  That should, however, have no influence of the link description
> (called `desc` in the code in `org-html-link`), which is the thing
> that I actually want to change?

They have no influence over the link description (which is "1" in both
cases, as you noticed). If you want to change the description, simply
provide one:

  [[test_fun][whatever]]

Regards,

-- 
Nicolas Goaziou

Re: HTML Export of Links to Source Blocks seems broken

[timor]

Hello Nicolas,

2016-06-20 14:52 GMT+02:00 Nicolas Goaziou <mail@nicolasgoaziou.fr>:
> They have no influence over the link description (which is "1" in both
> cases, as you noticed). If you want to change the description, simply
> provide one:
>
>   [[test_fun][whatever]]

Sorry for not being able to express myself more clearly, since this is
the exact thing I was making a suggestion about in the first place.
The thing is, I have a lot of code blocks that define functions, which
are named exactly after that function.  And as I frequently want to
reference one of those in the text, I don't want to say

    [[test_fun][test_fun]] ..
[[another_long_function][another_long_function]]...

everytime, since [[test_fun]] already contains all the information
needed to generate the link, and the description.  The description is
always the same as the link target.  That is why I would want to
change the way that the default link description is generated in the
case that none is provided.

I think that would make sense, given that the way the default
description is generated at the moment does not seem to provide any
benefit.


> Regards,
>
> --
> Nicolas Goaziou

Re: HTML Export of Links to Source Blocks seems broken

[Nicolas Goaziou]

timor <timor.dd@gmail.com> writes:

> The thing is, I have a lot of code blocks that define functions, which
> are named exactly after that function.  And as I frequently want to
> reference one of those in the text, I don't want to say
>
>     [[test_fun][test_fun]] ..
> [[another_long_function][another_long_function]]...
>
> everytime, since [[test_fun]] already contains all the information
> needed to generate the link, and the description.  The description is
> always the same as the link target.  That is why I would want to
> change the way that the default link description is generated in the
> case that none is provided.

You can use a hook, which will work at the Org level, or a filter, to
work at the HTML level. See, e.g., (info "(org) Advanced configuration").

> I think that would make sense, given that the way the default
> description is generated at the moment does not seem to provide any
> benefit.

It does, but not in your example. See (info "(org) Internal links") for
details.

Regards,