From a5888ac26d2a7e0115aa09bb1d00e9b70b49eed4 Mon Sep 17 00:00:00 2001
From: Matthew Flatt <mflatt@racket-lang.org>
Date: Thu, 10 Jan 2008 23:42:23 +0000
Subject: [PATCH] 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
---
 collects/scribble/manual.ss                |  5 ++-
 collects/scribblings/scribble/how-to.scrbl | 22 ++++++-------
 collects/scribblings/scribble/info.ss      |  3 +-
 collects/scribblings/scribble/manual.scrbl | 36 +++++++++++++++++++---
 4 files changed, 48 insertions(+), 18 deletions(-)

diff --git a/collects/scribble/manual.ss b/collects/scribble/manual.ss
index 3fba5418..c47fc9b7 100644
--- 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
index afcdbd05..cee2c9a9 100644
--- 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
index b9de7e65..f9850b27 100644
--- 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
index f3842a06..d82087d7 100644
--- 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")].
+
+If @scheme[underline?] is @scheme[#f], then the hyperlink is rendered
+in HTML without an underline.}
 
 
-@defproc[(seclink [tag string?] [pre-content any/c] ...) element?]{
+@defproc[(seclink [tag string?] 
+                  [#:doc module-path (or/c module-path? false/c) #f]
+                  [#:underline? underline? any/c #t]
+                  [pre-content any/c] ...) element?]{
 
-The @tech{decode}d @scheme[pre-content] is hyperlinked to the section
-tagged @scheme[tag].}
+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?]{