explain EEI and other improvements to before.rst

also add some color
thanks Ryan Jaskiel
some typos
begin replacing "unfocused" with "collimated"
some more references to things and people
make a proper table out of reference wheel table

docs/_static/color.css

@@ -8,6 +8,10 @@
 /* Colors and text decoration.
  For example, :black:`text in black` or :blink:`text blinking` in rST. */
 
+.brown {
+    color: brown;
+}
+
 .black {
     color: black;
 }
@@ -39,6 +43,9 @@
 .magenta {
     color: magenta;
 }
+.hlmagenta {
+    background-color: magenta;
+}
 
 .fuchsia {
     color: fuchsia;
@@ -55,6 +62,9 @@
 .yellow {
     color: yellow;
 }
+.hlyellow {
+    background-color: yellow;
+}
 
 .lime {
     color: lime;
@@ -75,6 +85,9 @@
 .cyan {
     color: cyan;
 }
+.hlcyan {
+    background-color: cyan;
+}
 
 .aqua {
     color: aqua;
@@ -83,6 +96,10 @@
 .blue {
     color: blue;
 }
+.hlblue {
+    color: white;
+    background-color: blue;
+}
 
 .navy {
     color: navy;

docs/before.rst

@@ -12,6 +12,20 @@
 Before your Beamtime
 ====================
 
+This page is a check list of things each user must do before beamtime
+at BMM.  Several tasks on this page are called out in caution boxes
+that look like this:
+
+.. caution::
+
+   This is a caution box.
+
+The tl;dr for this page is: *do all the things in all the caution
+boxes.*
+
+Failure to do all the tasks in caution boxes will result in delay or
+cancellation of your experiment.
+
 Register for BNL Site Access
 ----------------------------
 
@@ -138,50 +152,60 @@ Training
 --------
 
 Please complete all required online user training at least one week
-before the starting date.  Failure to complete training will result in a
-delay starting your experiment.
+before the starting date.  
 
 To complete your training, follow the training instructions at:
-https://www.bnl.gov/ps/userguide/beforearrival.php
+https://www.bnl.gov/nsls2/userguide/before-arrival.php#step2
+
+.. caution::
+
+   Failure to complete training will result in a delay starting your
+   experiment.
 
 
 Electrical Equipment
 --------------------
 
 Any equipment with an electrical cable including low-voltage
 instruments and sample holderss are considered electrical equipment
-(laptop computers are excluded). 
+(laptop computers are excluded) and are subject to an electrical
+equipment inspection (EEI).
+
+If you plan to bring electrical equipment for your experiment, go to
+http://bit.ly/m/eei to fill out the EEI request form.
+
+The EEI request form includes questions describing the user supplied
+equipment, thus is a chore better suited for the user who has
+knowledge of the equipment coming to the beamline.
 
-If you plan to bring electrical equipment for your experiment, please
-contact Jerome Malley, Electrical Equipment Inspection (EEI) Manager
-at malley@bnl.gov as soon as practical and at least two weeks before
-the start of your experiment.  Be prepared to provide manuals, photos,
-electrical diagrams, and schematics.
+.. caution:: Failure to schedule an EEI will result in a delay to your
+	     experiment.  Equipment that cannot pass EEI may not be used
+	     at NSLS-II.
 
-Please include beamline staff (Bruce Ravel <bravel@bnl.gov> for all
-experiments; Vesna Stanic <vstanic@bnl.gov> & Jean Jordan-Sweet
-<jlj@bnl.gov> for XRD experiments) in your communication as some
-pre-approved electrical equipment (e.g., potentiostat, heaters,
-temperature meters, and controllers) may be available at the beamline.
+Note that some pre-approved electrical equipment (e.g., potentiostat,
+heaters, temperature meters, and controllers) is available at the
+beamline.
 
-.. note:: Failure to comply with EEI will result in a delay to your
-	  experiment.  Equipment that cannot pass EEI may not be used
-	  at NSLS-II.
 
 Research Equipment Pool
 -----------------------
 
-Many experimental tools are available from `the NSLS-II Research
+Some experimental tools are available from `the NSLS-II Research
 Equipment Pool
 <https://public.bnl.gov/sites/rep/SitePages/Home.aspx>`__.  If you
 wish to use any items from equipment pool, contact `Bruce Ravel
 <mailto:bravel@bnl.gov>`__ well ahead of your experiment.
 
+If you wish to use a potentiostat in lab 4L-L09 to pre-condition
+battery or other electrochemical samples, contact `Bruce
+<mailto:bravel@bnl.gov>`__ to have a potentiostat from the equipment
+pool reserved for you.
+
 
 Shipping things to the beamline
 -------------------------------
 
-Things should be shipped to
+Packages should be shipped to
 
 .. code-block:: none
 
@@ -190,6 +214,12 @@ Things should be shipped to
    Brookhaven National Laboratory
    Upton NY 11973
 
+If shipping radiological materials, **do not ship samples directly to
+the beamline**.  Follow the `instructions for radiological materials
+transport
+<https://www.bnl.gov/nsls2/userguide/shipping.php#tabs-2>`__.
+
+
 The Day of your Experiment
 --------------------------
 

docs/intro.rst

@@ -65,7 +65,7 @@ Essential links
 :Operations schedule:  https://www.bnl.gov/nsls2/schedule/
 :Beamtime schedule:  https://scheduler.nsls2.bnl.gov/
 :NSLS Status:  https://www.bnl.gov/nsls2/operating-status.php
-:BMM's at Github:  https://github.com/NSLS-II-BMM
+:BMM at Github:  https://github.com/NSLS-II-BMM
 
 
 The user experience
@@ -106,7 +106,7 @@ CA Dashboard
 ~~~~~~~~~~~~
 
 At the top of the some screens, you see a crude-but-handy beamline
-monitor.  It looks like this:
+monitor.  It looks something like this:
 
 .. _fig-cadashboard:
 .. figure::  _images/cadashboard.png
@@ -116,45 +116,51 @@ monitor.  It looks like this:
 
    The CA dashboard beamline monitor
 
-This provides a (very) concise overview of the state of the beamline.
+This provides a concise (but rather color-blind-unfriendly) overview of
+the state of the beamline.
 
 **Top line**
    In short, if the top line has no red text, the beamline is all ready to go.
 
-   + BMM is enabled (green) or disabled (gray)
-   + The BM, FE, & user photon shutters are open (green) or closed (gray)
+   + BMM is enabled (:green:`green`) or disabled (:gray:`gray`)
+   + The BM, FE, & user photon shutters are open (:green:`green`) or closed (:gray:`gray`)
    + Indicators that the temperature sensors in the racks are in range
-     (green) or running hot (red)
-   + The state of vacuum sections 1 through 7 |nd| green means vacuum
-     level is OK, red means vacuum level is high
+     (:green:`green`) or running hot (:red:`red`)
+   + The state of vacuum sections 1 through 7 |nd| :green:`green` means vacuum
+     level is OK, :red:`red` means vacuum level is high
    + The state of the in-vacuum motors, 4 on the DCM, 2 on the
-     focusing mirror, 2 on the harmonic rejection mirror |nd| green
-     means temperature is OK, red means temperature is high
-   + The open (green) or closed (red) state of the 3 front end gate
+     focusing mirror, 2 on the harmonic rejection mirror |nd| :green:`green`
+     means temperature is OK, :red:`red` means temperature is high
+   + The open (:green:`green`) or closed (:red:`red`) state of the 3 front end gate
      valves and the 6 beamline gate valves
 
+.. role:: hlyellow
+.. role:: hlcyan
+.. role:: hlmagenta
+.. role:: hlblue
+
 **Middle line**
    + The energy position of the monochromator
    + The current element and edge configuration of the beamline
    + The ring current
    + The signals on the I\ :sub:`0`, I\ :sub:`t`, and I\ :sub:`r` ion
      chambers, measured in nanoamps
    + The current operation at the beamline, options are: idle (white),
-     XAFS scan (pink), line scan (cyan), area scan (yellow), or time
-     scan (blue)
+     XAFS scan (:hlmagenta:`pink`), line scan (:hlcyan:`cyan`), area scan (:hlyellow:`yellow`), or time
+     scan (:hlblue:`blue`)
+
+.. role:: brown
 
 **Bottom line**
    + Positions of common sample motors
    + size of sample slits
    + the element currently in the reference position
    + the state of the instrument being used |nd| in this example, *the
      ex-situ* sample wheel
-   + the brown block at the end is a heartbeat monitor to visually
+   + the :brown:`brown` block at the end is a heartbeat monitor to visually
      verify that the dashboard is functioning correctly
 
-For more information about this tool, `follow this link
-<https://wiki-nsls2.bnl.gov/beamline6BM/index.php/Cadashboard>`_.
-
+.. todo:: Document cadashboard in appendix of this manual.
 
 .. _slack:
 
@@ -405,18 +411,22 @@ about 300 |mu| m by 250 |mu| m.
 Acknowledgements
 ----------------
 
-This documentation project uses the lovely `{book}theme
+This documentation project uses `Sphinx
+<https://www.sphinx-doc.org/en/master/index.html>`__ and the lovely
+`{book}theme
 <https://sphinx-book-theme.readthedocs.io/en/latest/index.html>`__
 from the `The Executable Book Project
-<https://ebp.jupyterbook.org/>`__.  Appendices are numbered properly using the ``appendix.py`` extension from https://github.com/heig-tin-info/handout.
+<https://ebp.jupyterbook.org/>`__.  Appendices are numbered properly
+using the ``appendix.py`` extension from
+https://github.com/heig-tin-info/handout.
 
 BMM's `Bluesky <https://blueskyproject.io/>`__ profile was mostly
 written by Bruce.  But this would not have happened without the help
 of several members of NSLS-II's DSSI program.  In particular, I want
 to thank Dan Allan, Tom Caswell, Josh Lynch, Max Rakitin, Dmitri
-Gavrilov, Stuart Campbell, Abby Giles, and Garrett Bishof.  And I need
-to thank every BMM user |nd| being a BMM user and being a beta tester
-for the beamline software are the same thing!
+Gavrilov, Stuart Campbell, Abby Giles, Garrett Bishof, and Ryan
+Jaskiel.  And I need to thank every BMM user |nd| being a BMM user and
+being a beta tester for the beamline software are the same thing!
 
 BMM makes use of `lots of great python tools
 <https://speakerdeck.com/jakevdp/the-unexpected-effectiveness-of-python-in-science?slide=52>`__.
@@ -425,7 +435,7 @@ to process every XAS scan that gets measured and Matt's `lmfit
 <https://lmfit.github.io/lmfit-py/>`__ is used for many alignment
 chores.
 
-This project uses a GitHub action to build and deploy `(see details
+This manual uses a GitHub action to build and deploy `(see details
 here)
 <https://github.com/marketplace/actions/sphinx-docs-to-github-pages>`__
 this document whenever a ``git push`` happens.  We are grateful to the

docs/pds.rst

@@ -47,7 +47,7 @@ If using the focusing mirror, do this:
    RE(change_edge('Fe', focus=True))
 
 Excluding the ``focus`` argument |nd| or setting it to False |nd|
-indicates setup for unfocused beam.
+indicates setup for collimated beam.
 
 This edge change can be put into a :numref:`macro (see Section %s)
 <macro>` like so:
@@ -72,9 +72,11 @@ Automating reference foil changes
 A wheel is used to hold and switch between reference foils and stable
 oxides.  The standard reference wheel has most of the elements
 accessible at BMM, including all the lanthanides (except Pm!).  A
-double wheel (:numref:`see Figure %s <fig-doublewheel>`) is used
-to hold the standards.  The wheel is mounted on a rotation stage which
-is, in turn, mounted on an XY stage for alignment.
+double wheel (:numref:`see Figure %s <fig-doublewheel>`) is used to
+hold the standards.  The wheel is mounted on a rotation stage which
+is, in turn, mounted on an XY stage for alignment.  See
+:numref:`Table %s <tab-reference-wheel>` for the contents of reference
+wheel.
 
 .. _fig-ref_wheel:
 .. figure::  _images/ref_wheel.jpg
@@ -106,7 +108,7 @@ translating to the correct ring on the wheel.
 The ``change_edge()`` command does this automatically, so long as the
 target edge is available on the reference holder.
 
-The foil holder interface is configured as a python dictionary.  See
+The reference wheel content is configured as a python dictionary.  See
 ``xafs_ref.mapping``.
 
 This dictionary identifies the positions in ``xafs_ref`` and
@@ -120,9 +122,7 @@ reference wheel, do ``%se``.
 <https://nsls-ii-bmm.github.io/bmm-standards/BMM-standards.html>`__ in
 BMM's collection.
 
-
-.. _roichannels:
-
+
 ..
   Automating fluorescence ROI changes
   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -168,7 +168,7 @@ where,
 
 ``focus``
   ``True``: set up for using the focusing mirror, modes A, B, C;
-  ``False``: unfocused beam, modes D, E, F.  Default is ``False``.
+  ``False``: collimated beam, modes D, E, F.  Default is ``False``.
 
 ``edge``
   If not specified, use K or L3, as appropriate for the energy range
@@ -196,9 +196,14 @@ where,
   Default is 300.
 
 
-Most of those parameters are rarely used, except for ``edge`` and
-``focus``.  If you need to set up for measuring an L\ :sub:`2` or L\
-:sub:`1` edge, you must specify ``edge``.
+Except for ``edge`` and ``focus``, most of those parameters are rarely
+used.  If you need to set up for measuring an L\ :sub:`2` or L\
+:sub:`1` edge, you must specify ``edge``.  For example:
+
+.. code-block:: python
+
+   RE(change_edge('Pt', edge='L1'))
+
 
 
 For all the details about the individual parts of the photon delivery