From 987b9e76814a873b9034162e44d15267c3bf6c9a Mon Sep 17 00:00:00 2001 From: Matthew Flatt Date: Mon, 28 Jan 2008 19:40:52 +0000 Subject: [PATCH] scribbled dynext (from Will Farr) svn: r8450 --- collects/dynext/doc.txt | 212 ------------------- collects/dynext/info.ss | 4 +- collects/scribblings/reference/startup.scrbl | 11 +- collects/scribblings/scribble/how-to.scrbl | 4 +- collects/scribblings/scribble/style.scrbl | 4 + 5 files changed, 15 insertions(+), 220 deletions(-) delete mode 100644 collects/dynext/doc.txt diff --git a/collects/dynext/doc.txt b/collects/dynext/doc.txt deleted file mode 100644 index 4d13f6e702..0000000000 --- a/collects/dynext/doc.txt +++ /dev/null @@ -1,212 +0,0 @@ - -The _dynext_ collection provides three libraries --- compile.ss, -link.ss, and file.ss --- for communicating with a platform-specific C -compiler and linker. - -_compile.ss_ ------------- - -> (compile-extension quiet? input-file output-file includes) - quiet? - Boolean indicating whether command should be echoed to stdout - input-file - A C source path/string - output-file - A compiled object path/string - includes - A list of include directory paths/strings; MzScheme's - include is added automatically. - -Compilation is controlled by a number of parameters for Windows -and Unix: - -> current-extension-compiler - compiler executable path/string or - #f. The default is set by searching for an executable using the - PATH environment variable, or using the CC or - MZSCHEME_DYNEXT_COMPILER environment variable if either is defined - (and the latter takes precedence). Under windows, the search looks - for cl.exe, then gcc.exe, then bcc32.exe (Borland). Under Unix, it - looks for gcc, then cc. #f indicates that no compiler could be - found. - -> current-extension-compiler-flags - list of paths/strings and thunks - (see `expand-for-compile-variant' below) for strings passed to the - compiler as flags. Under Windows, the default is (list "/c" "/O2" - "/MT" 3m-flag-thunk) for cl.exe and (list "-c" "-O2" "-fPIC" - 3m-flag-thunk) for gcc.exe and bcc32.exe, where 3m-flag-thunk - returns (list "-DMZ_PRECISE_GC") for the '3m variant and null for - the 'cgc variant; under Unix, the default is usually (list "-c" - "-O2" "-fPIC" 3m-flag-thunk). If the CFLAGS or - MZSCHEME_DYNEXT_COMPILER_FLAGS environment variable is defined - (the latter takes precedence), then its value is parsed as a list - of strings that is appended before the defaults. - -> current-make-compile-include-strings - procedure that takes an - include directory path/string and returns a list of strings for - the command line. Windows: "dir" -> (list "/Idir") for cl.exe, - (list "-Idir") for gcc.exe and bcc32.exe; Unix: "dir" -> (list - "-Idir"). If the CFLAGS environment variable is defined, then its - value is parsed as a list of flags that is appended before the - defaults. - -> current-make-compile-input-strings - procedure that takes an - input file path/string and returns a list of strings for the - command line. The default is `list'. - -> current-make-compile-output-strings - procedure that takes an - output file path/string and returns a list of strings for the - command line. Windows: "file" -> (list "/Fofile") for cl.exe, - (list "-o" "file") for gcc.exe and bcc32.exe; Unix: "file" -> - (list "-o" "file"). - -> current-extension-preprocess-flags - list of paths/strings and thunks - (see `expand-for-compile-variant' below) for strings passed to the - compiler as flags to pre-process instead of compile; use these - flags for preprocessing instead of `current-extension-compiler-flags'. - The defaults are similar to `current-extension-compiler-flags', but - with "/E" (Windows cl.exe) or "-E" and without non-"-D" flags. - -> compile-variant - a symbol, either 'normal, 'cgc, or '3m, that indicates - the target for compilation, where 'normal is an alias for the result - of `(system-type 'gc)' - -Helper functions: - -> (use-standard-compiler name) sets the above parameters for a - particular known compiler. The acceptable names are - platforms-specific: - Unix: 'cc or 'gcc - Windows: 'gcc, 'msvc, or 'borland - MacOS: 'cw - -> (get-standard-compilers) returns a list of standard compiler - names for the current platform. - -> (expand-for-compile-variant l) takes a list of paths/strings and - thunks and returns a list of strings. Each thunk in the input list - is applied to get a list of strings that is inlined in the - corresponding position in the output list. This expansion enables - occasional parameterization of flag lists, etc., depending on the - current compile variant. - -Under MacOS, none of these options are used. The compiler always -uses CodeWarrior if it can be found and the compilation options -cannot be changed. - -The unit form _dynext:compile@_ from _compile-unit.ss_ requires no -imports and exports _dynext:compile^_ from _compile-sig.ss_. - -_link.ss_ ---------- - -> (link-extension quiet? input-files output-file) - quiet? - Boolean indicating whether command should be echoed to stdout - input-files - A list of compiled object filename paths/strings - output-file - An extension filename path/string - - For Windows, a special linking sequence is initiated if the - linker's name is ld.exe (for gcc). - -Linking parameters: - -> current-extension-linker - linker executable path/string or #f. - The default is set by searching for an executable using the PATH - environment variable, or by using the LD or - MZSCHEME_DYNEXT_LINKER environment variable if it is defined (and - the latter takes precedence). Under Windows, it looks for cl.exe, - then ld.exe (gcc), then ilink32.exe (Borland). Under Cygwin, Solaris, - FreeBSD 2.x, or HP/UX, it looks for ld. Under other Unix variants, it - looks for cc. #f indicates that no linker could be found. - -> current-extension-linker-flags - list of paths/strings and thunks - (see `expand-for-link-variant' below). Under Windows, default is - (list "/LD") for cl.exe, (list "--dll") for ld.exe, and (list - "/Tpd" "/c") for ilink32.exe. Under Unix, the default varies - greatly among platforms. If the LDFLAGS or - MZSCHEME_DYNEXT_LINKER_FLAGS (the latter takes precedence) - environment variable is defined, then its value is parsed as a - list of strings that is appended before the defaults. - -> current-make-link-input-strings - procedure that takes an - input file path/string and returns a list of strings for the - command line. The default is `list'. - -> current-make-link-output-strings - procedure that takes an output - file path/string and returns a list of strings for the command - line. Windows: "file" -> (list "/Fefile") for cl.exe, something - like (list "-e" "_dll_entry@12" "-o" "file") for ld.exe, - something complex for ilink32.exe; Unix: "file" -> (list "-o" - "file") - -> current-standard-link-libraries - a list of paths/strings and thunks - (see `expand-for-link-variant' below) for file paths to be linked - with all supplied files. For most platforms, the default is - (list (build-path (collection-path "mzscheme" "lib") - (system-library-subpath) - mzdyn-thunk)) - where mzdyn-thunk produces (list "mzdyn.o") for the 'cgc - variant and (list "mzdyn3m.o") for the '3m variant (also see - `current-use-mzdyn'). - -> current-use-mzdyn - whether the default standard link libraries - include the mzdyn library. Defaults to #t. - -> link-variant - a symbol, either 'normal, 'cgc, or '3m, that - indicates the target for linking, where 'normal is an alias - for the result of `(system-type 'gc)' - -Helper functions: - -> (use-standard-linker name) sets the above parameters for a - particular known linker. The acceptable names are - platforms-specific, the same as for use-standard-compiler. - -> (expand-for-link-variant l) is the same as - `expand-for-compile-variant' (see above). - -Under MacOS, none of these options are used. The linker always uses -CodeWarrior if it can be found and the linking options cannot be -changed. - -The unit form _dynext:link@_ from _link-unit.ss_ requires no -imports and exports _dynext:link^_ from _link-sig.ss_. - -_file.ss_ ---------- - -> (append-zo-suffix s) - appends the .zo file suffix to the - path/string s, returning a path. The existing suffix, if any, is - perserved and converted as with `path-add-suffix'. - -> (append-object-suffix s) - appends the platform-standard compiled - object file suffix to the path/string s, returning a path. - -> (append-c-suffix s) - appends the platform-standard C source - file suffix to the path/string s, returning a path. - -> (append-constant-pool-suffix s) - appends the constant pool file - suffix (.kp) to the path/string s, returning a path. - -> (append-extension-suffix s) - appends the platform-standard dynamic - extension file suffix to the path/string s, returning a path. - -> (extract-base-filename/ss s program) - strips the Scheme file suffix - from the path/string s and returns a stripped path. Unlike the - other functions below, when `program' is not #f, then any suffix - (including no suffix) is allowed. If s is not a Scheme file and - `program' is #f, #f is returned. The `program' argument is optional - and defaults to #f. - -> (extract-base-filename/c s program) - strips the Scheme file suffix - from the path/string s and returns a stripped path. If s is not a - Scheme file name and `program' is a symbol, and error is signaled. - If s is not a Scheme file and `program' is #f, #f is returned. The - `program' argument is optional and defaults to #f. - -> (extract-base-filename/kp s program) - same as - extract-base-filename/c, but for constant pool files. - -> (extract-base-filename/o s program) - same as - extract-base-filename/c, but for compiled object files. - -> (extract-base-filename/ext s program) - same as - extract-base-filename/c, but for extension files. - -The unit form _dynext:file@_ from _file-unit.ss_ requires no -imports and exports _dynext:file^_ from _file-sig.ss_. diff --git a/collects/dynext/info.ss b/collects/dynext/info.ss index 4d9eb8d731..f368f862d1 100644 --- a/collects/dynext/info.ss +++ b/collects/dynext/info.ss @@ -1,5 +1,5 @@ (module info setup/infotab - (define doc.txt "doc.txt") - (define name "Dynext")) + (define name "Dynext") + (define scribblings '(("dynext.scrbl" (multi-page))))) diff --git a/collects/scribblings/reference/startup.scrbl b/collects/scribblings/reference/startup.scrbl index 7a4a7941ea..340752cda2 100644 --- a/collects/scribblings/reference/startup.scrbl +++ b/collects/scribblings/reference/startup.scrbl @@ -8,6 +8,9 @@ @(define (DFlagFirst n) (as-index (DFlag n))) @(define (PFlagFirst n) (as-index (PFlag n))) +@(define (nontermstr s) + @elem{@schemevalfont{"}@nonterm[s]@schemevalfont{"}}) + @(define eventspace @tech[#:doc '(lib "scribblings/gui/gui.scrbl")]{eventspace}) @@ -114,12 +117,12 @@ flags: @nonterm{file} : @scheme[require]s @nonterm{file}.} @item{@FlagFirst{l} @nonterm{path} or @DFlagFirst{lib} - @nonterm{path} : @scheme[require]s @scheme[(lib - @nonterm{path})].} + @nonterm{path} : @scheme[require]s @scheme[(lib #, + @nontermstr{path})].} @item{@FlagFirst{p} @nonterm{file} @nonterm{u} @nonterm{path} : - @scheme[require]s @scheme[(planet @nonterm{file} - @nonterm{user} @nonterm{pkg})].} + @scheme[require]s @scheme[(planet #, @nontermstr{file} + #, @nontermstr{user} #, @nontermstr{pkg})].} @item{@FlagFirst{r} @nonterm{file} or @DFlagFirst{script} @nonterm{file} : @scheme[load]s @nonterm{file} as a diff --git a/collects/scribblings/scribble/how-to.scrbl b/collects/scribblings/scribble/how-to.scrbl index cee2c9a939..2e66bd9e33 100644 --- a/collects/scribblings/scribble/how-to.scrbl +++ b/collects/scribblings/scribble/how-to.scrbl @@ -283,11 +283,11 @@ manual: @(require scribble/manual (for-label scheme)) @(define ref-src - '(lib "scribblings/reference/reference.scrbl"))] + '(lib "scribblings/reference/reference.scrbl")) @title{My Library} - See also @italic{@secref[#:doc reference-src]{pairs}}. + See also @italic{@secref[#:doc ref-src]{pairs}}. EOS ] diff --git a/collects/scribblings/scribble/style.scrbl b/collects/scribblings/scribble/style.scrbl index 01d1c04d58..388b406e35 100644 --- a/collects/scribblings/scribble/style.scrbl +++ b/collects/scribblings/scribble/style.scrbl @@ -103,3 +103,7 @@ for quotation marks that are part of code. Do not use a citation reference (as created by @scheme[cite]) as a noun; use it as an annotation. + +Do not start a sentence with a Scheme variable name, since it is +normally lowercase. For example, use ``The @scheme[_thing] argument +is...'' instead of ``@scheme[_thing] is...''