diff --git a/collects/scribble/manual.ss b/collects/scribble/manual.ss index fc1be7c1d9..dcb1e0018a 100644 --- a/collects/scribble/manual.ss +++ b/collects/scribble/manual.ss @@ -303,7 +303,13 @@ [s (element->string f)]) (index* (list (substring s 1 (sub1 (string-length s)))) (list f) f))) (define (exec . str) - (make-element 'tt str)) + (if (andmap string? str) + (make-element 'tt str) + (make-element #f (map (lambda (s) + (if (string? s) + (make-element 'tt (list s)) + s)) + str)))) (define (Flag . str) (make-element 'no-break (list (make-element 'tt (cons "-" (decode-content str)))))) (define (DFlag . str) diff --git a/collects/scribblings/drscheme/drscheme.scrbl b/collects/scribblings/drscheme/drscheme.scrbl index 86f1eaa5bb..cf8d2fb877 100644 --- a/collects/scribblings/drscheme/drscheme.scrbl +++ b/collects/scribblings/drscheme/drscheme.scrbl @@ -12,8 +12,8 @@ PLT Scheme programming languages. @include-section["interface-essentials.scrbl"] @include-section["languages.scrbl"] -@include-section["custom.scrbl"] @include-section["interface-ref.scrbl"] +@include-section["extending.scrbl"] @; ---------------------------------------------------------------------- diff --git a/collects/scribblings/drscheme/extending.scrbl b/collects/scribblings/drscheme/extending.scrbl new file mode 100644 index 0000000000..c3c1549b7f --- /dev/null +++ b/collects/scribblings/drscheme/extending.scrbl @@ -0,0 +1,162 @@ +#lang scribble/doc +@(require "common.ss" + (for-label compiler/cm)) + +@title[#:tag "extending-drscheme"]{Extending DrScheme} + +DrScheme supports two forms of extension to the programming + environment: + +@itemize[ + +@item{@index['("languages" "extending")]{@index['("DrScheme + Teachpacks")]{A @deftech{teachpack}}} extends the set of procedures + that are built into a language in DrScheme. For example, a + teachpack might extend the Beginning Student language with a + procedure for playing sounds. + + Teachpacks are particularly useful in a classroom setting, where an + instructor can provide a teachpack that is designed for a specific + exercise. To use the teachpack, each student must download the + teachpack file and select it through the @menuitem["Language" "Add + Teachpack..."] menu item. + + See @secref["teachpacks"] for information in creating teachpacks.} + +@item{A @deftech{tool} extends the set of utilities within the + DrScheme environment. For example, DrScheme's @onscreen{Check + Syntax} button starts a syntax-checking tool. For information on + creating @tech{tools}, see @other-manual['(lib + "scribblings/tools/tools.scrbl")].} + +] + +@; ---------------------------------------- + +@section[#:tag "teachpacks"]{Teachpacks} + +Teachpacks are designed to supplement student programs with code that +cannot be expressed in a teaching language. For +example, to enable students to play hangman, we supply a teachpack that + +@itemize{ + + @item{implements the random choosing of a word, } + + @item{maintains the state variable of how many guesses have gone wrong, and} + + @item{manages the GUI.} + +} + +All these tasks are beyond students in the third week and/or impose +memorization of currently useless knowledge on students. The essence +of the hangman game, however, is not. The use of teachpacks enables +the students to implement the interesting part of this exercise and +still be able to enjoy today's graphics without the useless +memorization. + +A single Scheme source file defines a teachpack (although the file may +access other files via @scheme[require]). The file must contain a +module (see @secref[#:doc '(lib "scribblings/guide/guide.scrbl") +"modules"]). Each exported syntax definition or value definition from +the module is provided as a new primitive form or primitive operation +to the user, respectively. + +As an example, the following teachpack provides a lazy cons +implementation. To test it, be sure to save it in a file named +@filepath{lazycons.ss}. + +@schememod[ +scheme + +(provide (rename-out :lcons lcons) lcar lcdr) + +(define-struct lcons (hd tl)) + +(define-syntax (:lcons stx) + (syntax-case stx () + [(_ hd-exp tl-exp) + (syntax (make-lcons + (delay hd-exp) + (delay tl-exp)))])) + +(define (lcar lcons) (force (lcons-hd lcons))) +(define (lcdr lcons) (force (lcons-tl lcons))) +] + +Then, in this program: + +@schemeblock[ +(define (lmap f l) + (lcons + (f (lcar l)) + (lmap f (lcdr l)))) + +(define all-nums (lcons 1 (lmap add1 all-nums))) +] + +the list @scheme[all-nums] is bound to an infinite list + of ascending numbers. + +For more examples, see the @filepath{htdp} sub-collection in the +@filepath{teachpack} collection of the PLT installation. + +@; ---------------------------------------------------------------------- + +@section{Environment Variables} + +Several environment variables can affect DrScheme's behavior: + +@itemize[ + + @item{@indexed-envvar{PLTNOTOOLS} : When this environment variable is + set, DrScheme doesn't load any tools.} + + @item{@indexed-envvar{PLTONLYTOOL} : When this environment variable + is set, DrScheme only loads the tools in the collection named + by the value of the environment variable. If the variable is + bound to a parenthesized list of collections, only the tools in + those collections are loaded (The contents of the environment + variable are @scheme[read] and expected to be a single symbol + or a list of symbols).} + + @item{@indexed-envvar{PLTDRCM} : When this environment variable is + set, DrScheme installs the compilation manager before starting + up, which means that the @filepath{.zo} files are automatically + kept up to date, as DrScheme's (or a tools) source is modified. + + If the variable is set to @litchar{trace} then the compilation + manager's output is traced, using the + @scheme[manager-trace-handler] procedure.} + + @item{@indexed-envvar{PLTDRDEBUG} : When this environment variable is + set, DrScheme starts up with errortrace enabled. If the + variable is set to @litchar{profile}, DrScheme also records + profiling information about itself.} + + @item{@indexed-envvar{PLTDRBREAK} : When this environment variable is + set, DrScheme creates a window with a break button, during + startup. Clicking the button breaks DrScheme's eventspace's + main thread. This works well in combination with + @envvar{PLTDRDEBUG} since the source locations are reported for + the breaks.} + + @item{@indexed-envvar{PLTDRTESTS} : When this environment variable is + set, DrScheme installs a special button in the button bar that + starts the test suite. (The test suite is available only in the + source distribution.)} + + @item{@indexed-envvar{PLTSTRINGCONSTANTS} : When this environment + variable is set, DrScheme prints out the string constants that + have not yet been translated. If it is set to a particular + language (corresponding to one of the files in + @filepath{string-constants} collection) it only shows the unset + string constants matching that language. + + This environment variable must be set when @filepath{.zo} files + are made. To ensure that you see its output properly, run + @exec{setup-plt} with the @Flag{c} flag, set the environment + variable, and then run @exec{setup-plt} again.} + +] diff --git a/collects/scribblings/drscheme/files.scrbl b/collects/scribblings/drscheme/files.scrbl new file mode 100644 index 0000000000..28a8f2b447 --- /dev/null +++ b/collects/scribblings/drscheme/files.scrbl @@ -0,0 +1,126 @@ +#lang scribble/doc +@(require "common.ss") + +@title[#:tag "drscheme-files"]{DrScheme Files} + +@; ---------------------------------------- + +@section[#:tag "drscheme-file-formats"]{Program Files} + +The standard @as-index{file extension} for a PLT Scheme program file +is @indexed-file{.ss}. The extensions @indexed-file{.scm} and +@indexed-file{.sch} are also popular. + +DrScheme's editor can save a program file in two different formats: + +@itemize{ + + @item{@deftech{Plain-text file format} --- All text editors can read + this format. DrScheme saves a program in plain-text format by + default, unless the program contains images or text boxes. + (Plain-text format does not preserve images or text boxes.) + + Plain-text format is platform-specific because different + platforms have different newline conventions. However, most + tools for moving files across platforms support a ``text'' + transfer mode that adjusts newlines correctly.} + + @item{@deftech{Multimedia file format} --- This format is specific to + DrScheme, and no other editor recognizes it. DrScheme saves a + program in multimedia format by default when the program + contains images, text boxes, or formatted text. + + Multimedia format is platform-independent, and it uses an ASCII + encoding (so that different ways of transferring the file are + unlikely to corrupt the file).} + +} + +@; ---------------------------------------- + +@section[#:tag "drscheme-autosave-files"]{Backup and Autosave Files} + +When you modify an existing file in DrScheme and save it, DrScheme +copies the old version of the file to a special backup file if no +backup file exists. The backup file is saved in the same directory as +the original file, and the backup file's name is generated from the +original file's name: + +@itemize{ + + @item{Under Unix and Mac OS X, a @filepath{~} is added to the end of + the file's name.} + + @item{Under Windows, the file's extension is replaced with + @filepath{.bak}.} + +} + +When a file in an active DrScheme editor is modified but not saved, +DrScheme saves the file to a special autosave file after five minutes +(in case of a power failure or catastrophic error). If the file is +later saved, or if the user exists DrScheme without saving the file, +the autosave file is removed. The autosave file is saved in the same +directory as the original file, and the autosave file's name is +generated from the original file's name: + +@itemize{ + + @item{Under Unix and Mac OS X, a @filepath{#} is added to the start + and end of the file's name, then a number is added after the + ending @filepath{#}, and then one more @filepath{#} is appended + after the number. The number is selected to make the autosave + filename unique.} + + @item{Under Windows, the file's extension is replaced with a number + to make the autosave filename unique.} + +} + +@; ---------------------------------------- + +@section{Preference Files} + +On start-up, DrScheme reads configuration information from a +preferences file. The name and location of the preferences file +depends on the platform and user: + +@margin-note{The expression @scheme[(find-system-path 'pref-file)] + returns the platform- and user-specific preference file path.} + +@itemize[ + + @item{Under Unix, preferences are stored in a + @indexed-file{.plt-scheme} subdirectory in the user's home + directory, in a file @indexed-file{plt-prefs.ss}.} + + @item{Under Windows, preferences are stored in a file + @indexed-file{plt-prefs.ss} in a sub-directory @indexed-file{PLT + Scheme} in the user's application-data folder as specified by the + Windows registry; the application-data folder is usually + @indexed-file{Application Data} in the user's profile directory, and + that directory is usually hidden in the Windows GUI.} + + @item{Under Mac OS X, preferences are stored in + @indexed-file{org.plt-scheme.prefs.ss} in the user's preferences + folder.} + +] + +A lock file is used while modifying the preferences file, and it is +created in the same directory as the preferences file. Under Windows, +the lock file is named @indexed-file{_LOCKplt-prefs.ss}; under Unix, +it is @indexed-file{.LOCK.plt-prefs.ss}; under Mac OS X, it is +@indexed-file{.LOCK.org.plt-scheme.prefs.ss}. + +If the user-specific preferences file does not exist, and the file +@indexed-file{plt-prefs.ss} in the @filepath{defaults} collection does +exist, then it is used for the initial preference settings. (See +@secref[#:doc '(lib "scribblings/reference/reference.scrbl") +"collects"] for more information about collections.) This file thus +allows site-specific configuration for preference defaults. To set up +such a configuration, start DrScheme and configure the preferences to +your liking. Then, exit DrScheme and copy your preferences file into +the @filepath{defaults} collection as +@filepath{plt-prefs.ss}. Afterward, users who have no preference +settings already will get the preference settings that you chose. diff --git a/collects/scribblings/drscheme/interface-essentials.scrbl b/collects/scribblings/drscheme/interface-essentials.scrbl index c70469a788..3b256d93ca 100644 --- a/collects/scribblings/drscheme/interface-essentials.scrbl +++ b/collects/scribblings/drscheme/interface-essentials.scrbl @@ -479,7 +479,7 @@ A program can manipulate image values in various ways, such as using the @schememodname[htdp/image] library or as an @schememodname[image-snip%] value. -@subsection{XML Boxes and Scheme Boxes} +@subsection[#:tag "xml-boxes"]{XML Boxes and Scheme Boxes} DrScheme has special support for XML concrete syntax. The @menuitem["Special" "Insert XML Box"] menu item inserts an embedded diff --git a/collects/scribblings/drscheme/interface-ref.scrbl b/collects/scribblings/drscheme/interface-ref.scrbl index 862bc23223..4a7aba8bf0 100644 --- a/collects/scribblings/drscheme/interface-ref.scrbl +++ b/collects/scribblings/drscheme/interface-ref.scrbl @@ -1,420 +1,11 @@ #lang scribble/doc -@(require "common.ss" - scribble/struct) +@(require "common.ss") -@(define (defmenuitem . s) - (let ([mi (apply onscreen s)]) - @index*[(list (string-append (element->string mi) " menu item")) - (list (elem mi " menu item"))]{@|mi| :})) +@title[#:style 'toc]{Interface Reference} -@(define lam-str "\u03BB") - -@title{Interface Reference} - -@section{Menus} - -@subsection{@onscreen{File}} - -@itemize{ - - @item{@defmenuitem{New} Creates a new DrScheme window.} - - @item{@defmenuitem{Open...} Opens a find-file dialog for choosing - a file to load into a @tech{definitions window}.} - - @item{@defmenuitem{Open Recent} Lists recently opened - files. Choosing one of them opens that file for editing.} - - @item{@defmenuitem{Install PLT File...} Opens a dialog asking for the - location of the @filepath{.plt} file (either on the local disk or - on the web) and installs the contents of the file.} - - @item{@defmenuitem{Revert} Re-loads the file that is currently in the - @tech{definitions window}. All changes since the file was last saved - will be lost.} - - @item{@defmenuitem{Save Definitions} Saves the program in the - @tech{definitions window}. If the program has never been saved - before, a save-file dialog appears.} - - @item{@defmenuitem{Save Definitions As...} Opens a save-file dialog for - choosing a destination file to save the program in the definitions - window. Subsequent saves write to the newly-selected file.} - - @item{@defmenuitem{Save Other} Contains these sub-items - @itemize{ - - @item{@defmenuitem{Save Definitions As Text...} Like @onscreen{Save - Definitions As...}, but the file is saved in plain-text format (see - @secref["drscheme-file-formats"]). Subsequent saves also write in - plain-text format.} - - @item{@defmenuitem{Save Interactions} Saves the contents of the interactions - window to a file. If the interaction constants have never been saved - before, a save-file dialog appears.} - - @item{@defmenuitem{Save Interactions As...} Opens a save-file dialog for - choosing a destination file to save the contents of the interactions - window. Subsequent saves write to the newly-selected file.} - - @item{@defmenuitem{Save Interactions As Text...} Like @onscreen{Save - Interactions As...}, but the file is saved in plain-text format (see - @secref["drscheme-file-formats"]). Subsequent saves are write in - plain-text format.} - - }} - -@item{@defmenuitem{Log Definitions and Interactions...} Starts a - running of log of the text in the interactions and definitions - windows, organized by executions. In a directory of your choosing, - DrScheme saves files with the names @filepath{01-definitions}, - @filepath{01-interactions}, @filepath{02-definitions}, - @filepath{02-interactions}, @|etc| as you interact with various - programs.} - - @item{@defmenuitem{Print Definitions...} Opens a dialog for printing - the current program in the @tech{definitions window}.} - - @item{@defmenuitem{Print Interactions...} Opens a dialog for printing the - contents of the @tech{interactions window}.} - -@item{@defmenuitem{Search in Files...} Opens a dialog where you can - specify the parameters of a multi-file search. The results of the - search are displayed in a separate window.} - - @item{@defmenuitem{Close} Closes this DrScheme window. If this window - is the only open DrScheme window, then DrScheme quits, except under - Mac OS X.} - - @item{{@onscreen{Quit} or @onscreen{Exit}} Exits DrScheme. (Under Mac - OS X, this menu item is in the Apple menu.)} - -} - -@; ---------------------------------------- - -@subsection{@onscreen{Edit}} - -All @onscreen{Edit} menu items operate on either the definitions or -interactions window, depending on the location of the selection or -blinking caret. Each window maintains its own Undo and Redo history. - -@itemize{ - - @item{@defmenuitem{Undo} Reverses an editing action. Each window - maintains a history of actions, so multiple @onscreen{Undo} - operations can reverse multiple editing actions.} - - @item{@defmenuitem{Redo} Reverses an @onscreen{Undo} action. Each - window (and boxed-subwindow) maintains its own history of - @onscreen{Undo} actions, so multiple @onscreen{Redo} operations can - reverse multiple @onscreen{Undo} actions.} - - @item{@defmenuitem{Cut} Copies the selected text to the clipboard and - deletes it from the window.} - - @item{@defmenuitem{Copy} Copies the selected text to the clipboard.} - - @item{@defmenuitem{Paste} Pastes the current clipboard contents into the - window.} - - @item{@defmenuitem{Delete} or @defmenuitem{Clear} Deletes the selected text.} - - @item{@defmenuitem{Select All} Highlights the entire text of the buffer.} - - @item{@defmenuitem{Wrap Text} Toggles between wrapped text and - unwrapped text in the window.} - - @item{@defmenuitem{Find...} Opens a search dialog or, depending on the - preferences, an interactive searching window attached to the frame.} - - @item{@defmenuitem{Find Again} Finds the next occurrence of the text - that was last searched for.} - -@item{@defmenuitem{Replace & Find Again} Replaces the selection with the - replace string (if it matches the find string) and finds the next - occurrence of the text that was last searched for.} - -@item{@defmenuitem{Keybindings} -@itemize{ - -@item{@defmenuitem{Show Active Keybindings} Shows all of the - keybindings available in the current window.} - -@item{@defmenuitem{Add User-defined Keybindings...} Choosing this menu - item opens a file dialog where you can select a file containing - Scheme-definitions of keybindings. See @secref["defining-shortcuts"] - for more information.} - -}} - - @item{@defmenuitem{Preferences...} Opens the preferences dialog. See - @secref["prefs-explanation"]. (Under Mac OS X, this menu item is in - the Apple menu.)} } - -@; ---------------------------------------- - -@subsection{@onscreen{View}} - -One each of the following show/hide pairs of menu items -appears at any time. - -@itemize{ - - @item{@defmenuitem{Show Definitions} Shows the definitions window.} - - @item{@defmenuitem{Hide Definitions} Hides the definitions window.} - - @item{@defmenuitem{Show Interactions} Shows interactions window.} - - @item{@defmenuitem{Hide Interactions} Hides interactions window.} - - @item{@defmenuitem{Show Program Contour} Shows a ``20,000 foot'' - overview window along the edge of the DrScheme - window. Each pixel in this window corresponds to a letter - in the program text.} - - @item{@defmenuitem{Hide Program Contour} Hides the contour window.} - - @item{@defmenuitem{Show Module Browser} Shows the module DAG rooted - at the currently opened file in DrScheme.} - - @item{@defmenuitem{Hide Module Browser} Hides the module browser.} - - @item{@defmenuitem{Show Toolbar} Makes the toolbar (along the top of - DrScheme's window) and the status line (along the bottom) visible.} - - @item{@defmenuitem{Hide Toolbar} Hides the toolbar (along the top of - DrScheme's window) and the status line (along the bottom).} - - @item{@defmenuitem{Show Profile} Shows the current profiling - report. This menu is useful only if you have enabled profiling in - the @onscreen{Choose Language...} dialog's @onscreen{Details} - section. Profiling does not apply to all languages.} - - @item{@defmenuitem{Hide Profile} Hides any profiling - information currently displayed in the DrScheme window.} - - @item{@defmenuitem{Show Tracing} Shows a trace of functions called since - the last time @onscreen{Run} was clicked. This menu is useful only if - you have enabled tracing in the @onscreen{Choose Language...} dialog's - @onscreen{Details} section. Profiling does not apply to all languages.} - - @item{@defmenuitem{Hide Tracing} Hides the tracing display.} - - @item{@defmenuitem{Split} Splits the current window in half to - allow for two different portions of the current window to - be visible simultaneously.} - - @item{@defmenuitem{Collapse} If the window has been split before, this - menu item becomes enabled, allowing you to collapse the split - window.} - -} - -Note: whenever a program is run, the interactions window is made - visible if it is hidden. - -@; ---------------------------------------- - -@subsection{@onscreen{Language}} - -@itemize{ - - @item{@defmenuitem{Choose Language...} Opens a dialog for selecting - the current evaluation language. Click @onscreen{Run} to make the - language active in the interactions window. See - @secref["choose-language"] for more information about the - languages.} - - - @item{@defmenuitem{Add Teachpack...} Opens a find-file dialog for - choosing a teachpack to extend the current language. Click - @onscreen{Run} to make the teachpack available in the interactions - windows. See @secref["extending-drscheme"] for information on - creating teachpacks.} - -@item{@defmenuitem{Clear All Teachpacks} Clears all of the current - teachpacks. Click @onscreen{Run} to clear the teachpack from the - interactions window.} - -} - -In addition to the above items, a menu item for each teachpack that -clears only the corresponding teachpack. - -@; ---------------------------------------- - -@subsection{@onscreen{Scheme}} - -@itemize{ - - @item{@defmenuitem{Run} Resets the interactions window and runs the - program in the definitions window.} - - @item{@defmenuitem{Break} Breaks the current evaluation.} - - @item{@defmenuitem{Kill} Terminates the current evaluation.} - -@item{@defmenuitem{Clear Error Highlight} Removes the red -background that signals the source location of an error.} - - @item{@defmenuitem{Create Executable...} Creates a separate launcher - for running your program. See @secref["executables"] for more - info.} - -@item{@defmenuitem{Module Browser...} Prompts for a file and - then opens a window showing the module import structure - for the module import DAG starting at the selected module. - - The module browser window contains a square for each - module. The squares are colored based on the number of - lines of code in the module. If a module has more lines of - code, it gets a darker color. - - In addition, for each normal import, a blue line drawn is - from the module to the importing module. Similarly, purple - lines are drawn for each for-syntax import. In the initial - module layout, modules to the left import modules to the - right, but since modules can be moved around - interactively, that property might not be preserved. - - To open the file corresponding to the module, right-click or - control-click (Mac OS X) on the box for that module.} - - @item{@defmenuitem{Reindent} Indents the selected text according to - the standard Scheme formatting conventions. (Pressing the Tab key - has the same effect.)} - - @item{@defmenuitem{Reindent All} Indents all of the text in either - the definitions or interactions window, depending on the location of - the selection or blinking caret.} - - @item{@defmenuitem{Comment Out with Semicolons} Puts @litchar{;} - characters at each of the beginning of each selected line of text.} - - @item{@defmenuitem{Comment Out with a Box} Boxes the selected - text with a comment box.} - - @item{@defmenuitem{Uncomment} Removes all @litchar{;} characters at - the start of each selected line of text or removes a comment box - around the text. Uncommenting only removes a @litchar{;} if it - appears at the start of a line and it only removes the first - @litchar{;} on each line.} - -} - -@subsection{@onscreen{Insert}} - -@itemize{ - - @item{@defmenuitem{Insert Comment Box} Inserts a box that is ignored - by DrScheme; use it to write comments for people who read your - program.} - - @item{@defmenuitem{Insert Image...} Opens a find-file dialog for - selecting an image file in GIF, BMP, XBM, XPM, PNG, or JPG - format. The image is treated as a value.} - - @item{@defmenuitem{Insert Fraction...} Opens a dialog for a - mixed-notation fraction, and inserts the given fraction into the - current editor.} - - @item{@defmenuitem{Insert Large Letters...} Opens a dialog for a line of - text, and inserts a large version of the text (using semicolons and - spaces).} - - @item{@defmenuitem{Insert @|lam-str|} Inserts the symbol @|lam-str| - (as a Unicode character) into the program. The @|lam-str| symbol is - normally bound the same as @scheme[lambda].} - - @item{@defmenuitem{Insert Java Comment Box} Inserts a box that is - ignored by DrScheme. Unlike the @onscreen{Insert Comment Box} menu - item, this is designed for the ProfessorJ language levels. See - @secref["profj"].} - - @item{@defmenuitem{Insert Java Interactions Box} Inserts a box that - will allows Java expressions and statements within Scheme - programs. The result of the box is a Scheme value corresponding to - the result(s) of the Java expressions. At this time, Scheme values - cannot enter the box. The box will accept one Java statement or - expression per line.} - - @item{@defmenuitem{Insert XML Box} Inserts an XML; see - @secref["xml-boxes"] for more information.} - - @item{@defmenuitem{Insert Scheme Box} Inserts a box to contain Scheme - code, typically used inside an XML box; see @secref["xml-boxes"].} - - @item{@defmenuitem{Insert Scheme Splice Box} Inserts a box to contain Scheme - code, typically used inside an XML box; see also @secref["xml-boxes"].} - - @item{@defmenuitem{Insert Pict Box} Creates a box for generating a - Slideshow picture. Inside the pict box, insert and arrange Scheme - boxes that produce picture values.} - -} - -@; ---------------------------------------- - -@subsection[#:tag "menu:testing"]{@onscreen{Testing}} - -This menu is visible when in a language with built-in support for testing; -presently this includes the @|HtDP| languages and the ProfessorJ languages. - -@itemize{ - @item{@defmenuitem{Enable tests} Allows tests written in the definitions - window to be evaluated when the program is run.} - @item{@defmenuitem{Disable tests} Stops tests written in the definitions - window from evaluating when the program is run; disabling tests freezes - contents of any existing test report window.} - @item{@defmenuitem{Dock report} Like the dock button on the test report - window, this causes all test report windows to merge with the appropriate - DrScheme window at the bottom of the frame.} - @item{@defmenuitem{Undock report} Like the undock button on the test report - window, this causes the test reports attached to appropriate DrScheme tabs - to become separate windows.} - } - -@; ---------------------------------------- - -@subsection{@onscreen{Windows}} - -@itemize{ - - @item{@defmenuitem{Bring Frame to Front...} Opens a window that lists - all of the opened DrScheme frames. Selecting one of them brings the - window to the front.} - - @item{@defmenuitem{Most Recent Window} Toggles between the currently - focused window and the one that most recently had the focus.} - -} - -Additionally, after the above menu items, this menu contains -an entry for each window in DrScheme. Selecting a menu item -brings the corresponding window to the front. - -@; ---------------------------------------- - -@subsection{@onscreen{Help}} - -@itemize{ - - @item{@defmenuitem{Help Desk} Opens the Help Desk. This is the clearing - house for all documentation about DrScheme and its language.} - - @item{@defmenuitem{About DrScheme...} Shows the credits for DrScheme.} - - @item{@defmenuitem{Related Web Sites} Provides links to related web sites.} - - @item{@defmenuitem{Tool Web Sites} Provides links to web sites for - installed tools.} - - @item{@defmenuitem{Interact with DrScheme in English} Changes DrScheme's - interface to use English; the menu item appears only when the - current language is not English. Additional menu items switch - DrScheme to other languages.} - -} +@local-table-of-contents[] +@include-section["menus.scrbl"] +@include-section["prefs.scrbl"] +@include-section["keybindings.scrbl"] +@include-section["files.scrbl"] diff --git a/collects/scribblings/drscheme/keybindings.scrbl b/collects/scribblings/drscheme/keybindings.scrbl new file mode 100644 index 0000000000..63d37b1f8c --- /dev/null +++ b/collects/scribblings/drscheme/keybindings.scrbl @@ -0,0 +1,197 @@ +#lang scribble/doc +@(require "common.ss" + scribble/bnf + (for-label scheme/gui/base)) + +@(define (keybinding key . desc) + (apply item @index[(list (format "~a keybinding" key)) key] " : " desc)) + +@(define-syntax-rule (def-mod-beg id) + (begin + (require (for-label mzscheme)) + (define id @scheme[#%module-begin]))) +@(def-mod-beg mz-mod-begin) + +@title{Keyboard Shortcuts} + +@index['("keybindings")]{Most} key presses simply insert a character +into the editor, such as @litchar{a}, @litchar{3}, or +@litchar{(}. Other keys and key combinations act as keyboard shortcuts +that move the blinking caret, delete a line, copy the selection, +etc. Keyboard shortcuts are usually trigger by key combinations using +the Control, Meta, or Command key. + +@margin-note{Many of the key-binding actions can also be performed +with menu items.} + +C-@nonterm{key} means press the Control key, hold it down and then +press @nonterm{key} and then release them both. For example: C-e +(Control-E) moves the blinking caret to the end of the current line. + +M-@nonterm{key} is the same as C-@nonterm{key}, except with the Meta +key. Depending on your keyboard, Meta may be called ``Left,'' +``Right,'' or have a diamond symbol, but it's usually on the bottom +row next to the space bar. M-@nonterm{key} can also be performed as a +two-character sequence: first, strike and release the Escape key, then +strike @nonterm{key}. Under Windows and Mac OS X, Meta is only +available through the Escape key. + +DEL is the Delete key. + +SPACE is the Space bar. + +On most keyboards, ``<'' and ``>'' are shifted characters. So, to +get M->, you actually have to type Meta-Shift->. That is, press and +hold down both the Meta and Shift keys, and then strike ``>''. + +Under Windows, some of these keybindings are actually standard menu +items. Those keybindings will behave according to the menus, unless +the @onscreen{Enable keybindings in menus} preference is unchecked. + +@index['("Emacs keybindings")]{If} you are most familiar with +Emacs-style key bindings, you should uncheck the @onscreen{Enable +keybindings in menus} preference. Many of the keybindings below are +inspired by Emacs.} + + +@section{Moving Around} + +@itemize[ +@keybinding["C-f"]{move forward one character} +@keybinding["C-b"]{move backward one character} +@keybinding["M-f"]{move forward one word} +@keybinding["M-b"]{move backward one word} +@keybinding["C-v"]{move forward one page} +@keybinding["M-v"]{move backward one page} +@keybinding["M-<"]{move to beginning of file} +@keybinding["M->"]{move to end of file} + +@keybinding["C-a"]{move to beginning of line (left)} +@keybinding["C-e"]{move to end of line (right)} +@keybinding["C-n"]{move to next line (down)} +@keybinding["C-p"]{move to previous line (up)} + +@keybinding["M-C-f"]{move forward one S-expression} +@keybinding["M-C-b"]{move backward one S-expression} +@keybinding["M-C-u"]{move up out of an S-expression} +@keybinding["M-C-d"]{move down into a nested S-expression} +@keybinding["M-C-SPACE"]{select forward S-expression} +@keybinding["M-C-p"]{match parentheses backward} + +@keybinding["M-C-left"]{move backwards to the nearest editor box} +@keybinding["A-C-left"]{move backwards to the nearest editor box} +@keybinding["M-C-right"]{move forward to the nearest editor box} +@keybinding["A-C-right"]{move forward to the nearest editor box} +@keybinding["M-C-up"]{move up out of an embedded editor} +@keybinding["A-C-up"]{move up out of an embedded editor} +@keybinding["M-C-down"]{move down into an embedded editor} +@keybinding["A-C-down"]{move down into an embedded editor} +] + +@section{Editing Operations} + +@itemize[ +@keybinding["C-_"]{undo} +@keybinding["C-+"]{redo} +@keybinding["C-x u"]{undo} + +@keybinding["C-d"]{delete forward one character} +@keybinding["C-h"]{delete backward one character} +@keybinding["M-d"]{delete forward one word} +@keybinding["M-DEL"]{delete backward one word} +@keybinding["C-k"]{delete forward to end of line} +@keybinding["M-C-k"]{delete forward one S-expression} + +@keybinding["M-w"]{copy selection to clipboard} +@keybinding["C-w"]{delete selection to clipboard (cut)} +@keybinding["C-y"]{paste from clipboard (yank)} + +@keybinding["C-t"]{transpose characters} +@keybinding["M-t"]{transpose words} +@keybinding["M-C-t"]{transpose sexpressions} + +@keybinding["M-C-m"]{toggle dark green marking of matching parenthesis} +@keybinding["M-C-k"]{cut complete sexpression} + +@keybinding["M-("]{wrap selection in parentheses} +@keybinding["M-["]{wrap selection in square brackets} +@keybinding["M-{"]{wrap selection in curly brackets} +@keybinding["M-S-L"]{wrap selection in @litchar["(lambda\u20()\u20"]...@litchar{)} + and put the insertion point in the arglist of the lambda} + +@keybinding["C-c C-o"]{the sexpression following the + insertion point is put in place of its containing sexpression} +@keybinding["C-c C-l"]{wraps a let around the + sexpression following the insertion point and puts a printf in at + that point (useful for debugging).} + + +@keybinding["M-o"]{toggle @as-index{overwrite mode}} +] + +@section{File Operations} + +@itemize[ +@keybinding["C-x C-s"]{save file} +@keybinding["C-x C-w"]{save file under new name} +] + +@section{Searching} + +@itemize[ +@keybinding["C-s"]{search for string forward} +@keybinding["C-r"]{search for string backward} +] + +@section{Miscellaneous} + +@itemize[ +@keybinding["F5"]{Run} +] + + +@section{Interactions} + +The @tech{interactions window} has all of the same keyboard shortcuts +as the @tech{definitions window} plus a few more: + +@itemize[ +@keybinding["M-p"]{bring the previously entered expression down to the prompt} +@keybinding["M-n"]{bring the expression after the current expression in the + expression history down to the prompt} +] + +@section[#:tag "defining-shortcuts"]{Defining Custom Shortcuts} + + The @onscreen{Add User-defined Keybindings...} menu item in the + @onscreen{Keybindings} sub-menu of @onscreen{Edit} selects a file + containing Scheme definitions of keybindings. The file must contain a + single module that uses a special keybindings language, + @schememodname[framework/keybinding-lang]. For example, a file named + @filepath{mykeys.ss} for keybindings might contain the following + code: + +@schemeblock[ +(module mykeys framework/keybinding-lang + ...) +] + +The @scheme[framework/keybinding-lang] languages provides all bindings +@schememodname[mzscheme], @schememodname[scheme/gui/base], and +@scheme[scheme/classs], except that it adjusts @|mz-mod-begin| to +introduce a @schemeidfont{keybinding} form: + +@specform[#:literals (keybindings) + (keybinding string-expr proc-expr)]{ + +Declares a keybinding, where @scheme[string-expr] must produce a +suitable first argument for @xmethod[keymap% map-function], and the +@scheme[proc-expr] must produce a suitable second argument for +@xmethod[keymap% add-function].} + +Note that @schememodname[drscheme/tool-lib] adds all of the names +defined in @other-manual['(lib "scribblings/tools/tools.scrbl")] to +your keybindings module, which helps in defining DrScheme-specific +keybindings. + + diff --git a/collects/scribblings/drscheme/languages.scrbl b/collects/scribblings/drscheme/languages.scrbl index 11cced047e..28f15562bb 100644 --- a/collects/scribblings/drscheme/languages.scrbl +++ b/collects/scribblings/drscheme/languages.scrbl @@ -32,22 +32,10 @@ without a @hash-lang[] prefix: @itemize{ - @item{The @as-index{@drlang{Standard (R5RS)} language} contains those + @item{The @as-index{@drlang{R5RS} language} contains those primitives and syntax defined in the R@superscript{5}RS Scheme standard. See the @schememodname[r5rs] library for details.} - @item{The @as-index{@drlang{PLT Textual (MzScheme)} language} starts - with the same bindings as the @exec{mzscheme} executable in - interactive mode, which means the exports of the - @schememodname[scheme/init] library. It also evaluates a program in - the same way as @scheme[load], instead of as a module.} - - @item{The @as-index{@drlang{PLT Graphical (MrEd)} language} starts - with the same bindings as the @exec{mred} executable in interactive - mode, which means the exports of the @schememodname[scheme/gui/init] - library. Like @drlang{PLT Textual (MzScheme)}, it evaluates a - program in the same way as @scheme[load], instead of as a module.} - @item{The @as-index{@defterm{PLT Pretty Big} language} provides a language roughly compatible with a language in earlier versions of DrScheme. It evaluates a program in the same way as @scheme[load], @@ -253,10 +241,10 @@ language through the detail section of language-selection dialog. @itemize{ @item{@defterm{Constructor-style output} --- See - @secref["printing:cons"].} + @secref["output-syntax"].} @item{@defterm{Quasiquote-style output} --- See - @secref["printing:quasi"].} + @secref["output-syntax"].} @item{@defterm{Rational number printing} -- In the teaching languages, all numbers that have a finite decimal expansion are @@ -372,4 +360,12 @@ Unless disabled in the language configuration window, expression-level coverage @section[#:tag "experimental-langs"]{Other Experimental Languages} -... +For information on @onscreen{Lazy Scheme}, see @other-manual['(lib "lazy/lazy.scrbl")]. + +For information on @onscreen{FrTime}, see @other-manual['(lib "frtime/frtime.scrbl")]. + +For information on @onscreen{Algol 60}, see @other-manual['(lib "algol60/algol60.scrbl")]. + +@; ---------------------------------------- + +@include-section["printing.scrbl"] diff --git a/collects/scribblings/drscheme/menus.scrbl b/collects/scribblings/drscheme/menus.scrbl new file mode 100644 index 0000000000..b1324fee08 --- /dev/null +++ b/collects/scribblings/drscheme/menus.scrbl @@ -0,0 +1,418 @@ +#lang scribble/doc +@(require "common.ss" + scribble/struct) + +@(define (defmenuitem . s) + (let ([mi (apply onscreen s)]) + @index*[(list (string-append (element->string mi) " menu item")) + (list (elem mi " menu item"))]{@|mi| :})) + +@(define lam-str "\u03BB") + +@title{Menus} + +@section{@onscreen{File}} + +@itemize{ + + @item{@defmenuitem{New} Creates a new DrScheme window.} + + @item{@defmenuitem{Open...} Opens a find-file dialog for choosing + a file to load into a @tech{definitions window}.} + + @item{@defmenuitem{Open Recent} Lists recently opened + files. Choosing one of them opens that file for editing.} + + @item{@defmenuitem{Install PLT File...} Opens a dialog asking for the + location of the @filepath{.plt} file (either on the local disk or + on the web) and installs the contents of the file.} + + @item{@defmenuitem{Revert} Re-loads the file that is currently in the + @tech{definitions window}. All changes since the file was last saved + will be lost.} + + @item{@defmenuitem{Save Definitions} Saves the program in the + @tech{definitions window}. If the program has never been saved + before, a save-file dialog appears.} + + @item{@defmenuitem{Save Definitions As...} Opens a save-file dialog for + choosing a destination file to save the program in the definitions + window. Subsequent saves write to the newly-selected file.} + + @item{@defmenuitem{Save Other} Contains these sub-items + @itemize{ + + @item{@defmenuitem{Save Definitions As Text...} Like @onscreen{Save + Definitions As...}, but the file is saved in plain-text format (see + @secref["drscheme-file-formats"]). Subsequent saves also write in + plain-text format.} + + @item{@defmenuitem{Save Interactions} Saves the contents of the interactions + window to a file. If the interaction constants have never been saved + before, a save-file dialog appears.} + + @item{@defmenuitem{Save Interactions As...} Opens a save-file dialog for + choosing a destination file to save the contents of the interactions + window. Subsequent saves write to the newly-selected file.} + + @item{@defmenuitem{Save Interactions As Text...} Like @onscreen{Save + Interactions As...}, but the file is saved in plain-text format (see + @secref["drscheme-file-formats"]). Subsequent saves are write in + plain-text format.} + + }} + +@item{@defmenuitem{Log Definitions and Interactions...} Starts a + running of log of the text in the interactions and definitions + windows, organized by executions. In a directory of your choosing, + DrScheme saves files with the names @filepath{01-definitions}, + @filepath{01-interactions}, @filepath{02-definitions}, + @filepath{02-interactions}, @|etc| as you interact with various + programs.} + + @item{@defmenuitem{Print Definitions...} Opens a dialog for printing + the current program in the @tech{definitions window}.} + + @item{@defmenuitem{Print Interactions...} Opens a dialog for printing the + contents of the @tech{interactions window}.} + +@item{@defmenuitem{Search in Files...} Opens a dialog where you can + specify the parameters of a multi-file search. The results of the + search are displayed in a separate window.} + + @item{@defmenuitem{Close} Closes this DrScheme window. If this window + is the only open DrScheme window, then DrScheme quits, except under + Mac OS X.} + + @item{{@onscreen{Quit} or @onscreen{Exit}} Exits DrScheme. (Under Mac + OS X, this menu item is in the Apple menu.)} + +} + +@; ---------------------------------------- + +@section{@onscreen{Edit}} + +All @onscreen{Edit} menu items operate on either the definitions or +interactions window, depending on the location of the selection or +blinking caret. Each window maintains its own Undo and Redo history. + +@itemize{ + + @item{@defmenuitem{Undo} Reverses an editing action. Each window + maintains a history of actions, so multiple @onscreen{Undo} + operations can reverse multiple editing actions.} + + @item{@defmenuitem{Redo} Reverses an @onscreen{Undo} action. Each + window (and boxed-subwindow) maintains its own history of + @onscreen{Undo} actions, so multiple @onscreen{Redo} operations can + reverse multiple @onscreen{Undo} actions.} + + @item{@defmenuitem{Cut} Copies the selected text to the clipboard and + deletes it from the window.} + + @item{@defmenuitem{Copy} Copies the selected text to the clipboard.} + + @item{@defmenuitem{Paste} Pastes the current clipboard contents into the + window.} + + @item{@defmenuitem{Delete} or @defmenuitem{Clear} Deletes the selected text.} + + @item{@defmenuitem{Select All} Highlights the entire text of the buffer.} + + @item{@defmenuitem{Wrap Text} Toggles between wrapped text and + unwrapped text in the window.} + + @item{@defmenuitem{Find...} Opens a search dialog or, depending on the + preferences, an interactive searching window attached to the frame.} + + @item{@defmenuitem{Find Again} Finds the next occurrence of the text + that was last searched for.} + +@item{@defmenuitem{Replace & Find Again} Replaces the selection with the + replace string (if it matches the find string) and finds the next + occurrence of the text that was last searched for.} + +@item{@defmenuitem{Keybindings} +@itemize{ + +@item{@defmenuitem{Show Active Keybindings} Shows all of the + keybindings available in the current window.} + +@item{@defmenuitem{Add User-defined Keybindings...} Choosing this menu + item opens a file dialog where you can select a file containing + Scheme-definitions of keybindings. See @secref["defining-shortcuts"] + for more information.} + +}} + + @item{@defmenuitem{Preferences...} Opens the preferences dialog. See + @secref["prefs-explanation"]. (Under Mac OS X, this menu item is in + the Apple menu.)} } + +@; ---------------------------------------- + +@section{@onscreen{View}} + +One each of the following show/hide pairs of menu items +appears at any time. + +@itemize{ + + @item{@defmenuitem{Show Definitions} Shows the definitions window.} + + @item{@defmenuitem{Hide Definitions} Hides the definitions window.} + + @item{@defmenuitem{Show Interactions} Shows interactions window.} + + @item{@defmenuitem{Hide Interactions} Hides interactions window.} + + @item{@defmenuitem{Show Program Contour} Shows a ``20,000 foot'' + overview window along the edge of the DrScheme + window. Each pixel in this window corresponds to a letter + in the program text.} + + @item{@defmenuitem{Hide Program Contour} Hides the contour window.} + + @item{@defmenuitem{Show Module Browser} Shows the module DAG rooted + at the currently opened file in DrScheme.} + + @item{@defmenuitem{Hide Module Browser} Hides the module browser.} + + @item{@defmenuitem{Show Toolbar} Makes the toolbar (along the top of + DrScheme's window) and the status line (along the bottom) visible.} + + @item{@defmenuitem{Hide Toolbar} Hides the toolbar (along the top of + DrScheme's window) and the status line (along the bottom).} + + @item{@defmenuitem{Show Profile} Shows the current profiling + report. This menu is useful only if you have enabled profiling in + the @onscreen{Choose Language...} dialog's @onscreen{Details} + section. Profiling does not apply to all languages.} + + @item{@defmenuitem{Hide Profile} Hides any profiling + information currently displayed in the DrScheme window.} + + @item{@defmenuitem{Show Tracing} Shows a trace of functions called since + the last time @onscreen{Run} was clicked. This menu is useful only if + you have enabled tracing in the @onscreen{Choose Language...} dialog's + @onscreen{Details} section. Profiling does not apply to all languages.} + + @item{@defmenuitem{Hide Tracing} Hides the tracing display.} + + @item{@defmenuitem{Split} Splits the current window in half to + allow for two different portions of the current window to + be visible simultaneously.} + + @item{@defmenuitem{Collapse} If the window has been split before, this + menu item becomes enabled, allowing you to collapse the split + window.} + +} + +Note: whenever a program is run, the interactions window is made + visible if it is hidden. + +@; ---------------------------------------- + +@section{@onscreen{Language}} + +@itemize{ + + @item{@defmenuitem{Choose Language...} Opens a dialog for selecting + the current evaluation language. Click @onscreen{Run} to make the + language active in the interactions window. See + @secref["choose-language"] for more information about the + languages.} + + + @item{@defmenuitem{Add Teachpack...} Opens a find-file dialog for + choosing a teachpack to extend the current language. Click + @onscreen{Run} to make the teachpack available in the interactions + windows. See @secref["extending-drscheme"] for information on + creating teachpacks.} + +@item{@defmenuitem{Clear All Teachpacks} Clears all of the current + teachpacks. Click @onscreen{Run} to clear the teachpack from the + interactions window.} + +} + +In addition to the above items, a menu item for each teachpack that +clears only the corresponding teachpack. + +@; ---------------------------------------- + +@section{@onscreen{Scheme}} + +@itemize{ + + @item{@defmenuitem{Run} Resets the interactions window and runs the + program in the definitions window.} + + @item{@defmenuitem{Break} Breaks the current evaluation.} + + @item{@defmenuitem{Kill} Terminates the current evaluation.} + +@item{@defmenuitem{Clear Error Highlight} Removes the red +background that signals the source location of an error.} + + @item{@defmenuitem{Create Executable...} Creates a separate launcher + for running your program. See @secref["create-exe"] for more + info.} + +@item{@defmenuitem{Module Browser...} Prompts for a file and + then opens a window showing the module import structure + for the module import DAG starting at the selected module. + + The module browser window contains a square for each + module. The squares are colored based on the number of + lines of code in the module. If a module has more lines of + code, it gets a darker color. + + In addition, for each normal import, a blue line drawn is + from the module to the importing module. Similarly, purple + lines are drawn for each for-syntax import. In the initial + module layout, modules to the left import modules to the + right, but since modules can be moved around + interactively, that property might not be preserved. + + To open the file corresponding to the module, right-click or + control-click (Mac OS X) on the box for that module.} + + @item{@defmenuitem{Reindent} Indents the selected text according to + the standard Scheme formatting conventions. (Pressing the Tab key + has the same effect.)} + + @item{@defmenuitem{Reindent All} Indents all of the text in either + the definitions or interactions window, depending on the location of + the selection or blinking caret.} + + @item{@defmenuitem{Comment Out with Semicolons} Puts @litchar{;} + characters at each of the beginning of each selected line of text.} + + @item{@defmenuitem{Comment Out with a Box} Boxes the selected + text with a comment box.} + + @item{@defmenuitem{Uncomment} Removes all @litchar{;} characters at + the start of each selected line of text or removes a comment box + around the text. Uncommenting only removes a @litchar{;} if it + appears at the start of a line and it only removes the first + @litchar{;} on each line.} + +} + +@section{@onscreen{Insert}} + +@itemize{ + + @item{@defmenuitem{Insert Comment Box} Inserts a box that is ignored + by DrScheme; use it to write comments for people who read your + program.} + + @item{@defmenuitem{Insert Image...} Opens a find-file dialog for + selecting an image file in GIF, BMP, XBM, XPM, PNG, or JPG + format. The image is treated as a value.} + + @item{@defmenuitem{Insert Fraction...} Opens a dialog for a + mixed-notation fraction, and inserts the given fraction into the + current editor.} + + @item{@defmenuitem{Insert Large Letters...} Opens a dialog for a line of + text, and inserts a large version of the text (using semicolons and + spaces).} + + @item{@defmenuitem{Insert @|lam-str|} Inserts the symbol @|lam-str| + (as a Unicode character) into the program. The @|lam-str| symbol is + normally bound the same as @scheme[lambda].} + + @item{@defmenuitem{Insert Java Comment Box} Inserts a box that is + ignored by DrScheme. Unlike the @onscreen{Insert Comment Box} menu + item, this is designed for the ProfessorJ language levels. See + @secref["profj"].} + + @item{@defmenuitem{Insert Java Interactions Box} Inserts a box that + will allows Java expressions and statements within Scheme + programs. The result of the box is a Scheme value corresponding to + the result(s) of the Java expressions. At this time, Scheme values + cannot enter the box. The box will accept one Java statement or + expression per line.} + + @item{@defmenuitem{Insert XML Box} Inserts an XML; see + @secref["xml-boxes"] for more information.} + + @item{@defmenuitem{Insert Scheme Box} Inserts a box to contain Scheme + code, typically used inside an XML box; see @secref["xml-boxes"].} + + @item{@defmenuitem{Insert Scheme Splice Box} Inserts a box to contain Scheme + code, typically used inside an XML box; see also @secref["xml-boxes"].} + + @item{@defmenuitem{Insert Pict Box} Creates a box for generating a + Slideshow picture. Inside the pict box, insert and arrange Scheme + boxes that produce picture values.} + +} + +@; ---------------------------------------- + +@section[#:tag "menu:testing"]{@onscreen{Testing}} + +This menu is visible when in a language with built-in support for testing; +presently this includes the @|HtDP| languages and the ProfessorJ languages. + +@itemize{ + @item{@defmenuitem{Enable tests} Allows tests written in the definitions + window to be evaluated when the program is run.} + @item{@defmenuitem{Disable tests} Stops tests written in the definitions + window from evaluating when the program is run; disabling tests freezes + contents of any existing test report window.} + @item{@defmenuitem{Dock report} Like the dock button on the test report + window, this causes all test report windows to merge with the appropriate + DrScheme window at the bottom of the frame.} + @item{@defmenuitem{Undock report} Like the undock button on the test report + window, this causes the test reports attached to appropriate DrScheme tabs + to become separate windows.} + } + +@; ---------------------------------------- + +@section{@onscreen{Windows}} + +@itemize{ + + @item{@defmenuitem{Bring Frame to Front...} Opens a window that lists + all of the opened DrScheme frames. Selecting one of them brings the + window to the front.} + + @item{@defmenuitem{Most Recent Window} Toggles between the currently + focused window and the one that most recently had the focus.} + +} + +Additionally, after the above menu items, this menu contains +an entry for each window in DrScheme. Selecting a menu item +brings the corresponding window to the front. + +@; ---------------------------------------- + +@section{@onscreen{Help}} + +@itemize{ + + @item{@defmenuitem{Help Desk} Opens the Help Desk. This is the clearing + house for all documentation about DrScheme and its language.} + + @item{@defmenuitem{About DrScheme...} Shows the credits for DrScheme.} + + @item{@defmenuitem{Related Web Sites} Provides links to related web sites.} + + @item{@defmenuitem{Tool Web Sites} Provides links to web sites for + installed tools.} + + @item{@defmenuitem{Interact with DrScheme in English} Changes DrScheme's + interface to use English; the menu item appears only when the + current language is not English. Additional menu items switch + DrScheme to other languages.} + +} + diff --git a/collects/scribblings/drscheme/prefs.scrbl b/collects/scribblings/drscheme/prefs.scrbl new file mode 100644 index 0000000000..e3453cab99 --- /dev/null +++ b/collects/scribblings/drscheme/prefs.scrbl @@ -0,0 +1,195 @@ +#lang scribble/doc +@(require "common.ss" + scribble/bnf + scribble/struct) + +@(define (PrefItem . s) (apply onscreen s)) + +@title[#:tag "prefs-explanation"]{Preferences} + +The preferences dialog consists of several panels. + +@section{@onscreen{Font}} + + This panel controls the main font used by DrScheme. + +@section{@onscreen{Colors}} + + The @onscreen{Colors} panel has several sub-panels that let you + configure the colors that DrScheme uses for the editor background, + for highlighting matching parentheses, for the online coloring for + Scheme and Java modes, for @onscreen{Check Syntax}, and for the + colors of the text in the @tech{interactions window}. + + It also has two buttons, @onscreen{White on Black} and + @onscreen{Black on White}, which set a number of defaults for the + color preferences and change a few other aspects of DrScheme's + behavior to make DrScheme's colors look nicer for those two modes. + +@section{@onscreen{Editing}} + + The @onscreen{Editing} panel consists of several sub-panels: + + @itemize{ + + @item{@onscreen{Indenting} + + This panel controls which keywords DrScheme recognizes for + indenting, and how each keyword is treated.} + + @item{@onscreen{Square bracket} + + This panel controls which keywords DrScheme uses to determine + when to rewrite @litchar["["] to @litchar["("]. For + @scheme[cond]-like keywords, the number in parenthesis indicates + how many sub-expressions are skipped before square brackets are + started. + + See @secref["editor"] for details on how the entries in the + columns behave.} + + @item{@onscreen{General} + + @itemize{ + + @item{@PrefItem{Number of recent items} --- controls the + length of the @onscreen{Open Recent} menu (in the @onscreen{File} + menu).} + + @item{@PrefItem{Auto-save files} --- If checked, the editor + generates autosave files (see @secref["drscheme-autosave-files"]) + for files that have not been saved after five minutes.} + + @item{@PrefItem{Backup files} --- If checked, when saving a file for + the first time in each editing session, the original copy of the + file is copied to a backup file in the same directory. The backup + files have the same name as the original, except that they end in + either @indexed-file{.bak} or @indexed-file{~}.} + + @item{@PrefItem{Map delete to backspace} --- If checked, the editor + treats the Delete key like the Backspace key.} + + @item{@PrefItem{Show status-line} --- If checked, DrScheme shows a + status line at the bottom of each window.} + + @item{@PrefItem{Count column numbers from one} --- If checked, the + status line's column counter counts from one. Otherwise, it counts + from zero.} + + @item{@PrefItem{Display line numbers in buffer; not character + offsets} --- If checked, the status line shows a + @nonterm{line}:@nonterm{column} display for the current selection + rather than the character offset into the text.} + + @item{@PrefItem{Wrap words in editor buffers} --- If checked, + DrScheme editors auto-wrap text lines by default. Changing this + preference affects new windows only.} + + @item{@PrefItem{Use separate dialog for searching} --- If checked, + then selecting the @onscreen{Find} menu item opens a separate + dialog for searching and replacing. Otherwise, selecting + @onscreen{Find} opens an interactive search-and-replace panel at + the bottom of a DrScheme window.} + + @item{@PrefItem{Reuse existing frames when opening new files} --- + If checked, new files are opened in the same DrScheme window, + rather than creating a new DrScheme window for each new file.} + + @item{@PrefItem{Enable keybindings in menus} --- If checked, some + DrScheme menu items have keybindings. Otherwise, no menu items + have key bindings. This preference is designed for people who are + comfortable editing in Emacs and find the standard menu + keybindings interfere with the Emacs keybindings.} + + @item{@PrefItem{Color syntax interactively} --- If checked, DrScheme + colors your syntax as you type.} + + @item{@PrefItem{Automatically print to PostScript file} --- If + checked, printing will automatically save PostScript files. If + not, printing will use the standard printing mechanisms for your + computer.} + + @item{@PrefItem{Open files in separate tabs (not separate windows)} + -- If checked, DrScheme will use tabs in the front-most window to + open new files, rather than creating new windows for new files.} + + @item{@PrefItem{Automatically open interactions window when running + a program} -- If checked, DrScheme shows the interactions window + (if it is hidden) when a program is run.} + +@item{@PrefItem{Put the interactions window beside the definitions + window} -- If checked, DrScheme puts the interactions window to the + right of the definitions window. By default, the interactions + window is below the definitions window.} + + }} + + @item{@onscreen{Scheme} + + @itemize{ + + @item{@PrefItem{Highlight between matching parens} --- If checked, the + editor marks the region between matching parenthesis with a gray + background (in color) or a stipple pattern (in monochrome) when + the blinking caret is next to a parenthesis.} + + @item{@PrefItem{Correct parens} --- If checked, the editor + automatically converts a typed @litchar[")"] to @litchar["]"] to + match @litchar["["], or it converts a typed @litchar["]"] to + @litchar[")"] to match @litchar["("]. Also, the editor changes + typed @litchar["["] to match the context (as explained in + @secref["editor"]).} + + @item{@PrefItem{Flash paren match} --- If checked, typing a closing + parenthesis, square bracket, or quotation mark flashes the + matching open parenthesis/bracket/quote.} + + }} + +} + +@section{@onscreen{Warnings}} + + @itemize{ + + @item{@PrefItem{Ask before changing save format} --- If checked, + DrScheme consults the user before saving a file in non-text format + (see @secref["drscheme-file-formats"]).} + + @item{@PrefItem{Verify exit} --- If checked, DrScheme consults the + user before exiting.} + + @item{@PrefItem{Only warn once when executions and interactions are + not synchronized} --- If checked, DrScheme warns the user on the + first interaction after the definitions window, language, or + teachpack is changed without a corresponding click on + @onscreen{Run}. Otherwise, the warning appears on every + interaction.} + + @item{@PrefItem{Ask about clearing test coverage} --- If checked, + when test coverage annotations are displayed DrScheme prompts + about removing them. This setting only applies to the PLT + languages. DrScheme never asks in the teaching languages.} + + @item{@PrefItem{Check for newer PLT Scheme versions} --- If + checked, DrScheme periodically polls a server to determine + whether a newer version of DrScheme is available.} + + } + +@section{@onscreen{Profiling}} + + This preference panel configures the profiling report. The band of + color shows the range of colors that profiled functions take + on. Colors near the right are used for code that is not invoked + often and colors on the right are used for code that is invoked + often. + + If you are interested in more detail at the low end, choose the + @onscreen{Square root} check box. If you are interested in more + detail at the upper end, choose the @onscreen{Square} check box. + +@section{@onscreen{Browser}} + + This preferences panel allows you to configure your HTTP + proxy. Contact your system administrator for details. diff --git a/collects/scribblings/drscheme/custom.scrbl b/collects/scribblings/drscheme/printing.scrbl similarity index 85% rename from collects/scribblings/drscheme/custom.scrbl rename to collects/scribblings/drscheme/printing.scrbl index 435b9dad36..4d24235a7d 100644 --- a/collects/scribblings/drscheme/custom.scrbl +++ b/collects/scribblings/drscheme/printing.scrbl @@ -25,21 +25,7 @@ row)) rows)))) -@title[#:tag "custom" #:style 'toc]{Customizing Language Details} - -Different languages supported by DrScheme offer different possible -customizations through the @onscreen{Show Details} button in the -dialog opened by @menuitem["Language" "Choose Language..."]. - -This chapter scribes some of the most common customizations that are -available, though the actual set available depends on each language, -which is in turn extensible through plug-ins. - -@local-table-of-contents[] - -@; ---------------------------------------- - -@section[#:tag "output-syntax"]{Output Syntax} +@title[#:tag "output-syntax"]{Output Printing Styles} @section-index["printing format"] diff --git a/collects/scribblings/mzc/make.scrbl b/collects/scribblings/mzc/make.scrbl index 5d33a88586..4e6ebf9058 100644 --- a/collects/scribblings/mzc/make.scrbl +++ b/collects/scribblings/mzc/make.scrbl @@ -234,7 +234,7 @@ A parameter for a procedure of one argument that is called whenever a compilation starts. The argument to the procedure is the file's path.} -@defparam[manager-compile-trace-handler notify (string? . -> . any)]{ +@defparam[manager-trace-handler notify (string? . -> . any)]{ A parameter for a procedure of one argument that is called to report compilation-manager actions, such as checking a file. The argument to