clarify comment handling and parsing. document masses section.

doc/src/molecule.rst

@@ -91,8 +91,8 @@ use that attribute (e.g. no bonds).
 
 .. note::
 
-   Offsets are **ignored** if the molecule file lines using type labels,
+   Offsets are **ignored** on lines using type labels, as the type
-   as the type labels will determine the actual types depending on the
+   labels will determine the actual types directly depending on the
    current :doc:`labelmap <labelmap>` settings.
 
 The *scale* keyword scales the size of the molecule.  This can be
@@ -125,14 +125,18 @@ The format of an individual molecule file is similar but
 (not identical) to the data file read by the :doc:`read_data <read_data>`
 commands, and is as follows.
 
-A molecule file has a header and a body.  The header appears first.
+A molecule file has a header and a body.  The header appears first.  The
-The first line of the header is always skipped; it typically contains
+first line of the header and thus of the molecule file is *always* skipped;
-a description of the file.  Then lines are read one at a time.  Lines
+it typically contains a description of the file or a comment from the software
-can have a trailing comment starting with '#' that is ignored.  If the
+that created the file.
-line is blank (only white-space after comment is deleted), it is
+
+Then lines are read one line at a time.  Lines can have a trailing
+comment starting with '#' that is ignored.  There *must* be at least one
+blank between any valid content and the comment.  If the line is blank
+(i.e. contains only white-space after comments are deleted), it is
 skipped.  If the line contains a header keyword, the corresponding
-value(s) is read from the line.  If it does not contain a header
+value(s) is/are read from the line.  A line that is *not* blank and does
-keyword, the line begins the body of the file.
+*not* contains a header keyword begins the body of the file.
 
 The body of the file contains zero or more sections.  The first line
 of a section has only a keyword.  The next line is skipped.  The

doc/src/read_data.rst

@@ -166,8 +166,8 @@ that attribute (e.g. no bonds).
 
 .. note::
 
-   Offsets are **ignored** for any data file lines using type labels, as
+   Offsets are **ignored** on lines using type labels, as the type
-   the type labels will determine the actual types depending on the
+   labels will determine the actual types directly depending on the
    current :doc:`labelmap <labelmap>` settings.
 
 The *shift* keyword can be used to specify an (Sx, Sy, Sz)
@@ -233,22 +233,27 @@ The file will be read line by line, but there is a limit of 254
 characters per line and characters beyond that limit will be ignored.
 
 A data file has a header and a body.  The header appears first.  The
-first line of the header is always skipped; it typically contains a
+first line of the header and thus of the data file is *always* skipped;
-description of the file.  Then lines are read one at a time.  Lines
+it typically contains a description of the file or a comment from the
-can have a trailing comment starting with '#' that is ignored.  If the
+software that created the file.
-line is blank (only white-space after comment is deleted), it is
-skipped.  If the line contains a header keyword, the corresponding
-value(s) is read from the line.  If it does not contain a header
-keyword, the line begins the body of the file.
 
-The body of the file contains zero or more sections.  The first line
+Then lines are read one line at a time.  Lines can have a trailing
-of a section has only a keyword.  This line can have a trailing
+comment starting with '#' that is ignored.  There *must* be at least one
-comment starting with '#' that is either ignored or can be used to
+blank between any valid content and the comment. If a line is blank
-check for a style match, as described below.  The next line is
+(i.e. contains only white-space after comments are deleted), it is
-skipped.  The remaining lines of the section contain values.  The
+skipped.  If the line contains a header keyword, the corresponding
-number of lines depends on the section keyword as described below.
+value(s) is/are read from the line.  A line that is *not* blank and does
-Zero or more blank lines can be used between sections.  Sections can
+*not* contain a header keyword begins the body of the file.
-appear in any order, with a few exceptions as noted below.
+
+The body of the file contains zero or more sections.  The first line of
+a section has only a keyword.  This line can have a trailing comment
+starting with '#' that is either ignored or can be used to check for a
+style match, as described below.  There must be a blank between the
+keyword and any comment. The *next* line is *always* skipped.  The
+remaining lines of the section contain values.  The number of lines
+depends on the section keyword as described below.  Zero or more blank
+lines can be used *between* sections.  Sections can appear in any order,
+with a few exceptions as noted below.
 
 The keyword *fix* can be used one or more times.  Each usage specifies
 a fix that will be used to process a specific portion of the data
@@ -510,7 +515,8 @@ section is described including the number of lines it must contain and
 rules (if any) for where it can appear in the data file.
 
 Any individual line in the various sections can have a trailing
-comment starting with "#" for annotation purposes.  E.g. in the
+comment starting with "#" for annotation purposes. There must be at least
+one blank between valid content and the comment. E.g. in the
 Atoms section:
 
 .. parsed-literal::
@@ -1324,7 +1330,7 @@ The *Lines* section must appear after the *Atoms* section.
 
   .. parsed-literal::
 
-       ID = atom type (1-N)
+       ID = atom type (1-N or atom type label)
        mass = mass value
 
 * example:
@@ -1338,6 +1344,13 @@ This defines the mass of each atom type.  This can also be set via the
 used for atom styles that define a mass for individual atoms -
 e.g. :doc:`atom_style sphere <atom_style>`.
 
+Using type labels instead of atom type numbers is only allowed if the
+type label has been defined by the :doc:`labelmap <labelmap>` command or
+a Atom Type Labels section earlier in the data file.  See the
+:doc:`Howto type labels <Howto_type_labels>` doc page for the allowed
+syntax of type labels and a general discussion of how type labels can be
+used.
+
 ----------
 
 *MiddleBondTorsion Coeffs* section: