doc scribble/xref, and start net docs
svn: r8021 original commit: bfecd9e0f5c91e9aecad4fb6ecb2ba69a89cb0f4
This commit is contained in:
Matthew Flatt
parent
7a53e8ef7e
commit
8e3ed2fcf4
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
(let* ([renderer (new (html:render-mixin render%)
|
||||
(define (load-xref sources #:render% [render% (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 (cadr r) ci))))
|
||||
(send renderer deserialize-info (src) 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)
|
||||
(let ([renderer (new (html:render-mixin render%)
|
||||
(define (xref-tag->path+anchor xrefs tag #:render% [render% (html:render-mixin render%)])
|
||||
(let ([renderer (new render%
|
||||
[dest-dir (find-system-path 'temp-dir)])])
|
||||
(send renderer tag->path+anchor (xrefs-ri xrefs) tag)))
|
||||
|
|
|
|||
|
|
@ -1,14 +1,15 @@
|
|||
#lang scribble/doc
|
||||
@require[scribble/manual]
|
||||
@require["utils.ss"]
|
||||
@require[(for-syntax scheme/base)]
|
||||
@(require scribble/manual
|
||||
"utils.ss"
|
||||
(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
|
||||
functions that are relatively specific to writing PLT Scheme
|
||||
documentation.}
|
||||
library provides all of @schememodname[scribble/basic], plus
|
||||
additional functions that are relatively specific to writing PLT
|
||||
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.}
|
||||
|
|
|
|||
|
|
@ -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.}
|
||||
|
||||
@defmodule*/no-declare[(scribble/text-render)]{The
|
||||
@schememodname[scribble/text-render] module provides
|
||||
@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.}
|
||||
which implements the core of a renderer. This rendering class must be
|
||||
refined with a mixin from @schememodname[scribble/text-render],
|
||||
@schememodname[scribble/html-render], or
|
||||
@schememodname[scribble/latex-render].}
|
||||
|
||||
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.}}
|
||||
|
|
|
|||
|
|
@ -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
|
||||
PLT Scheme documentation; re-exports @schememodname[scribble/basic]. See
|
||||
@secref["manual"].}
|
||||
@item{@schememodname[scribble/manual]: a library of support functions
|
||||
for writing PLT Scheme documentation; re-exports
|
||||
@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
|
||||
code at document-build time, especially for showing
|
||||
examples. See @secref["eval"].}
|
||||
@item{@schememodname[scribble/eval]: a library of support functions
|
||||
for evaluating code at document-build time, especially for
|
||||
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
|
||||
exports a @scheme{struct.ss}-based document, generating output with a
|
||||
The @exec{scribble} command-line utility generates output with a
|
||||
specified renderer. More specifically, the executable installs a
|
||||
renderer, loads the specified modules and extracts the @scheme[doc]
|
||||
export of each (which must be an instance of @scheme[section] from
|
||||
@schememodname[scribble/struct]), and renders each. Use @exec{scribble -h} for more
|
||||
renderer, loads the modules specified on the command line, extracts
|
||||
the @scheme[doc] export of each module (which must be an instance of
|
||||
@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[]
|
||||
|
|
|
|||
|
|
@ -1,6 +1,7 @@
|
|||
#lang scribble/doc
|
||||
@require[scribble/manual]
|
||||
@require["utils.ss"]
|
||||
@(require scribble/manual
|
||||
"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?)]
|
||||
[entry-seq list?])]{
|
||||
[plain-seq (and/c (listof string?) cons?)]
|
||||
[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
|
||||
@scheme[entry-seq] list must have the same length, and it provides
|
||||
the form of each key to render in the final document. See also
|
||||
@scheme[index].
|
||||
element is the main key, the second is a sub-key, etc. For example, an
|
||||
``night'' portion of an index might have sub-entries for ``night,
|
||||
things that go bump in'' and ``night, defender of the''. The former
|
||||
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) ()]{
|
||||
|
|
|
|||
108
collects/scribblings/scribble/xref.scrbl
Normal file
108
collects/scribblings/scribble/xref.scrbl
Normal file
|
|
@ -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.}
|
||||
Loading…
Reference in New Issue
Block a user