Enable COLVARS_LEPTON for make, update build doc for USER-COLVARS

doc/src/Build_extras.txt

@@ -642,33 +642,61 @@ make lib-linalg args="-m gfortran"  # build with GNU Fortran compiler :pre
 
 USER-COLVARS package :h4,link(user-colvars)
 
+This package includes into the LAMMPS distribution the Colvars library, which
+can be built for the most part with all major versions of the C++ language.
+
+A few of the most recent features require C++11 support.  In particular, the
+library is optionally built together with the
+"Lepton"_https://simtk.org/projects/lepton library, a copy of which is also
+included in the LAMMPS distribution.  Lepton implements the
+"customFunction"_http://colvars.github.io/colvars-refman-lammps/colvars-refman-lammps.html#colvar|customFunction
+feature, and requires C++11 support.
+
+See "here"_https://colvars.github.io/README-c++11.html for a detailed list of
+C++11-only features.
+
 [CMake build]:
 
-The USER-COLVARS package requires the use of a C++11 compiler to compile
-the included Lepton library. You can set the flag "-D COLVARS_LEPTON=no"
-in addition to "-D PKG_USER-COLVARS=yes" in order to instruct CMake to
-skip building and including the Lepton library into the USER-COLVARS code.
+This is the recommended build recipe: no additional settings are normally
+needed besides "-D PKG_USER-COLVARS=yes".
+
+Building and linking of Lepton (or other C++11-only features) is enabled
+automatically when compilation is carried out with C++11 support, and disabled
+otherwise.  Optionally, Lepton build may be manually controlled with the flag
+"-D COLVARS_LEPTON=yes|no".
 
 [Traditional make]:
 
-Before building LAMMPS, you must build the COLVARS library in
-lib/colvars.  You can do this manually if you prefer; follow the
-instructions in lib/colvars/README.  You can also do it in one step
-from the lammps/src dir, using a command like these, which simply
-invoke the lib/colvars/Install.py script with the specified args:
+Before building LAMMPS, one must build the Colvars library in lib/colvars.
+
+This can be done manually in the same folder by using or adapting one of the
+provided Makefiles: for example, Makefile.g++ for the GNU compiler.
+
+In general, it is safer to use build setting consistent with the rest of
+LAMMPS.  This is best carried out from the LAMMPS src directory using a
+command like these, which simply invoke the lib/colvars/Install.py script with
+the specified args:
 
 make lib-colvars                      # print help message
 make lib-colvars args="-m serial"     # build with GNU g++ compiler (settings as with "make serial")
 make lib-colvars args="-m mpi"        # build with default MPI compiler (settings as with "make mpi")
 make lib-colvars args="-m g++-debug"  # build with GNU g++ compiler and colvars debugging enabled :pre
 
-The build should produce two files: lib/colvars/libcolvars.a and
-lib/colvars/Makefile.lammps.  The latter is copied from an existing
-Makefile.lammps.* and has settings needed to build LAMMPS with the
-COLVARS library (though typically the settings are just blank).  If
-necessary, you can edit/create a new lib/colvars/Makefile.machine file
-for your system, which should define an EXTRAMAKE variable to specify
-a corresponding Makefile.lammps.machine file.
+The "machine" argument of the "-m" flag is used to find a Makefile.machine to
+use as build recipe.  If it does not already exist in lib/colvars, it will be
+auto-generated by using compiler flags consistent with those parsed from the
+core LAMMPS makefiles.
+
+Optional flags may be specified as environment variables:
+
+COLVARS_DEBUG=yes make lib-colvars args="-m machine"  # Build with debug code (much slower)
+COLVARS_LEPTON=no make lib-colvars args="-m machine"  # Build without Lepton (included otherwise)
+
+The build should produce two files: the library lib/colvars/libcolvars.a
+(which also includes Lepton objects if enabled) and the specification file
+lib/colvars/Makefile.lammps.  The latter is auto-generated, and normally does
+not need to be edited.
+
 
 :line