From bf3e7237c31df663c62a3dca8977de0fc5878299 Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Fri, 21 Feb 2020 15:08:18 -0500 Subject: [PATCH] replace dir with directory where appropriate --- doc/src/Build_package.rst | 2 +- doc/src/Build_settings.rst | 2 +- doc/src/Howto.rst | 2 +- doc/src/Howto_client_server.rst | 2 +- doc/src/Install_git.rst | 21 +++++---- doc/src/Install_patch.rst | 10 ++--- doc/src/Install_svn.rst | 8 ++-- doc/src/Manual_build.rst | 36 +++++++++------- doc/src/Modify_contribute.rst | 75 ++++++++++++++++----------------- doc/src/Modify_overview.rst | 18 ++++---- doc/src/fix_client_md.rst | 2 +- doc/src/pair_polymorphic.rst | 4 +- 12 files changed, 92 insertions(+), 90 deletions(-) diff --git a/doc/src/Build_package.rst b/doc/src/Build_package.rst index 783ae4c28c..d051bee621 100644 --- a/doc/src/Build_package.rst +++ b/doc/src/Build_package.rst @@ -242,4 +242,4 @@ Type "make package-overwrite" to overwrite files in the package sub-directories with src files. Type "make package-diff" to list all differences between pairs of -files in both the src dir and a package dir. +files in both the source directory and the package directory. diff --git a/doc/src/Build_settings.rst b/doc/src/Build_settings.rst index 2035f50cb9..1427f0eab7 100644 --- a/doc/src/Build_settings.rst +++ b/doc/src/Build_settings.rst @@ -307,7 +307,7 @@ As with CMake, you do not need to set JPG\_INC or JPG\_PATH, if make can find the graphics header and library files. You must specify JPG\_LIB with a list of graphics libraries to include in the link. You must insure ffmpeg is in a directory where LAMMPS can find it at runtime, -i.e. a dir in your PATH environment variable. +that is a directory in your PATH environment variable. **CMake and make info**\ : diff --git a/doc/src/Howto.rst b/doc/src/Howto.rst index 3a36c82674..eb764342a0 100644 --- a/doc/src/Howto.rst +++ b/doc/src/Howto.rst @@ -5,7 +5,7 @@ These doc pages describe how to perform various tasks with LAMMPS, both for users and developers. The `glossary `_ website page also lists MD terminology with links to corresponding LAMMPS manual pages. The -example input scripts included in the examples dir of the LAMMPS +example input scripts included in the examples directory of the LAMMPS distribution and highlighted on the :doc:`Examples ` doc page also show how to setup and run various kinds of simulations. diff --git a/doc/src/Howto_client_server.rst b/doc/src/Howto_client_server.rst index f2c6b6ce8b..b6bcaa686c 100644 --- a/doc/src/Howto_client_server.rst +++ b/doc/src/Howto_client_server.rst @@ -97,7 +97,7 @@ client or server code: * examples/COUPLE/lammps\_nwchem * examples/COUPLE/lammps\_vasp -The examples/message dir couples a client instance of LAMMPS to a +The examples/message directory couples a client instance of LAMMPS to a server instance of LAMMPS. The files in the *lammps\_mc* folder show how to couple LAMMPS as diff --git a/doc/src/Install_git.rst b/doc/src/Install_git.rst index b1987bcd21..03c3494c3f 100644 --- a/doc/src/Install_git.rst +++ b/doc/src/Install_git.rst @@ -1,5 +1,5 @@ -Download source via Git -======================= +Download the LAMMPS source with Git +=================================== All LAMMPS development is coordinated through the "LAMMPS GitHub site". If you clone the LAMMPS repository onto your local machine, it @@ -16,13 +16,12 @@ the public Git server for LAMMPS. .. warning:: - As of Oct 2016, the official home of public LAMMPS - development is on GitHub. The previously advertised LAMMPS git - repositories on git.lammps.org and bitbucket.org are now deprecated, - may not be up-to-date, and may go away at any time. - -.. _git: http://git-scm.com + As of October 2016, the official home of public LAMMPS development is + on GitHub. The previously advertised LAMMPS git repositories on + git.lammps.org and bitbucket.org are now deprecated, may not be + up-to-date, and may go away at any time. +.. _git: https://git-scm.com You can follow LAMMPS development on 3 different Git branches: @@ -107,15 +106,15 @@ after a patch has been installed. If you wish to edit/change a src file that is from a package, you should edit the version of the file inside the package sub-directory with src, then re-install the package. The version in - the src dir is merely a copy and will be wiped out if you type "make + the source directory is merely a copy and will be wiped out if you type "make package-update". .. warning:: The GitHub servers support both the "git://" and "https://" access protocols for anonymous read-only access. If you - have a correspondingly configured GitHub account, you may also use SSH - with "git@github.com:/lammps/lammps.git". + have a correspondingly configured GitHub account, you may also use + passwordless SSH access with the URL "git@github.com:lammps/lammps.git". The LAMMPS GitHub project is managed by Christoph Junghans (LANL, junghans at lanl.gov), Axel Kohlmeyer (Temple U, akohlmey at diff --git a/doc/src/Install_patch.rst b/doc/src/Install_patch.rst index 7569b0b146..4c9151e348 100644 --- a/doc/src/Install_patch.rst +++ b/doc/src/Install_patch.rst @@ -56,8 +56,8 @@ up to date. .. warning:: - If you wish to edit/change a src file that is from a - package, you should edit the version of the file inside the package - sub-dir of src, then re-install the package. The version in the src - dir is merely a copy and will be wiped out if you type "make - package-update". + If you wish to edit/change a source file that is part of a package, + you should edit the version of the file inside the package folder in + src, and then re-install or update the package. The version in the + src directory is merely a copy and will be wiped out when you type + "make package-update". diff --git a/doc/src/Install_svn.rst b/doc/src/Install_svn.rst index 42d5d2e855..6103ba5ea5 100644 --- a/doc/src/Install_svn.rst +++ b/doc/src/Install_svn.rst @@ -85,10 +85,10 @@ after a patch has been installed. .. warning:: - If you wish to edit/change a src file that is from a - package, you should edit the version of the file inside the package - sub-directory with src, then re-install the package. The version in - the src dir is merely a copy and will be wiped out if you type "make + If you wish to edit/change a source file that is from a package, you + should edit the version of the file inside the package sub-directory + with src, then re-install the package. The version in the src + directory is merely a copy and will be wiped out if you type "make package-update". The LAMMPS GitHub project is managed by Christoph Junghans (LANL, diff --git a/doc/src/Manual_build.rst b/doc/src/Manual_build.rst index 22160a4d88..28e5c49666 100644 --- a/doc/src/Manual_build.rst +++ b/doc/src/Manual_build.rst @@ -22,25 +22,27 @@ If you downloaded LAMMPS from the public SVN or Git repositories, then the HTML and PDF files are not included. Instead you need to create them, in one of two ways: -a. You can "fetch" the current HTML and PDF files from the LAMMPS web site. - Just type "make fetch". This should create a html\_www dir and - Manual\_www.pdf/Developer\_www.pdf files. Note that if new LAMMPS features - have been added more recently than the date of your version, the fetched - documentation will include those changes (but your source code will not, unless - you update your local repository). +a. You can "fetch" the current HTML and PDF files from the LAMMPS web + site. Just type "make fetch". This should download a html\_www + directory and Manual\_www.pdf/Developer\_www.pdf files. Note that if + new LAMMPS features have been added more recently than the date of + your LAMMPS version, the fetched documentation will include those + changes (but your source code will not, unless you update your local + repository). -b. You can build the HTML and PDF files yourself, by typing "make - html" followed by "make pdf". This requires various tools including +b. You can build the HTML and PDF files yourself, by typing "make html" + followed by "make pdf". This requires various tools including Sphinx, which the build process will attempt to download and install - into a virtual environment in the folder doc/docenv, if not already - available. See more details below. To generate the PDF version of - the manual, additionally PDFLaTeX and several LaTeX packages are required. + automatically into a virtual environment in the folder doc/docenv, if + not already available. See more details below. To generate the PDF + version of the manual, additionally the PDFLaTeX software and several + LaTeX packages are required. ---------- The generation of all documentation is managed by the Makefile in -the doc dir. +the doc directory. .. code-block:: bash @@ -60,7 +62,6 @@ the doc dir. make style_check # check for complete and consistent style lists make spelling # spell-check the manual - ---------- @@ -127,11 +128,14 @@ Installing prerequisites for epub build ePUB ---- -Same as for HTML. This uses the same tools and configuration -files as the HTML tree. +Same as for HTML. This uses mostly the same tools and configuration +files as the HTML tree. In addition it uses LaTeX to convert embedded +math expressions transparently into embedded images. For converting the generated ePUB file to a MOBI format file -(for e-book readers like Kindle, that cannot read ePUB), you +(for e-book readers, like Kindle, that cannot read ePUB), you also need to have the 'ebook-convert' tool from the "calibre" software installed. `http://calibre-ebook.com/ `_ You first create the ePUB file and then convert it with 'make mobi' +On the Kindle readers in particular, you also have support for +PDF files, so you could download and view the PDF version as an alternative. diff --git a/doc/src/Modify_contribute.rst b/doc/src/Modify_contribute.rst index 5e20d5c6bb..0fd333b568 100644 --- a/doc/src/Modify_contribute.rst +++ b/doc/src/Modify_contribute.rst @@ -77,15 +77,16 @@ one or more new class files which are invoked as a new style within a LAMMPS input script. If designed correctly, these additions typically do not require changes to the main core of LAMMPS; they are simply add-on files. If you think your new feature requires non-trivial -changes in core LAMMPS files, you'll need to `communicate with the developers `_, since we may or may -not want to make those changes. An example of a trivial change is -making a parent-class method "virtual" when you derive a new child -class from it. +changes in core LAMMPS files, you should `communicate with the +developers `_, since we may or +may not want to include those changes for some reason. An example of a +trivial change is making a parent-class method "virtual" when you derive +a new child class from it. Here is a checklist of steps you need to follow to submit a single file or user package for our consideration. Following these steps will save -both you and us time. See existing files in packages in the src dir for -examples. If you are uncertain, please ask. +both you and us time. Please have a look at the existing files in +packages in the src directory for examples. If you are uncertain, please ask. * All source files you provide must compile with the most current version of LAMMPS with multiple configurations. In particular you @@ -146,41 +147,39 @@ examples. If you are uncertain, please ask. would be nice for developers as well as users who try to read your code. -* You **must** also create a **documentation** file for each new command or - style you are adding to LAMMPS. For simplicity and convenience, the +* You **must** also create a **documentation** file for each new command + or style you are adding to LAMMPS. For simplicity and convenience, the documentation of groups of closely related commands or styles may be combined into a single file. This will be one file for a single-file feature. For a package, it might be several files. These are text - files with a .rst extension using the - `reStructuredText `_ markup language, that are then converted to HTML - and PDF using the `Sphinx `_ documentation - generator tool. Running Sphinx with the included configuration - requires Python 3.x. Configuration - settings and custom extensions for this conversion are included in - the source distribution, and missing python packages will be - transparently downloaded into a virtual environment via pip. Thus, - if your local system is missing required packages, you need access - to the internet. The translation can be as simple as doing - "make html pdf" in the doc folder. - As appropriate, the text files can include inline mathematical - expression or figures (see doc/JPG for examples). Additional PDF - files with further details (see doc/PDF for examples) may also be - included. The doc page should also include literature citations as - appropriate; see the bottom of doc/fix\_nh.rst for examples and - the earlier part of the same file for how to format the cite itself. - Citation labels must be unique across all .rst files. - The "Restrictions" section of the doc page should indicate if - your command is only available if LAMMPS is built with the - appropriate USER-MISC or USER-FOO package. - See other user package doc files for examples of how to do this. - Please run at least "make html" and carefully inspect and proofread - the resulting HTML format doc page before submitting your code. - Upon submission of a pull request, checks for error free completion - of the HTML and PDF build will be performed and also a spell check, - a check for correct anchors and labels, and a check for completeness - of references all styles in their corresponding tables and lists is - run. In case the spell check reports false positives they can be - added to the file doc/utils/sphinx-config/false_positives.txt + files with a .rst extension using the `reStructuredText `_ + markup language, that are then converted to HTML and PDF using the + `Sphinx `_ documentation generator tool. Running Sphinx with + the included configuration requires Python 3.x. Configuration + settings and custom extensions for this conversion are included in the + source distribution, and missing python packages will be transparently + downloaded into a virtual environment via pip. Thus, if your local + system is missing required packages, you need access to the + internet. The translation can be as simple as doing "make html pdf" in + the doc folder. As appropriate, the text files can include inline + mathematical expression or figures (see doc/JPG for examples). + Additional PDF files with further details (see doc/PDF for examples) + may also be included. The doc page should also include literature + citations as appropriate; see the bottom of doc/fix\_nh.rst for + examples and the earlier part of the same file for how to format the + cite itself. Citation labels must be unique across all .rst files. + The "Restrictions" section of the doc page should indicate if your + command is only available if LAMMPS is built with the appropriate + USER-MISC or USER-FOO package. See other user package doc files for + examples of how to do this. Please run at least "make html" and "make + spelling" and carefully inspect and proofread the resulting HTML + format doc page before submitting your code. Upon submission of a + pull request, checks for error free completion of the HTML and PDF + build will be performed and also a spell check, a check for correct + anchors and labels, and a check for completeness of references all + styles in their corresponding tables and lists is run. In case the + spell check reports false positives they can be added to the file + doc/utils/sphinx-config/false_positives.txt * For a new package (or even a single command) you should include one or more example scripts demonstrating its use. These should run in no diff --git a/doc/src/Modify_overview.rst b/doc/src/Modify_overview.rst index 33d8b0e2ff..9e60702046 100644 --- a/doc/src/Modify_overview.rst +++ b/doc/src/Modify_overview.rst @@ -10,15 +10,15 @@ computations are written in vanilla C-style code and operate on simple C-style data structures (vectors and arrays). Most of the new features described on the :doc:`Modify ` doc -page require you to write a new C++ derived class (except for -exceptions described below, where you can make small edits to existing -files). Creating a new class requires 2 files, a source code file -(\*.cpp) and a header file (\*.h). The derived class must provide -certain methods to work as a new option. Depending on how different -your new feature is compared to existing features, you can either -derive from the base class itself, or from a derived class that -already exists. Enabling LAMMPS to invoke the new class is as simple -as putting the two source files in the src dir and re-building LAMMPS. +page require you to write a new C++ derived class (except for exceptions +described below, where you can make small edits to existing files). +Creating a new class requires 2 files, a source code file (\*.cpp) and a +header file (\*.h). The derived class must provide certain methods to +work as a new option. Depending on how different your new feature is +compared to existing features, you can either derive from the base class +itself, or from a derived class that already exists. Enabling LAMMPS to +invoke the new class is as simple as putting the two source files in the +src directory and re-building LAMMPS. The advantage of C++ and its object-orientation is that all the code and variables needed to define the new feature are in the 2 files you diff --git a/doc/src/fix_client_md.rst b/doc/src/fix_client_md.rst index 85b0762d21..f274341a68 100644 --- a/doc/src/fix_client_md.rst +++ b/doc/src/fix_client_md.rst @@ -61,7 +61,7 @@ specify boundary conditions or force constraints in the usual way, which will be added to the per-atom forces returned by the server code. -See the examples/message dir for example scripts where LAMMPS is both +See the examples/message directory for example scripts where LAMMPS is both the "client" and/or "server" code for this kind of client/server MD simulation. The examples/message/README file explains how to launch LAMMPS and another code in tandem to perform a coupled simulation. diff --git a/doc/src/pair_polymorphic.rst b/doc/src/pair_polymorphic.rst index d623480a85..c0cb35f8d1 100644 --- a/doc/src/pair_polymorphic.rst +++ b/doc/src/pair_polymorphic.rst @@ -114,8 +114,8 @@ LAMMPS atom types: See the pair\_coeff doc page for alternate ways to specify the path for the potential file. Several files for polymorphic potentials are -included in the potentials dir of the LAMMPS distribution. They have a -"poly" suffix. +included in the potentials directory of the LAMMPS distribution. They +have a "poly" suffix. As an example, imagine the SiC\_tersoff.polymorphic file has tabulated functions for Si-C tersoff potential. If your LAMMPS simulation has 4