Counters

[shashi]

It would be nice to provide a way of creating and using counters within notebooks. (These maybe most commonly interpolated into Markdown).

The basic idea is that there is a global dictionary of counters, and they are incremented as they appear in the notebook, and not as they get evaluated. Then we can use these to number sections, exercises ;), figures, or LaTeX snippets, or footnotes.

Section 2.1 of the LaTeX doc https://www.ntg.nl/doc/lamport/latex2e.pdf describes how to create and use counters in LaTeX. This is a good starting point!

[shashi]

There could be a PlutoCounters.jl package which provide the usual counters (sections, figures, footnotes), which is built on some counter functionality.

[dralletje]

It's really hard (impossible?) for Pluto to know the values of the counters with topologic execution. Basically the only thing that can act on the cell order is the client side. What you can do, is use CSS counter-reset and counter-increment like I do here

https://mybinder.org/v2/gh/fonsp/pluto-on-binder/master?urlpath=pluto/open?url=https%3A%2F%2Fgist.githubusercontent.com%2Fdralletje%2F7f10d3124e4019dd5d6839f8237b54c9%2Fraw%2Fee8f08f7a9a3a7511822a121d691a6c47fc2647b%2FCountersInPluto.jl

Is this useful? I could make a julia wrapper around it so you don't need to work with css itself.

This can also be combined with things that aren't headers, just let me know what you think is useful :)

[mossr]

@dralletje that is super useful, especially when making lecture-style notebooks to quickly reference sections. Thank you for putting that together! Is this something that could be packaged with PlutoUI?

Man, I love Pluto...(also the name is subtlety clever af)

[dralletje]

@mossr you're welcome :)

My problem is that I wouldn't use this myself - I only write notebooks to make small utils for myself and experiment with Julia. If you have some example notebooks where this would be useful, that would help me a bunch with adding something plutoUI.

Im also thinking about cases where you want counters that aren't the headers.. Any idea? I love to implement stuff but here I'm clueless to what needs to be implemented 😂

[mossr]

(Sorry for the wall of text, this stuff excites me)

@dralletje I'm creating lectures for Julia Academy on using POMDPs.jl for decision making under uncertainty, and it's really nice to have section and subsection numbers in my notebooks so I can refer back to specific portions of the code/text by their number.

Building off the ideas that @shashi mentioned (figures, sections, and footnotes), I actually do have a few use-cases where counters would really help: citing references, numbering cells, and numbering equations.

Citing references: I've been using $^1$ within markdown and manually adjusting citations in a bottom "References" section within a notebook (which can get ugly with more than a handful of citations). You can also use markdown's built-in reference footnotes with [^name] which includes a link to the reference, but I prefer the numbered and non-bold versions with $^1$. Here's a simple notebook showcasing this (also note that the [^name]: is "quoted" in markdown, which ):

### A Pluto.jl notebook ###
# v0.11.14

using Markdown
using InteractiveUtils

# ╔═╡ 3cfa31c0-fad1-11ea-3e1c-b7c2cbd9ae32
md"Sentence with manual \$\\LaTeX\$ reference.$^2$ Markdown footnote references.[^pomdp]"

# ╔═╡ 56d722b0-fad1-11ea-303a-cf6edc688769
md"""
## References

1. Mykel J. Kochenderfer, "Decision Making Under Uncertainty: Theory and Applications", *MIT Press*, 2015.

[^pomdp]: Maxim Egorov, Zachary N. Sunberg, Edward Balaban, Tim A. Wheeler, Jayesh K. Gupta, and Mykel J. Kochenderfer, "POMDPs.jl: A Framework for Sequential Decision Making under Uncertainty", *Journal of Machine Learning Research*, vol. 18, no. 26, pp. 1–5, 2017.

"""

# ╔═╡ Cell order:
# ╠═3cfa31c0-fad1-11ea-3e1c-b7c2cbd9ae32
# ╠═56d722b0-fad1-11ea-303a-cf6edc688769

Cell numbering: This refers to sequential numbering of cells, either on the right-hand side or somewhere unintrusive. Note, this is not the ordering of their executing like Jupyter, but instead their ordering within the notebook so they can be referenced by their number (e.g. "refer to cell 12 for example code to blah blah blah").

Numbering equations: Something I've also been using in my lecture notebooks are equations in markdown via $$...$$. It would be nice to have a means to provide a numbered label so they could be referenced later in the text. This post talks about adding this support for JupyterLabs but it seems to still be open.

Of course, these are just what I think would be useful for academic lecture-style usages of Pluto.

[fonsp]

About Cell numbering: Referencing cells by number means that adding, removing or moving cells breaks your references. I think it would be better to reference cells by some unique ID.

The same for referencing equations, sections: the lesson from LaTeX is that you should reference elements by a unique ID, and render those references as numbers. That way you are free to modify your document after creating a reference.

[dralletje]

@mossr Nice bunch of examples there, I had a stab at counters for footnotes in https://mybinder.org/v2/gh/fonsp/pluto-on-binder/master?urlpath=pluto/open?url=https%3A%2F%2Fgist.githubusercontent.com%2Fdralletje%2F7f10d3124e4019dd5d6839f8237b54c9%2Fraw%2Fee8f08f7a9a3a7511822a121d691a6c47fc2647b%2FCountersInPluto.jl

Let me know what you think - not sure how useful it is

[mossr]

@dralletje Did you link the wrong notebook? I only see counters for headers in that one. (btw, thanks for taking a stab!)

[fonsp]

Maybe it's this one?

[shashi]

Cool notebook!

In LaTeX you can do \label{foo}

and refer to the section as Section \ref{foo} we saw that...

Would this be possible just with CSS?

[mossr]

I'd like to point out that the notebooks from above (thank you, by the way) cause subsection counters to never increment:

This is a known issue that is detailed here:

• https://stackoverflow.com/questions/33830376/numbering-h1-h2-h3-with-css-with-presence-of-article-tag
• https://stackoverflow.com/questions/31658111/how-do-i-stop-div-tags-interfering-with-counters

If I find a Pluto-specific fix, I'll come back and post it here 🤞

[mossr]

I figured out a modified way to do it using JavaScript; a little hacky as I have to save the original header text so if this gets called multiple times it doesn't produce "2.1 2.1 2.1 Section Name" (as an example). This is modified from this fiddle, without the use of JQuery.

html"""
<script>
var section = 0;
var subsection = 0;
var headers = document.querySelectorAll('h2, h3');
for (var i=0; i < headers.length; i++) {
    var header = headers[i];
    var text = header.innerText;
    var original = header.getAttribute("text-original");
    if (original === null) {
        // Save original header text
        header.setAttribute("text-original", text);
    } else {
        // Replace with original text before adding section number
        text = header.getAttribute("text-original");
    }
    var numbering = "";
    switch (header.tagName) {
        case 'H2':
            section += 1;
            numbering = section + ".";
            subsection = 0;
            break;
        case 'H3':
            subsection += 1;
            numbering = section + "." + subsection;
            break;
    }
    header.innerText = numbering + " " + text;
};
</script>
"""

One benefit of this over the pure CSS approach is that the section/subsection numbers show up in the PlutoUI TableOfContents. But one draw-back is that this does not automatically update when a new Markdown header is created.