scribbled dynext (from Will Farr)

svn: r8450

collects/dynext/doc.txt

@@ -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_.

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)))))
 

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} : @scheme[require]s @scheme[(lib #,
-       @nonterm{path})].}
+       @nontermstr{path})].}
 
   @item{@FlagFirst{p} @nonterm{file} @nonterm{u} @nonterm{path} :
-       @scheme[require]s @scheme[(planet @nonterm{file}
+       @scheme[require]s @scheme[(planet #, @nontermstr{file}
-       @nonterm{user} @nonterm{pkg})].}
+       #, @nontermstr{user} #, @nontermstr{pkg})].}
 
   @item{@FlagFirst{r} @nonterm{file} or @DFlagFirst{script}
         @nonterm{file} : @scheme[load]s @nonterm{file} as a

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
 ]
 

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...''