commit c2616f298c41d99c68346019902153d6c19a1da4
parent 0e5dd24c61217735ae1c308a826dd921973b4dd4
Author: Matthew Flatt <mflatt@racket-lang.org>
Date: Sat, 27 Jul 2013 08:39:41 -0600
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
Diffstat:
4 files changed, 126 insertions(+), 48 deletions(-)
diff --git a/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/config.scrbl b/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,
- and the second argument is a section title. This macro is used
- by @racket[secref] to reference a section (other than a
- document or top-level section within a document), and 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]{ChapRef} --- like @ltx{SecRef}, but for a top-level
- section within a document. The default implementation defers to
- @ltx{SecRef}.}
-
- @item{@ltxd[2]{PartRef} --- like @ltx{SecRef}, but for a top-level
- section within a document whose part has the @racket['grouper]
- style property. The default shows ``part'' followed by the
- section number (ignoring the title).}
-
- @item{@ltxd[2]{BookRef} --- like @ltx{SecRef}, but for a document (as
+ @item{@ltxd[3]{SecRefLocal} --- the first argument is a Latex label,
+ the second argument is a section number, and the third argument
+ is a section title. This macro is used by @racket[secref] to
+ reference a section (other than a document or top-level section
+ within a document) that has a number and that is local to the
+ current document. The default expands to @ltx{SecRef}, passing
+ along just the second and third arguments (so that the label is
+ ignored).}
+
+ @item{@ltxd[2]{SecRef} --- like @ltx{SecRefLocal}, but used when the
+ referenced section is in a different document, so that no label
+ 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[3]{ChapRefLocal} and @ltxd[2]{ChapRef} --- like
+ @ltx{SecRefLocal} and @ltx{SecRef}, but for a top-level section
+ within a document. The default implementation defers to
+ @ltx{SecRefLocal} or @ltx{SecRef}.}
+
+ @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.}
-
- @item{@ltxd[2]{SecRefUC} --- like @ltx{SecRef}, but for @racket[Secref].
- The default shows ``Section'' followed by the section number.}
-
- @item{@ltxd[2]{ChapRefUC} --- like @ltx{ChapRef}, but for @racket[Secref].
- section with a document. The default implementation defers to
- @ltx{SecRefUC}.}
-
- @item{@ltxd[2]{PartRefUC} --- like @ltx{PartRef}, but for @racket[Secref].
- The default shows ``Part'' followed by the section number.}
-
- @item{@ltxd[2]{BookRefUC} --- like @ltx{BookRef}, but for @racket[Secref].
- The default shows defers to @ltx{BookRef}.}
+ @ltx{BookRef} implementation shows the title in italic.}
+
+ @item{@ltxd[3]{SecRefLocalUC} and @ltxd[2]{SecRefUC} --- like
+ @ltx{SecRefLocal} and @ltx{SecRef}, but for @racket[Secref].
+ The default @ltx{SecRefUC} shows ``Section'' followed by the
+ section number.}
+
+ @item{@ltxd[3]{ChapRefLocalUC} and @ltxd[2]{ChapRefUC} --- like
+ @ltx{ChapRefLocal} and @ltx{ChapRef}, but for
+ @racket[Secref]. The default @ltx{ChapRefUC}implementation
+ defers to @ltx{SecRefUC}.}
+
+ @item{@ltxd[3]{PartRefLocalUC} and @ltxd[2]{PartRefUC} --- like
+ @ltx{PartRefLocal} and @ltx{PartRef}, but for @racket[Secref].
+ The default @ltx{PartRefUC} shows ``Part'' followed by the
+ section number.}
+
+ @item{@ltxd[3]{BookRefLocalUC} and @ltxd[2]{BookRefUC} --- like
+ @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},
diff --git a/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/core.scrbl b/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.}
diff --git a/pkgs/scribble-pkgs/scribble-lib/scribble/latex-render.rkt b/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))]
- [number (and dest (vector-ref dest 2))])
- (printf "\\~aRef~a{"
+ (define-values (dest ext?) (resolve-get/ext? part ri (link-element-tag e)))
+ (let* ([number (and dest (vector-ref dest 2))]
+ [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
- (if dest
- (if (list? number)
- (format-number number null)
- (begin (eprintf "Internal tag error: ~s -> ~s\n"
- (link-element-tag e)
- dest)
- '("!!!")))
- (list "???"))
- part ri)
- (printf "}{")))
+ (when lbl?
+ (printf "t:~a}{" (t-encode (vector-ref dest 1))))
+ (unless (null? formatted-number)
+ (render-content
+ (if dest
+ (if (list? number)
+ formatted-number
+ (begin (eprintf "Internal tag error: ~s -> ~s\n"
+ (link-element-tag e)
+ dest)
+ '("!!!")))
+ (list "???"))
+ part ri)
+ (printf "}{"))))
(let* ([es (cond
[(element? e) (element-style e)]
[(multiarg-element? e) (multiarg-element-style e)]
diff --git a/pkgs/scribble-pkgs/scribble-lib/scribble/scribble.tex b/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
