docs: start with howto section

doc/src/Howto_couple.rst

@@ -36,7 +36,7 @@ the context of your application.
    steps, invoke the command, etc.
 
    In this scenario, the other code can be called as a library, as in
-   1., or it could be a stand-alone code, invoked by a system() call
+   1., or it could be a stand-alone code, invoked by a ``system()`` call
    made by the command (assuming your parallel machine allows one or
    more processors to start up another program).  In the latter case the
    stand-alone code could communicate with LAMMPS through files that the

doc/src/Howto_elastic.rst

@@ -4,21 +4,27 @@ Calculate elastic constants
 Elastic constants characterize the stiffness of a material. The formal
 definition is provided by the linear relation that holds between the
 stress and strain tensors in the limit of infinitesimal deformation.
-In tensor notation, this is expressed as s_ij = C_ijkl \* e_kl, where
+In tensor notation, this is expressed as 
-the repeated indices imply summation. s_ij are the elements of the
+
-symmetric stress tensor. e_kl are the elements of the symmetric strain
+.. math::
-tensor. C_ijkl are the elements of the fourth rank tensor of elastic
+
-constants. In three dimensions, this tensor has 3\^4=81 elements. Using
+   s_{ij} = C_{ijkl} e_{kl}
-Voigt notation, the tensor can be written as a 6x6 matrix, where C_ij
+
-is now the derivative of s_i w.r.t. e_j. Because s_i is itself a
+where
-derivative w.r.t. e_i, it follows that C_ij is also symmetric, with at
+the repeated indices imply summation. :math:`s_{ij}` are the elements of the
-most 7\*6/2 = 21 distinct elements.
+symmetric stress tensor. :math:`e_{kl}` are the elements of the symmetric strain
+tensor. :math:`C_{ijkl}` are the elements of the fourth rank tensor of elastic
+constants. In three dimensions, this tensor has :math:`3^4=81` elements. Using
+Voigt notation, the tensor can be written as a 6x6 matrix, where :math:`C_{ij}`
+is now the derivative of :math:`s_i` w.r.t. :math:`e_j`. Because :math:`s_i` is itself a
+derivative w.r.t. :math:`e_i`, it follows that :math:`C_{ij}` is also symmetric, with at
+most :math:`\frac{7 \times 6}{2}` = 21 distinct elements.
 
 At zero temperature, it is easy to estimate these derivatives by
 deforming the simulation box in one of the six directions using the
 :doc:`change_box <change_box>` command and measuring the change in the
 stress tensor. A general-purpose script that does this is given in the
-examples/ELASTIC directory described on the :doc:`Examples <Examples>`
+``examples/ELASTIC`` directory described on the :doc:`Examples <Examples>`
 doc page.
 
 Calculating elastic constants at finite temperature is more
@@ -33,7 +39,7 @@ the :doc:`compute born/matrix <compute_born_matrix>` command,
 which works for any bonded or non-bonded potential in LAMMPS.
 The most expensive part of the calculation is the sampling of
 the stress fluctuations. Several examples of this method are
-provided in the examples/ELASTIC_T/BORN_MATRIX directory
+provided in the ``examples/ELASTIC_T/BORN_MATRIX`` directory
 described on the :doc:`Examples <Examples>` doc page.
 
 A second way is to measure
@@ -43,7 +49,7 @@ the systematic and statistical errors in this method, the magnitude of
 the deformation must be chosen judiciously, and care must be taken to
 fully equilibrate the deformed cell before sampling the stress
 tensor. An example of this method is provided in the
-examples/ELASTIC_T/DEFORMATION directory
+``examples/ELASTIC_T/DEFORMATION`` directory
 described on the :doc:`Examples <Examples>` doc page.
 
 Another approach is to sample the triclinic cell fluctuations

doc/src/Howto_multiple.rst

@@ -44,7 +44,7 @@ For large numbers of independent simulations, you can use
 :doc:`variables <variable>` and the :doc:`next <next>` and
 :doc:`jump <jump>` commands to loop over the same input script
 multiple times with different settings.  For example, this
-script, named in.polymer
+script, named ``in.polymer``
 
 .. code-block:: LAMMPS
 
