Feature request: "Figure #:" in labels of listings

Feature request: "Figure #:" in labels of listings

[Clément Pit--Claudel]

[-- Attachment #1.1: Type: text/plain, Size: 808 bytes --]

This org file:

    #+CAPTION: Some C code
    #+NAME: fig:c
    #+BEGIN_SRC c
    int main() { return 0; }
    #+END_SRC

    See figure [[fig:c]].

produces HTML similar to this:

    …
    <label class="org-src-name">Some C code</label>
    <pre class="src src-c" id="org632b2ee">…</pre>
    </div>

    <p>
    See figure <a href="#org632b2ee">1</a>.
    </p>

The link says "Figure (1)", but the figure label doesn't include the figure number. It would be great to have an option to include it! (or even to always include it as is done for images, since it can be hidden from CSS).

Thanks!
Clément.

(PS: btw, does anyone have tips for stepping through org-mode sources? The `info` parameters are so large that they cause edebug to be very slow when stepping around).


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 819 bytes --]

Re: Feature request: "Figure #:" in labels of listings

[Nicolas Goaziou]

Hello,

Clément Pit--Claudel <clement.pit@gmail.com> writes:

> This org file:
>
>     #+CAPTION: Some C code
>     #+NAME: fig:c
>     #+BEGIN_SRC c
>     int main() { return 0; }
>     #+END_SRC
>
>     See figure [[fig:c]].
>
> produces HTML similar to this:
>
>     …
>     <label class="org-src-name">Some C code</label>
>     <pre class="src src-c" id="org632b2ee">…</pre>
>     </div>
>
>     <p>
>     See figure <a href="#org632b2ee">1</a>.
>     </p>
>
> The link says "Figure (1)", but the figure label doesn't include the
> figure number. It would be great to have an option to include it! (or
> even to always include it as is done for images, since it can be
> hidden from CSS).

I agreed we can add it unconditionally, using (org-html--translate
"Listing %d:" info).

What class do you suggest for the listing number, "<span
class=\"listing-number\">"? If so, should `org-html-style-default' be modified?

Regards,

-- 
Nicolas Goaziou

Re: Feature request: "Figure #:" in labels of listings

[Clément Pit--Claudel]

[-- Attachment #1.1: Type: text/plain, Size: 914 bytes --]

On 2016-08-15 11:43, Nicolas Goaziou wrote:
> Hello,
>
> [...]
>
> I agreed we can add it unconditionally, using (org-html--translate
> "Listing %d:" info).

Neat, thanks!

> What class do you suggest for the listing number, "<span
> class=\"listing-number\">"? 

Sounds good :) 

> If so, should `org-html-style-default' be modified?

Maybe? It currently doesn't mention the related "figure-number" class, so it doesn't really need to mention "listing-number" class IMO; for backwards compatibility, though, we could consider adding 

  .listing-number { display: none; }

to it. I don't like this option too much, since it might create confusion in the future (I'd wonder why such a default — visible figure numbers, but hidden listing numbers — was chosen). It might be better to add this snippet to the NEWS file if users want to revert to the old behaviour. 

Cheers,
Clément.


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 819 bytes --]

Re: Feature request: "Figure #:" in labels of listings

[Nicolas Goaziou]

Hello,

Clément Pit--Claudel <clement.pit@gmail.com> writes:

