suzanne.soy/racket
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

finish up main page: release notes, etc.; add Yavuz's errortrace scribbling

Browse Source 
svn: r8314
This commit is contained in:
Matthew Flatt 2008-01-13 14:53:54 +00:00
parent 25fec67495
commit d532fe4781
21 changed files with 678 additions and 382 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
collects/drscheme/acks.ss
View File

@ -9,10 +9,12 @@
(define (get-general-acks)
(string-append
"The following individuals contributed to the implementation"
" of DrScheme and associated tools: "
" and documentation of PLT Scheme: "
"Yavuz Arkun, "
"Ian Barland, "
"Eli Barzilay, "
"Gann Bierner, "
"Richard Cleis, "
"John Clements, "
"Richard Cobbe, "
"Greg Cooper, "

334
collects/errortrace/doc.txt
View File

@ -1,334 +0,0 @@
[index entries: _debug_ _debugger_ _debugging_
_profile_ _profiler_ _profiling_
_coverage_ ]
_Errortrace_ is a stack-trace-on-exceptions/profiler/coverage tool for
MzScheme. Errortrace is not a complete debugger, and a real debugger
in DrScheme is expected eventually; meanwhile, using errortrace might
be better than MzScheme's limited stack-trace reporting.
Quick instructions
------------------
0) Throw away .zo versions of your source
1) Prefix your program with
(require (lib "errortrace.ss" "errortrace"))
or start MzScheme with the -M flag:
mzscheme -M errortrace
2) When an exception occurs, the exception handler prints something
like a stack trace, most recent contexts first
The errortrace module is strange; don't import it into another module.
Instead, the errortrace module is meant to be invoked from the
top-level, so that it can install an evaluation handler, exception
handler, etc.
To reuse parts of the code of errortrace, import _errortrace-lib.ss_.
It contains all of the names here but does not set the compilation
handler or the error display handler.
Exception Information
---------------------
Invoking the _errortrace.ss_ module sets the compilation handler to
instrument Scheme source code. It also sets the error display handler
to report source information for an exception, and it sets the
`use-compiled-file-paths' parameter to trigger the use of
errortrace-specific .zo files.
NOTE: errortrace has no effect on code loaded as compiled byte code
(i.e., from a .zo file) or native code (i.e., from a .dll or .so
file). But use the "--mode errortrace" flag to Setup PLT to create
.zo files with errortrace information.
Explicitly requiring "errortrace.ss" within a module is generally a
bad idea, since "errortrace.ss" sets various parameters.
Errortrace's instrumentation can be explicitly disabled via the
`instrumenting-enabled' boolean parameter. Instrumentation is on by
default. The `instrumenting-enabled' parameter affects only the way
that source code is compiled, not the way that exception information
is reported.
> (instrumenting-enabled) - returns #t if error tracing
instrumentation is enabled, #f otherwise
> (instrumenting-enabled on?) - enables/disables error tracing
instrumentation
The instrumentation for storing exception information slows most
programs by a factor of 2 or 3.
The `print-error-trace' procedure takes a port and exception and
prints the errortrace-collected debugging information contained in the
exception. It is used by the exception handler installed by
errortrace.
> (print-error-trace output-port exn) - prints the errortrace
information in `exn' to `output-port'.
The `error-context-display-depth' parameter controls how much context
errortrace's exception handler displays. The default value is 10000.
> (error-context-display-depth) - returns the current context display
depth
> (error-context-display-depth d) - sets the context display depth to
`d'
Profiling
---------
Errortrace's profiling instrumentation is off by default. Enable
profiling instrumentation with the `profiling-enabled' boolean
parameter (but setting `instrumenting-enabled' to #f also disables
profiling):
> (profiling-enabled) - returns #t if profiling instrumentation is
enabled, #f otherwise
> (profiling-enabled on?) - enables/disables profiling instrumentation
> (profiling-record-enabled) - returns #t if profiling info is
recorded for instrumented code, #f otherwise; the default is #t
> (profiling-record-enabled on?) - enables/disables the recording of
profiling info (independent of whether newly evaluated code is
instrumented)
Profiling records:
* the number of times a procedure was called.
* the number of milliseconds consumed by the procedure's body across
all calls (including the time consumed by any nested non-tail call
within the procedure, but not including time consumed by a
tail-call from the procedure).
* an inferred name for the procedure.
* the procedure's source in the form of a syntax object (which might,
in turn, provide a source location file and position).
* optionally, information about the procedure call path (i.e., a
stack trace) for every call to the procedure; collecting this
information is relatively expensive. Path information is collected
when the `profile-paths-enabled' boolean parameter is #t; the
default is #f, but setting the parameter to #t immediately affects
all procedure instrumented for profiling information:
> (profile-paths-enabled) - returns #t if profiling collects path
information, #f otherwise
> (profile-paths-enabled on?) - enables/disables collecting path
information for profiling
Profiling information is accumulated in a hash table. If a procedure
is redefined, new profiling information is accumulated for the new
version of the procedure, but the old information is also preserved.
To retrieve all profiling information accumulated so far, call
`get-profile-results':
> (get-profile-results) - returns a list of lists that contain:
* the number of times the procedure was called;
* the number of milliseconds of process time consumed by the
procedure;
* the inferred name or #f of the procedure;
* the syntax source of the procedure; and
* a list of unique call paths recorded while `profile-paths-enabled'
is set to #t. Each call path is a pair of a count (the number of
times the path occurred) and a list containing two-element lists;
each two-element list contains the calling procedure's name or
source expression and the calling procedure's source file or #f.
Depending of the source program, profiling usually induces a factor of
2 to 4 slowdown (in addition to any slowdown from the exception
information instrumentation).
> (output-profile-results paths? sort-time?)
Gets the current profile results and displays them. It optionally
shows paths information (if it is recorded) and sorts by either time
or call counts.
> (clear-profile-results)
Clears accumulated profile results.
Coverage
--------
Errortrace can produce coverage information in two flavors: both count
the number of times each expression in the source was used during
execution. The first flavor uses a simple approach, where each
expression is counted when executed; the second one uses the same
annotations that the profiler uses, so only function bodies are
counted. To see the difference between the two approaches, try this
program:
(define (foo x) (if x 1 2))
(equal? (foo #t) 1)
The first approach will produce exact results, but it is more
expensive; use it when you want to know how covered your code is (when
the expected counts are small). The second approach produces coarser
results (which, in the above case, will miss the `2' expression), but
is less expensive; use it when you want to use the counts for
profiling (when the expected counts are large).
> (coverage-counts-enabled [on?])
> (execute-counts-enabled [on?])
parameters that determine if the first (exact coverage) or second
(profiler-based coverage) are enabled. (Remember that setting
`instrumenting-enabled' to #f also disables both)
> (get-coverage-counts)
> (get-execute-counts)
returns a list of pairs, one for each instrumented expression. The
first element of the pair is a syntax object (usually containing
source location information) for the original expression, and the
second element of the pair is the number of times that the
expression has been evaluated. These elements are destructively
modified, so to take a snapshot you will need to copy them.
> (annotate-covered-file filename-path [display-string])
> (annotate-executed-file filename-path [display-string])
writes the named file to the current output port, inserting an
additional line between each source line to reflect execution counts
(as reported by `get-coverage-counts' or `get-execute-counts'). The
optional display string is used for the annotation: the first
character is used for expressions that were visited 0 times, the
second character for 1 time, ..., and the last character for
expressions that were visited more times. It can also be #t for a
maximal display ("012...9ABC...Z"), #f for a minimal display
("#-"). The default for `annotate-covered-file' is #f, and the
default for `annotate-executed-file' is "^.,".
_Re-using errortrace handlers_
-----------------------------------
The _errortrace-lib.ss_ module exports all of the exports of
"errortrace.ss", plus a few more. It does not install any handlers.
The addition exports are as follows:
> (errortrace-compile-handler stx immediate-eval?) - compiles `stx'
using the compilation handler that was active when the
"errortrace-lib.ss" module was executed, but first instruments the
code for errortrace information. The code is instrumented only if
the namespace is the same as when the module was executed. This
procedure is suitable for use as a compilation handler.
> (errortrace-error-display-handler string exn) - displays information
about the exception; this procedure is suitable for use as an error
display handler.
> (errortrace-annotate stx) - macro-expands and instruments the given
top-level form. If the form is a module named `errortrace-key', no
instrumentation is applied. This annotation function is used by
`errortrace-compile-handler'.
> (annotate-top stx) - like `errortrace-annotate', but without the
special case for `errortrace-key'. Also, if `stx' is a module
declaration, it is not enriched with imports to explicitly load
errortrace run-time support.
_Re-using errortrace stack tracing_
-----------------------------------
The errortrace collection also includes a _stacktrace.ss_ library. It
exports the _stacktrace@_ unit, its import signature
_stacktrace-imports^_, and its export signature _stacktrace^_.
The export signature contains these names:
> annotate : syntax boolean -> syntax
> annotate-top : syntax boolean -> syntax
> make-st-mark : syntax -> syntax
> st-mark-source : st-mark -> any
> st-mark-bindings : st-mark -> (listof (list syntax any))
The first two functions annotate expressions with errortrace
information. The `annotate-top' function should be called with a
top-level expression, and `annotate' should be called with a nested
expression (e.g., by `profile-point'). The boolean argument indicates
whether the expression is a transformer expression (#t) or a normal
expression (#f).
The `st-mark-source' and `st-mark-bindings' functions extract
information from a particular kind of value. The value must be
created by `make-st-mark'. `st-mark-source' extracts the value
originally provided to the expression-maker, and `st-mark-bindings'
returns local binding information (if available).
The import signature contains these names:
> with-mark : syntax syntax -> syntax
This procedure is called by `annotate' and `annotate-top' to wrap
expressions with `with-continuation-mark'. The first argument is
the source expression and the second argument is the expression to
be wrapped.
> test-coverage-enabled : (parameter boolean)
This parameter determines if the test coverage annotation is
inserted into the code. This parameter controls how compilation
happens -- it does not affect the dynamic behavior of the already
compiled code. If the parameter is set, calls to test-covered are
inserted into the code (and initialize-test-coverage-point is called
during compilation). If not, no calls to test-covered are inserted.
> test-covered : symbol -> void
During execution of the program, this is called for each point with
the key for that program point that was passed to
initialize-test-coverage-point.
> initialize-test-coverage-point : symbol syntax -> void
During compilation of the program, this function is called with each
sub-expression of the program. The first argument is a special key
used to identify this program point. The second argument is the
syntax of this program point.
> profile-key : symbol
only used for profiling paths.
> profiling-enabled : -> boolean
determines if profiling information is currently collected (affects
the behavior of compiling the code -- does not affect running code).
If this always returns #f, the other profiling functions are never
called.
> initialize-profile-point : symbol (union #f syntax[symbol]) syntax -> void
called as the program is compiled for each profiling point that
might be encountered during the program's execution. The first
argument is a key identifying this code. The second argument is the
inferred name at this point and the final argument is the syntax of
this expression.
> register-profile-start : symbol -> (union #f number)
Called when some profiled code is about to be executed. If the
result is a number, it is expected to be the current number of
milliseconds. The symbol is a key that is unique to this fragment
of code -- it is the same symbol passed to initialize-profile-point
for this code fragment.
> register-profile-done : symbol (union #f number) -> void
This function is called when some profiled code is finished
executing.
Note that register-profile-start and register-profile-done can be
called in a nested manner; in this case, the result of
register-profile-point should be #f.

394
collects/errortrace/scribblings/errortrace.scrbl Normal file
View File

@ -0,0 +1,394 @@
#lang scribble/doc
@(require scribble/manual
(for-label scheme
errortrace
errortrace/errortrace-lib
errortrace/stacktrace))
@title[#:tag "top"]{@bold{Errortrace}: Debugging and Profiling}
@bold{Errortrace} is a stack-trace-on-exceptions, profiler, and
coverage tool for MzScheme. It is not a complete debugger; DrScheme
provides more. Meanwhile, using Errortrace might be better than
MzScheme's limited stack-trace reporting.
@table-of-contents[]
@; ----------------------------------------------
@section[#:tag "quick-instructions"]{Quick Instructions}
@itemize{@item{Throw away @filepath{.zo} versions of your source.}
@item{Prefix your program with
@schemeblock[(require errortrace)]
or start MzScheme with the @Flag{l} option before the
arguments to load your program:
@commandline{mzscheme -l errortrace ...}}
@item{When an exception occurs, the exception handler prints
something like a stack trace, most recent contexts first.}
}
The @schememodname[errortrace] module is strange; don't import it
into another module. Instead, the @schememodname[errortrace]
module is meant to be invoked from the top-level, so that it can install
an evaluation handler, exception handler, etc.
To reuse parts of the code of @schememodname[errortrace], import
@schememodname[errortrace/errortrace-lib]. It contains all of the
bindings described here, but does not set the compilation handler or
the error display handler.
@; ----------------------------------------------
@section[#:tag "installing-errortrace"]{Installing Errortrace}
Invoking the
@schememodname[errortrace] module sets the compilation
handler to instrument Scheme source code. It also sets the error
display handler to report source information for an exception, and it
sets the @scheme[use-compiled-file-paths] parameter to trigger the use
of Errortrace-specific @filepath{.zo} files.
NOTE: @schememodname[errortrace] has no effect on code
loaded as compiled byte code (i.e., from a @filepath{.zo} file) or
native code (i.e., from a @filepath{.dll}, @filepath{.so} or
@filepath{.dylib} file). You can use the @DFlag{mode errortrace} flag
to @exec{setup-plt} to create @filepath{.zo} files with
Errortrace information.
Explicitly requiring @schememodname[errortrace] within a module is
generally a bad idea, since @schememodname[errortrace] sets various
parameters.
@; ---------------------------------------------
@section[#:tag "using-errortrace"]{Using Errortrace}
@defmodule[errortrace]
@; ---------------------------------------------
@subsection[#:tag "instrumentation-and-profiling"]{Instrumentation and Profiling}
By default, @schememodname[errortrace] only instruments for
stack-trace-on-exception. Profiling and coverage need to be enabled
separately.
@defboolparam[instrumenting-enabled on?]{
A parameter that determines whether tracing instrumentation is
enabled, @scheme[#t] by default. Affects only the way that source code is
compiled, not the way that exception information is reported. The
instrumentation for storing exception information slows most programs
by a factor of 2 or 3.}
@defboolparam[profiling-enabled on?]{
Errortrace's profiling instrumentation is @scheme[#f] by default. To use it,
you also need to ensure that @scheme[instrumenting-enabled] is on.}
@defboolparam[profiling-record-enabled on?]{
Enables/disables the recording of profiling info for the instrumented code.
The default is @scheme[#t].}
Profiling information is accumulated in a hash table. If a procedure
is redefined, new profiling information is accumulated for the new
version of the procedure, but the old information is also preserved.
Depending of the source program, profiling usually induces a factor of
2 to 4 slowdown in addition to any slowdown from the exception
information instrumentation.
@defproc[(output-profile-results [paths? any/c] [sort-time? any/c]) void?]{
Gets the current profile results using @scheme[get-profile-results] and
displays them. It optionally shows paths information (if it is recorded),
and sorts by either time or call counts.}
@defproc[(get-profile-results) list?]{
Returns a list of lists that contain all profiling information accumulated
so far:
@itemize{
@item{the number of times a procedure was called.}
@item{the number of milliseconds consumed by the procedure's body across
all calls (including the time consumed by any nested non-tail call
within the procedure, but not including time consumed by a
tail-call from the procedure).}
@item{an inferred name (or @scheme[#f]) for the procedure.}
@item{the procedure's source in the form of a syntax object (which might,
in turn, provide a source location file and position).}
@item{optionally, a list of unique call paths (i.e. stack traces)
recorded if @scheme[profile-paths-enabled] is set to @scheme[#t].
Each call path is a pair of
@itemize{
@item{a count (the number of times the path occurred), and}
@item{a list containing two-element lists. Each two-element list
contains
@itemize{
@item{the calling procedure's name or source expression,
and}
@item{the calling procedure's source file or @scheme[#f].}}
}
}
Collecting this information is relatively expensive.}
}}
@defboolparam[profile-paths-enabled on?]{
Enables/disables collecting path information for profiling. The default is
@scheme[#f], but setting the parameter to @scheme[#t] immediately affects
all procedures instrumented for profiling information.}
@defproc[(clear-profile-results) void?]{
Clears accumulated profile results.}
@; ------------------------------------------------
@subsection[#:tag "coverage"]{Coverage}
Errortrace can produce coverage information in two flavors: both count
the number of times each expression in the source was used during
execution. The first flavor uses a simple approach, where each
expression is counted when executed; the second one uses the same
annotations that the profiler uses, so only function bodies are
counted. To see the difference between the two approaches, try this
program:
@schemeblock[(define (foo x) (if x 1 2))
(equal? (foo #t) 1)]
The first approach will produce exact results, but it is more
expensive; use it when you want to know how covered your code is (when
the expected counts are small). The second approach produces coarser
results (which, in the above case, will miss the @scheme[2] expression),
but is less expensive; use it when you want to use the counts for
profiling (when the expected counts are large).
@deftogether[(
@defboolparam[coverage-counts-enabled on?]
@defboolparam[execute-counts-enabled on?])]{
Parameters that determine if the first (exact coverage) or second
(profiler-based coverage) are enabled. Remember that setting
@scheme[instrumenting-enabled] to @scheme[#f] also disables both.}
@deftogether[(
@defproc[(get-coverage-counts) list?]
@defproc[(get-execute-counts) list?])]{
Returns a list of pairs, one for each instrumented expression. The
first element of the pair is a @scheme[syntax?] object (usually containing
source location information) for the original expression, and the
second element of the pair is the number of times that the
expression has been evaluated. These elements are destructively
modified, so to take a snapshot you will need to copy them.}
@deftogether[(
@defproc[(annotate-covered-file
[filename-path path-string?]
[display-string (or/c string? false/c) #f])
void?]
@defproc[(annotate-executed-file
[filename-path path-string?]
[display-string (or/c string? false/c) "^.,"])
void?])]{
Writes the named file to the @scheme[current-output-port], inserting an
additional line between each source line to reflect execution counts
(as reported by @scheme[get-coverage-counts] or @scheme[get-execute-counts]).
The optional @scheme[display-string] is used for the annotation: the first
character is used for expressions that were visited 0 times, the
second character for 1 time, ..., and the last character for
expressions that were visited more times. It can also be @scheme[#t]
for a maximal display (@scheme["012...9ABC...Z"]), or @scheme[#f] for
a minimal display (@scheme["#-"]).}
@; ------------------------------------------------------
@subsection[#:tag "other-errortrace-bindings"]{Other Errortrace Bindings}
The @schememodname[errortrace] module also exports:
@defproc[(print-error-trace [output-port output-port?] [exn exn?]) void?]{
The @scheme[print-error-trace] procedure takes a port and exception and
prints the Errortrace-collected debugging information contained in the
exception. It is used by the exception handler installed by
Errortrace.}
@defparam[error-context-display-depth d integer?]{The
@scheme[error-context-display-depth] parameter controls how much context
Errortrace's exception handler displays. The default value is 10,000.}
@; ------------------------------------------------------
@section[#:tag "errortrace-library"]{Errortrace Library}
@defmodule[errortrace/errortrace-lib]{
The @schememodname[errortrace/errortrace-lib] module exports all of the
exports of @schememodname[errortrace], plus a few more. It does
not install any handlers.}
The additional exports are as follows:
@defproc[(errortrace-compile-handler (stx any/c) (immediate-eval? any/c))
compiled-expression?]{
Compiles @scheme[stx] using the compilation handler that was active
when the @schememodname[errortrace/errortrace-lib] module was executed,
but first instruments the code for Errortrace information. The code is
instrumented only if the namespace is the same as when the module was
executed. This procedure is suitable for use as a compilation handler.}
@defproc[(errortrace-error-display-handler (string string?) (exn exn?)) void?]{
Displays information about the exception; this procedure is suitable
for use as an error display handler.}
@defproc[(errortrace-annotate (stx any/c)) any/c]{
Macro-expands and instruments the given top-level form. If the form is
a module named @schemeidfont{errortrace-key}, no instrumentation is
applied. This annotation function is used by
@scheme[errortrace-compile-handler].}
@defproc[(annotate-top (stx any/c)) any/c]{
Like @scheme[errortrace-annotate], but without the special case for
@scheme[errortrace-key]. Also, if @scheme[stx] is a module declaration,
it is not enriched with imports to explicitly load Errortrace run-time
support.}
@; -----------------------------------------------
@section[#:tag "stacktrace"]{Re-using Errortrace Stack Tracing}
@(define-syntax-rule (schemein id) (sigelem stacktrace-imports^ id))
@(define-syntax-rule (schemeout id) (sigelem stacktrace^ id))
@defmodule[errortrace/stacktrace]{
The errortrace collection also includes a
@schememodname[errortrace/stacktrace] library. It exports
the @scheme[stacktrace@] unit, its import signature
@scheme[stacktrace-imports^], and its export signature
@scheme[stacktrace^].}
@defthing[stacktrace@ unit?]{
Imports @scheme[stacktrace-imports^] and exports @scheme[stacktrace^].}
@defsignature[stacktrace^ ()]{
@deftogether[(
@defproc[(annotate (stx syntax?) (trans? boolean?)) syntax?]
@defproc[(annotate-top (stx syntax?) (trans? boolean?)) syntax?])]{
Annotate expressions with errortrace information. The
@schemeout[annotate-top] function should be called with a top-level
expression, and @schemeout[annotate] should be called with a nested
expression (e.g., by @schemein[initialize-profile-point]). The
boolean argument indicates whether the expression is a transformer
expression (@scheme[#t]) or a normal expression (@scheme[#f]).}
@deftogether[(
@defproc[(make-st-mark (syntax syntax?)) st-mark?]
@defproc[(st-mark-source (st-mark st-mark?)) syntax?]
@defproc[(st-mark-bindings (st-mark st-mark?)) list?])]{
The @schemeout[st-mark-source] and @schemeout[st-mark-bindings]
functions extract information from a particular kind of value. The
value must be created by @schemeout[make-st-mark]. The
@schemeout[st-mark-source] extracts the value originally provided to
the expression-maker, and @schemeout[st-mark-bindings] returns local
binding information (if available) as a list of two element (syntax?
any/c) lists. The @schemeout[st-mark-bindings] function is currently
hardwired to return @scheme[null]. }
}
@defsignature[stacktrace-imports^ ()]{
@defproc[(with-mark (source-stx any/c) (dest-stx any/c)) any/c]{
Called by @schemeout[annotate] and @schemeout[annotate-top] to wrap
expressions with @scheme[with-continuation-mark]. The first argument
is the source expression and the second argument is the expression to
be wrapped.}
@defboolparam[test-coverage-enabled on?]{
Determines if the test coverage annotation is inserted into the code.
This parameter controls how compilation happens---it does not affect the
dynamic behavior of the already compiled code. If the parameter is set,
calls to @schemein[test-covered] are inserted into the code (and
@schemein[initialize-test-coverage-point] is called during compilation).
If not, no calls to test-covered are inserted.}
@defproc[(test-covered (key any/c)) void?]{
During execution of the program, this is called for each point with
the key for that program point that was passed to
@schemein[initialize-test-coverage-point].}
@defproc[(initialize-test-coverage-point (key any/c) (stx any)) void?]{
During compilation of the program, this function is called with each
sub-expression of the program. The first argument is a special key
used to identify this program point. The second argument is the
syntax of this program point.}
@defthing[profile-key any/c]{
Only used for profiling paths.}
@defboolparam[profiling-enabled on?]{
Determines if profiling information is currently collected (affects
the behavior of compiling the code---does not affect running code).
If this always returns @scheme[#f], the other profiling functions are
never called.}
@defproc[(initialize-profile-point (key any/c)
(name (or/c syntax? false/c))
(stx any/c))
void?]{
Called as the program is compiled for each profiling point that
might be encountered during the program's execution. The first
argument is a key identifying this code. The second argument is the
inferred name at this point and the final argument is the syntax of
this expression.}
@defproc[(register-profile-start (key any/c)) (or/c number? false/c)]{
Called when some profiled code is about to be executed. If the
result is a number, it is expected to be the current number of
milliseconds. @scheme[key] is unique to this fragment of code---it is
the same key passed to @schemein[initialize-profile-point] for this code
fragment.}
@defproc[(register-profile-done (key any/c)
(start (or/c number? false/c)))
void?]{
This function is called when some profiled code is finished executing.
Note that @schemein[register-profile-start] and
@schemein[register-profile-done] can be called in a nested manner; in
this case, the result of @schemein[register-profile-start] should be
@scheme[#f].}
}

3
collects/errortrace/scribblings/info.ss Normal file
View File

@ -0,0 +1,3 @@
(module info setup/infotab
(define name "Errortrace documentation")
(define scribblings '(("errortrace.scrbl" (multi-page)))))

16
collects/scribble/html-render.ss
View File

@ -482,7 +482,11 @@
(if (current-no-links)
(super render-element e part ri)
(parameterize ([current-no-links #t])
`((a ((href ,(target-url-addr style))
`((a ((href ,(let ([addr (target-url-addr style)])
(if (path? addr)
(from-root addr
(get-dest-directory))
addr)))
,@(if (string? (target-url-style style))
`((class ,(target-url-style style)))
null))
@ -586,11 +590,19 @@
'(wbr)
`(span ((class "mywbr")) " "))
(render-other (substring i (cdar m)) part ri))
(list i)))]
(ascii-ize i)))]
[(eq? i 'mdash) `(" " ndash " ")]
[(eq? i 'hline) `((hr))]
[(symbol? i) (list i)]
[else (list (format "~s" i))]))
(define/private (ascii-ize s)
(let ([m (regexp-match-positions #rx"[^\u01-\u7E]" s)])
(if m
(append (ascii-ize (substring s 0 (caar m)))
(list (char->integer (string-ref s (caar m))))
(ascii-ize (substring s (cdar m))))
(list s))))
;; ----------------------------------------

2
collects/scribble/struct.ss
View File

@ -175,7 +175,7 @@
[parent (or/c false/c part?)]
[info any/c])]
[target-url ([addr string?][style any/c])]
[target-url ([addr (or/c string? path?)][style any/c])]
[url-anchor ([name string?])]
[image-file ([path path-string?])])

9
collects/scribblings/acks/acks.scrbl Normal file
View File

@ -0,0 +1,9 @@
#lang scribble/doc
@(require scribble/manual
drscheme/acks)
@title{Acknowledgements}
@(get-general-acks)
@(get-translating-acks)

4
collects/scribblings/acks/info.ss Normal file
View File

@ -0,0 +1,4 @@
(module info setup/infotab
(define name "Scribblings: Acknowledgments")
(define scribblings '(("acks.scrbl")))
(define doc-categories '(omit)))

4
collects/scribblings/license/info.ss Normal file
View File

@ -0,0 +1,4 @@
(module info setup/infotab
(define name "Scribblings: License")
(define scribblings '(("license.scrbl")))
(define doc-categories '(omit)))

122
collects/scribblings/license/license.scrbl Normal file
View File

@ -0,0 +1,122 @@
#lang scribble/doc
@(require scribble/manual)
@(define (copyright . strs)
(verbatim (apply string-append
" "
(map (lambda (s)
(if (string=? s "\n")
"\n "
s))
strs))))
@title{License}
PLT software and documentation is distributed under the GNU Lesser
General Public License (LGPL). This means
@itemize{
@item{You can link PLT software (such as MzScheme or MrEd) into
proprietary applications, provided you follow the specific
rules stated in the LGPL.}
@item{You can modify PLT software. If you distribute a modified
version, you must distribute it under the terms of the LGPL,
which in particular means that you must release the source code
for the modified software.}
}
See @filepath{doc/release-notes/COPYING.LIB} in your PLT installation
for more information.
@copyright{
PLT Scheme
Copyright (c) 1995-2003 PLT
Copyright (c) 2004-2008 PLT Scheme Inc.}
PLT software includes or extends the following copyrighted material:
@copyright{
DrScheme
Copyright (c) 1995-2003 PLT
Copyright (c) 2004-2008 PLT Scheme Inc.
All rights reserved.}
@copyright{
MrEd
Copyright (c) 1995-2003 PLT
Copyright (c) 2004-2008 PLT Scheme Inc.
All rights reserved.}
@copyright{
MzScheme
Copyright (c) 1995-2003 PLT
Copyright (c) 2004-2008 PLT Scheme Inc.
All rights reserved.}
@copyright{
libscheme
Copyright (c) 1994 Brent Benson
All rights reserved.}
@copyright{
wxWindows
Copyright (c) 1994 Artificial Intelligence Applications Institute,
The University of Edinburgh
All rights reserved.}
@copyright{
wxWindows Xt
Copyright (c) 1994 Artificial Intelligence Applications Institute,
The University of Edinburgh
Copyright (c) 1995 GNU (Markus Holzem)
All rights reserved.}
@copyright{
Conservative garbage collector
Copyright (c) 1988, 1989 Hans-J. Boehm, Alan J. Demers
Copyright (c) 1991-1996 Xerox Corporation
Copyright (c) 1996-1999 Silicon Graphics
Copyright (c) 1999-2001 by Hewlett-Packard Company
All rights reserved.}
@copyright{
Collector C++ extension by Jesse Hull and John Ellis
Copyright (c) 1994 Xerox Corporation
All rights reserved.}
@copyright{
The A List
Copyright (c) 1997-2000 Kyle Hammond.
All rights reserved.}
@copyright{
Independent JPEG Group library
Copyright (c) 1991-1998 Thomas G. Lane.
All rights reserved.}
@copyright{
libpng
Copyright (c) 2000-2002 Glenn Randers-Pehrson
All rights reserved.}
@copyright{
zlib
Copyright (c) 1995-2002 Jean-loup Gailly and Mark Adler
All rights reserved.}
@copyright{
GNU MP Library
Copyright (c) 1992, 1993, 1994, 1996 by Free Software
Foundation, Inc.}
@copyright{
GNU lightning
Copyright (c) 1994, 1995, 1996, 1999, 2000, 2001, 2002
Free Software Foundation, Inc.}
@copyright{
GNU Classpath
GNU Public License with special exception}

4
collects/scribblings/release/info.ss Normal file
View File

@ -0,0 +1,4 @@
(module info setup/infotab
(define name "Scribblings: Release Notes")
(define scribblings '(("release.scrbl")))
(define doc-categories '(omit)))

23
collects/scribblings/release/release.scrbl Normal file
View File

@ -0,0 +1,23 @@
#lang scribble/doc
@(require scribble/manual
setup/dirs)
@(define (rl-link path . content)
(apply link (apply build-path (find-doc-dir) "release-notes" path)
content))
@title{Release Notes}
@itemize{
@item{@rl-link['("drscheme" "HISTORY.txt")]{DrScheme}}
@item{@rl-link['("mzscheme" "HISTORY.txt")]{MzScheme}
@itemize{
@item{@rl-link['("mzscheme" "MzScheme_4.txt")]{Porting from v3xx to v4.x}}
@item{@rl-link['("mzscheme" "MzScheme_300.txt")]{Porting from v2xx to v3xx}}
@item{@rl-link['("mzscheme" "MzScheme_200.txt")]{Porting from v1xx to v2xx}}
}}
@item{@rl-link['("mred" "HISTORY.txt")]{MrEd}}
@item{@rl-link['("stepper" "HISTORY.txt")]{Stepper}}
}

49
collects/scribblings/scribble/manual.scrbl
View File

@ -4,13 +4,15 @@
(for-syntax scheme/base)
(for-label scribble/manual-struct))
@title[#:tag "manual"]{Manual Forms}
@title[#:tag "manual" #:style 'toc]{Manual Forms}
@defmodule[scribble/manual]{The @schememodname[scribble/manual]
library provides all of @schememodname[scribble/basic], plus
additional functions that are relatively specific to writing PLT
Scheme documentation.}
@local-table-of-contents[]
@; ------------------------------------------------------------------------
@section[#:tag "scribble:manual:code"]{Typesetting Code}
@ -180,7 +182,7 @@ procedure, but use @scheme[var] if that cannot work for some reason.}
in a form definition.}
@; ------------------------------------------------------------------------
@section{Documenting Modules}
@section[#:tag "doc-modules"]{Documenting Modules}
@defform[(defmodule id pre-flow ...)]{
@ -238,7 +240,7 @@ list of @scheme[module-path]s is shown, for example, when the user
hovers the mouse over one of the bindings defined within the section.}
@; ------------------------------------------------------------------------
@section{Documenting Forms, Functions, Structure Types, and Values}
@section[#:tag "doc-forms"]{Documenting Forms, Functions, Structure Types, and Values}
@defform/subs[(defproc prototype
result-contract-expr-datum
@ -476,7 +478,7 @@ Like @scheme[schemegrammar], but for typesetting multiple productions
at once, aligned around the @litchar{=} and @litchar{|}.}
@; ------------------------------------------------------------------------
@section{Documenting Classes and Interfaces}
@section[#:tag "doc-classes"]{Documenting Classes and Interfaces}
@defform[(defclass id super-id (intf-id ...) pre-flow ...)]{
@ -575,7 +577,40 @@ Like @scheme[method], but the hyperlink shows both the method name and
the containing class/interface.}
@; ------------------------------------------------------------------------
@section{Various String Forms}
@section[#:tag "doc-signatures"]{Documenting Signature}
@defform[(defsignature id (super-id ...) pre-flow ...)]{
Defines a signature @scheme[id] that extends the @scheme[super-id]
signatures. Any elements defined in @tech{decode}d
@scheme[pre-flow]s---including forms, procedures, structure types,
classes, interfaces, and mixins---are defined as members of the
signature instead of direct bindings. These definitions can be
referenced through @scheme[sigelem] instead of @scheme[scheme].
The @tech{decode}d @scheme[pre-flow]s inset under the signature
declaration in the typeset output, so no new sections, @|etc| can be
started.}
@defform[(defsignature/splice id (super-id ...) pre-flow ...)]{
Like @scheme[defsignature], but the @tech{decode}d @scheme[pre-flow]s
are not typeset under the signature declaration, and new sections,
@|etc| can be started in the @scheme[pre-flow]s.}
@defproc[(signature-desc [pre-flow any/c] ...) any/c]{
Produces an opaque value that @scheme[defsignature] recognizes to
outdent in the typeset form. This is useful for text describing the
signature as a whole to appear right after the signature declaration.}
@defform[(sigelem sig-id id)]{
Typesets the identifier @scheme[id] with a hyperlink to its definition
as a member of the signature named by @scheme[sig-id].}
@; ------------------------------------------------------------------------
@section[#:tag "doc-strings"]{Various String Forms}
@defproc[(emph [pre-content any/c] ...) element?]{Typesets the
@tech{decode}d @scheme[pre-content] with emphasis (e.g., in italic).}
@ -636,7 +671,7 @@ Extensions to @scheme[math] are likely, such as recognizing @litchar{_}
and @litchar{^} for subscripts and superscripts.}
@; ------------------------------------------------------------------------
@section[#:tag "scribble:manual:section-links"]{Links}
@section[#:tag "section-links"]{Links}
@defproc[(secref [tag string?]
[#:doc module-path (or/c module-path? false/c) #f]
@ -865,7 +900,7 @@ an inset command-line example (e.g., in typewriter font).}
a paragraph to be typeset in the margin instead of inlined.}
@; ------------------------------------------------------------------------
@section{Index-Entry Descriptions}
@section[#:tag "index-entries"]{Index-Entry Descriptions}
@defmodule[scribble/manual-struct]{The
@schememodname[scribble/manual-struct] library provides types used to

83
collects/scribblings/start/manuals.ss
View File

@ -2,8 +2,10 @@
(require scribble/manual
scribble/struct
scribble/decode
setup/getinfo
setup/main-collects)
setup/main-collects
setup/dirs)
(provide build-contents)
@ -34,6 +36,15 @@
(define (main-collects? dir)
(pair? (path->main-collects-relative dir)))
(define (to-toc target label)
(make-toc-element
#f
null
(list (link target
#:underline? #f
(make-element "tocsubseclink"
(list label))))))
(define (build-contents all?)
(let* ([dirs (find-relevant-directories '(scribblings))]
[infos (map get-info/full dirs)]
@ -92,32 +103,46 @@
(lambda (doc)
(plain-line (hspace 2)
(other-manual doc #:underline? #f)))])
(make-delayed-flow-element
(lambda (renderer part resolve-info)
(make-table
#f
(cdr
(apply append
(map (lambda (sec)
(let ([docs (filter (lambda (doc)
(eq? (car doc) (sec-cat sec)))
docs)])
(list*
(plain-line (hspace 1))
(plain-line (sec-label sec))
(map
cdr
(sort
(map (lambda (doc) (cons (cadr doc)
(line (caddr doc))))
docs)
(lambda (ad bd)
(let ([a (cadr (paragraph-content (car (flow-paragraphs (cadr ad)))))]
[b (cadr (paragraph-content (car (flow-paragraphs (cadr bd)))))])
(if (= (car ad) (car bd))
(begin
(string-ci<? (element->string a renderer part resolve-info)
(element->string b renderer part resolve-info)))
(> (car ad) (car bd))))))))))
sections))))))))
(make-splice
(list
(make-delayed-flow-element
(lambda (renderer part resolve-info)
(make-table
#f
(cdr
(apply append
(map (lambda (sec)
(let ([docs (filter (lambda (doc)
(eq? (car doc) (sec-cat sec)))
docs)])
(list*
(plain-line (hspace 1))
(plain-line (sec-label sec))
(map
cdr
(sort
(map (lambda (doc) (cons (cadr doc)
(line (caddr doc))))
docs)
(lambda (ad bd)
(let ([a (cadr (paragraph-content (car (flow-paragraphs (cadr ad)))))]
[b (cadr (paragraph-content (car (flow-paragraphs (cadr bd)))))])
(if (= (car ad) (car bd))
(begin
(string-ci<? (element->string a renderer part resolve-info)
(element->string b renderer part resolve-info)))
(> (car ad) (car bd))))))))))
sections))))))
(to-toc "master-index/index.html"
"Master Index")
(make-toc-element
#f
null
(list 'nbsp))
(to-toc (build-path (find-doc-dir) "license/index.html")
"License")
(to-toc (build-path (find-doc-dir) "acks/index.html")
"Acknowledgments")
(to-toc (build-path (find-doc-dir) "release/index.html")
"Release Notes")))))

7
collects/scribblings/start/start.scrbl
View File

@ -12,10 +12,3 @@
@(build-contents #f)
@(make-toc-element
#f
null
(list @link["master-index/index.html"
#:underline? #f
(make-element "tocsubseclink"
(list "Master Index"))]))

2
collects/trace/scribblings/trace.scrbl
View File

@ -19,7 +19,7 @@ depth of the continuation.
@item{Prefix your program with
@schemeblock[(require trace/calltrace)]
perhaps by starting @exec{mzscheme} with
@commandline{mzscheme -l trace/calltrace}
@commandline{mzscheme -l trace/calltrace ...}
before arguments to load your program.}
@item{Run your program}
}

0
doc/release-notes/drscheme/HISTORY → doc/release-notes/drscheme/HISTORY.txt
View File

0
doc/release-notes/mred/HISTORY → doc/release-notes/mred/HISTORY.txt
View File

0
doc/release-notes/mzscheme/HISTORY → doc/release-notes/mzscheme/HISTORY.txt
View File

0
doc/release-notes/stepper/HISTORY → doc/release-notes/stepper/HISTORY.txt
View File

0
doc/release-notes/teachpack/HISTORY → doc/release-notes/teachpack/HISTORY.txt
View File