Commits

guillermooo committed 2ae9ded

installpackages.rst (packaging): Revised 'Syntax of configuration files' for flow.

Comments (0)

Files changed (1)

Doc/packaging/enduser/installpackages.rst

 
 .. _packaging-config-syntax:
 
-Syntax of config files
-----------------------
+Syntax of configuration files
+-----------------------------
 
-The Packaging configuration files all have the same syntax. The config files
-are grouped into sections. There is one section for each Packaging command,
-plus a ``global`` section for global options that affect every command. Each
-section consists of one option per line, specified as ``option = value``.
+All Packaging configuration files share the same syntax. Options defined in
+them are grouped into sections, and each Packaging command gets its own section.
+Additionally, there's a ``global`` section for options that affect every command.
+Sections consist of one or more lines containing a single option specified as
+``option = value``.
 
-For example, the following is a complete config file that just forces all
-commands to run quietly by default::
+For example, here's a complete configuration file that forces all commands to
+run quietly by default::
 
    [global]
    verbose = 0
 
-If this is installed as the system config file, it will affect all processing
-of any Python module distribution by any user on the current system. If it is
-installed as your personal config file (on systems that support them), it will
-affect only module distributions processed by you. And if it is used as the
-:file:`setup.cfg` for a particular module distribution, it affects only that
-distribution.
+If this was the system configuration file, it would affect all processing
+of any Python module distribution by any user on the current system. If it was
+installed as your personal configuration file (on systems that support them),
+it would affect only module distributions processed by you. Lastly, if it was
+used as the :file:`setup.cfg` for a particular module distribution, it would
+affect that distribution only.
 
-You could override the default "build base" directory and make the
-:command:`build\*` commands always forcibly rebuild all files with the
-following::
+.. XXX "(on systems that support them)" seems wrong info
+
+If you wanted to, you could override the default "build base" directory and
+make the :command:`build\*` commands always forcibly rebuild all files with
+the following::
 
    [build]
    build-base = blib
    force = 1
 
-which corresponds to the command-line arguments ::
+which corresponds to the command-line arguments::
 
    python -m packaging.run build --build-base blib --force
 
 except that including the :command:`build` command on the command-line means
-that command will be run. Including a particular command in config files has no
-such implication; it only means that if the command is run, the options in the
-config file will apply. (Or if other commands that derive values from it are
-run, they will use the values in the config file.)
+that command will be run. Including a particular command in configuration files
+has no such implication; it only means that if the command is run, the options
+for it in the configuration file will apply. (This is also true if you run
+other commands that derive values from it.)
 
 You can find out the complete list of options for any command using the
 :option:`--help` option, e.g.::
 
 See also the "Reference" section of the "Distributing Python Modules" manual.
 
+.. XXX no links to the relevant section exist.
+
 
 .. _packaging-building-ext: