diff --git a/collects/drscheme/acks.ss b/collects/drscheme/acks.ss index ed40141e20..71086880bb 100644 --- a/collects/drscheme/acks.ss +++ b/collects/drscheme/acks.ss @@ -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, " diff --git a/collects/errortrace/doc.txt b/collects/errortrace/doc.txt deleted file mode 100644 index 90512049f6..0000000000 --- a/collects/errortrace/doc.txt +++ /dev/null @@ -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. diff --git a/collects/errortrace/scribblings/errortrace.scrbl b/collects/errortrace/scribblings/errortrace.scrbl new file mode 100644 index 0000000000..f4c043a4e8 --- /dev/null +++ b/collects/errortrace/scribblings/errortrace.scrbl @@ -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].} + +} diff --git a/collects/errortrace/scribblings/info.ss b/collects/errortrace/scribblings/info.ss new file mode 100644 index 0000000000..2fab5f5d7d --- /dev/null +++ b/collects/errortrace/scribblings/info.ss @@ -0,0 +1,3 @@ +(module info setup/infotab + (define name "Errortrace documentation") + (define scribblings '(("errortrace.scrbl" (multi-page))))) diff --git a/collects/scribble/html-render.ss b/collects/scribble/html-render.ss index 3f26a91211..8de6dccba0 100644 --- a/collects/scribble/html-render.ss +++ b/collects/scribble/html-render.ss @@ -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)))) ;; ---------------------------------------- diff --git a/collects/scribble/struct.ss b/collects/scribble/struct.ss index c18c6fb0cc..b17ef6b1ca 100644 --- a/collects/scribble/struct.ss +++ b/collects/scribble/struct.ss @@ -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?])]) diff --git a/collects/scribblings/acks/acks.scrbl b/collects/scribblings/acks/acks.scrbl new file mode 100644 index 0000000000..ac22920f56 --- /dev/null +++ b/collects/scribblings/acks/acks.scrbl @@ -0,0 +1,9 @@ +#lang scribble/doc +@(require scribble/manual + drscheme/acks) + +@title{Acknowledgements} + +@(get-general-acks) + +@(get-translating-acks) diff --git a/collects/scribblings/acks/info.ss b/collects/scribblings/acks/info.ss new file mode 100644 index 0000000000..683a6fe67f --- /dev/null +++ b/collects/scribblings/acks/info.ss @@ -0,0 +1,4 @@ +(module info setup/infotab + (define name "Scribblings: Acknowledgments") + (define scribblings '(("acks.scrbl"))) + (define doc-categories '(omit))) diff --git a/collects/scribblings/license/info.ss b/collects/scribblings/license/info.ss new file mode 100644 index 0000000000..ade1eebc19 --- /dev/null +++ b/collects/scribblings/license/info.ss @@ -0,0 +1,4 @@ +(module info setup/infotab + (define name "Scribblings: License") + (define scribblings '(("license.scrbl"))) + (define doc-categories '(omit))) diff --git a/collects/scribblings/license/license.scrbl b/collects/scribblings/license/license.scrbl new file mode 100644 index 0000000000..6f228fee73 --- /dev/null +++ b/collects/scribblings/license/license.scrbl @@ -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} diff --git a/collects/scribblings/release/info.ss b/collects/scribblings/release/info.ss new file mode 100644 index 0000000000..442094958b --- /dev/null +++ b/collects/scribblings/release/info.ss @@ -0,0 +1,4 @@ +(module info setup/infotab + (define name "Scribblings: Release Notes") + (define scribblings '(("release.scrbl"))) + (define doc-categories '(omit))) diff --git a/collects/scribblings/release/release.scrbl b/collects/scribblings/release/release.scrbl new file mode 100644 index 0000000000..4d2d2ac9a9 --- /dev/null +++ b/collects/scribblings/release/release.scrbl @@ -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}} + +} diff --git a/collects/scribblings/scribble/manual.scrbl b/collects/scribblings/scribble/manual.scrbl index d82087d78f..df234cb116 100644 --- a/collects/scribblings/scribble/manual.scrbl +++ b/collects/scribblings/scribble/manual.scrbl @@ -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 diff --git a/collects/scribblings/start/manuals.ss b/collects/scribblings/start/manuals.ss index fccaa4852d..d1c8862bfe 100644 --- a/collects/scribblings/start/manuals.ss +++ b/collects/scribblings/start/manuals.ss @@ -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-cistring 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-cistring 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"))))) diff --git a/collects/scribblings/start/start.scrbl b/collects/scribblings/start/start.scrbl index cc5896ffa8..57a8b5c06a 100644 --- a/collects/scribblings/start/start.scrbl +++ b/collects/scribblings/start/start.scrbl @@ -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"))])) diff --git a/collects/trace/scribblings/trace.scrbl b/collects/trace/scribblings/trace.scrbl index cf22c652a6..60e85e2ea6 100644 --- a/collects/trace/scribblings/trace.scrbl +++ b/collects/trace/scribblings/trace.scrbl @@ -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} } diff --git a/doc/release-notes/drscheme/HISTORY b/doc/release-notes/drscheme/HISTORY.txt similarity index 100% rename from doc/release-notes/drscheme/HISTORY rename to doc/release-notes/drscheme/HISTORY.txt diff --git a/doc/release-notes/mred/HISTORY b/doc/release-notes/mred/HISTORY.txt similarity index 100% rename from doc/release-notes/mred/HISTORY rename to doc/release-notes/mred/HISTORY.txt diff --git a/doc/release-notes/mzscheme/HISTORY b/doc/release-notes/mzscheme/HISTORY.txt similarity index 100% rename from doc/release-notes/mzscheme/HISTORY rename to doc/release-notes/mzscheme/HISTORY.txt diff --git a/doc/release-notes/stepper/HISTORY b/doc/release-notes/stepper/HISTORY.txt similarity index 100% rename from doc/release-notes/stepper/HISTORY rename to doc/release-notes/stepper/HISTORY.txt diff --git a/doc/release-notes/teachpack/HISTORY b/doc/release-notes/teachpack/HISTORY.txt similarity index 100% rename from doc/release-notes/teachpack/HISTORY rename to doc/release-notes/teachpack/HISTORY.txt