Two new link-render-style modes: short and number-and-title

scribble-doc/scribblings/scribble/core.scrbl

@@ -1114,10 +1114,26 @@ property}:
        Instead, the word ``section'' is shown followed by a
        hyperlinked section number. The word ``section'' starts in
        uppercase if the element's style includes a @racket['uppercase]
-       property.}
+       property.
+
+       In @racket['short] mode, only the section number is shown, as
+       ``§3.2'', the whole thing (symbol and number together)
+       hyperlinked as a unit --- no word, no title.
+
+       In @racket['number-and-title] mode, both the number and the
+       title are shown together, hyperlinked as a unit: the section
+       number (if the section has one), the symbol ``§'', and the
+       section title in quotes --- e.g., ``§3.2 “Some Section”''.
+
+       For both @racket['short] and @racket['number-and-title], a
+       section with no number (e.g., an @racket['unnumbered] part)
+       falls back instead to just the title, with no ``§'' or number:
+       quoted for @racket['number-and-title], plain for
+       @racket['short].}
 
  @item{For Latex/PDF output, the generated reference's format can
-       depend on the document style in addition the @racket[_mode].
+       depend on the document style in addition the @racket[_mode],
+       for the @racket['default] and @racket['number] modes.
        For the @racket['default] mode and a default document style, a
        section number is shown by the word ``section'' followed by the
        section number, and the word ``section'' and the section number
@@ -1130,10 +1146,17 @@ property}:
        only the number is hyperlinked, not the word ``section'' or
        the ``§'' symbol.
 
-       A new document style can customize Latex/PDF output (see
-       @secref["config"]) by redefining the @ltx{SecRefLocal}, @|etc|,
-       macros (see @secref["builtin-latex"]). The @ltx{SecRef},
-       @|etc|, variants are used in @racket['number] mode.}
+       A new document style can customize this part of Latex/PDF
+       output (see @secref["config"]) by redefining the
+       @ltx{SecRefLocal}, @|etc|, macros (see
+       @secref["builtin-latex"]). The @ltx{SecRef}, @|etc|, variants
+       are used in @racket['number] mode.
+
+       The @racket['short] and @racket['number-and-title] modes
+       render the same way as they do for HTML (described above),
+       @emph{regardless} of the document style: they bypass the
+       @ltx{SecRefLocal} macro family entirely, so a document style
+       cannot customize their appearance by redefining those macros.}
 
 ]
 
@@ -1172,7 +1195,9 @@ properties for all @racket[element]s:
 ]
 
 @history[#:changed "1.26" @elem{Added @racket[link-render-style] support.}
-         #:changed "1.65" @elem{Added @racket[link-query-addition] support.}]}
+         #:changed "1.65" @elem{Added @racket[link-query-addition] support.}
+         #:changed "1.69" @elem{Added the @racket['short] and
+           @racket['number-and-title] modes.}]}
 
 
 @defstruct[(index-element element) ([tag tag?]
@@ -1640,7 +1665,7 @@ subsection numbers. See also @racket[collected-info].
 @history[#:added "1.1"]}
 
 
-@defstruct[link-render-style ([mode (or/c 'default 'number)])]{
+@defstruct[link-render-style ([mode (or/c 'default 'number 'short 'number-and-title)])]{
 
 Used as a @tech{style property} for a @racket[part] or a specific
 @racket[link-element] to control the way that a hyperlink is rendered
@@ -1655,7 +1680,16 @@ hyperlinked. The @racket['default] style is more flexible, allowing a
 more appropriate choice for the rendering context, such as using the
 target section's name for a hyperlink in HTML.
 
-@history[#:added "1.26"]}
+The @racket['short] mode shows just the number, as ``§3.2''; the
+@racket['number-and-title] mode shows the number and the title
+together, as ``§3.2 “Some Section”''. Both bypass the document style's
+own customization of @racket['default]/@racket['number] rendering; see
+@racket[link-element] for the exact rendering, including how each
+falls back when a section has no number.
+
+@history[#:added "1.26"
+         #:changed "1.69" @elem{Added the @racket['short] and
+           @racket['number-and-title] modes.}]}
 
 
 @defparam[current-link-render-style style link-render-style?]{

scribble-lib/info.rkt

@@ -21,7 +21,7 @@
 
 (define pkg-authors '(mflatt eli))
 
-(define version "1.68")
+(define version "1.69")
 
 (define license
   '((Apache-2.0 OR MIT)

scribble-lib/scribble/core.rkt

@@ -192,7 +192,7 @@
  link-render-style?
  link-render-style-mode
  (contract-out
-  [link-render-style ((or/c 'default 'number)
+  [link-render-style ((or/c 'default 'number 'short 'number-and-title)
                       . -> . link-render-style?)]
   [current-link-render-style (parameter/c link-render-style?)]))
 

scribble-lib/scribble/html-render.rkt

@@ -1461,15 +1461,30 @@
                                    external-tag-path)
                               (values #f #f)
                               (resolve-get/ext-id part ri (link-element-tag e)))]
+                         [(has-number?)
+                          ;; If the section number is empty, don't generate an
+                          ;; empty link:
+                          (cond
+                            [dest
+                             (define n (dest-number dest))
+                             (not (or (not n)
+                                      (string=? "" (apply string-append (format-number n '(""))))))]
+                            [else #f])]
                          [(number-link?)
                           (and dest
                                (not ext-id)
-                               (let ([n (dest-number dest)])
-                                 ;; If the section number is empty, don't generate an
-                                 ;; empty link:
-                                 (not (or (not n)
-                                          (string=? "" (apply string-append (format-number n '("")))))))
+                               has-number?
                                (eq? 'number (link-render-style-at-element e))
+                               (empty-content? (element-content e)))]
+                         [(short-link?)
+                          (and dest
+                               (not ext-id)
+                               (eq? 'short (link-render-style-at-element e))
+                               (empty-content? (element-content e)))]
+                         [(number-and-title-link?)
+                          (and dest
+                               (not ext-id)
+                               (eq? 'number-and-title (link-render-style-at-element e))
                                (empty-content? (element-content e)))])
              (define (extract-query)
                (let ([s (element-style e)])
@@ -1554,6 +1569,15 @@
                     ,@(if (empty-content? (element-content e))
                           (cond
                             [number-link? (format-number (dest-number dest) '(""))]
+                            [short-link?
+                             (if has-number?
+                                 `("§" ,@(format-number (dest-number dest) '("")))
+                                 (render-content (strip-aux (dest-title dest)) part ri))]
+                            [number-and-title-link?
+                             `(,@(if has-number?
+                                     `("§" ,@(format-number (dest-number dest) '(" ")))
+                                     '())
+                               "“" ,@(render-content (strip-aux (dest-title dest)) part ri) "”")]
                             [else
                              (render-content (strip-aux (dest-title dest)) part ri)])
                           (render-content (element-content e) part ri))))