>> What class do you suggest for the listing number, "<span
>> class=\"listing-number\">"? 
>
> Sounds good :) 
>
>> If so, should `org-html-style-default' be modified?
>
> Maybe? It currently doesn't mention the related "figure-number" class, so it doesn't really need to mention "listing-number" class IMO; for backwards compatibility, though, we could consider adding 
>
>   .listing-number { display: none; }
>
> to it. I don't like this option too much, since it might create
> confusion in the future (I'd wonder why such a default — visible
> figure numbers, but hidden listing numbers — was chosen). It might be
> better to add this snippet to the NEWS file if users want to revert to
> the old behaviour.

Done. Thank you.


Regards,

-- 
Nicolas Goaziou

Re: Feature request: "Figure #:" in labels of listings

[Clément Pit--Claudel]

[-- Attachment #1.1: Type: text/plain, Size: 1095 bytes --]

On 2016-08-22 16:27, Nicolas Goaziou wrote:
> Done. Thank you.

Works great; thanks!

One small difficulty is that html export uses two separate counters for figures and listings, while LaTeX export calls both figures, and uses a single counter. This makes it tricky to reference figures in a way that works with both HTML and LaTeX: for HTML one needs to write "Figure [[fig:a]] shows x, Listing [[lst:b]] shows y" (which exports into "Figure 1 shows x, Listing 1 shows y", while for LaTeX one needs to write "Figure [[fig:a]] shows x, Figure [[lst:a]] shows y" (which exports into "Figure 1 shows x, Figure 2 shows y"). I don't know of an easy way to achieve this.

Potential solutions:
* Using a single counter in HTML, and calling listings "Figure"s, as in LaTeX
* Using two counters in LaTeX as well, though this will require changes to existing Org documents, which is not ideal.
* Introducing an org-mode equivalent of \autoref that would insert (and hyperlink, which would be nice) "Figure", "Listing", "Section", … as appropriate based on the link's target.

Clément.


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 819 bytes --]

Re: Feature request: "Figure #:" in labels of listings

[Nicolas Goaziou]

Hello,

Clément Pit--Claudel <clement.pit@gmail.com> writes:

> One small difficulty is that html export uses two separate counters
> for figures and listings, while LaTeX export calls both figures, and
> uses a single counter.

This is not necessarily true. For example, when "listings" package is
used, listings and floats get a different counter.

> This makes it tricky to reference figures in a way that works with
> both HTML and LaTeX: for HTML one needs to write "Figure [[fig:a]]
> shows x, Listing [[lst:b]] shows y" (which exports into "Figure
> 1 shows x, Listing 1 shows y", while for LaTeX one needs to write
> "Figure [[fig:a]] shows x, Figure [[lst:a]] shows y" (which exports
> into "Figure 1 shows x, Figure 2 shows y"). I don't know of an easy
> way to achieve this.

You can use @@html:Listing@@@@latex:Figure@@ [[lst:a]], or with a macro

  #+macro: listing @@html:Listing@@@@latex:Figure@@

and

  {{{listing}}} [[lst:a]]

> Potential solutions:
> * Using a single counter in HTML, and calling listings "Figure"s, as in LaTeX

As stated above, this is not always correct.

> * Using two counters in LaTeX as well, though this will require changes to existing Org documents, which is not ideal.

Counters in "latex" back-end are handled on the LaTeX side, unlike to
"html".

> * Introducing an org-mode equivalent of \autoref that would insert
> (and hyperlink, which would be nice) "Figure", "Listing", "Section", …
> as appropriate based on the link's target.

I'm not sure about what you mean here, and to what export back-end it
applies.

In any case, I don't think there is a single satisfying solution. It
really depends on one's needs. I guess we could introduce a variable to
switch from one counting system to the other, if needed. Patches
welcome.


Regards,

-- 
Nicolas Goaziou

Re: Feature request: "Figure #:" in labels of listings

[Clément Pit--Claudel]

[-- Attachment #1.1: Type: text/plain, Size: 1964 bytes --]



On 2016-08-24 15:51, Nicolas Goaziou wrote:
> Hello,
> 
> Clément Pit--Claudel <clement.pit@gmail.com> writes:
> 
>> One small difficulty is that html export uses two separate counters
>> for figures and listings, while LaTeX export calls both figures, and
>> uses a single counter.
> 
> This is not necessarily true. For example, when "listings" package is
> used, listings and floats get a different counter.

Ah, I see; thanks for pointing this out!

>> This makes it tricky to reference figures in a way that works with
>> both HTML and LaTeX: for HTML one needs to write "Figure [[fig:a]]
>> shows x, Listing [[lst:b]] shows y" (which exports into "Figure
>> 1 shows x, Listing 1 shows y", while for LaTeX one needs to write
>> "Figure [[fig:a]] shows x, Figure [[lst:a]] shows y" (which exports
>> into "Figure 1 shows x, Figure 2 shows y"). I don't know of an easy
>> way to achieve this.
> 
> You can use @@html:Listing@@@@latex:Figure@@ [[lst:a]], or with a macro
> 
>   #+macro: listing @@html:Listing@@@@latex:Figure@@
> 
> and
> 
>   {{{listing}}} [[lst:a]]

Thanks! That's a convenient workaround. Macros names are not case-sensitive, right? (so having to macros {{{listing}}} and {{{Listing}}} won't do)

>> Potential solutions:
>> * Using a single counter in HTML, and calling listings "Figure"s, as in LaTeX
> 
> As stated above, this is not always correct.

Thanks; I missed that part.

>> * Using two counters in LaTeX as well, though this will require changes to existing Org documents, which is not ideal.
> 
> Counters in "latex" back-end are handled on the LaTeX side, unlike to
> "html".

Got it.

> In any case, I don't think there is a single satisfying solution. It
> really depends on one's needs. I guess we could introduce a variable to
> switch from one counting system to the other, if needed. Patches
> welcome.

Thanks for the clear and comprehensive answer!

Clément.


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 819 bytes --]