Apply suggestions from @gonuke

Co-authored-by: Paul Wilson <[email protected]>

docs/CMakeLists.txt

@@ -14,5 +14,5 @@ if (DOXYGEN_FOUND)
   configure_file(${CMAKE_CURRENT_SOURCE_DIR}/requirements.txt ${CMAKE_CURRENT_BINARY_DIR}/requirements.txt COPYONLY)
   configure_file(${CMAKE_CURRENT_SOURCE_DIR}/make.bat ${CMAKE_CURRENT_BINARY_DIR}/make.bat COPYONLY)
 else()
-  message(WARNING "Doxygen is required to build the documentation for double-down.")
+  message(WARNING "Doxygen is required to build the documentation for DAGMC.")
 endif()

docs/filespec/h5m_file_spec.rst

@@ -13,7 +13,7 @@ Geometric EntitySets¶
 ---------------------
 
 For an `.h5m` file to be used with :term:`DAGMC`, :term:`EntitySet`'s that are
-"tagged" specific information must be present. Only :term:`EntitySet`'s that are
+"tagged" with specific information must be present. Only :term:`EntitySet`'s that are
 tagged with the required information will be "seen" by the :term:`DAGMC`
 interface. These tags are used to identify the geometric entities (volumes,
 surfaces, curves, and vertices) as well as their relationships to each other.
@@ -50,6 +50,7 @@ to the transport code you intened to use.
 |                       |                  |            |      |             | indicates tht the surafce has a sense that is forward with respect to                                        |
 |                       |                  |            |      |             | the volume `EntityHandle` in that position. An entry in the second position                                  |
 |                       |                  |            |      |             | indicates that the surface has a sense reversed with respect to the volume `EntityHandle` in that position.  |
+|                       |                  |            |      |             | Only relevant for `EntitySet`s that represent a surface.                  |
 +-----------------------+------------------+------------+------+-------------+--------------------------------------------------------------------------------------------------------------+
 | `GEOM_SENSE_N_ENTS`   | `EntityHandle`   | `uint64_t` | N    | `EntitySet` | Relates a curve to any topologically adjacent surface `EntitySet`s.                                          |
 +-----------------------+------------------+------------+------+-------------+--------------------------------------------------------------------------------------------------------------+
@@ -123,4 +124,4 @@ Each surface is tagged with the two volume handles of the adjacent
 volumes. The first of the two surfaces is designated as the forward direction
 and the second is designated with the reverse direction. It is important to note
 that these surfaces senses may not be consistent with how an MC code determines
-the surface sense.
+the surface sense.  The surfaces are also expected to have a parent-child relationship to each of those volumes.

docs/theoryguide/understanding_ray_history.rst

@@ -3,23 +3,24 @@ Understanding ray history state in DAG-MCNP5/6
 
 Note that all the information here applies to both DAG-MCNP5 and DAG-MCNP6.
 
+DAGMC uses a ray history to improve robustness against situations when floating point arithmetic and logical comparisons can result in inconsistent or ambiguous outcomes.  The ray history is a list of facets that were crosses since the last collision/change in direction of the particle.
 Documenting calls to the track() method in MCNP
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The method used in MCNP to find the distance to the next boundary is
-track().  DAGMC completely circumvents any call to track() and uses
+`subroutine track()`.  DAGMC completely circumvents any call to `track()` and uses
 its own version.
 
 As a first step to understanding the generic set of use cases for the
 ray-to-boundary method, and in particular, the different states of the
 physics code during these uses cases, this document will itemize these
 cases for MCNP.
 
-1. (hstory.F90): non-forced collision neutral particle transport
-2. (hstory.F90): forced collision neutral particle transport
-3. (tally.F90): tracking to tally segmenting surface (not relevant for DAGMC)
-4. (transm.F90): optical thickness of material for point detector/dxtran
-5. (electr.F90): electron substep transport  (also in the updated electron_history.F90)
+1. (`hstory.F90`): non-forced collision neutral particle transport
+2. (`hstory.F90`): forced collision neutral particle transport
+3. (`tally.F90`): tracking to tally segmenting surface (not relevant for DAGMC)
+4. (`transm.F90`): optical thickness of material for point detector/dxtran
+5. (`electr.F90`): electron substep transport  (also in the updated electron_history.F90)
 
 Mapping the possible ray history states
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -37,7 +38,7 @@ There are 2 circumstances that reset a ray history:
     * a change in direction other than reflection
         * note that during reflection, the previous direction is changed
           to make it look like a boundary crossing/streaming event
-          (dagmc_surf_reflection)
+          (`dagmc_surf_reflection`)
 
 During reflection, we reset the history to the last interaction,
 erasing the tail except for the last facet.
@@ -47,12 +48,12 @@ It is also possible to rollback the history removing the most recent interaction
 Other history state variables
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-* visited_surface (bool)
+* `visited_surface` (bool)
     * turned on when a surface interaction is handled either in surface crossing or reflection
     * turned off immediately following the next ray fire
-* last_uvw (unit direction vector)
+* `last_uvw` (unit direction vector)
     * set during reflection to spoof a surface crossing
     * set following every ray fire to record direction of last ray_fire
     * note: not reset for each history because is not used until after
       the first ray_fire in each history
-* last_nps (int)
+* `last_nps` (int)