diff --git a/collects/tests/info.ss b/collects/tests/info.ss index f322e1780b..538218d19f 100644 --- a/collects/tests/info.ss +++ b/collects/tests/info.ss @@ -26,6 +26,7 @@ "syntax-color" "typed-scheme" "units" + "unstable" "xml" "html" "web-server")) diff --git a/collects/unstable/scribblings/gui.scrbl b/collects/unstable/scribblings/gui.scrbl new file mode 100644 index 0000000000..aaa4d74da7 --- /dev/null +++ b/collects/unstable/scribblings/gui.scrbl @@ -0,0 +1,6 @@ +#lang scribble/doc +@(require scribble/base + scribble/manual + (for-label scribble/base)) + +@title[#:tag "unstable-gui"]{GUI libraries} diff --git a/collects/unstable/scribblings/unstable.scrbl b/collects/unstable/scribblings/unstable.scrbl index 9b1978d9cc..96fd95e919 100644 --- a/collects/unstable/scribblings/unstable.scrbl +++ b/collects/unstable/scribblings/unstable.scrbl @@ -1,21 +1,102 @@ #lang scribble/doc @(require scribble/base - scribble/manual) + scribble/manual + (for-syntax scheme/base scheme/path) + (for-label scribble/base)) @title[#:tag "unstable"]{Unstable} @defmodule[unstable] -This manual documents some of the libraries available in the @schememodname[unstable] collection. +This manual documents some of the libraries available in the +@schememodname[unstable] collection. The name @schememodname[unstable] is intended as a warning that the @bold{interfaces} in particular are unstable. Developers of planet packages and external projects should avoid using modules in the unstable collection. Contracts may change, names may change or disappear, even entire modules may move or disappear without warning to the outside world. +Developers of unstable libraries must follow the guidelines in +@secref{guidelines}. + @local-table-of-contents[] +@;{--------} + +@section[#:tag "guidelines"]{Guidelines for developing @schememodname[unstable] libraries} + +Any collection developer may add modules to the +@schememodname[unstable] collection. + +Every module needs an owner to be responsible for it. + +@itemize[ + +@item{If you add a module, you are its owner. Add a comment with your +name at the top of the module.} + +@item{If you add code to someone else's module, tag your additions +with your name. The module's owner may ask you to move your code to a +separate module if they don't wish to accept responsibility for it.} +] + +When changing a library, check all uses of the library in the +collections tree and update them if necessary. Notify users of major +changes. + +Place new modules according to the following rules. (These rules are +necessary for maintaining PLT's separate text, gui, and drscheme +distributions.) + +@itemize[ + +@item{Non-GUI modules go under @tt{unstable} (or subcollections +thereof). Put the documentation in @tt{unstable/scribblings} and +include with @scheme[include-section] from +@tt{unstable/scribblings/unstable.scrbl}.} + +@item{GUI modules go under @tt{unstable/gui}. Put the documentation +in @tt{unstable/scribblings/gui} and include them with +@scheme[include-section] from @tt{unstable/scribblings/gui.scrbl}.} + +@item{Do not add modules depending on DrScheme to the +@schememodname[unstable] collection.} + +@item{Put tests in @tt{tests/unstable}.} +] + +Keep documentation and tests up to date. + + +@;{--------} + +@;{ + Add new documentation links to the list immediately below. +} + @include-section["bytes.scrbl"] @include-section["contract.scrbl"] @include-section["exn.scrbl"] @include-section["list.scrbl"] @include-section["net.scrbl"] @include-section["path.scrbl"] -@include-section["string.scrbl"] \ No newline at end of file +@include-section["string.scrbl"] + +@;{--------} + +@;{ + Include the "Unstable GUI libraries docs" if it is part of + the current distribution. +} + +@(begin + ;; Include gui.scrbl if present. + (define-for-syntax here + (build-path (collection-path "unstable") "scribblings")) + (define-for-syntax gui-file + "gui.scrbl") + (define-syntax (if-gui-present stx) + (syntax-case stx () + [(_ then else) + (if (file-exists? (build-path here gui-file)) + #'then + #'else)]))) + +@if-gui-present[(include-section "gui.scrbl") (begin)]