scribble: fix PDF rendering of references to unnumbered sections

Instead of "section" or "part" without a folowing number,
a reference to an unnumbered section renders as the section
name in quotes and then "on page <n>" (to help clarify that
the quoted part is a section name).

More generally, enable LaTeX macros for `secref' to work with the
LaTeX-level label (to expand to a page number, for example) in
the case of document-local references.

Closes PR 13935

original commit: 68d9da17fa9e9b1957ca6426727773cc4f1bb8ca

pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/config.scrbl

@@ -260,40 +260,74 @@ style:
        @racketmodname[scribble/manual] configuration uses
        @ltx{newpage} to start each chapter on a new page.}
 
- @item{@ltxd[2]{SecRef} --- the first argument is a section number,
+ @item{@ltxd[3]{SecRefLocal} --- the first argument is a Latex label,
-       and the second argument is a section title. This macro is used
+       the second argument is a section number, and the third argument
-       by @racket[secref] to reference a section (other than a
+       is a section title. This macro is used by @racket[secref] to
-       document or top-level section within a document), and the
+       reference a section (other than a document or top-level section
-       default shows ``section'' followed by the section number
+       within a document) that has a number and that is local to the
-       (ignoring the title). The @racketmodname[scribble/manual]
+       current document. The default expands to @ltx{SecRef}, passing
-       redefinition of this macro shows ``§'', the section number, and
+       along just the second and third arguments (so that the label is
-       the title in quotes.}
+       ignored).}
 
- @item{@ltxd[2]{ChapRef} --- like @ltx{SecRef}, but for a top-level
+ @item{@ltxd[2]{SecRef} --- like @ltx{SecRefLocal}, but used when the
-       section within a document. The default implementation defers to
+       referenced section is in a different document, so that no label
-       @ltx{SecRef}.}
+       is available. The default shows ``section'' followed by the
+       section number (ignoring the title). The
+       @racketmodname[scribble/manual] redefinition of this macro
+       shows ``§'', the section number, and the title in quotes.}
 
- @item{@ltxd[2]{PartRef} --- like @ltx{SecRef}, but for a top-level
+ @item{@ltxd[3]{ChapRefLocal} and @ltxd[2]{ChapRef} --- like
-       section within a document whose part has the @racket['grouper]
+       @ltx{SecRefLocal} and @ltx{SecRef}, but for a top-level section
-       style property. The default shows ``part'' followed by the
+       within a document. The default implementation defers to
-       section number (ignoring the title).}
+       @ltx{SecRefLocal} or @ltx{SecRef}.}
 
- @item{@ltxd[2]{BookRef} --- like @ltx{SecRef}, but for a document (as
+ @item{@ltxd[3]{PartRefLocal} and @ltxd[2]{PartRef} --- like
+       @ltx{SecRefLocal} and @ltx{SecRef}, but for a top-level section
+       within a document whose part has the @racket['grouper] style
+       property. The default @ltx{PartRef} shows ``part'' followed by
+       the section number (ignoring the title).}
+
+ @item{@ltxd[3]{BookRefLocal} and @ltxd[2]{BookRef} --- like
+       @ltx{SecRefLocal} and @ltx{SecRef}, but for a document (as
        opposed to a section within the document). The default
-       implementation shows the title in italic.}
+       @ltx{BookRef} implementation shows the title in italic.}
 
- @item{@ltxd[2]{SecRefUC} --- like @ltx{SecRef}, but for @racket[Secref].
+ @item{@ltxd[3]{SecRefLocalUC} and @ltxd[2]{SecRefUC} --- like
-       The default shows ``Section'' followed by the section number.}
+       @ltx{SecRefLocal} and @ltx{SecRef}, but for @racket[Secref].
+       The default @ltx{SecRefUC} shows ``Section'' followed by the
+       section number.}
 
- @item{@ltxd[2]{ChapRefUC} --- like @ltx{ChapRef}, but for @racket[Secref].
+ @item{@ltxd[3]{ChapRefLocalUC} and @ltxd[2]{ChapRefUC} --- like
-       section with a document. The default implementation defers to
+       @ltx{ChapRefLocal} and @ltx{ChapRef}, but for
-       @ltx{SecRefUC}.}
+       @racket[Secref]. The default @ltx{ChapRefUC}implementation
+       defers to @ltx{SecRefUC}.}
 
- @item{@ltxd[2]{PartRefUC} --- like @ltx{PartRef}, but for @racket[Secref].
+ @item{@ltxd[3]{PartRefLocalUC} and @ltxd[2]{PartRefUC} --- like
-       The default shows ``Part'' followed by the section number.}
+       @ltx{PartRefLocal} and @ltx{PartRef}, but for @racket[Secref].
+       The default @ltx{PartRefUC} shows ``Part'' followed by the
+       section number.}
 
- @item{@ltxd[2]{BookRefUC} --- like @ltx{BookRef}, but for @racket[Secref].
+ @item{@ltxd[3]{BookRefLocalUC} and @ltxd[2]{BookRefUC} --- like
-       The default shows defers to @ltx{BookRef}.}
+       @ltx{BookRefLocal} and @ltx{BookRef}, but for @racket[Secref].
+       The default @ltx{BookRefUC} defers to @ltx{BookRef}.}
+
+ @item{@ltxd[2]{SecRefLocalUN}, @ltxd[1]{SecRefUCUN},
+       @ltxd[2]{SecRefLocalUCUN}, @ltxd[1]{SecRefUN},
+       @ltxd[2]{PartRefLocalUN}, @ltxd[1]{PartRefUN},
+       @ltxd[2]{PartRefLocalUCUN}, @ltxd[1]{PartRefUCUN},
+       @ltxd[2]{BookRefLocalUN}, @ltxd[1]{BookRefUN},
+       @ltxd[2]{BookRefLocalUCUN}, @ltxd[1]{BookRefUCUN},
+       @ltxd[2]{ChapRefLocalUN}, @ltxd[1]{ChapRefUN},
+       @ltxd[2]{ChapRefLocalUCUN}, and @ltxd[1]{ChapRefUCUN} --- like
+       @ltx{SecRefLocal}, etc., but in the case that a
+       section/part/chapter number is unavailable. The default
+       implementation of @ltx{BookRefUN} uses @ltx{BookRef} with an
+       empty first argument. The default @ltx{SecRefLocalUN} expands
+       to its second argument in quotes followed by ``on page'' as a
+       @ltx{pageref} using the first argument, while the default
+       @ltx{SecRefUN} expands to its only argument in quotes. The
+       default @ltx{PartRef} and @ltx{ChapRef} variants expand to the
+       corresponding @ltx{SecRef} variant.}
 
  @item{@ltxd[2]{Ssection}, @ltxd[2]{Ssubsection},
         @ltxd[2]{Ssubsubsection}, @ltxd[2]{Ssubsubsubsection},

pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/core.scrbl

@@ -1036,7 +1036,7 @@ Computed for each part by the @techlink{collect pass}.
 The length of the @racket[number] list indicates the section's nesting
 depth.  Numbers in @racket[number] correspond to the section's number,
 it's parent's number, etc. A non-empty string is used for a
-@racket['grouping] section. For an unnumbered section, @racket[#f] is
+@racket['grouper] section. For an unnumbered section, @racket[#f] is
 used in place of all numbers and @racket[""] in place of all non-empty
 strings.}
 

pkgs/scribble-pkgs/scribble-lib/scribble/latex-render.rkt

@@ -289,28 +289,43 @@
             (printf "\\label{t:~a}"
                     (t-encode (add-current-tag-prefix (tag-key (target-element-tag e) ri)))))
           (when part-label?
-            (let* ([dest (resolve-get part ri (link-element-tag e))]
+            (define-values (dest ext?) (resolve-get/ext? part ri (link-element-tag e)))
-                   [number (and dest (vector-ref dest 2))])
+            (let* ([number (and dest (vector-ref dest 2))]
-              (printf "\\~aRef~a{"
+                   [formatted-number (and dest
+                                          (list? number)
+                                          (format-number number null))]
+                   [lbl? (and dest 
+                              (not ext?)
+                              (not (show-link-page-numbers)))])
+              (printf "\\~aRef~a~a~a{"
                       (case (and dest (number-depth number))
                         [(0) "Book"]
                         [(1) (if (string? (car number)) "Part" "Chap")]
                         [else "Sec"])
+                      (if lbl?
+                          "Local"
+                          "")
                       (if (let ([s (element-style e)])
                             (and (style? s) (memq 'uppercase (style-properties s))))
                           "UC"
+                          "")
+                      (if (null? formatted-number)
+                          "UN"
                           ""))
-              (render-content
+              (when lbl?
-               (if dest
+                (printf "t:~a}{" (t-encode (vector-ref dest 1))))
-                   (if (list? number)
+              (unless (null? formatted-number)
-                       (format-number number null)
+                (render-content
-                       (begin (eprintf "Internal tag error: ~s -> ~s\n"
+                 (if dest
-                                       (link-element-tag e)
+                     (if (list? number)
-                                       dest)
+                         formatted-number
-                              '("!!!")))
+                         (begin (eprintf "Internal tag error: ~s -> ~s\n"
-                   (list "???"))
+                                         (link-element-tag e)
-               part ri)
+                                         dest)
-              (printf "}{")))
+                                '("!!!")))
+                     (list "???"))
+                 part ri)
+                (printf "}{"))))
           (let* ([es (cond
                       [(element? e) (element-style e)]
                       [(multiarg-element? e) (multiarg-element-style e)]

pkgs/scribble-pkgs/scribble-lib/scribble/scribble.tex

@@ -37,6 +37,35 @@
 \newcommand{\SecRefUC}[2]{Section~#1}
 \newcommand{\PartRefUC}[2]{Part~#1}
 
+% Variants of the above with a label for an internal reference:
+\newcommand{\BookRefLocal}[3]{\BookRef{#2}{#3}}
+\newcommand{\ChapRefLocal}[3]{\ChapRef{#2}{#3}}
+\newcommand{\SecRefLocal}[3]{\SecRef{#2}{#3}}
+\newcommand{\PartRefLocal}[3]{\PartRef{#2}{#3}}
+\newcommand{\BookRefLocalUC}[3]{\BookRefUC{#2}{#3}}
+\newcommand{\ChapRefLocalUC}[3]{\ChapRefUC{#2}{#3}}
+\newcommand{\SecRefLocalUC}[3]{\SecRefUC{#2}{#3}}
+\newcommand{\PartRefLocalUC}[3]{\PartRefUC{#2}{#3}}
+
+% Variants of the above with a section number is empty (i.e., UnNumbered):
+\newcommand{\BookRefUN}[1]{\BookRef{}{#1}}
+\newcommand{\ChapRefUN}[1]{\SecRefUN{#1}}
+\newcommand{\SecRefUN}[1]{``#1''}
+\newcommand{\PartRefUN}[1]{\SecRefUN{#1}}
+\newcommand{\BookRefUCUN}[1]{\BookRefUN{#1}}
+\newcommand{\ChapRefUCUN}[1]{\ChapRefUN{#1}}
+\newcommand{\SecRefUCUN}[1]{\SecRefUN{#1}}
+\newcommand{\PartRefUCUN}[1]{\PartRefUN{#1}}
+
+\newcommand{\BookRefLocalUN}[2]{\BookRefUN{#2}}
+\newcommand{\ChapRefLocalUN}[2]{\SecRefLocalUN{#1}{#2}}
+\newcommand{\SecRefLocalUN}[2]{\SecRefUN{#2} on page~\pageref{#1}}
+\newcommand{\PartRefLocalUN}[2]{\SecRefLocalUN{#1}{#2}}
+\newcommand{\BookRefLocalUCUN}[2]{\BookRefLocalUN{#1}{#2}}
+\newcommand{\ChapRefLocalUCUN}[2]{\ChapRefLocalUN{#1}{#2}}
+\newcommand{\SecRefLocalUCUN}[2]{\SecRefLocalUN{#1}{#2}}
+\newcommand{\PartRefLocalUCUN}[2]{\PartRefLocalUN{#1}{#2}}
+
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 % Fonts