emacs-orgmode@gnu.org archives
 help / color / mirror / code / Atom feed

* HTML Export of Links to Source Blocks seems broken
@ 2016-06-16 10:18 timor
  2016-06-17  7:51 ` Nicolas Goaziou
  0 siblings, 1 reply; 8+ messages in thread
From: timor @ 2016-06-16 10:18 UTC (permalink / raw)
  To: emacs-orgmode

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

^ permalink raw reply	[flat|nested] 8+ messages in thread

• * Re: HTML Export of Links to Source Blocks seems broken
    2016-06-16 10:18 HTML Export of Links to Source Blocks seems broken timor
  @ 2016-06-17  7:51 ` Nicolas Goaziou
    2016-06-17 10:46   ` timor
    0 siblings, 1 reply; 8+ messages in thread
  From: Nicolas Goaziou @ 2016-06-17  7:51 UTC (permalink / raw)
    To: timor; +Cc: emacs-orgmode
  
  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
  
  ^ permalink raw reply	[flat|nested] 8+ messages in thread

• • * Re: HTML Export of Links to Source Blocks seems broken
      2016-06-17  7:51 ` Nicolas Goaziou
    @ 2016-06-17 10:46   ` timor
      2016-06-17 11:56     ` Nicolas Goaziou
      0 siblings, 1 reply; 8+ messages in thread
    From: timor @ 2016-06-17 10:46 UTC (permalink / raw)
      To: emacs-orgmode, mail
    
    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
    
    ^ permalink raw reply	[flat|nested] 8+ messages in thread

  • • * Re: HTML Export of Links to Source Blocks seems broken
        2016-06-17 10:46   ` timor
      @ 2016-06-17 11:56     ` Nicolas Goaziou
        2016-06-20  8:18       ` timor
        0 siblings, 1 reply; 8+ messages in thread
      From: Nicolas Goaziou @ 2016-06-17 11:56 UTC (permalink / raw)
        To: timor; +Cc: emacs-orgmode
      
      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
      
      ^ permalink raw reply	[flat|nested] 8+ messages in thread

    • • * Re: HTML Export of Links to Source Blocks seems broken
          2016-06-17 11:56     ` Nicolas Goaziou
        @ 2016-06-20  8:18       ` timor
          2016-06-20 12:52         ` Nicolas Goaziou
          0 siblings, 1 reply; 8+ messages in thread
        From: timor @ 2016-06-20  8:18 UTC (permalink / raw)
          To: emacs-orgmode, mail
        
        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
        
        ^ permalink raw reply	[flat|nested] 8+ messages in thread

      • • * Re: HTML Export of Links to Source Blocks seems broken
            2016-06-20  8:18       ` timor
          @ 2016-06-20 12:52         ` Nicolas Goaziou
            2016-06-20 13:07           ` timor
            0 siblings, 1 reply; 8+ messages in thread
          From: Nicolas Goaziou @ 2016-06-20 12:52 UTC (permalink / raw)
            To: timor; +Cc: emacs-orgmode
          
          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
          
          ^ permalink raw reply	[flat|nested] 8+ messages in thread

        • • * Re: HTML Export of Links to Source Blocks seems broken
              2016-06-20 12:52         ` Nicolas Goaziou
            @ 2016-06-20 13:07           ` timor
              2016-06-20 20:23             ` Nicolas Goaziou
              0 siblings, 1 reply; 8+ messages in thread
            From: timor @ 2016-06-20 13:07 UTC (permalink / raw)
              To: emacs-orgmode, mail
            
            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
            
            ^ permalink raw reply	[flat|nested] 8+ messages in thread

          • • * Re: HTML Export of Links to Source Blocks seems broken
                2016-06-20 13:07           ` timor
              @ 2016-06-20 20:23             ` Nicolas Goaziou
                0 siblings, 0 replies; 8+ messages in thread
              From: Nicolas Goaziou @ 2016-06-20 20:23 UTC (permalink / raw)
                To: timor; +Cc: emacs-orgmode
              
              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,
              
              ^ permalink raw reply	[flat|nested] 8+ messages in thread

end of thread, other threads:[~2016-06-20 20:24 UTC | newest]

Thread overview: 8+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2016-06-16 10:18 HTML Export of Links to Source Blocks seems broken timor
2016-06-17  7:51 ` Nicolas Goaziou
2016-06-17 10:46   ` timor
2016-06-17 11:56     ` Nicolas Goaziou
2016-06-20  8:18       ` timor
2016-06-20 12:52         ` Nicolas Goaziou
2016-06-20 13:07           ` timor
2016-06-20 20:23             ` Nicolas Goaziou

Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).