commit a5888ac26d2a7e0115aa09bb1d00e9b70b49eed4
parent 6c34d346a773a8065c853fa51cdda3e0150c69d0
Author: Matthew Flatt <mflatt@racket-lang.org>
Date: Thu, 10 Jan 2008 23:42:23 +0000
doc build automatically go to main doc dir; added doc categories for start doc; fix locale-sensitive byte<->string ops to actually use the locale; other small edits
svn: r8286
original commit: 1e069dd2bcd7b1dd84213f6943f6f549681219f8
Diffstat:
4 files changed, 48 insertions(+), 18 deletions(-)
diff --git a/collects/scribble/manual.ss b/collects/scribble/manual.ss
@@ -1771,6 +1771,9 @@
(define (seclink tag #:underline? [u? #t] #:doc [doc #f] . s)
(make-link-element (if u? #f "plainlink") (decode-content s) `(part ,(doc-prefix doc tag))))
+ (define (other-manual #:underline? [u? #t] doc)
+ (secref #:doc doc #:underline? u? "top"))
+
(define (*schemelink stx-id id . s)
(let ([content (decode-content s)])
(make-delayed-element
@@ -1786,7 +1789,7 @@
(define-syntax schemelink
(syntax-rules ()
[(_ id . content) (*schemelink (quote-syntax id) 'id . content)]))
- (provide secref seclink schemelink)
+ (provide secref seclink schemelink other-manual)
(define (pidefterm . s)
(let ([c (apply defterm s)])
diff --git a/collects/scribblings/scribble/how-to.scrbl b/collects/scribblings/scribble/how-to.scrbl
@@ -19,8 +19,10 @@ To document a collection or @|PLaneT| package:
@itemize{
@item{Create a file in your collection or planet package with the
- file extension @filepath{.scrbl}. The remainder of these
- instructions assume that the file is called @filepath{manual.scrbl}.}
+ file extension @filepath{.scrbl}. Beware that the file name you
+ choose will determine the output directory's name. The
+ remainder of these instructions assume that the file is called
+ @filepath{manual.scrbl}.}
@item{Start @filepath{manual.scrbl} like this:
@verbatim[#<<EOS
@@ -67,15 +69,13 @@ EOS
collection, optionally supply @Flag{l} followed by the
collection name to limit the build process to that collection.}
- @item{The generated documentation is
- @filepath{compiled/doc/manual/index.html} within the
- collection or @|PLaneT| package directory.
-
- If you want the output to be relative to the PLT Scheme
- documentation directory (which is recommend only for those who
- produce the ``official'' PLT Scheme distribution, and even
- then only in certain cases), add the @scheme['main-doc] option
- to the @scheme[scribblings] definition in @filepath{info.ss}.}
+ @item{The generated documentation is normally
+ @filepath{doc/manual/index.html} within the collection or
+ @|PLaneT| package directory. If the collection in the PLT
+ Scheme installation's the main @filepath{collects} directory,
+ however, then the documentation is generated as
+ @filepath{manual/index.html} in the installation's main
+ @filepath{doc} directory.}
}
diff --git a/collects/scribblings/scribble/info.ss b/collects/scribblings/scribble/info.ss
@@ -1,3 +1,4 @@
(module info setup/infotab
(define name "Scribblings: Scribble")
- (define scribblings '(("scribble.scrbl" (multi-page main-doc)))))
+ (define scribblings '(("scribble.scrbl" (multi-page main-doc))))
+ (define doc-categories '(tool)))
diff --git a/collects/scribblings/scribble/manual.scrbl b/collects/scribblings/scribble/manual.scrbl
@@ -638,17 +638,43 @@ and @litchar{^} for subscripts and superscripts.}
@; ------------------------------------------------------------------------
@section[#:tag "scribble:manual:section-links"]{Links}
-@defproc[(secref [tag string?]) element?]{
+@defproc[(secref [tag string?]
+ [#:doc module-path (or/c module-path? false/c) #f]
+ [#:underline? underline? any/c #t])
+ element?]{
Inserts the hyperlinked title of the section tagged @scheme[tag], but
@scheme{aux-element} items in the title content are omitted in the
-hyperlink label.}
+hyperlink label.
+If @scheme[module-path] is provided, the @scheme[tag] refers to a tag
+with a prefix determined by @scheme[module-path]. When
+@exec{setup-plt} renders documentation, it automatically adds a tag
+prefix to the document based on the source module. Thus, for example,
+to refer to a section of the PLT Scheme reference,
+@scheme[module-path] would be @scheme['(lib
+"scribblings/reference/reference.scrbl")].
-@defproc[(seclink [tag string?] [pre-content any/c] ...) element?]{
+If @scheme[underline?] is @scheme[#f], then the hyperlink is rendered
+in HTML without an underline.}
-The @tech{decode}d @scheme[pre-content] is hyperlinked to the section
-tagged @scheme[tag].}
+
+@defproc[(seclink [tag string?]
+ [#:doc module-path (or/c module-path? false/c) #f]
+ [#:underline? underline? any/c #t]
+ [pre-content any/c] ...) element?]{
+
+Like @scheme[secref], but the link label is the @tech{decode}d
+@scheme[pre-content] insteda of the target section's name.}
+
+@defproc[(other-manual [module-path module-path?]
+ [#:underline? underline? any/c #t])
+ element?]{
+
+Like @scheme[secref] for the document's implicit @scheme["top"]
+tag. Use this function to refer to a whole manual instead of
+@scheme[secref], in case a special style in the future is used for
+manual titles.}
@defproc[(schemelink [id symbol?] [pre-content any/c] ...) element?]{