@@ -57,7 +57,7 @@ script, named in.polymer
    next d
    jump in.polymer
 
-would run 8 simulations in different directories, using a data.polymer
+would run 8 simulations in different directories, using a ``data.polymer``
 file in each directory.  The same concept could be used to run the
 same system at 8 different temperatures, using a temperature variable
 and storing the output in different log and dump files, for example
@@ -83,10 +83,10 @@ partition of processors.  LAMMPS can be run on multiple partitions via
 the :doc:`-partition command-line switch <Run_options>`.
 
 In the last 2 examples, if LAMMPS were run on 3 partitions, the same
-scripts could be used if the "index" and "loop" variables were
+scripts could be used if the ``index`` and ``loop`` variables were
 replaced with *universe*\ -style variables, as described in the
-:doc:`variable <variable>` command.  Also, the "next t" and "next a"
+:doc:`variable <variable>` command.  Also, the :lammps:`next t` and :lammps:`next a`
-commands would need to be replaced with a single "next a t" command.
+commands would need to be replaced with a single :lammps:`next a t` command.
 With these modifications, the 8 simulations of each script would run
 on the 3 partitions one after the other until all were finished.
 Initially, 3 simulations would be started simultaneously, one on each

doc/src/Howto_restart.rst

@@ -26,8 +26,8 @@ scripts are based on.  If that script had the line
 
    restart         50 tmp.restart
 
-added to it, it would produce 2 binary restart files (tmp.restart.50
+added to it, it would produce two binary restart files (``tmp.restart.50``
-and tmp.restart.100) as it ran.
+and ``tmp.restart.100``) as it ran.
 
 This script could be used to read the first restart file and re-run the
 last 50 timesteps:
@@ -47,21 +47,21 @@ last 50 timesteps:
    run             50
 
 Note that the following commands do not need to be repeated because
-their settings are included in the restart file: *units, atom_style,
+their settings are included in the restart file: :lammps:`units`, :lammps:`atom_style`,
-special_bonds, pair_style, bond_style*.  However, these commands do
+:lammps:`special_bonds`, :lammps:`pair_style`, :lammps:`bond_style`.  However, these commands do
 need to be used, since their settings are not in the restart file:
-*neighbor, fix, timestep*\ .
+:lammps:`neighbor`, :lammps:`fix`, :lammps:`timestep`.
 
 If you actually use this script to perform a restarted run, you will
 notice that the thermodynamic data match at step 50 (if you also put a
-"thermo 50" command in the original script), but do not match at step
+:lammps:`thermo 50` command in the original script), but do not match at step
 100.  This is because the :doc:`fix langevin <fix_langevin>` command
 uses random numbers in a way that does not allow for perfect restarts.
 
 As an alternate approach, the restart file could be converted to a data
 file as follows:
 
-.. code-block:: LAMMPS
+.. code-block:: bash
 
    lmp_g++ -r tmp.restart.50 tmp.restart.data
 
@@ -89,8 +89,8 @@ Then, this script could be used to re-run the last 50 steps:
    reset_timestep  50
    run             50
 
-Note that nearly all the settings specified in the original *in.chain*
+Note that nearly all the settings specified in the original ``in.chain``
-script must be repeated, except the *pair_coeff* and *bond_coeff*
+script must be repeated, except the :lammps:`pair_coeff` and :lammps:`bond_coeff`
 commands, since the new data file lists the force field coefficients.
 Also, the :doc:`reset_timestep <reset_timestep>` command is used to tell
 LAMMPS the current timestep.  This value is stored in restart files, but

doc/src/Howto_viz.rst

@@ -6,7 +6,7 @@ analyzed in a variety of ways.
 
 LAMMPS snapshots are created by the :doc:`dump <dump>` command, which
 can create files in several formats. The native LAMMPS dump format is a
-text file (see "dump atom" or "dump custom") which can be visualized by
+text file (see :lammps:`dump atom` or :lammps:`dump custom`) which can be visualized by
 `several visualization tools <https://www.lammps.org/viz.html>`_ for MD
 simulation trajectories.  `OVITO <https://www.ovito.org>`_ and `VMD
 <https://www.ks.uiuc.edu/Research/vmd>`_ seem to be the most popular