scribble/manual: clicking on a section title shows linking information
Thanks to Matthew Butterick for help and advice. original commit: b8cc111e92e1c704a0f3462102c86dc24f8f5615
This commit is contained in:
Matthew Flatt
parent
d7a02588da
commit
b76831a2cf
|
|
@ -598,7 +598,11 @@ document style. By default, only the section number is shown in the
|
|||
reference, but the @racketmodname[scribble/manual] style shows the
|
||||
title after the section number. Customize the output (see
|
||||
@secref["config"]) by redefining the @ltx{BookRef}, @|etc|, macros (see
|
||||
@secref["builtin-latex"]).}
|
||||
@secref["builtin-latex"]).
|
||||
|
||||
In Racket documentation that is rendered to HTML, clicking on a
|
||||
section title normally shows the @racket[secref] call that is needed
|
||||
to link to the section.}
|
||||
|
||||
|
||||
@defproc[(Secref [tag string?]
|
||||
|
|
|
|||
|
|
@ -479,6 +479,12 @@ The recognized @tech{style properties} are as follows:
|
|||
how objects that subscribe to the @racketmodname[file/convertible]
|
||||
protocol are rendered.}
|
||||
|
||||
@item{@racket[document-source] structure --- For HTML, provides a
|
||||
module path for the part's source. Clicking on an HTML section
|
||||
title generated for the part or its sub-parts may show the
|
||||
module path plus a section-tag string, so that the user can
|
||||
create a reference to the section.}
|
||||
|
||||
]
|
||||
|
||||
The @racket[to-collect] field contains @techlink{content} that is
|
||||
|
|
@ -1557,6 +1563,21 @@ Used as a @tech{style property} to associate an @tt{id} attribute with
|
|||
an HTML tag.}
|
||||
|
||||
|
||||
@defstruct[document-source ([module-path module-path?])]{
|
||||
|
||||
Used as a @tech{style property} to associate a module path with a
|
||||
part. Clicking on a section title within the part may show
|
||||
@racket[module-path] with the part's tag string, so that authors of
|
||||
other documents can link to the section.
|
||||
|
||||
More specifically, the section title is given the HTML attributes
|
||||
@tt{x-source-module} and @tt{x-part-tag}. The
|
||||
@racketmodname[scribble/manual] style recognizes those tags to make
|
||||
clicking a title show cross-reference information.
|
||||
|
||||
@history[#:added "1.2"]}
|
||||
|
||||
|
||||
@defstruct[html-defaults ([prefix (or/c bytes? path-string?
|
||||
(cons/c 'collects (listof bytes?)))]
|
||||
[style (or/c bytes? path-string?
|
||||
|
|
|
|||
|
|
@ -22,4 +22,4 @@
|
|||
|
||||
(define pkg-authors '(mflatt eli))
|
||||
|
||||
(define version "1.1")
|
||||
(define version "1.2")
|
||||
|
|
|
|||
|
|
@ -6,6 +6,8 @@
|
|||
|
||||
(provide-structs
|
||||
[body-id ([value string?])]
|
||||
[document-source ([module-path module-path?])]
|
||||
|
||||
[hover-property ([text string?])]
|
||||
[script-property ([type string?]
|
||||
[script (or/c path-string? (listof string?))])]
|
||||
|
|
|
|||
|
|
@ -770,13 +770,19 @@
|
|||
d ri)))))))))
|
||||
ps)))))))
|
||||
|
||||
(define/public (extract-part-body-id d ri)
|
||||
(define/private (extract-inherited d ri pred extract)
|
||||
(or (ormap (lambda (v)
|
||||
(and (body-id? v)
|
||||
(body-id-value v)))
|
||||
(and (pred v)
|
||||
(extract v)))
|
||||
(style-properties (part-style d)))
|
||||
(let ([p (part-parent d ri)])
|
||||
(and p (extract-part-body-id p ri)))))
|
||||
(and p (extract-inherited p ri pred extract)))))
|
||||
|
||||
(define/public (extract-part-body-id d ri)
|
||||
(extract-inherited d ri body-id? body-id-value))
|
||||
|
||||
(define/public (extract-part-source d ri)
|
||||
(extract-inherited d ri document-source? document-source-module-path))
|
||||
|
||||
(define/public (part-nesting-depth d ri)
|
||||
0)
|
||||
|
|
@ -1079,6 +1085,16 @@
|
|||
[(1) 'h3]
|
||||
[(2) 'h4]
|
||||
[else 'h5])
|
||||
,(let ([src (extract-part-source d ri)]
|
||||
[taglet (for/or ([t (in-list (part-tags d))])
|
||||
(and (pair? t)
|
||||
(eq? 'part (car t))
|
||||
(= 2 (length t))
|
||||
(cadr t)))])
|
||||
(if (and src taglet)
|
||||
`([x-source-module ,(format "~s" src)]
|
||||
[x-part-tag ,(format "~s" taglet)])
|
||||
'()))
|
||||
,@(format-number number '((tt nbsp)))
|
||||
,@(map (lambda (t)
|
||||
`(a ([name ,(format "~a" (anchor-name
|
||||
|
|
|
|||
|
|
@ -305,4 +305,15 @@ tbody > tr:first-child > td > .together {
|
|||
left: 0px;
|
||||
top: 0px;
|
||||
z-index: 1;
|
||||
}
|
||||
}
|
||||
|
||||
/* ---------------------------------------- */
|
||||
/* For section source modules & tags */
|
||||
|
||||
.RPartExplain {
|
||||
background: #eee;
|
||||
font-size: 0.9rem;
|
||||
margin-top: 0.2rem;
|
||||
padding: 0.2rem;
|
||||
text-align: left;
|
||||
}
|
||||
|
|
|
|||
82
pkgs/scribble-pkgs/scribble-lib/scribble/manual-racket.js
Normal file
82
pkgs/scribble-pkgs/scribble-lib/scribble/manual-racket.js
Normal file
|
|
@ -0,0 +1,82 @@
|
|||
/* For the Racket manual style */
|
||||
|
||||
AddOnLoad(function() {
|
||||
/* Look for header elements that have x-source-module and x-part tag.
|
||||
For those elements, add a hidden element that explains how to
|
||||
link to the section, and set the element's onclick() to display
|
||||
the explanation. */
|
||||
var tag_names = ["h1", "h2", "h3", "h4", "h5"];
|
||||
for (var j = 0; j < tag_names.length; j++) {
|
||||
elems = document.getElementsByTagName(tag_names[j]);
|
||||
for (var i = 0; i < elems.length; i++) {
|
||||
var elem = elems.item(i);
|
||||
AddPartTitleOnClick(elem);
|
||||
}
|
||||
}
|
||||
})
|
||||
|
||||
function AddPartTitleOnClick(elem) {
|
||||
var mod_path = elem.getAttribute("x-source-module");
|
||||
var tag = elem.getAttribute("x-part-tag");
|
||||
if (mod_path && tag) {
|
||||
var info = document.createElement("div");
|
||||
info.className = "RPartExplain";
|
||||
|
||||
/* The "top" tag refers to a whole document: */
|
||||
var is_top = (tag == "\"top\"");
|
||||
info.appendChild(document.createTextNode("Link to this "
|
||||
+ (is_top ? "document" : "section")
|
||||
+ " with "));
|
||||
|
||||
/* Break `secref` into two lines if the module path and tag
|
||||
are long enough: */
|
||||
var is_long = (is_top ? false : (mod_path.length + tag.length > 60));
|
||||
|
||||
var line1 = document.createElement("div");
|
||||
var line2 = (is_long ? document.createElement("div") : line1);
|
||||
|
||||
function add(dest, str, cn) {
|
||||
var s = document.createElement("span");
|
||||
s.className = cn;
|
||||
s.style.whiteSpace = "nowrap";
|
||||
s.appendChild(document.createTextNode(str));
|
||||
dest.appendChild(s);
|
||||
}
|
||||
/* Construct a `secref` call with suitable syntax coloring: */
|
||||
add(line1, "\xA0@", "RktRdr");
|
||||
add(line1, (is_top ? "other-doc" : "secref"), "RktSym");
|
||||
add(line1, "[", "RktPn");
|
||||
if (!is_top)
|
||||
add(line1, tag, "RktVal");
|
||||
if (is_long) {
|
||||
/* indent second line: */
|
||||
add(line2, "\xA0\xA0\xA0\xA0\xA0\xA0\xA0\xA0", "RktPn");
|
||||
}
|
||||
if (!is_top)
|
||||
add(line2, " #:doc ", "RktPn");
|
||||
add(line2, "'", "RktVal");
|
||||
add(line2, mod_path, "RktVal");
|
||||
add(line2, "]", "RktPn");
|
||||
|
||||
info.appendChild(line1);
|
||||
if (is_long)
|
||||
info.appendChild(line2);
|
||||
|
||||
info.style.display = "none";
|
||||
|
||||
/* Add the new element afterthe header: */
|
||||
var n = elem.nextSibling;
|
||||
if (n)
|
||||
elem.parentNode.insertBefore(info, n);
|
||||
else
|
||||
elem.parentNode.appendChild(info);
|
||||
|
||||
/* Clicking the header shows the explanation element: */
|
||||
elem.onclick = function () {
|
||||
if (info.style.display == "none")
|
||||
info.style.display = "block";
|
||||
else
|
||||
info.style.display = "none";
|
||||
}
|
||||
}
|
||||
}
|
||||
|
|
@ -18,7 +18,9 @@
|
|||
(scribble-file "manual-fonts.css")))
|
||||
#:properties (list
|
||||
(css-style-addition
|
||||
(scribble-file "manual-racket.css")))
|
||||
(scribble-file "manual-racket.css"))
|
||||
(js-style-addition
|
||||
(scribble-file "manual-racket.js")))
|
||||
#t))
|
||||
|
||||
(define-on-demand manual-doc-style
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user