Footnote html numbers

[fare]

No description provided.

[github-actions]

Resyntax analyzed 2 files in this pull request and found no issues.

[mflatt]

How about using a symbol instead of #t? A symbol is more descriptive, and it more easily adapts to future extensions. Different symbols might be suitable to replacement for #t in the parameter versus #t as an argument to note.

Although I won't insist, it would be better for the code to follow more Rackety style with square brackets and indentation and using cond instead of if to support local definitions insteda of let. (It looks like the user of square brackets are so ingrained in Racket code that it's not even mentioned in the style guide, unless I'm overlooking it.)

That's a nice use of cond-element. I forgot that it exists.

[fare]

Sorry, I'm a bit new here.

1. I'm not sure what symbol would make sense instead of #t in this particular situation. That looks like one case where #t might be appropriate.
2. I reindented note (oops) and rebracketed the cond clauses with [], but after reading the "Textual Matters" style guide, I'm not sure what other style rules I violated. In particular, I don't see how cond could improve those ifs with binding. Maybe a match might—do you want me to use a match to compute n in note?

[github-actions]

Resyntax analyzed 2 files in this pull request and found no issues.

[mflatt]

How about 'next as the symbol? I see now that it's more convenient to pick just once symbol, since the #:number argument to note defaults to (note-number).

Style-wise, thanks for switching to [] and reindenting, and the part looks good. I would use cond instead of if in (if number ....)so that I could usedefineinstead oflet*fornandf`, but it's not so important.

[fare]

Aha, I didn't know you could use (define ...) in a (cond ...). That's a Racket extension not available in Scheme. Nice.

I changed the documentation and its contract to advertise 'next instead of #t... but remarkably, the code for note and note-number do not check their contract and accept either(!)

[github-actions]

Resyntax analyzed 2 files in this pull request and found no issues.

[mflatt]

I started to make a recommendation for checking the argument, but now I realize that I have been looking at the changes too shallowly. My apologies for belatedly going back to ask about the basic design here.

I originally expected that this change would build on the numbering that define-footnote implements, and then I overlooked that it doesn't. A big difference is that the define-footnote form avoids a side effect at documentation-creation time. That kind of side effect is fragile for a document that is implemented in multiple files/modules. So, define-footnote instead creates a counter that relies on Scribble's "traverse" phase, which reliably follows document-content order.

Does define-footnote provide the numbering functionality that you wanted in the first place? (In other words, I'm wondering whether note turned out to be a distraction.) Or would it make sense to improve define-footnote instead of changing note?

[fare]

I admit I don't understand the counter functionality in private/counter.rkt used in define-footnote—it looks vastly more complex than what I used, maybe because it tries to work on both backends (are there backends beside HTML and LaTeX?).

note is simple because it defers to LaTeX footnotes on LaTeX, and to a trivial expansion in HTML, with CSS magic.

[fare]

Reading the docs for make-traverse-element, I realize that:

1. There is a lot there that I don't understand about the architecture of scribble/core
2. There is also a text backend that is not well-served by note and for which I suppose define-footnote was invented.
3. Refactoring, etc., will be hard without breaking things because there is not enough of a clear test suite.

On the other hand, regarding side-effects from note, are there modes of execution with separate compilation for documents? Or processing of many documents in a same program run? Because that would indeed break this (and other) side effects I have in my documents.

[mflatt]

note is simple because it defers to LaTeX footnotes on LaTeX, and to a trivial expansion in HTML, with CSS magic.

Ok, I think I understand better what you're looking for and why define-footnote isn't quite right in it's current form. I think it's closer than it may appear, though. It does use Latex's footnote system for Latex output. The remaining problem is that a footnote section has to be rendered separately. I think it would be straightforward to have an option on define-footnote that renders the HTML target inline, and then your CSS magic can finish the job. I'll put together a suggestion (in the form of an implementation) later today, and we can see whether it would do what you need.

On the other hand, regarding side-effects from note, are there modes of execution with separate compilation for documents? Or processing of many documents in a same program run? Because that would indeed break this (and other) side effects I have in my documents.

I don't think separate compilation is an issue with the state in the PR. But, yes, rendering multiple documents at once (by just supplying multiple documents to scribble) could run into trouble.

When a module imports other modules (note that include-section is an import, really), the order of side effects is well defined, and we sometimes rely on it. But that order this also fragile, because it's easy for a change in the imports of one module to reorder effects as seen by another module far away, where the other module uses similar imports in a different order. So, for an individual document where I know how it's going to be rendered, I don't worry much about using state. But when designing a library, it's much better to avoid relying on module-level state.

[mflatt]

@fare Is #545 a workable direction for your context?

[fare]

#545 sounds like a good idea—but should note remain unimproved because define-footnote too could be improved?

This code works now for me, it's much better than what exists, especially when I write a lot of footnotes, some of them long, as I do right now.

[mflatt]

but should note remain unimproved because define-footnote too could be improved?

Yes. We should focus effort one way of doing things, as much as possible, in the interest of long-term maintenance.

While the current PR may work ok for your immediate purposes, more is needed in terms of argument checking and testing, and anything we add will have to be maintained going forward. If we can get something that both works for your use and is more flexible in the long run, we should go that direction.

[fare]

Well, I believe the entire note API was made as a simpler alternative because define-note was complex and opaque and hard to fix. But yes, making define-note better would be great. The functions are big enough that they are hard to fathom though. Maybe they could try to reuse the same strategy as note when possible, because otherwise it will be hard to align the notes with the main text in the margins the way the CSS does it for you right now. That's more complex logic, but should be better. To support nested footnotes even in this setting would be even better, but that's asking a lot (two modes: if the note is from the main text, align; if it's from another note, push down a FIFO(?) queue).

Regarding state management, one thing we do a lot in Common Lisp or Elisp is having "hooks" so that extensions can register initializers or wrappers for their extra state. In this case, since resetting note-number is desired around documents, the note extension would register (note-number #f) or (lambda (k) (note-number #f k)) in some hook consulted at the beginning of the document.

[mflatt]

Git history suggests that I added both note and define-footnote. I'm pretty sure I wrote define-footnote as an improvement over note to get numbering in HTML output, and at a point in time where I knew the approach to side effects (reflected in "private/counter.rkt") that plays well with Scribble. I see the difference in times between a document being constructed/exported and being rendered as somewhat like the difference in times between a module being compiled and being run, and I've run into a similar set of problems (including trying to find a notion of "before" or "after" to reset something) if state lives at the wrong layer.

Meanwhile, it seems like you could lift out your approach to note into a module alongside your document; it's not relying on much of anything as part of scriblib/footnote. And if it's good enough for your document and easier because it's tailored more precisely to your needs, then that's great and the way things are supposed to work. I have some similarly stateful implementations for some of my own documents. But I'm not comfortable maintaining an API based on module-level state for note in scriblib/footnote.

Also meanwhile, I appreciate the reminder from your implementation about cond-element, which I have used to clean up some awkward duplicated output generated by define-footnote in a revised #545.