From c2d7746d83e7fa0a261b2ae1128e739d7afde524 Mon Sep 17 00:00:00 2001 From: Francois-Rene Rideau Date: Sun, 4 Jan 2026 01:16:04 -0500 Subject: [PATCH 1/6] 1.63: scriblib/footnote add optional numbering in HTML for note --- .../scriblib/scribblings/footnote.scrbl | 29 ++++++++++++++- scribble-lib/info.rkt | 2 +- scribble-lib/scriblib/footnote.rkt | 35 ++++++++++++++++--- 3 files changed, 59 insertions(+), 7 deletions(-) diff --git a/scribble-doc/scriblib/scribblings/footnote.scrbl b/scribble-doc/scriblib/scribblings/footnote.scrbl index 9e93a99585..ecc61ce38d 100644 --- a/scribble-doc/scriblib/scribblings/footnote.scrbl +++ b/scribble-doc/scriblib/scribblings/footnote.scrbl @@ -8,10 +8,37 @@ @defmodule[scriblib/footnote] -@defproc[(note [pre-content pre-content?] ...) element?]{ +@defparam[note-number number (or/c integer? boolean?)]{ + This parameter controls the number of footnotes in the HTML renderer. + See @racket[note] for how it is interpreted. + + To enable footnote numbers in HTML, + add @racket[#:number #t] to your first call to @racket[note] + (you can also add it to subsequent calls, but that is not necessary); + or set this parameter to either 1 or @racket[#t]. + To disable footnote numbers again in HTML, + set this parameter back to @racket[#f] (the default). + +@history[#:added "1.62"] +} + +@defproc[(note [#:number number (or/c integer? boolean?) (note-number)] + [pre-content pre-content?] ...) element?]{ Creates a margin note for HTML and a footnote for Latex/PDF output. +If rendering HTML, then the number parameter is used, which default to @racket[(note-number)]. +If it is @racket[#f] then no number is used (default / legacy behavior). +If it is @racket[#t] and @racket[(note-number)] is an integer, +then the latter value is used. +If it is @racket[#t] and @racket[(note-number)] is not integer, +then the value 1 will be used instead. +If it is an integer, then its value is used. +If an integer value is used, then @racket[(note-number)] is set to the next integer. + +@history[#:changed "1.63" @elem{Added @racket[#:number].}] +} + To produce a numbered note for HTML (which can useful if a CSS specialization changes how ``margin notes'' are rendered), use @racket[define-footnote] with @racket[#:margin], instead. diff --git a/scribble-lib/info.rkt b/scribble-lib/info.rkt index 59a6a6608f..74f39ae32f 100644 --- a/scribble-lib/info.rkt +++ b/scribble-lib/info.rkt @@ -21,7 +21,7 @@ (define pkg-authors '(mflatt eli)) -(define version "1.62") +(define version "1.63") (define license '((Apache-2.0 OR MIT) diff --git a/scribble-lib/scriblib/footnote.rkt b/scribble-lib/scriblib/footnote.rkt index f927295a38..6bb6fdeb44 100644 --- a/scribble-lib/scriblib/footnote.rkt +++ b/scribble-lib/scriblib/footnote.rkt @@ -2,6 +2,9 @@ (require (for-syntax racket/base) scribble/core + (only-in racket/format ~a) + (only-in scribble/base superscript) + (only-in scriblib/render-cond cond-element) scribble/decode scribble/html-properties scribble/latex-properties @@ -11,6 +14,7 @@ "private/counter.rkt") (provide note + note-number define-footnote) (define footnote-style-extras @@ -24,11 +28,32 @@ (define note-box-style (make-style "NoteBox" footnote-style-extras)) (define note-content-style (make-style "NoteContent" footnote-style-extras)) -(define (note . text) - (make-element - note-box-style - (make-element note-content-style - (decode-content text)))) +(define note-number (make-parameter #f)) + +(define (note #:number (number (note-number)) . text) + (define (no-number) + (make-element + note-box-style + (make-element note-content-style + (decode-content text)))) + (cond-element + (html + (if number + (let* ((n (if (integer? number) + number + (let ((nn (note-number))) + (if (integer? nn) nn 1)))) + (s (superscript (~a n)))) + (note-number (+ n 1)) + (make-element plain + (list s + (make-element + note-box-style + (make-element note-content-style + (list s ": " (decode-content text))))))) + (no-number))) + (else + (no-number)))) (define footnote-style (make-style "Footnote" footnote-style-extras)) From 6dfd8aef9cdf50ac43f6ed8ce3c8bf46e12fbc23 Mon Sep 17 00:00:00 2001 From: Francois-Rene Rideau Date: Sun, 4 Jan 2026 02:32:07 -0500 Subject: [PATCH 2/6] scriblib/footnote: make the HTML numbers clickable --- scribble-lib/scriblib/footnote.rkt | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/scribble-lib/scriblib/footnote.rkt b/scribble-lib/scriblib/footnote.rkt index 6bb6fdeb44..27c96c6d90 100644 --- a/scribble-lib/scriblib/footnote.rkt +++ b/scribble-lib/scriblib/footnote.rkt @@ -2,7 +2,6 @@ (require (for-syntax racket/base) scribble/core - (only-in racket/format ~a) (only-in scribble/base superscript) (only-in scriblib/render-cond cond-element) scribble/decode @@ -43,19 +42,25 @@ number (let ((nn (note-number))) (if (integer? nn) nn 1)))) - (s (superscript (~a n)))) + (f (lambda (s d) + (define a `(a ((name ,(format "~a~a" s n)) (href ,(format "#~a~a" d n))) + (sup () ,(format "~a" n)))) + (make-element (make-style #f (list (xexpr-property a ""))) '())))) (note-number (+ n 1)) (make-element plain - (list s + (list + (f "__footnote_src_" "__footnote_dst_") (make-element note-box-style (make-element note-content-style - (list s ": " (decode-content text))))))) + (list + (f "__footnote_dst_" "__footnote_src_") + ": " + (decode-content text))))))) (no-number))) (else (no-number)))) - (define footnote-style (make-style "Footnote" footnote-style-extras)) (define footnote-ref-style (make-style "FootnoteRef" footnote-style-extras)) (define footnote-content-style (make-style "FootnoteContent" footnote-style-extras)) From 52acc72913887c3adc0f445d96ec40a8d91957d9 Mon Sep 17 00:00:00 2001 From: Francois-Rene Rideau Date: Sun, 4 Jan 2026 07:56:56 -0500 Subject: [PATCH 3/6] scriblib/footnote: minor cleanup --- scribble-lib/scriblib/footnote.rkt | 46 +++++++++++++++--------------- 1 file changed, 23 insertions(+), 23 deletions(-) diff --git a/scribble-lib/scriblib/footnote.rkt b/scribble-lib/scriblib/footnote.rkt index 27c96c6d90..bb81494117 100644 --- a/scribble-lib/scriblib/footnote.rkt +++ b/scribble-lib/scriblib/footnote.rkt @@ -37,29 +37,29 @@ (decode-content text)))) (cond-element (html - (if number - (let* ((n (if (integer? number) - number - (let ((nn (note-number))) - (if (integer? nn) nn 1)))) - (f (lambda (s d) - (define a `(a ((name ,(format "~a~a" s n)) (href ,(format "#~a~a" d n))) - (sup () ,(format "~a" n)))) - (make-element (make-style #f (list (xexpr-property a ""))) '())))) - (note-number (+ n 1)) - (make-element plain - (list - (f "__footnote_src_" "__footnote_dst_") - (make-element - note-box-style - (make-element note-content-style - (list - (f "__footnote_dst_" "__footnote_src_") - ": " - (decode-content text))))))) - (no-number))) - (else - (no-number)))) + (if number + (let* ((n (if (integer? number) + number + (let ((nn (note-number))) + (if (integer? nn) nn 1)))) + (f (lambda (s d) + (define a `(a ((name ,(format "~a~a" s n)) (href ,(format "#~a~a" d n))) + (sup () ,(format "~a" n)))) + (make-element (make-style #f (list (xexpr-property a ""))) '())))) + (note-number (+ n 1)) + (make-element plain + (list + (f "__footnote_src_" "__footnote_dst_") + (make-element + note-box-style + (make-element note-content-style + (list + (f "__footnote_dst_" "__footnote_src_") + ": " + (decode-content text))))))) + (no-number))) + (else + (no-number)))) (define footnote-style (make-style "Footnote" footnote-style-extras)) (define footnote-ref-style (make-style "FootnoteRef" footnote-style-extras)) From 32b4bf75bb4979f427e13841cdc162c7bc6314ac Mon Sep 17 00:00:00 2001 From: Francois-Rene Rideau Date: Sun, 4 Jan 2026 13:37:33 -0500 Subject: [PATCH 4/6] scriblib/footnote: some rebracketting. --- scribble-lib/scriblib/footnote.rkt | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/scribble-lib/scriblib/footnote.rkt b/scribble-lib/scriblib/footnote.rkt index bb81494117..bc49e73ee0 100644 --- a/scribble-lib/scriblib/footnote.rkt +++ b/scribble-lib/scriblib/footnote.rkt @@ -29,23 +29,23 @@ (define note-number (make-parameter #f)) -(define (note #:number (number (note-number)) . text) +(define (note #:number [number (note-number)] . text) (define (no-number) (make-element note-box-style (make-element note-content-style (decode-content text)))) (cond-element - (html + [html (if number - (let* ((n (if (integer? number) + (let* ([n (if (integer? number) number - (let ((nn (note-number))) - (if (integer? nn) nn 1)))) - (f (lambda (s d) - (define a `(a ((name ,(format "~a~a" s n)) (href ,(format "#~a~a" d n))) - (sup () ,(format "~a" n)))) - (make-element (make-style #f (list (xexpr-property a ""))) '())))) + (let ([nn (note-number)]) + (if (integer? nn) nn 1)))] + [f (lambda (s d) + (define a `(a ([name ,(format "~a~a" s n)] [href ,(format "#~a~a" d n)]) + [sup () ,(format "~a" n)])) + (make-element (make-style #f (list (xexpr-property a ""))) '()))]) (note-number (+ n 1)) (make-element plain (list @@ -57,9 +57,9 @@ (f "__footnote_dst_" "__footnote_src_") ": " (decode-content text))))))) - (no-number))) - (else - (no-number)))) + (no-number))] + [else + (no-number)])) (define footnote-style (make-style "Footnote" footnote-style-extras)) (define footnote-ref-style (make-style "FootnoteRef" footnote-style-extras)) From 597ad57bf405286349fc8bf2e2f9e783bfaeb853 Mon Sep 17 00:00:00 2001 From: Francois-Rene Rideau Date: Sun, 4 Jan 2026 15:20:53 -0500 Subject: [PATCH 5/6] scriblib/footnote: advertise 'next instead of #t as #:number for note --- scribble-doc/scriblib/scribblings/footnote.scrbl | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/scribble-doc/scriblib/scribblings/footnote.scrbl b/scribble-doc/scriblib/scribblings/footnote.scrbl index ecc61ce38d..eec9c93581 100644 --- a/scribble-doc/scriblib/scribblings/footnote.scrbl +++ b/scribble-doc/scriblib/scribblings/footnote.scrbl @@ -8,14 +8,14 @@ @defmodule[scriblib/footnote] -@defparam[note-number number (or/c integer? boolean?)]{ +@defparam[note-number number (or/c integer? #f 'next)]{ This parameter controls the number of footnotes in the HTML renderer. See @racket[note] for how it is interpreted. To enable footnote numbers in HTML, - add @racket[#:number #t] to your first call to @racket[note] + add @racket[#:number 'next] to your first call to @racket[note] (you can also add it to subsequent calls, but that is not necessary); - or set this parameter to either 1 or @racket[#t]. + or set this parameter to either 1 or @racket['next]. To disable footnote numbers again in HTML, set this parameter back to @racket[#f] (the default). @@ -29,9 +29,9 @@ Creates a margin note for HTML and a footnote for Latex/PDF output. If rendering HTML, then the number parameter is used, which default to @racket[(note-number)]. If it is @racket[#f] then no number is used (default / legacy behavior). -If it is @racket[#t] and @racket[(note-number)] is an integer, +If it is @racket['next] and @racket[(note-number)] is an integer, then the latter value is used. -If it is @racket[#t] and @racket[(note-number)] is not integer, +If it is @racket['next] and @racket[(note-number)] is not integer, then the value 1 will be used instead. If it is an integer, then its value is used. If an integer value is used, then @racket[(note-number)] is set to the next integer. From 32c1d63599a995481c51c5fb704285e4702a81e1 Mon Sep 17 00:00:00 2001 From: Francois-Rene Rideau Date: Tue, 13 Jan 2026 11:49:42 +0100 Subject: [PATCH 6/6] scriblib/footnote: Slight cleanup --- scribble-lib/scriblib/footnote.rkt | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/scribble-lib/scriblib/footnote.rkt b/scribble-lib/scriblib/footnote.rkt index bc49e73ee0..5b3ddd1b13 100644 --- a/scribble-lib/scriblib/footnote.rkt +++ b/scribble-lib/scriblib/footnote.rkt @@ -29,6 +29,10 @@ (define note-number (make-parameter #f)) +;; TODO: move this utility function somewhere it can be exported from +(define (xexpr-element xexpr) + (make-element (make-style #f (list (xexpr-property xexpr ""))) '())) + (define (note #:number [number (note-number)] . text) (define (no-number) (make-element @@ -42,19 +46,19 @@ number (let ([nn (note-number)]) (if (integer? nn) nn 1)))] - [f (lambda (s d) - (define a `(a ([name ,(format "~a~a" s n)] [href ,(format "#~a~a" d n)]) - [sup () ,(format "~a" n)])) - (make-element (make-style #f (list (xexpr-property a ""))) '()))]) + [a (lambda (x y) + (xexpr-element `[a ([name ,(format "__footnote_~a_~a__" x n)] + [href ,(format "#__footnote_~a_~a__" y n)]) + [sup () ,(format "~a" n)]]))]) (note-number (+ n 1)) (make-element plain (list - (f "__footnote_src_" "__footnote_dst_") + (a "source" "target") (make-element note-box-style (make-element note-content-style (list - (f "__footnote_dst_" "__footnote_src_") + (a "target" "source") ": " (decode-content text))))))) (no-number))]