doc scribble/xref, and start net docs

svn: r8021

original commit: bfecd9e0f5c91e9aecad4fb6ecb2ba69a89cb0f4

collects/help/search.ss

@@ -107,7 +107,7 @@
                        (make-link-element
                         "indexlink"
                         (entry-content entry)
-                        (entry-link-key entry))
+                        (entry-tag entry))
                        (make-extra-content
                         (entry-desc entry))))
               (limit-length

collects/scribble/xref.ss

@@ -20,7 +20,7 @@
 
 (define-struct entry (words    ; list of strings: main term, sub-term, etc.
                       content  ; Scribble content to the index label
-                      link-key ; for generating a Scribble link
+                      tag ; for generating a Scribble link
                       desc))   ; further info that depends on the kind of index entry
 
 ;; Private:
@@ -33,14 +33,13 @@
 
 (define-namespace-anchor here)
 
-(define (load-xref sources)
+(define (load-xref sources #:render% [render% (html:render-mixin render%)])
-  (let* ([renderer (new (html:render-mixin render%) 
+  (let* ([renderer (new render%
                         [dest-dir (find-system-path 'temp-dir)])]
          [ci (send renderer collect null null)])
     (for-each (lambda (src)
                 (parameterize ([current-namespace (namespace-anchor->empty-namespace here)])
-                  (let ([r (with-input-from-file src read)])
+                  (send renderer deserialize-info (src) ci)))
-                    (send renderer deserialize-info (cadr r) ci))))
               sources)
     (make-xrefs renderer (send renderer resolve null null ci))))
 
@@ -59,11 +58,11 @@
                                       (cadr k)
                                       (caddr v)))))))
 
-(define (xref-render xrefs doc dest-file)
+(define (xref-render xrefs doc dest-file #:render% [render% (html:render-mixin render%)])
   (let* ([dest-file (if (string? dest-file)
                         (string->path dest-file)
                         dest-file)]
-         [renderer (new (html:render-mixin render%) 
+         [renderer (new render%
                         [dest-dir (path-only dest-file)])]
          [ci (send renderer collect (list doc) (list dest-file))])
     (send renderer transfer-info ci (resolve-info-ci (xrefs-ri xrefs)))
@@ -114,7 +113,7 @@
   (let-values ([(tag form?) (xref-binding-tag xrefs src id)])
     tag))
 
-(define (xref-tag->path+anchor xrefs tag)
+(define (xref-tag->path+anchor xrefs tag #:render% [render% (html:render-mixin render%)])
-  (let ([renderer (new (html:render-mixin render%) 
+  (let ([renderer (new render%
                        [dest-dir (find-system-path 'temp-dir)])])
     (send renderer tag->path+anchor (xrefs-ri xrefs) tag)))

collects/scribblings/scribble/manual.scrbl

@@ -1,14 +1,15 @@
 #lang scribble/doc
-@require[scribble/manual]
+@(require scribble/manual
-@require["utils.ss"]
+          "utils.ss"
-@require[(for-syntax scheme/base)]
+          (for-syntax scheme/base)
+          (for-label scribble/manual-struct))
 
 @title[#:tag "manual"]{PLT Manual Forms}
 
 @defmodule[scribble/manual]{The @schememodname[scribble/manual]
-provides all of @schememodname[scribble/basic], plus additional
+library provides all of @schememodname[scribble/basic], plus
-functions that are relatively specific to writing PLT Scheme
+additional functions that are relatively specific to writing PLT
-documentation.}
+Scheme documentation.}
 
 @; ------------------------------------------------------------------------
 @section[#:tag "scribble:manual:code"]{Typesetting Code}
@@ -773,3 +774,69 @@ an inset command-line example (e.g., in typewriter font).}
 
 @defproc[(margin-note [pre-content any/c] ...) paragraph?]{Produces
 a paragraph to be typeset in the margin instead of inlined.}
+
+@; ------------------------------------------------------------------------
+@section{Index-Entry Descriptions}
+
+@defmodule[scribble/manual-struct]{The
+@schememodname[scribble/manual-struct] library provides types used to
+describe index entries created by @schememodname[scribble/manual]
+functions. These structure types are provided separate from
+@schememodname[scribble/manual] so that
+@schememodname[scribble/manual] need not be loaded when deserializing
+cross-reference information that was generated by a previously
+rendered document.}
+
+@defstruct[module-path-index-desc ()]{
+
+Indicates that the index entry corresponds to a module definition via
+@scheme[defmodule] and company.}
+
+@defstruct[exported-index-desc ([name symbol?]
+                               [from-libs (listof module-path?)])]{
+
+Indicates that the index entry corresponds to the definition of an
+exported binding. The @scheme[name] field and @scheme[from-libs] list
+correspond to the documented name of the binding and the primary
+modules that export the documented name (but this list is not
+exhaustive, because new modules can re-export the binding).}
+
+@defstruct[(procedure-index-desc exported-index-desc) ()]{
+
+Indicates that the index entry corresponds to the definition of a
+syntactic form via @scheme[defform] and company.}
+
+@defstruct[(procedure-index-desc exported-index-desc) ()]{
+
+Indicates that the index entry corresponds to the definition of a
+procedure binding via @scheme[defproc] and company.}
+
+@defstruct[(thing-index-desc exported-index-desc) ()]{
+
+Indicates that the index entry corresponds to the definition of a
+binding via @scheme[defthing] and company.}
+
+@defstruct[(struct-index-desc exported-index-desc) ()]{
+
+Indicates that the index entry corresponds to the definition of a
+structure type via @scheme[defstruct] and company.}
+
+@defstruct[(class-index-desc exported-index-desc) ()]{
+
+Indicates that the index entry corresponds to the definition of a
+class via @scheme[defclass] and company.}
+
+@defstruct[(interface-index-desc exported-index-desc) ()]{
+
+Indicates that the index entry corresponds to the definition of an
+interface via @scheme[definterface] and company.}
+
+@defstruct[(method-index-desc exported-index-desc) ([method-name symbol?]
+                                                    [class-tag tag?])]{
+
+Indicates that the index entry corresponds to the definition of an
+method via @scheme[defmethod] and company. The @scheme[_name] field
+from @scheme[exported-index-desc] names the class or interface that
+contains the method. The @scheme[method-name] field names the method.
+The @scheme[class-tag] field provides a pointer to the start of the
+documentation for the method's class or interface.}

collects/scribblings/scribble/renderer.scrbl

@@ -3,6 +3,15 @@
 @require["utils.ss"]
 @require[(for-label scheme/class)]
 
+@(define-syntax-rule (defmodule/local lib . content)
+   (begin
+     (define-syntax-rule (intro)
+       (begin
+         (require (for-label lib))
+         (defmodule lib)
+         . content))
+     (intro)))
+
 @title[#:tag "renderer"]{Renderer}
 
 A renderer is an object that provides two main methods:
@@ -13,26 +22,14 @@ tends to be format-independent, and it usually implemented completely
 by the base renderer. The latter method generates the actual output,
 which is naturally specific to a particular format.
 
+@section{Base Renderer}
+
 @defmodule[scribble/base-render]{The
 @schememodname[scribble/base-render] module provides @scheme[render%],
-which implements the core of a renderer.}
+which implements the core of a renderer. This rendering class must be
-
+refined with a mixin from @schememodname[scribble/text-render],
-@defmodule*/no-declare[(scribble/text-render)]{The
+@schememodname[scribble/html-render], or
-@schememodname[scribble/text-render] module provides
+@schememodname[scribble/latex-render].}
-@schemeidfont{renderer-mixin}, which specializes @scheme[render%] for
-generating plain text.}
-
-@defmodule*/no-declare[(scribble/html-render)]{The
-@schememodname[scribble/html-render] module provides
-@schemeidfont{renderer-mixin}, which specializes @scheme[render%] for
-generating a single HTML file. It also supplies
-@schemeidfont{multi-renderer-mixin}, which further specializes the
-renderer to produce multi-file HTML.}
-
-@defmodule*/no-declare[(scribble/latex-render)]{The
-@schememodname[scribble/latex-render] module provides
-@schemeidfont{renderer-mixin}, which specializes @scheme[render%] for
-generating Latex.}
 
 The mixin structure is meant to support document-specific extensions
 to the renderers. For example, the @exec{scribble} command-line tool
@@ -97,3 +94,38 @@ Adds the deserialized form of @scheme[v] to @scheme[ci].
 }
 
 }
+
+@; ----------------------------------------
+
+@section{Text Renderer}
+
+@defmodule/local[scribble/text-render]{
+
+@defthing[render-mixin ((subclass?/c render%) . -> . (subclass?/c render%))]{
+
+Specializes @scheme[render%] for generating plain text.}}
+
+@; ----------------------------------------
+
+@section{HTML Renderer}
+
+@defmodule/local[scribble/html-render]{
+
+@defthing[render-mixin ((subclass?/c render%) . -> . (subclass?/c render%))]{
+
+Specializes @scheme[render%] for generating a single HTML file.}
+
+@defthing[render-multi-mixin ((subclass?/c render%) . -> . (subclass?/c render%))]{
+
+Further specializes @scheme[render%] for generating a multiple HTML
+files. The input class must be first extended with @scheme[render-mixin].}}
+
+@; ----------------------------------------
+
+@section{Latex Renderer}
+
+@defmodule/local[scribble/latex-render]{
+
+@defthing[render-mixin ((subclass?/c render%) . -> . (subclass?/c render%))]{
+
+Specializes @scheme[render%] for generating Latex input.}}

collects/scribblings/scribble/scribble.scrbl

@@ -61,25 +61,31 @@ The layers are:
  @item{@schememodname[scribble/scheme]: a library of support functions for
        typesetting Scheme code. See @secref["scheme"].}
 
- @item{@schememodname[scribble/manual]: a library of support functions for writing
+ @item{@schememodname[scribble/manual]: a library of support functions
-       PLT Scheme documentation; re-exports @schememodname[scribble/basic]. See
+       for writing PLT Scheme documentation; re-exports
-       @secref["manual"].}
+       @schememodname[scribble/basic]. Also, the
+       @schememodname[scribble/manual-struct] library provides
+       types for index-entry descriptions created by functions in
+       @schememodname[scribble/manual]. See @secref["manual"].}
 
- @item{@schememodname[scribble/eval]: a library of support functions for ealuating
+ @item{@schememodname[scribble/eval]: a library of support functions
-       code at document-build time, especially for showing
+       for evaluating code at document-build time, especially for
-       examples. See @secref["eval"].}
+       showing examples. See @secref["eval"].}
 
  @item{@schememodname[scribble/bnf]: a library of support functions for writing
        grammars. See @secref["bnf"].}
 
+ @item{@schememodname[scribble/xref]: a library of support functions
+       for using cross-reference information, typically after a
+       document is rendered (e.g., to search). See @secref["xref"].}
+
 }
 
-The @exec{scribble} command-line utility works with a module that
+The @exec{scribble} command-line utility generates output with a
-exports a @scheme{struct.ss}-based document, generating output with a
 specified renderer. More specifically, the executable installs a
-renderer, loads the specified modules and extracts the @scheme[doc]
+renderer, loads the modules specified on the command line, extracts
-export of each (which must be an instance of @scheme[section] from
+the @scheme[doc] export of each module (which must be an instance of
-@schememodname[scribble/struct]), and renders each. Use @exec{scribble -h} for more
+@scheme[part]), and renders each. Use @exec{scribble -h} for more
 information.
 
 @; ------------------------------------------------------------------------
@@ -94,5 +100,6 @@ information.
 @include-section["manual.scrbl"]
 @include-section["eval.scrbl"]
 @include-section["bnf.scrbl"]
+@include-section["xref.scrbl"]
 
 @index-section[]

collects/scribblings/scribble/struct.scrbl

@@ -1,6 +1,7 @@
 #lang scribble/doc
-@require[scribble/manual]
+@(require scribble/manual
-@require["utils.ss"]
+          "utils.ss"
+          (for-label scribble/manual-struct))
 
 @title[#:tag "struct"]{Document Structures And Processing}
 
@@ -362,16 +363,32 @@ Hyperlinks the content to @scheme[tag].
 
 
 @defstruct[(index-element element) ([tag tag?]
-                                    [plain-seq (listof string?)]
+                                    [plain-seq (and/c (listof string?) cons?)]
-                                    [entry-seq list?])]{
+                                    [entry-seq list?]
+                                    [desc any/c])]{
 
 The @scheme[plain-seq] specifies the keys for sorting, where the first
- element is the main key, the second is a sub-key, etc. The
+element is the main key, the second is a sub-key, etc. For example, an
- @scheme[entry-seq] list must have the same length, and it provides
+``night'' portion of an index might have sub-entries for ``night,
- the form of each key to render in the final document. See also
+things that go bump in'' and ``night, defender of the''. The former
- @scheme[index].
+would be represented by @scheme[plain-seq] @scheme['("night" "things
+that go bump in")], and the latter by @scheme['("night" "defender of
+the")]. Naturally, single-element @scheme[plain-seq] lists are the
+common case, and at least one word is required, but there is no limit
+to the word-list length.
 
-}
+The @scheme[entry-seq] list must have the same length as
+@scheme[plain-seq]. It provides the form of each key to render in the
+final document.
+
+The @scheme[desc] field provides additional information about the
+index entry as supplied by the entry creator. For example, a reference
+to a procedure binding can be recognized when @scheme[desc] is an
+instance of @scheme[procedure-index-desc]. See
+@schememodname[scribble/manual-struct] for other typical types of
+@scheme[desc] values.
+
+See also @scheme[index].}
 
 
 @defstruct[(aux-element element) ()]{

collects/scribblings/scribble/xref.scrbl

@@ -0,0 +1,108 @@
+#lang scribble/doc
+@(require scribble/manual
+          "utils.ss"
+          (for-label scribble/xref
+                     scribble/base-render
+                     scribble/html-render))
+
+@title[#:tag "xref"]{Cross-Reference Utilities}
+
+@defmodule[scribble/xref]{The @schememodname[scribble/xref] library
+provides utilities for querying cross-reference information that was
+collected from a document build.}
+
+@; ------------------------------------------------------------------------
+
+@defproc[(xref? [v any/c]) boolean?]{
+
+Returns @scheme[#t] if @scheme[v] is a cross-reference record created
+by @scheme[load-xref], @scheme[#f] otherwise.}
+
+
+@defproc[(load-xref [sources (listof (-> any/c))]
+                    [#:render% using-render% (subclass?/c render%)
+                               (render-mixin render%)])
+         xref?]{
+
+Creates a cross-reference record given a list of functions that each
+produce a serialized information obtained from @xmethod[render%
+serialize-info].
+
+Since the format of serialized information is specific to a rendering
+class, the optional @scheme[using-render%] argument accepts the
+relevant class. It default to HTML rendering.}
+
+
+@defproc[(xref-binding->definition-tag [xref xref?]
+                                       [mod (or/c module-path?
+                                                  module-path-index?
+                                                  path?
+                                                  resolved-module-path?)]
+                                       [sym symbol?])
+         (or/c tag? false/c)]{
+
+Locates a tag in @scheme[xref] that documents @scheme[sym] as defined
+by @scheme[mod]. The @scheme[sym] and @scheme[mod] combination
+correspond to the first two elements of a @scheme[identifier-binding]
+list result.
+
+If a documentation point exists in @scheme[xref], a tag is returned,
+which might be used with @scheme[xref-tag->path+anchor] or embedded in
+a document rendered via @scheme[xref-render]. If no definition point
+is found in @scheme[xref], the result is @scheme[#f].}
+
+                                                  
+@defproc[(xref-tag->path+anchor [xref xref?]
+                                [tag tag?]
+                                [#:render% using-render% (subclass?/c render%)
+                                           (render-mixin render%)])
+         (values (or/c false/c path?)
+                 (or/c false/c string?))]{
+
+Returns a path and anchor string designated by the key @scheme[tag]
+according the cross-reference @scheme[xref]. The first result is
+@scheme[#f] if no mapping is found for the given tag. The second
+result is @scheme[#f] if the first result is @scheme[#f], and it can
+also be @scheme[#f] if the tag refers to a page rather than a specific
+point in a page.
+
+The optional @scheme[using-render%] argument is as for
+@scheme[load-xref].}
+                                
+
+
+@defproc[(xref-render [xref xref?]
+                      [doc part?]
+                      [dest path-string?]
+                      [#:render% using-render% (subclass?/c render%)
+                                 (render-mixin render%)])
+         void?]{
+
+Renders @scheme[doc] using the cross-reference info in @scheme[xref]
+to the destination @scheme[dest]. For example, @scheme[doc] might be a
+generated document of search results using link tags described in
+@scheme[xref].
+
+The optional @scheme[using-render%] argument is as for
+@scheme[load-xref]. It determines the kind of output that is
+generated.}
+
+
+@defproc[(xref-index [xref xref?]) (listof entry?)]{
+
+Converts indexing information @scheme[xref] into a list of
+@scheme[entry] structures.}
+
+
+@defstruct[entry ([words (and/c (listof string?) cons?)]
+                  [content list?]
+                  [tag tag?]
+                  [desc any/c])]{
+
+Represents a single entry in a Scribble document index.
+
+The @scheme[words] list corresponds to
+@scheme[index-element-plain-seq]. The @scheme[content] list
+corresponds to @scheme[index-element-entry-seq]. The @scheme[desc]
+value corresponds to @scheme[index-element-desc]. The @scheme[tag] is
+the destination for the index link into the main document.}