docs: update BC and CS references

Replace "3m and/or CGC" with "BC", use "implementation" instead of
"variant", add a section on implementations to the reference,
update corners where the documentation suggests that BC/3m is the
default, and generally order CS first.

pkgs/racket-doc/scribblings/foreign/intro.scrbl

@@ -453,7 +453,8 @@ convenience) can be used directly as a pointer value (unlike character
 strings, which are always copied for UTF-8 encoding or decoding).
 
 For more information about memory management and garbage collection,
-see @secref[#:doc InsideRacket-doc "im:memoryalloc"] in
+see @secref[#:doc InsideRacket-doc "cs-memory"]
+and @secref[#:doc InsideRacket-doc "im:memoryalloc"] in
 @|InsideRacket|.
 
 @; --------------------------------------------------

pkgs/racket-doc/scribblings/foreign/pointers.scrbl

@@ -61,10 +61,10 @@ memory that is (assumed to be) managed by the garbage collector,
 @racket[#f] otherwise.
 
 For a pointer based on @racket[_gcpointer] as a result type,
-@racket[cpointer-gcable?] will return @racket[#t]. In the @3m[] and
+@racket[cpointer-gcable?] will return @racket[#t]. In the @BC[]
-@CGC[] variants of Racket, @racket[cpointer-gcable?] will return
+implementation of Racket, @racket[cpointer-gcable?] will return
 @racket[#f] for a pointer based on @racket[_pointer] as a result type.
-The @CS[] variant is mostly the sane, except that if a pointer is
+The @CS[] implementation is mostly the same, except that if a pointer is
 extracted using the @racket[_pointer] type from memory allocated as
 @racket['nonatomic], @racket[cpointer-gcable?] will report @racket[#t]
 for the extracted pointer.}
@@ -262,7 +262,7 @@ specification is required at minimum:
        garbage collector. The initial content of the memory is
        unspecified.
 
-       For the @3m[] and @CGC[] Racket variants, this allocation mode corresponds
+       For the @BC[] Racket implementation, this allocation mode corresponds
        to @cpp{scheme_malloc_atomic} in the C API.}
 
      @item{@indexed-racket['nonatomic] --- Allocates memory that can
@@ -270,10 +270,10 @@ specification is required at minimum:
        garbage collector as holding only pointers, and is initially
        filled with zeros.
 
-       For the @3m[] and @CGC[] Racket variants, this allocation mode corresponds
+       For the @BC[] Racket implementation, this allocation mode corresponds
        to @cpp{scheme_malloc} in the C API.
 
-       For the @CS[] Racket variant, this mode is of limited use,
+       For the @CS[] Racket implementation, this mode is of limited use,
        because a pointer allocated this way cannot be passed to
        foreign functions that expect a pointer to pointers. The result
        can only be used with functions like @racket[ptr-set!] and
@@ -284,7 +284,7 @@ specification is required at minimum:
        the garbage collector as long as the allocated object is
        retained.
 
-       For the @3m[] and @CGC[] Racket variants, a reference can point
+       For the @BC[] Racket implementation, a reference can point
        to the interior of the object, instead of its starting address.
        This allocation mode corresponds to
        @cpp{scheme_malloc_atomic_allow_interior} in the C API.}
@@ -294,7 +294,7 @@ specification is required at minimum:
        by the garbage collector as long as the allocated object is
        retained.
 
-       This mode is supported only for the @3m[] and @CGC[] Racket variants, and
+       This mode is supported only for the @BC[] Racket implementation, and
        it corresponds to @cpp{scheme_malloc_allow_interior} in the C
        API.}
 
@@ -302,14 +302,14 @@ specification is required at minimum:
        start with a @tt{short} value that is registered as a tag with
        the garbage collector.
 
-       This mode is supported only for the @3m[] and @CGC[] Racket variants, and
+       This mode is supported only for the @BC[] Racket implementation, and
        it corresponds to @cpp{scheme_malloc_tagged} in the C API.}
 
      @item{@indexed-racket['stubborn] --- Like @racket['nonatomic],
        but supports a hint to the GC via @racket[end-stubborn-change]
        after all changes to the object have been made.
 
-       This mode is supported only for the @3m[] and @CGC[] Racket variants, and
+       This mode is supported only for the @BC[] Racket implementation, and
        it corresponds to @cpp{scheme_malloc_stubborn} in the C API.}
 
      @item{@indexed-racket['eternal] --- Like @racket['raw], except the
@@ -468,8 +468,8 @@ use by such finalizers.}
          bytes?]{
 
 Returns a byte string made of the given pointer and the given length
-in the @3m[] and @CGC[] variants of Racket; no copying is performed.
+in the @BC[] implementation of Racket; no copying is performed.
-In the @CS[] variant, the @racket[exn:fail:unsupported] exception is
+In the @CS[] implementation, the @racket[exn:fail:unsupported] exception is
 raised.
 
 Beware that the representation of a Racket byte string normally

pkgs/racket-doc/scribblings/foreign/types.scrbl

@@ -284,15 +284,15 @@ converting between byte strings and C's @cpp{char*} type.
 A type for UCS-4 format strings that include a nul terminator. As
 usual, the type treats @racket[#f] as @cpp{NULL} and vice versa.
 
-For the @3m[] and @CGC[] variants of Racket, the conversion of a
+For the @CS[] implementation of Racket, the conversion of a Racket string for
+the foreign side is a copy of the Racket representation, where the
+copy is managed by the garbage collector.
+
+For the @BC[] implementation of Racket, the conversion of a
 Racket string for the foreign side shares memory with the Racket
 string representation, since UCS-4 is the native representation format
 for those variants. The foreign pointer corresponds to the
-@cpp{mzchar*} type in Racket's C API.
+@cpp{mzchar*} type in Racket's C API.}
-
-For the @CS[] variant of Racket, the conversion of a Racket string for
-the foreign side is a copy of the Racket representation, where the
-copy is managed by the garbage collector.}
 
 
 @deftogether[(
@@ -313,9 +313,9 @@ Simple @cpp{char*} strings that are nul terminated, corresponding to
 Racket's @tech[#:doc reference.scrbl]{path or string}. As usual, the
 type treats @racket[#f] as @cpp{NULL} and vice versa.
 
-For the @3m[] and @CGC[] variants of Racket, the conversion of a
+For the @BC[] implementation of Racket, the conversion of a
 Racket path for the foreign side shares memory with the Racket path
-representation. Otherwise (for the @CS[] variant or for Racket
+representation. Otherwise (for the @CS[] implementation or for Racket
 strings), conversion for the foreign side creates a copy that is
 managed by the garbage collector.
 
@@ -332,15 +332,15 @@ Simple @cpp{char*} strings as Racket symbols (encoded in UTF-8 and nul
 terminated), intended as read-only for the foreign side. Return values
 using this type are interned as symbols.
 
-For the @3m[] and @CGC[] variants of Racket, the conversion of a
+For the @CS[] implementation of Racket, the conversion of a Racket symbol for
+the foreign side is a copy of the Racket representation, where the
+copy is managed by the garbage collector.
+
+For the @BC[] implementation of Racket, the conversion of a
 Racket symbol for the foreign side shares memory with the Racket
 symbol representation, but points to the middle of the symbol's
 allocated memory---so the string pointer must not be used across a
-garbage collection.
+garbage collection.}
-
-For the @CS[] variant of Racket, the conversion of a Racket symbol for
-the foreign side is a copy of the Racket representation, where the
-copy is managed by the garbage collector.}
 
 
 @subsection{Fixed Auto-Converting String Types}
@@ -446,7 +446,7 @@ The same as @racket[_pointer] as an argument type, but as a result
 type, @racket[_gcpointer] corresponds to a C pointer value that refers
 to memory managed by the garbage collector.
 
-In the @3m[] and @CGC[] variants of Racket, a @racket[_gcpointer] result
+In the @BC[] implementation of Racket, a @racket[_gcpointer] result
 pointer can reference to memory that is not
 managed by the garbage collector, but beware of using an address that
 might eventually become managed by the garbage collector. For example,
@@ -615,7 +615,7 @@ For @tech{callouts} to foreign functions with the generated type:
  @item{If @racket[blocking?] is true, then a foreign @tech{callout}
        deactivates tracking of the calling OS thread---to the degree
        supported by the Racket variant---during the foreign call. The
-       value of @racket[blocking?] affects only the @CS[] variant of
+       value of @racket[blocking?] affects only the @CS[] implementation of
        Racket, where it enable activity
        such as garbage collection in other OS threads while the
        @tech{callout} blocks. If the blocking @tech{callout} can
@@ -705,7 +705,7 @@ For @tech{callbacks} to Racket functions with the generated type:
        @racket[keep] is based on the original function for the
        callback, not the result of @racket[wrapper].}
 
- @item{If @racket[atomic?] is true or when using the @CS[] variant of
+ @item{If @racket[atomic?] is true or when using the @CS[] implementation of
        Racket, then when a Racket procedure is given this type and
        called as a @tech{callback} from foreign code, then the Racket
        process is put into atomic mode while evaluating the Racket
@@ -721,9 +721,9 @@ For @tech{callbacks} to Racket functions with the generated type:
        to avoid C-level stack overflow; otherwise, the process may
        crash or misbehave.
 
-       Callbacks are always atomic in the @CS[] variant of Racket,
+       Callbacks are always atomic in the @CS[] implementation of Racket,
        because Racket threads do not capture C-stack context. Even on
-       the @3m[] or @CGC[] variants of Racket, atomic mode is
+       the @BC[] implementation of Racket, atomic mode is
        typically needed for callbacks, because capturing by copying a
        portion of the C stack is often incompatible with C libraries.}
 
@@ -1198,10 +1198,10 @@ type; a byte string is passed as @racket[_bytes] without any copying.
 Beware that a Racket byte string is not necessarily nul terminated;
 see also @racket[_bytes/nul-terminated].
 
-In the @3m[] and @CGC[] variants of Racket, a C non-NULL result value
+In the @BC[] implementation of Racket, a C non-NULL result value
 is converted to a Racket byte string without copying; the pointer is
 treated as potentially managed by the garbage collector (see
-@racket[_gcpointer] for caveats). In the @CS[] variant of Racket,
+@racket[_gcpointer] for caveats). In the @CS[] implementation of Racket,
 conversion requires copying to represent a C @cpp{char*}
 result as a Racket byte string, and the original pointer is @emph{not}
 treated as managed by the garbage collector. In both cases, the C result must have
@@ -1209,10 +1209,10 @@ a nul terminator to determine the Racket byte string's length.
 
 A @racket[(_bytes o len-expr)] form is a @tech{custom function type}.
 As an argument, a byte string is allocated with the given length; in
-the @3m[] and @CGC[] variants, that byte string includes an extra byte
+the @BC[] implementation, that byte string includes an extra byte
 for the nul terminator, and @racket[(_bytes o len-expr)] as a result
 wraps a C non-NULL @cpp{char*} pointer as a byte string of the given
-length. For the @CS[] variant, the allocated argument does not include
+length. For the @CS[] implementation, the allocated argument does not include
 a nul terminator and a copy is made for a result string.
 
 As usual, @racket[_bytes] treats @racket[#f] as @cpp{NULL} and vice

pkgs/racket-doc/scribblings/foreign/unexported.scrbl

@@ -101,11 +101,11 @@ A predicate for callback values that are created by @racket[ffi-callback].
 
 Creates a ``late'' will executor that readies a will for a value
 @scheme[_v] only if no normal will executor has a will registered for
-@scheme[_v]. In addition, for the @3m[] and @CGC[] variants of Racket,
+@scheme[_v]. In addition, for the @BC[] implementation of Racket,
 normal weak references to @scheme[_v] are cleared before a will for
 @racket[_v] is readied by the late will executor, but late weak
 references created by @racket[make-late-weak-box] and
-@racket[make-late-weak-hasheq] are not. For the @CS[] variant of
+@racket[make-late-weak-hasheq] are not. For the @CS[] implementation of
 Racket, a will is readied for @racket[_v] only when it is not reachable
 from any value that has a late will; if a value @racket[_v] is
 reachable from itself (i.e., through any field of @racket[_v], as

pkgs/racket-doc/scribblings/foreign/utils.rkt

@@ -19,7 +19,7 @@
          reference.scrbl
          ->>
          tech-place
-         3m CGC CS
+         CS BC 3m CGC
          (all-from-out scribble/manual)
          (for-label (all-from-out racket/base
                                   racket/contract
@@ -46,6 +46,7 @@
 (define (tech-place)
   (tech "place" #:doc '(lib "scribblings/reference/reference.scrbl")))
 
+(define (CS) (tech #:doc guide.scrbl "CS"))
+(define (BC) (tech #:doc guide.scrbl "BC"))
 (define (CGC) (tech #:doc guide.scrbl "CGC"))
 (define (3m) (tech #:doc guide.scrbl "3m"))
-(define (CS) (tech #:doc guide.scrbl "CS"))

pkgs/racket-doc/scribblings/guide/performance.scrbl

@@ -52,8 +52,8 @@ Non-interactive mode should be used instead of the
 
 @section[#:tag "virtual-machines"]{Racket Virtual Machine Implementations}
 
-Racket is available in three implementation variants: @deftech{CS},
+Racket is available in two implementations, @deftech{CS} and
-@deftech{3m}, and @deftech{CGC}:
+@deftech{BC}:
 
 @itemlist[
 
@@ -61,46 +61,54 @@ Racket is available in three implementation variants: @deftech{CS},
        a newer implementation that builds on
        @hyperlink["https://www.scheme.com/"]{Chez Scheme} as its core
        virtual machine. This implementation performs better than
-       the @tech{3m} implementation for most programs.
+       the @tech{BC} implementation for most programs.
 
-       For this variant, @racket[(system-type 'vm)] reports
+       For this implementation, @racket[(system-type 'vm)] reports
        @racket['chez-scheme] and @racket[(system-type 'gc)] reports
        @racket['cs].}
 
- @item{@tech{3m} is an older variant, and was the default until version 8.0.
+ @item{@tech{BC} is an older implementation, and was the default until version 8.0.
        The implementation features a compiler and runtime written in C,
        with a precise garbage collector and a just-in-time compiler (JIT)
        on most platforms.
 
-       For this variant, @racket[(system-type 'vm)] reports
+       For this implementation, @racket[(system-type 'vm)] reports
-       @racket['racket] and @racket[(system-type 'gc)] reports
+       @racket['racket].
+
+       The BC implementation itself has two variants, @deftech{3m} and
+       @deftech{CGC}:
+
+       @itemlist[
+
+        @item{@tech{3m} is the normal BC variant with a precise
+             garbage collector.
+
+             For this variant, @racket[(system-type 'gc)] reports
             @racket['3m].}
 
- @item{@tech{CGC} is an older variant. It's the same basic
-       implementation as @tech{3m} (i.e., the same virtual machine),
-       but compiled to rely on a ``conservative'' garbage collector,
-       which affects the way that Racket interacts with C code. (See
-       @secref["CGC versus 3m" #:doc inside-doc] in
-       @other-manual[inside-doc] for more information.)
 
-       For this variant, @racket[(system-type 'vm)] reports
+        @item{@tech{CGC} is the oldest variant. It's the same basic
-       @racket['racket] and @racket[(system-type 'gc)] reports
+              implementation as @tech{3m} (i.e., the same virtual
+              machine), but compiled to rely on a ``conservative''
+              garbage collector, which affects the way that Racket
+              interacts with C code. See @secref["CGC versus 3m"
+              #:doc inside-doc] in @other-manual[inside-doc] for more
+              information.
+
+              For this variant, @racket[(system-type 'gc)] reports
               @racket['cgc].}
 
-
+       ]}
 
 ]
 
-The @tech{3m} and @tech{CGC} variants are collectively known as the
-@deftech{BC} (``before CS'') variant.
-
 In general, Racket programs should run the same in all variants.
 Furthermore, the performance characteristics of Racket program should
-be similar in the @tech{3m} and @tech{CS} variants. The cases where a
+be similar in the @tech{CS} and @tech{BC} implementations. The cases
-program may depends on the variant will typically involve interactions
+where a program may depends on the implementation will typically
-with foreign libraries; in particular, the Racket C API described in
+involve interactions with foreign libraries; in particular, the Racket
-@other-doc[inside-doc] is different for the @tech{3m} and @tech{CGC}
+C API described in @other-doc[inside-doc] is different for the
-variants versus the @tech{CS} variant.
+@tech{CS} implementation versus the @tech{BC} implementation.
 
 @; ----------------------------------------------------------------------
 
@@ -121,16 +129,16 @@ elimination. For example, in an environment where @racket[+] has its
 usual binding, the expression @racket[(let ([x 1] [y (lambda () 4)]) (+
 1 (y)))] is compiled the same as the constant @racket[5].
 
-For the @tech{CS} variant of Racket, the main bytecode format is
+For the @tech{CS} implementation of Racket, the main bytecode format
-non-portable machine code. For the @tech{3m} and @tech{CGC} variants
+is non-portable machine code. For the @tech{BC} implementation of
-of Racket, bytecode is portable in the sense that it is
+Racket, bytecode is portable in the sense that it is
 machine-independent. Setting @racket[current-compile-target-machine]
 to @racket[#f] selects a separate machine-independent and
-variant-independent format on all Racket variants, but running code in
+variant-independent format on all Racket implementations, but running
-that format requires an additional internal conversion step to the
+code in that format requires an additional internal conversion step to
-variant's main bytecode format.
+the implementation's main bytecode format.
 
-Machine-independent bytecode for @tech{3m} or @tech{CGC} is further
+Machine-independent bytecode for @tech{BC} implementation is further
 compiled to native code via a @deftech{just-in-time} or @deftech{JIT}
 compiler. The @tech{JIT} compiler substantially speeds programs that
 execute tight loops, arithmetic on small integers, and arithmetic on
@@ -139,7 +147,7 @@ for x86, x86_64 (a.k.a. AMD64), 32-bit ARM, and 32-bit PowerPC processors.
 The @tech{JIT} compiler can be disabled via the
 @racket[eval-jit-enabled] parameter or the @DFlag{no-jit}/@Flag{j}
 command-line flag for @exec{racket}. Setting @racket[eval-jit-enabled]
-to @racket[#f] has not effect on the @tech{CS} variant of Racket.
+to @racket[#f] has not effect on the @tech{CS} implementation of Racket.
 
 The @tech{JIT} compiler works incrementally as functions are applied,
 but the @tech{JIT} compiler makes only limited use of run-time
@@ -151,7 +159,7 @@ overhead for @tech{JIT} compilation is normally so small that it is
 difficult to detect.
 
 For information about viewing intermediate Racket code
-representations, especially for the @tech{CS} variant, see
+representations, especially for the @tech{CS} implementation, see
 @refsecref["compiler-inspect"].
 
 @; ----------------------------------------------------------------------
@@ -397,7 +405,7 @@ flonum-specific operation with two arguments.}
 Finally, the compiler can detect some flonum-valued loop
 accumulators and avoid boxing of the accumulator.
 @margin-note*{Unboxing of local bindings and accumulators is not
-supported by the @tech{3m} variant's JIT for PowerPC.}
+supported by the @tech{BC} implementation's JIT for PowerPC.}
 
 For some loop patterns, the compiler may need hints to enable
 unboxing. For example:
@@ -419,7 +427,7 @@ changing the result @racket[sum] to @racket[(fl+ sum)] gives the
 compiler hints and license to unbox @racket[sum].
 
 The bytecode decompiler (see @secref[#:doc '(lib
-"scribblings/raco/raco.scrbl") "decompile"]) for the @tech{3m} variant
+"scribblings/raco/raco.scrbl") "decompile"]) for the @tech{BC} implementation
 annotates combinations where the JIT can avoid boxes with
 @racketidfont{#%flonum}, @racketidfont{#%as-flonum}, and
 @racketidfont{#%from-flonum}. For the @tech{CS} variant, the
@@ -509,10 +517,10 @@ string or byte string, write a constant @tech{regexp} using an
 
 @section[#:tag "gc-perf"]{Memory Management}
 
-The @tech{3m} (default) and @tech{CS} Racket
+The @tech{CS} (default) and @tech{BC} Racket
 @seclink["virtual-machines"]{virtual machines} each use a modern,
 @deftech{generational garbage collector} that makes allocation
-relatively cheap for short-lived objects. The @tech{CGC} variant uses
+relatively cheap for short-lived objects. The @tech{CGC} variant of @tech{BC} uses
 a @deftech{conservative garbage collector} which facilitates
 interaction with C code at the expense of both precision and speed for
 Racket memory management.

pkgs/racket-doc/scribblings/inside/contmarks.scrbl

@@ -1,7 +1,7 @@
 #lang scribble/doc
 @(require "utils.rkt")
 
-@title[#:tag "contmarks"]{Continuation Marks}
+@bc-title[#:tag "contmarks"]{Continuation Marks}
 
 A mark can be attached to the current continuation frame using
 @cppi{scheme_set_cont_mark}. To force the creation of a new frame

pkgs/racket-doc/scribblings/inside/cs-embedding.scrbl

@@ -2,7 +2,7 @@
 @(require "utils.rkt"
           scribble/bnf)
 
-@title[#:tag "cs-embedding"]{Embedding into a Program}
+@cs-title[#:tag "cs-embedding"]{Embedding into a Program}
 
 @section-index["embedding Racket CS"]
 

pkgs/racket-doc/scribblings/inside/cs-eval.scrbl

@@ -2,7 +2,7 @@
 @(require "utils.rkt"
           (for-label ffi/unsafe/vm))
 
-@title[#:tag "cs-eval"]{Evaluation and Running Modules}
+@cs-title[#:tag "cs-eval"]{Evaluation and Running Modules}
 
 The @cppi{racket_apply} function provides basic evaluation support,
 but @cppi{racket_eval}, @cppi{racket_dynamic_require}, and

pkgs/racket-doc/scribblings/inside/cs-overview.scrbl

@@ -1,9 +1,9 @@
 #lang scribble/doc
 @(require "utils.rkt")
 
-@title[#:tag "cs-overview"]{Overview}
+@cs-title[#:tag "cs-overview"]{Overview}
 
-The Racket CS run-time system is implemented by a wrapper around the
+The Racket CS runtime system is implemented by a wrapper around the
 Chez Scheme kernel. The wrapper implements additional glue to the
 operating system (e.g., for I/O and networking) and provides entry
 points into the Racket layer's evaluator.
@@ -23,7 +23,7 @@ the Racket wrapper.
 @index['("allocation")]{Racket} values may be moved or garbage
 collected any time that @cpp{racket_...} functions are used to run
 Racket code. Do not retain a reference to any Racket value across such
-a call. This requirement contrasts with the 3m and CGC variants of
+a call. This requirement contrasts with the BC implementation of
 Racket, which provide a way for C code to more directly cooperate with
 the memory manager.
 

pkgs/racket-doc/scribblings/inside/cs-procs.scrbl

@@ -1,7 +1,7 @@
 #lang scribble/doc
 @(require "utils.rkt")
 
-@title[#:tag "cs-procs"]{Calling Procedures}
+@cs-title[#:tag "cs-procs"]{Calling Procedures}
 
 As an entry point into Racket, C programs should normally call Racket
 procedures by using @cppi{racket_apply}, which calls the procedure in

pkgs/racket-doc/scribblings/inside/cs-start.scrbl

@@ -1,7 +1,7 @@
 #lang scribble/doc
 @(require "utils.rkt")
 
-@title[#:tag "cs-start"]{Starting and Declaring Initial Modules}
+@cs-title[#:tag "cs-start"]{Starting and Declaring Initial Modules}
 
 As sketched in @secref["cs-embedding"], and embedded instance of
 Racket CS is started with @cppi{racket_boot}. Functions such as

pkgs/racket-doc/scribblings/inside/cs-thread.scrbl

@@ -1,7 +1,7 @@
 #lang scribble/doc
 @(require "utils.rkt")
 
-@title[#:tag "cs-thread"]{Managing OS-Level Threads}
+@cs-title[#:tag "cs-thread"]{Managing OS-Level Threads}
 
 Chez Scheme functionality can only be accessed from OS-level threads
 that are known to the Chez Scheme runtime system. Otherwise, there's a

pkgs/racket-doc/scribblings/inside/cs-values.scrbl

@@ -3,7 +3,7 @@
           (for-label racket/unsafe/ops
                      ffi/unsafe))
 
-@title[#:tag "cs-values+types"]{Values and Types}
+@cs-title[#:tag "cs-values+types"]{Values and Types}
 
 A Racket value is represented by a pointer-sized value. The low bits
 of the value indicate the encoding that it uses. For example, two (on

pkgs/racket-doc/scribblings/inside/custodians.scrbl

@@ -2,7 +2,7 @@
 @(require "utils.rkt"
           (for-label ffi/unsafe/custodian))
 
-@title{Custodians}
+@bc-title[#:tag "Custodians"]{Custodians}
 
 When an extension allocates resources that must be explicitly freed
 (in the same way that a port must be explicitly closed), a Racket

pkgs/racket-doc/scribblings/inside/embedding.scrbl

@@ -4,7 +4,7 @@
 
 @(define cgc-v-3m "CGC versus 3m")
 
-@title[#:tag "embedding"]{Embedding into a Program}
+@bc-title[#:tag "embedding"]{Embedding into a Program}
 
 @section-index["embedding Racket BC"]
 

pkgs/racket-doc/scribblings/inside/eval.scrbl

@@ -1,7 +1,7 @@
 #lang scribble/doc
 @(require "utils.rkt")
 
-@title{Evaluation}
+@bc-title[#:tag "Evaluation"]{Evaluation}
 
 A Racket S-expression is evaluated by calling @cppi{scheme_eval}.
 This function takes an S-expression (as a @cpp{Scheme_Object*}) and a

pkgs/racket-doc/scribblings/inside/exns.scrbl

@@ -1,7 +1,7 @@
 #lang scribble/doc
 @(require "utils.rkt")
 
-@title[#:tag "exceptions"]{Exceptions and Escape Continuations}
+@bc-title[#:tag "exceptions"]{Exceptions and Escape Continuations}
 
 When Racket encounters an error, it raises an exception. The default
 exception handler invokes the error display handler and then the error

pkgs/racket-doc/scribblings/inside/extensions.scrbl

@@ -1,7 +1,7 @@
 #lang scribble/doc
 @(require "utils.rkt")
 
-@title[#:tag "Writing Racket Extensions"]{Writing Racket Extensions}
+@bc-title[#:tag "Writing Racket Extensions"]{Writing Racket Extensions}
 
 @section-index["extending Racket"]
 

pkgs/racket-doc/scribblings/inside/inside.scrbl

@@ -6,11 +6,18 @@
 
 @author["Matthew Flatt"]
 
+The Racket runtime system is responsible for the implementation of
+primitive datatypes such as numbers and strings, the macro expansion
+and compilation of Racket from source, the allocation and reclamation
+of memory used during evaluation, and the scheduling of concurrent
+threads and parallel tasks.
+
 This manual describes the C interface of Racket's runtime system,
-which varies depending on the variant of Racket (see @secref[#:doc
+which varies depending on the implementation of Racket (see
-'(lib "scribblings/guide/guide.scrbl") "virtual-machines"]): the CS
+@secref[#:doc '(lib "scribblings/guide/guide.scrbl")
-variant of Racket has one interface, while the BC (3m and CGC)
+"virtual-machines"]): the CS implementation of Racket has one
-variants of Racket have another.
+interface, while the BC (3m and CGC) implementation of Racket has
+another.
 
 The C interface is relevant to some degree when interacting with
 foreign libraries as described in @other-manual['(lib

pkgs/racket-doc/scribblings/inside/memory.scrbl

@@ -2,7 +2,7 @@
 @(require "utils.rkt" (for-label ffi/unsafe
                                  ffi/unsafe/collect-callback))
 
-@title[#:tag "im:memoryalloc"]{Memory Allocation}
+@bc-title[#:tag "im:memoryalloc"]{Memory Allocation}
 
 @section-index{memory}
 @section-index{garbage collection}

pkgs/racket-doc/scribblings/inside/misc.scrbl

@@ -2,7 +2,7 @@
 @(require "utils.rkt"
           (for-label ffi/unsafe/global))
 
-@title{Miscellaneous Utilities}
+@bc-title[#:tag "Miscellaneous Utilities"]{Miscellaneous Utilities}
 
 The @cppi{MZSCHEME_VERSION} preprocessor macro is defined as a string
 describing the version of Racket. The @cppi{MZSCHEME_VERSION_MAJOR}

pkgs/racket-doc/scribblings/inside/namespaces.scrbl

@@ -1,7 +1,7 @@
 #lang scribble/doc
 @(require "utils.rkt")
 
-@title[#:tag "im:env"]{Namespaces and Modules}
+@bc-title[#:tag "im:env"]{Namespaces and Modules}
 
 A Racket namespace (a top-level environment) is represented by a value
 of type @cppi{Scheme_Env*} --- which is also a Racket value, castable

pkgs/racket-doc/scribblings/inside/numbers.scrbl

@@ -1,7 +1,7 @@
 #lang scribble/doc
 @(require "utils.rkt")
 
-@title{Bignums, Rationals, and Complex Numbers}
+@bc-title[#:tag "Bignums, Rationals, and Complex Numbers"]{Bignums, Rationals, and Complex Numbers}
 
 Racket supports integers of an arbitrary magnitude; when an integer
 cannot be represented as a fixnum (i.e., 30 or 62 bits plus a sign

pkgs/racket-doc/scribblings/inside/overview.scrbl

@@ -1,14 +1,12 @@
 #lang scribble/doc
 @(require "utils.rkt")
 
-@title[#:tag "overview"]{Overview}
+@bc-title[#:tag "overview"]{Overview}
 
-The Racket run-time system is responsible for the implementation of
+The Racket BC runtime system is implemented in C and provides the
-primitive datatypes such as numbers and strings, the evaluation and/or
+compiler from source to bytecode format, the JIT compiler from
-JIT compilation of Racket bytecode, the macro expansion and
+bytecode to machine code, I/O functionality, threads, and memory
-compilation of Racket from source to bytecode, the allocation and
+management.
-reclamation of memory used during evaluation, and the scheduling of
-concurrent threads and parallel tasks.
 
 @section{``Scheme'' versus ``Racket''}
 
@@ -22,19 +20,19 @@ all should be renamed to start @cpp{racket_}.
 
 @section[#:tag "CGC versus 3m"]{CGC versus 3m}
 
-Before mixing any C code with Racket, first decide whether to use the
+Before mixing any C code with Racket BC, first decide whether to use the
 @bold{3m} variant of Racket, the @bold{CGC} variant of Racket, or
 both:
 
 @itemize[
 
-@item{@bold{@as-index{3m}} : the main variant of Racket, which uses
+@item{@bold{@as-index{3m}} : the main variant of Racket BC, which uses
   @defterm{precise} garbage collection and requires explicit
   registration of pointer roots and allocation shapes. The precise
   garbage collector may move its objects in memory during a
   collection.}
 
-@item{@bold{@as-index{CGC}} : the original variant of Racket, where
+@item{@bold{@as-index{CGC}} : the original variant of Racket BC, where
   memory management depends on a @defterm{conservative} garbage
   collector. The conservative garbage collector can automatically find
   references to managed values from C local variables and (on some

pkgs/racket-doc/scribblings/inside/params.scrbl

@@ -1,7 +1,7 @@
 #lang scribble/doc
 @(require "utils.rkt")
 
-@title[#:tag "config"]{Parameterizations}
+@bc-title[#:tag "config"]{Parameterizations}
 
 A @defterm{parameterization} is a set of parameter values. Each thread
 has its own initial parameterization, which is extended functionally

pkgs/racket-doc/scribblings/inside/ports.scrbl

@@ -1,7 +1,7 @@
 #lang scribble/doc
 @(require "utils.rkt")
 
-@title{Ports and the Filesystem}
+@bc-title[#:tag "Ports and the Filesystem"]{Ports and the Filesystem}
 
 Ports are represented as Racket values with the types
 @cppi{scheme_input_port_type} and @cppi{scheme_output_port_type}.  The

pkgs/racket-doc/scribblings/inside/procedures.scrbl

@@ -1,7 +1,7 @@
 #lang scribble/doc
 @(require "utils.rkt")
 
-@title{Procedures}
+@bc-title[#:tag "Procedure"]{Procedures}
 
 A @defterm{primitive procedure} is a Racket-callable procedure that is
 implemented in C.  Primitive procedures are created in Racket with

pkgs/racket-doc/scribblings/inside/security.scrbl

@@ -1,7 +1,7 @@
 #lang scribble/doc
 @(require "utils.rkt")
 
-@title[#:tag "security"]{Security Guards}
+@bc-title[#:tag "security"]{Security Guards}
 
 Before a primitive procedure accesses the filesystem or creates a
 network connection, it should first consult the current security guard

pkgs/racket-doc/scribblings/inside/strings.scrbl

@@ -1,7 +1,7 @@
 #lang scribble/doc
 @(require "utils.rkt")
 
-@title[#:tag "im:encodings"]{String Encodings}
+@bc-title[#:tag "im:encodings"]{String Encodings}
 
 The @cpp{scheme_utf8_decode} function decodes a @cpp{char} array as
 UTF-8 into either a UCS-4 @cpp{mzchar} array or a UTF-16 @cpp{short}

pkgs/racket-doc/scribblings/inside/structures.scrbl

@@ -1,7 +1,7 @@
 #lang scribble/doc
 @(require "utils.rkt")
 
-@title{Structures}
+@bc-title[#:tag "Structures"]{Structures}
 
 A new Racket structure type is created with
 @cppi{scheme_make_struct_type}.  This creates the structure type, but

pkgs/racket-doc/scribblings/inside/subprocesses.scrbl

@@ -2,7 +2,7 @@
 @(require "utils.rkt"
           (for-label racket/system))
 
-@title{Subprocesses}
+@bc-title[#:tag "Subprocesses"]{Subprocesses}
 
 On Unix and Mac OS, subprocess handling involves
 @as-index[@cpp{fork}], @as-index[@cpp{waitpid}], and

pkgs/racket-doc/scribblings/inside/threads.scrbl

@@ -1,7 +1,7 @@
 #lang scribble/doc
 @(require "utils.rkt" (for-label scheme/tcp))
 
-@title[#:tag "threads"]{Threads}
+@bc-title[#:tag "threads"]{Threads}
 
 The initializer function @cppi{scheme_basic_env} creates the main
 Racket thread; all other threads are created through calls to

pkgs/racket-doc/scribblings/inside/utils.rkt

@@ -7,7 +7,8 @@
          (for-syntax scheme/base)
          (for-label scheme/base))
 
-(provide Racket
+(provide cs-title bc-title
+         Racket
          mzc cpp cppi cppdef (rename-out [*var var])
          function subfunction together
          FormatD
@@ -16,6 +17,12 @@
          (except-out (all-from-out scribble/manual) var)
          (for-label (all-from-out scheme/base)))
 
+(define (cs-title #:tag tag . content)
+  (apply title #:tag tag (append content (list " (CS)"))))
+
+(define (bc-title #:tag tag . content)
+  (apply title #:tag tag (append content (list " (BC)"))))
+
 (define (as-cpp-defn name s)
   (make-target-element #f
                        (list (as-index s))

pkgs/racket-doc/scribblings/inside/values.scrbl

@@ -1,7 +1,7 @@
 #lang scribble/doc
 @(require "utils.rkt")
 
-@title[#:tag "im:values+types"]{Values and Types}
+@bc-title[#:tag "im:values+types"]{Values and Types}
 
 A Racket value is represented by a pointer-sized value. The low bit is
 a mark bit: a 1 in the low bit indicates an immediate integer, a 0

pkgs/racket-doc/scribblings/reference/compiler.scrbl

@@ -22,17 +22,17 @@ parameter to @racket[#f] or supplying the @DFlag{compile-any}/@Flag{M}
 flag on startup. See @racket[current-compile-target-machine] for more
 information.
 
-Other compilation modes depend on the Racket variant
+Other compilation modes depend on the Racket variant (see
-(3m/CGC versus CS).
+@secref["implementations"]).
 
 
-@subsection[#:tag "3m-compiler-modes"]{3m and CGC Compilation Modes}
+@subsection[#:tag "3m-compiler-modes"]{BC Compilation Modes}
 
-The 3m and CGC variants of Racket support two
+The @tech{BC} implementation of Racket supports two
 compilation modes: bytecode and machine-independent. The bytecode
 format is also machine-independent in the sense that it works the same
-on all operating systems for the 3m and/or CGC variants
+on all operating systems for the BC implementation
-of Racket, but it does not work with the CS variant of Racket.
+of Racket, but it does not work with the CS implementation of Racket.
 
 Bytecode is further compiled to machine code at run time, unless the
 JIT compiler is disabled. See @racket[eval-jit-enabled].
@@ -40,10 +40,10 @@ JIT compiler is disabled. See @racket[eval-jit-enabled].
 
 @subsection[#:tag "cs-compiler-modes"]{CS Compilation Modes}
 
-The CS variant of Racket supports several compilation modes:
+The @tech{CS} implementation of Racket supports several compilation modes:
 machine code, machine-independent, interpreted, and JIT. Machine code
 is the primary mode, and the machine-independent mode is the same as
-for 3m and CGC. Interpreted mode uses an interpreter at
+for BC. Interpreted mode uses an interpreter at
 the level of core @tech{linklet} forms with no compilation. JIT mode
 triggers compilation of individual function forms on demand.
 
@@ -79,7 +79,7 @@ compiled forms whenever a Racket form is compiled. For all Racket
 variants, the output shows one or more @tech{linklets} that are
 generated from the original Racket form.
 
-For the CS variant of Racket, a ``schemified'' version of the linklet
+For the @tech{CS} implementation of Racket, a ``schemified'' version of the linklet
 is also shown as the translation of the @racket[linklet] form to a
 Chez Scheme procedure form. The following environment variables imply
 @envvar{PLT_LINKLET_SHOW} and show additional intermediate compiled

pkgs/racket-doc/scribblings/reference/cont.scrbl

@@ -190,7 +190,7 @@ called in tail position, and the continuation procedure supplied to
 A continuation obtained from @racket[call-with-escape-continuation] is
 actually a kind of prompt. Escape continuations are provided mainly
 for backwards compatibility, since they pre-date general prompts in
-Racket. In the 3m and CGC variants of Racket,
+Racket. In the @tech{BC} implementation of Racket,
 @racket[call-with-escape-continuation] is implemented more efficiently
 than @racket[call-with-current-continuation], so
 @racket[call-with-escape-continuation] can sometimes replace

pkgs/racket-doc/scribblings/reference/custodians.scrbl

@@ -80,9 +80,8 @@ down, then it cannot be a subordinate of @racket[super].}
 
 @defproc[(custodian-memory-accounting-available?) boolean?]{
 
-@margin-note{Memory accounting is normally available in Racket 3m,
+@margin-note{Memory accounting is normally available, but not in
-which is the main variant of Racket, and not normally available in
+the @tech{CGC} implementation.}
-Racket CGC.}
 
 Returns @racket[#t] if Racket is compiled with support for
 per-custodian memory accounting, @racket[#f] otherwise.}

pkgs/racket-doc/scribblings/reference/debugging.scrbl

@@ -5,9 +5,9 @@
 
 Racket's built-in debugging support is limited to context (i.e.,
 ``stack trace'') information that is printed with an exception. In
-some cases, for 3m and CGC variants of Racket, disabling the
+some cases, for @tech{BC} implementation of Racket, disabling the
-@tech{JIT} compiler can affect context information. For the CS variant
+@tech{JIT} compiler can affect context information. For the @tech{CS}
-of Racket, setting the @envvar-indexed{PLT_CS_DEBUG} environment
+implementation of Racket, setting the @envvar-indexed{PLT_CS_DEBUG} environment
 variable causes compilation to record expression-level context
 information, instead of just function-level information.
 

pkgs/racket-doc/scribblings/reference/eval-model.scrbl

@@ -1088,8 +1088,8 @@ The values managed by a custodian are semi-weakly held by the
 custodian: a @techlink{will} can be executed for a value that is
 managed by a custodian; in addition, weak references via weak
 @tech{hash tables}, @tech{ephemerons}, or @tech{weak box}es can be
-dropped on the 3m or CGC variants of Racket, but not on the CS
+dropped on the @tech{BC} implementation of Racket, but not on the @tech{CS}
-variant. For all variants, a custodian only weakly
+implementation. For all variants, a custodian only weakly
 references its subordinate custodians; if a subordinate custodian is
 unreferenced but has its own subordinates, then the custodian may be
 garbage collected, at which point its subordinates become immediately

pkgs/racket-doc/scribblings/reference/implementation.scrbl

@@ -0,0 +1,46 @@
+#lang scribble/doc
+@(require "mz.rkt")
+
+@title[#:tag "implementations" #:style 'quiet]{Implementations}
+
+The definition of Racket aims for determinism and independence from
+its implementation. Nevertheless, some details inevitably vary with
+the implementation. Racket currently has two main implementations:
+
+@itemlist[
+
+ @item{The @deftech{CS} implementation is the default implementation
+       as of Racket version 8.0. This variant is called ``CS'' because
+       it uses Chez Scheme as its core compiler and runtime system.
+
+       The CS implementation typically provides the best performance
+       for Racket programs. Compiled Racket CS code in a
+       @filepath{.zo} file normally contains machine code that is
+       specific to an operating system and architecture.}
+
+ @item{The @deftech{BC} implementation was the default implementation
+       up until version 7.8. The ``BC'' label stands for ``before
+       Chez'' or ``bytecode.''
+
+       Compiled Racket BC code in a @filepath{.zo} file normally
+       contains platform-independent bytecode that is further compiled
+       to machine code ``just in time'' as the code is loaded.
+
+       Racket BC has two subvariants: @deftech{3m} and @deftech{CGC}.
+       The difference is the @tech{garbage collection} implementation,
+       where 3m uses a garbage collector that moves objects in memory
+       (an effect that is visible to foreign libraries, for example)
+       and keeps precise track of allocated objects, while CGC uses a
+       ``conservative'' collector that requires less cooperation from
+       an embedding foreign environment. The 3m subvariant tends to
+       perform much better than CGC, and it because the default
+       variant in version 370 (which would be v3.7 in the current
+       versioning convention).}
+
+]
+
+Most Racket programs run the same in all variants, but some Racket
+features are available only on some implementation variants, and the
+interaction of Racket and foreign functions is significantly different
+across the variants. Use @racket[system-type] to get information about
+the current running implementation.

pkgs/racket-doc/scribblings/reference/memory.scrbl

@@ -224,10 +224,10 @@ to a value that starts with @litchar{0}, @litchar{n}, or @litchar{N} to
 disable incremental-mode requests.
 
 Each garbage collection logs a message (see @secref["logging"]) at the
-@racket['debug] level with topic @racket['GC]. In the 3m and CS
+@racket['debug] level with topic @racket['GC]. In the @tech{CS} and @tech{3m}
-variants of Racket, ``major'' collections are also logged at the
+implementations of Racket, ``major'' collections are also logged at the
-@racket['debug] level with the topic @racket['GC:major]. In the 3m
+@racket['debug] level with the topic @racket['GC:major]. In the @tech{CS}
-and CS variants of Racket, the data portion of the message is an
+and @tech{3m} implementations of Racket, the data portion of the message is an
 instance of a @indexed-racket[gc-info] @tech{prefab} structure type
 with 10 fields as follows, but future versions of Racket may use a
 @racket[gc-info] @tech{prefab} structure with additional fields:
@@ -360,9 +360,9 @@ garbage-collection mode, depending on @racket[request]:
        The intent of incremental mode is to significantly reduce pause
        times due to major collections, but incremental mode may imply
        longer minor-collection times and higher memory use. Currently,
-       incremental mode is only meaningful when @racket[(system-type
+       incremental mode is only meaningful for @tech{CS} and @tech{3m}
-       'gc)] returns @racket['3m] or @racket['cs]; it has no effect in
+       Racket implementations; it has no effect in
-       other Racket variants.
+       other Racket implementations.
 
        If the @envvar{PLT_INCREMENTAL_GC} environment variable's value
        starts with @litchar{0}, @litchar{n}, or @litchar{N} on
@@ -373,7 +373,7 @@ garbage-collection mode, depending on @racket[request]:
 @history[#:changed "6.3" @elem{Added the @racket[request] argument.}
          #:changed "6.3.0.2" @elem{Added @racket['incremental] mode.}
          #:changed "7.7.0.4" @elem{Added @racket['incremental] effect
-                                   for Racket CS.}]}
+                                   for Racket @tech{CS}.}]}
 
 
 @defproc[(current-memory-use [mode (or/c #f 'cumulative custodian?) #f])
@@ -437,8 +437,7 @@ manager that memory is allocated within the process but through a
 separate allocator, such as through a foreign library that is accessed
 via @racketmodname[ffi/unsafe]. This hint is used to trigger
 @tech{garbage collections} or to compute the result of
-@racket[current-memory-use]. Currently, the hint is used only in
+@racket[current-memory-use].
-Racket 3m (the main variant of Racket).
 
 @defproc[(phantom-bytes? [v any/c]) boolean?]{
 

pkgs/racket-doc/scribblings/reference/model.scrbl

@@ -9,3 +9,4 @@
 @include-section["syntax-model.scrbl"]
 @include-section["reader.scrbl"]
 @include-section["printer.scrbl"]
+@include-section["implementation.scrbl"]

pkgs/racket-doc/scribblings/reference/places.scrbl

@@ -25,16 +25,16 @@ take advantage of machines with multiple processors, cores, or
 hardware threads.
 
 @margin-note{Currently, parallel support for places is enabled
-  only for the CS and 3m variants of Racket, and for 3m, only
+  only for the @tech{CS} and @tech{3m} implementations of Racket, and for @tech{3m}, only
   by default for Windows, Linux x86/x86_64, and Mac OS x86/x86_64. To
-  enable support for other platforms with 3m, use @DFlag{enable-places} with
+  enable support for other platforms with @tech{3m}, use @DFlag{enable-places} with
   @exec{configure} when building Racket. The @racket[place-enabled?]
   function reports whether places run in parallel.
 
   Implementation and operating-system constraints may limit the
   scalability of places. For example, although places can perform
-  garbage collections in parallel in the CS variant or independently
+  garbage collections in parallel in the @tech{CS} implementation or independently
-  in the 3m variant, a garbage collection
+  in the @tech{3m} implementation, a garbage collection
   may need to manipulate a page table that is shared across all
   places, and that shared page table can be a bottleneck with enough
   places---perhaps around 8 or 16.}

pkgs/racket-doc/scribblings/reference/printer.scrbl

@@ -624,7 +624,7 @@ the conversion of the source field is to preserve some source
 information but not expose or record a path that makes no sense on
 a different filesystem or platform.
 
-For internal testing purposes in the 3m and CGC variants of Racket, when the
+For internal testing purposes in the @tech{BC} implementation of Racket, when the
 @as-index{@envvar{PLT_VALIDATE_LOAD}} environment variable is set, the
 reader runs a validator on bytecode parsed from @litchar{#~}. The
 validator may catch miscompilations or bytecode-file corruption. The

pkgs/racket-doc/scribblings/reference/runtime.scrbl

@@ -43,7 +43,7 @@ or 64-bit program.
  about the @racket['vm] and @racket['gc] mode results.}
 
 In @indexed-racket['vm] mode,
-the possible symbol results are:
+the possible symbol results are (see also @secref["implementations"]):
 
 @itemize[
 @item{@indexed-racket['racket]}
@@ -51,7 +51,7 @@ the possible symbol results are:
 ]
 
 In @indexed-racket['gc] mode,
-the possible symbol results are:
+the possible symbol results are (see also @secref["implementations"]):
 
 @itemize[
 @item{@indexed-racket['cgc] --- when @racket[(system-type 'vm)] is @racket['racket]}