one more pass at revising the introductory pages of the LAMMPS manual

doc/src/Intro_overview.rst

@@ -29,25 +29,24 @@ versions can be downloaded as source code from the `LAMMPS website
 
 LAMMPS is designed to be easy to modify or extend with new capabilities,
 such as new force fields, atom types, boundary conditions, or
-diagnostics.  See the :doc:`Modify <Modify>` page for more details.
+diagnostics.  See the :doc:`Modify` section of for more details.
 
 In the most general sense, LAMMPS integrates Newton's equations of
-motion for a collection of interacting particles.  A single particle
-can be an atom or molecule or electron, a coarse-grained cluster of
-atoms, or a mesoscopic or macroscopic clump of material.  The
-interaction models that LAMMPS includes are mostly short-range in
-nature; some long-range models are included as well.
+motion for a collection of interacting particles.  A single particle can
+be an atom or molecule or electron, a coarse-grained cluster of atoms,
+or a mesoscopic or macroscopic clump of material.  The interaction
+models that LAMMPS includes are mostly short-ranged in nature; some
+long-range models are included as well.
 
-LAMMPS uses neighbor lists to keep track of nearby particles.  The
-lists are optimized for systems with particles that are repulsive at
-short distances, so that the local density of particles never becomes
-too large.  This is in contrast to methods used for modeling plasma
-or gravitational bodies (e.g. galaxy formation).
+LAMMPS uses neighbor lists to keep track of nearby particles.  The lists
+are optimized for systems with particles that are repulsive at short
+distances, so that the local density of particles never becomes too
+large.  This is in contrast to methods used for modeling plasma or
+gravitational bodies (e.g. galaxy formation).
 
 On parallel machines, LAMMPS uses spatial-decomposition techniques with
-MPI parallelization to partition the simulation domain into small
-sub-domains of equal computational cost, one of which is assigned to
-each processor.  Processors communicate and store "ghost" atom
-information for atoms that border their sub-domain.  Multi-threading
-parallelization and GPU acceleration with with particle-decomposition
-can be used in addition.
+MPI parallelization to partition the simulation domain into sub-domains
+of equal computational cost, one of which is assigned to each processor.
+Processors communicate and store "ghost" atom information for atoms that
+border their sub-domain.  Multi-threading parallelization and GPU
+acceleration with with particle-decomposition can be used in addition.

doc/src/Manual.rst

@@ -23,27 +23,33 @@ coordinated.
 ----------
 
 The content for this manual is part of the LAMMPS distribution.  The
-online version always corresponds to the latest development version.
-If needed, you can download or build a local copy of the manual as
-HTML pages or a PDF file by following the steps on the
-:doc:`Build_manual` page. If you have difficulties viewing the pages
-please :ref:`see this note <webbrowser>`.
+online version always corresponds to the latest feature release version.
+If needed, you can build a local copy of the manual as HTML pages or a
+PDF file by following the steps on the :doc:`Build_manual` page.  If you
+have difficulties viewing the pages please :ref:`see this note
+<webbrowser>`.
 
 -----------
 
 The manual is organized in three parts:
-1) the :ref:`User Guide <user_documentation>` for how to install
-and use LAMMPS, 2) the :ref:`Programmer Guide <programmer_documentation>`
-for how to write programs using the LAMMPS library from different
-programming languages and how to modify and extend LAMMPS, and 3) the
-:ref:`Command Reference <command_reference>` which includes detailed
-descriptions of all commands included in the LAMMPS code.
+
+1. the :ref:`User Guide <user_documentation>` with information about how
+   to obtain, configure, compile, install, and use LAMMPS,
+2. the :ref:`Programmer Guide <programmer_documentation>` with
+   information about how to use the LAMMPS library interface from
+   different programming languages, how to modify and extend LAMMPS,
+   the program design, internal programming interfaces, and code
+   design conventions,
+3. the :ref:`Command Reference <command_reference>` with detailed
+   descriptions of all input script commands available in LAMMPS.
+
+----------
 
 .. only:: html
 
    Once you are familiar with LAMMPS, you may want to bookmark
-   :doc:`this page <Commands_all>` since it gives quick access to
-   the documentation for all LAMMPS commands.
+   :doc:`this page <Commands_all>`, since it gives quick access to
+   tables with links to the documentation for all LAMMPS commands.
 
 .. _lws: https://www.lammps.org
 

doc/src/Manual_version.rst

@@ -6,38 +6,49 @@ The LAMMPS "version" is the date when it was released, such as 1 May
 correctly and reliably at all times.  You can follow its development
 in a public `git repository on GitHub <https://github.com/lammps/lammps>`_.
 
