diff --git a/doc/src/region2vmd.rst b/doc/src/region2vmd.rst
index aef8d48d16..c58efc463f 100644
--- a/doc/src/region2vmd.rst
+++ b/doc/src/region2vmd.rst
@@ -8,17 +8,27 @@ Syntax
.. code-block:: LAMMPS
- region2vmd file args
+ region2vmd file keyword arg ...
-* file = name of VMD script file to write
-* args = one or more region IDs may be appended
+* filename = name of file to write VMD script commands to
+* zero or more keyword/arg pairs may be appended
+* keyword = *region* or *color* or *material* or *command*
+
+ .. parsed-literal::
+
+ *region* region-ID = name of region to translate to VMD graphics
+ *color* color-name = set color for following visualized objects
+ *material* material-name = set material for following visualized objects
+ *command* string = string with custom VMD script command (in quotes)
Examples
""""""""
.. code-block:: LAMMPS
- region2vmd regions.vmd box c1 c2
+ region2vmd regions.vmd material Opaque color red region c1 color green region c2
+ region2vmd vizbox.vmd command "mol new system.lammpstrj waitfor all" region box
+ region2vmd regdefs.vmd region upper region lower region hole
Description
"""""""""""
@@ -28,17 +38,106 @@ Description
Write a `VMD `_ Tcl script file with
commands that aim to create a visualization of :doc:`LAMMPS regions
`. There may be multiple region visualizations stored in a
-single file. Only a limited amount of region styles and settings are
-currently supported. See **Restrictions** below.
+single file.
The visualization is implemented by creating a new (and empty) "VMD
-molecule" and then using VMD graphics primitives to represent the region
-in VMD. Each region will be stored in a separate "VMD molecule" with
-the name "LAMMPS region ".
+molecule" and then assigning a sequence of VMD graphics primitives to
+represent the region in VMD. Each region will be stored in a separate
+"VMD molecule" with the name "LAMMPS region ".
+
+The *region2vmd* command is following by the filename for the resulting
+VMD script and an arbitrary number of keyword argument pairs to either
+write out a new *region* visualization, change the *color* or *material*
+setting, or to insert arbitrary VMD script *command*s. The keywords
+and arguments are processed in sequence.
+
+The *region* keyword must be followed by a previously defined LAMMPS
+:doc:`region `. Only a limited set region styles and region
+settings are currently supported. See **Restrictions** below.
+Unsupported region styles or regions with unsupported settings will be
+skipped and a corresponding message is printed.
+
+The *color* keyword must be followed by a color name that is defined in
+VMD. This color will be used by all following region visualizations.
+The default setting is 'silver'. VMD has the following colors
+pre-defined:
+
+.. table_from_list::
+ :columns: 11
+
+ * blue
+ * red
+ * gray
+ * orange
+ * yellow
+ * tan
+ * silver
+ * green
+ * white
+ * pink
+ * cyan
+ * purple
+ * lime
+ * mauve
+ * ochre
+ * iceblue
+ * black
+ * yellow2
+ * yellow3
+ * green2
+ * green3
+ * cyan2
+ * cyan3
+ * blue2
+ * blue3
+ * violet
+ * violet2
+ * magenta
+ * magenta2
+ * red2
+ * red3
+ * orange2
+ * orange3
+
+The *material* keyword must be followed by a material name that is defined in
+VMD. This material will be used by all following visualizations. The
+default setting is 'Transparent'. VMD has the following materials
+pre-defined:
+
+.. table_from_list::
+ :columns: 7
+
+ * Opaque
+ * Transparent
+ * BrushedMetal
+ * Diffuse
+ * Ghost
+ * Glass1
+ * Glass2
+ * Glass3
+ * Glossy
+ * HardPlastic
+ * MetallicPastel
+ * Steel
+ * Translucent
+ * Edgy
+ * EdgyShiny
+ * EdgyGlass
+ * Goodsell
+ * AOShiny
+ * AOChalky
+ * AOEdgy
+ * BlownGlass
+ * GlassBubble
+ * RTChrome
+
+The *command* keyword must be followed by a VMD script command as a
+single string in quotes. This command will be directly inserted into
+the created VMD script.
The created file can be loaded into VMD either from the command line
-with the -e flag, or from the command prompt with play