Branch merge

4 files changed, 33 insertions, 8 deletions

diff --git a/Doc/library/packaging.util.rst b/Doc/library/packaging.util.rst
index ae96d87..2b3103c 100644
--- a/Doc/library/packaging.util.rst
+++ b/Doc/library/packaging.util.rst
@@ -116,7 +116,6 @@ This module contains various helpers for the other modules.
    values are ``n``, ``no``, ``f``, ``false``, ``off`` and ``0``.  Raises
    :exc:`ValueError` if *val* is anything else.
 
-.. TODO Add :term: markup to bytecode when merging into the stdlib
 
 .. function:: byte_compile(py_files[, optimize=0, force=0, prefix=None, base_dir=None, verbose=1, dry_run=0, direct=None])
 
@@ -134,7 +133,7 @@ This module contains various helpers for the other modules.
 
    If *force* is true, all files are recompiled regardless of timestamps.
 
-   The source filename encoded in each bytecode file defaults to the filenames
+   The source filename encoded in each :term:`bytecode` file defaults to the filenames
    listed in *py_files*; you can modify these with *prefix* and *basedir*.
    *prefix* is a string that will be stripped off of each source filename, and
    *base_dir* is a directory name that will be prepended (after *prefix* is
@@ -150,3 +149,6 @@ This module contains various helpers for the other modules.
    figure out to use direct compilation or not (see the source for details).
    The *direct* flag is used by the script generated in indirect mode; unless
    you know what you're doing, leave it set to ``None``.
+
+   This function is independent from the running Python's :option:`-O` or
+   :option:`-B` options; it is fully controlled by the parameters passed in.
diff --git a/Doc/packaging/builtdist.rst b/Doc/packaging/builtdist.rst
index b1e5e93..1d9a349 100644
--- a/Doc/packaging/builtdist.rst
+++ b/Doc/packaging/builtdist.rst
@@ -164,9 +164,7 @@ will reflect this and now has the form :file:`foo-1.0.win32-py2.0.exe`.  You
 have to create a separate installer for every Python version you want to
 support.
 
-.. TODO Add :term: markup to bytecode when merging into the stdlib
-
-The installer will try to compile pure modules into bytecode after installation
+The installer will try to compile pure modules into :term:`bytecode` after installation
 on the target system in normal and optimizing mode.  If you don't want this to
 happen for some reason, you can run the :command:`bdist_wininst` command with
 the :option:`--no-target-compile` and/or the :option:`--no-target-optimize`
diff --git a/Doc/packaging/commandref.rst b/Doc/packaging/commandref.rst
index 0ec7505..2165b56 100644
--- a/Doc/packaging/commandref.rst
+++ b/Doc/packaging/commandref.rst
@@ -115,7 +115,24 @@ Build C/C++ extension modules.
 -------------------
 
 Build the Python modules (just copy them to the build directory) and
-byte-compile them to .pyc files.
+:term:`byte-compile <bytecode>` them to :file:`.pyc` and/or :file:`.pyo` files.
+
+The byte compilation is controlled by two sets of options:
+
+- ``--compile`` and ``--no-compile`` are used to control the creation of
+  :file:`.pyc` files; the default is ``--no-compile``.
+
+- ``--optimize N`` (or ``-ON``) is used to control the creation of :file:`.pyo`
+  files: ``-O1`` turns on basic optimizations, ``-O2`` also discards docstrings,
+  ``-O0`` does not create :file:`.pyo` files; the default is ``-O0``.
+
+You can mix and match these options: for example, ``--no-compile --optimize 2``
+will create :file:`.pyo` files but no :file:`.pyc` files.
+
+.. XXX these option roles do not work
+
+Calling Python with :option:`-O` or :option:`-B` does not control the creation
+of bytecode files, only the options described above do.
 
 
 :command:`build_scripts`
@@ -341,7 +358,14 @@ Install C/C++ header files.
 :command:`install_lib`
 ----------------------
 
-Install C library files.
+Install all modules (extensions and pure Python).
+
+.. XXX what about C libraries created with build_clib?
+
+Similarly to ``build_py``, there are options to control the compilation of
+Python code to :term:`bytecode` files (see above).  By default, :file:`.pyc`
+files will be created (``--compile``) and :file:`.pyo` files will not
+(``--optimize 0``).
 
 
 :command:`install_scripts`
diff --git a/Doc/using/cmdline.rst b/Doc/using/cmdline.rst
index f7bd92b..bc38542 100644
--- a/Doc/using/cmdline.rst
+++ b/Doc/using/cmdline.rst
@@ -455,7 +455,8 @@ These environment variables influence Python's behavior.
 .. envvar:: PYTHONDONTWRITEBYTECODE
 
    If this is set, Python won't try to write ``.pyc`` or ``.pyo`` files on the
-   import of source modules.
+   import of source modules.  This is equivalent to specifying the :option:`-B`
+   option.
 
 
 .. envvar:: PYTHONIOENCODING