-Whenever we fix a bug or update or add a feature, it will be merged into
-the *develop* branch of the git repository.  When a sufficient number of
-changes have accumulated *and* the software passes a set of automated
-tests, we release it in the next *patch* release, which are made every
-few weeks.  The *release* branch of the git repository is updated with
-every such release.  Info on patch releases are on `this website page
-<https://www.lammps.org/bug.html>`_.
+Modifications of the LAMMPS source code - like bug fixes, code
+refactors, updates to existing features, or addition of new features -
+are organized into pull requests, and will be merged into the *develop*
+branch of the git repository when they pass automated testing and code
+review by the LAMMPS developers.  When a sufficient number of changes
+have accumulated *and* the software passes a set of automated tests, we
+release it as a *feature release* (or patch release), which are
+currently made every 4-8 weeks.  The *release* branch of the git
+repository is updated with every such release.  A summary of the most
+important changes of the patch releases are on `this website page
+<https://www.lammps.org/bug.html>`_.  More detailed release notes are
+`available on GitHub <https://github.com/lammps/lammps/releases/>`_.
 
-Once or twice a year, we have a period where we apply only bug fixes and
-small, non-intrusive changes to the *develop* branch and the code is at
-the same time subjected to more detailed and thorough manual testing
-than the default automated testing.  The latest patch release after such
-a period is then also labeled as a *stable* version and the *stable*
-branch is updated with it.  Between stable releases we occasionally
-release some updates to the stable release containing only bug fixes and
-updates back-ported from *develop* but no new features and update the
-*stable* branch accordingly.
+Once or twice a year, we have a "stabilization period" where we apply
+only bug fixes and small, non-intrusive changes to the *develop*
+branch.  At the same time the code is subjected to more detailed and
+thorough manual testing than the default automated testing.  Also
+several variants of static code analysis are run to improve the overall
+code quality, consistency, and compliance with programming standards,
+best practices and style conventions.
+
+The latest patch release after such a period is then also labeled as a
+*stable* version and the *stable* branch is updated with it.  Between
+stable releases we occasionally release updates to the stable release
+containing only bug fixes and updates back-ported from the *develop*
+branch and update the *stable* branch accordingly.
 
 Each version of LAMMPS contains all the documented features up to and
 including its version date.  For recently added features we add markers
-to the documentation at which specific LAMMPS version a feature was
-added or significantly changed.
+to the documentation at which specific LAMMPS version a feature or
+keyword was added or significantly changed.
 
-The version date is printed to the screen and logfile every time you
-run LAMMPS. It is also in the file src/version.h and in the LAMMPS
+The version date is printed to the screen and logfile every time you run
+LAMMPS.  It is also in the file src/version.h and in the LAMMPS
 directory name created when you unpack a tarball.  And it is on the
 first page of the :doc:`manual <Manual>`.
 
-* If you browse the HTML pages on the LAMMPS WWW site, they will by
-  default describe the most current patch release version of LAMMPS.
-  In the navigation bar on the bottom left, there is the option to
-  view instead the documentation for the most recent *stable* version
-  or the latest version from the current development branch.
-* If you browse the HTML pages included in your tarball, they
-  describe the version you have, which may be older.
+* If you browse the HTML pages of the online version of the LAMMPS
+  manual, they will by default describe the most current patch release
+  version of LAMMPS.  In the navigation bar on the bottom left, there is
+  the option to view instead the documentation for the most recent
+  *stable* version or the documentation corresponding to the state of
+  the development branch.
+* If you browse the HTML pages included in your downloaded tarball, they
+  describe the version you have, which may be older than the online
+  version.

doc/utils/sphinx-config/false_positives.txt

@@ -3009,6 +3009,7 @@ recursing
 Ree
 refactored
 refactoring
+refactors
 reflectionstyle
 Reinders
 reinit