Fixed some typos in REST docs. Added example of parsing LVAlert messages.

doc/source/lvalert.rst

@@ -39,7 +39,9 @@ nodes. Thus, a message sent to the node ``burst_cwb_allsky`` will *also* be sent
 node ``burst_cwb``. This property allows the user to filter by search at the level of
 specifying LVAlert processing scripts for individual nodes.
 
-.. tell them how to get the names of all of the nodes
+To see the names of all available nodes, simply execute::
+
+    lvalert_admin -a username -b password -i
 
 LVAlert message contents
 ================================================
@@ -56,17 +58,185 @@ following keys:
 For example, when a new event is created, an LVAlert message is created 
 with alert type ``new``, and the ``object`` is just the JSON representation of 
 of the event provided by the REST interface (see :ref:`searching_for_events`).
-
-.. examples of the different types
-.. demonstration of how to parse
-
-.. what kind of alert does a replacement trigger?
+Below are examples of the possible types of LVAlert message. These were generated
+by creating a new event, adding a couple of log messages, creating a Preliminary
+VOEvent, and applying the DQV label (in that order).
+
+New event::
+
+    {
+      "alert_type": "new", 
+      "description": "", 
+      "file": "https://gracedb.ligo.org/events/T129911/files/coinc.xml", 
+      "object": {
+        "created": "2015-06-17 22:10:43 UTC", 
+        "extra_attributes": {
+          "CoincInspiral": {
+            "combined_far": 3.772326334623149e-14, 
+            "end_time": 968929613, 
+            "end_time_ns": 817383681, 
+            "false_alarm_rate": 3.654963804145501e-08, 
+            "ifos": "H1,L1", 
+            "mass": 2.621732950210571, 
+            "mchirp": 1.139938473701477, 
+            "minimum_duration": null, 
+            "snr": 19.73621083881572
+          }
+        }, 
+        "far": 3.772326334623149e-14, 
+        "gpstime": 968929613.8173836, 
+        "graceid": "T129911", 
+        "group": "Test", 
+        "instruments": "H1,L1", 
+        "labels": {}, 
+        "likelihood": 8.33784842725385e+44, 
+        "links": {
+          "embb": "https://gracedb.ligo.org/api/events/T129911/embb/", 
+          "filemeta": "https://gracedb.ligo.org/api/events/T129911/filemeta/", 
+          "files": "https://gracedb.ligo.org/api/events/T129911/files/", 
+          "labels": "https://gracedb.ligo.org/api/events/T129911/labels/", 
+          "log": "https://gracedb.ligo.org/api/events/T129911/log/", 
+          "neighbors": "https://gracedb.ligo.org/api/events/T129911/neighbors/", 
+          "self": "https://gracedb.ligo.org/api/events/T129911", 
+          "tags": "https://gracedb.ligo.org/api/events/T129911/tag/"
+        }, 
+        "nevents": 2, 
+        "pipeline": "gstlal", 
+        "search": "MDC", 
+        "submitter": "branson.stephens@LIGO.ORG"
+      }, 
+      "uid": "T129911"
+    }
+
+
+Log message without file::
+
+    {
+      "alert_type": "update", 
+      "description": "LOG: This is a test.", 
+      "file": "", 
+      "object": {
+        "N": 4, 
+        "comment": "This is a test.", 
+        "created": "2015-06-17T17:10:43.381117", 
+        "file": null, 
+        "file_version": null, 
+        "filename": "", 
+        "issuer": {
+          "display_name": "Branson Stephens", 
+          "username": "branson.stephens@LIGO.ORG"
+        }, 
+        "self": "https://gracedb.ligo.org/api/events/T129911/log/4", 
+        "tag_names": [
+          "analyst_comments"
+        ], 
+        "tags": "https://gracedb.ligo.org/api/events/T129911/log/4/tag/"
+      }, 
+      "uid": "T129911"
+    }
+
+
+Log message with a file::
+
+    {
+      "alert_type": "update", 
+      "description": "UPLOAD: bayestar.fits This is a file.", 
+      "file": "bayestar.fits", 
+      "object": {
+        "N": 6, 
+        "comment": "This is a file.", 
+        "created": "2015-06-17T17:10:43.980188", 
+        "file": "https://gracedb.ligo.org/api/events/T129911/files/bayestar.fits%2C0", 
+        "file_version": 0, 
+        "filename": "bayestar.fits", 
+        "issuer": {
+          "display_name": "Branson Stephens", 
+          "username": "branson.stephens@LIGO.ORG"
+        }, 
+        "self": "https://gracedb.ligo.org/api/events/T129911/log/6", 
+        "tag_names": [
+          "sky_loc"
+        ], 
+        "tags": "https://gracedb.ligo.org/api/events/T129911/log/6/tag/"
+      }, 
+      "uid": "T129911"
+    }
+ 
+New VOEvent created::
+
+    {
+      "alert_type": "update", 
+      "description": "VOEVENT: T129911-1-Preliminary.xml", 
+      "file": "T129911-1-Preliminary.xml", 
+      "object": {
+        "N": 1, 
+        "created": "2015-06-17T17:10:44.172876", 
+        "file": "https://gracedb.ligo.org/api/events/T129911/files/T129911-1-Preliminary.xml%2C0", 
+        "file_version": 0, 
+        "filename": "T129911-1-Preliminary.xml", 
+        "issuer": {
+          "display_name": "Branson Stephens", 
+          "username": "branson.stephens@LIGO.ORG"
+        }, 
+        "ivorn": "ivo://gwnet/gcn_sender#T129911-1-Preliminary", 
+        "self": "https://gracedb.ligo.org/api/events/T129911/voevent/1", 
+        "text": "<voevent text>", 
+        "voevent_type": "PR"
+      }, 
+      "uid": "T129911"
+    }
+
+New DQV label applied::
+
+    {
+      "alert_type": "label", 
+      "description": "DQV", 
+      "file": "", 
+      "uid": "T129911"
+    }
+
+.. XXX what kind of alert does a replacement trigger?
+
+Receiving and Parsing LVAlert messages
+====================================================
+
+The LVAlert client tools include the ``lvalert_listen`` executable, which can be used to
+receive and respond to LVAlert messages::
+
+    lvalert_listen -a username -b password -c /path/to/lvalert_config.ini
+
+The ``-c`` (configuration file) option allows you to specify an executable script to be called 
+each time a message arrives over a particular node. Suppose one is only interested in
+events from the burst group, cWB pipeline, and MDC search. Then the 
+``lvalert_config.ini`` file could look like this::
+
+    [burst_cwb_mdc]
+    executable = /path/to/mdc_event_handler
+
+And the script ``mdc_event_handler`` could be any script that is prepared to receive the
+LVAlert message contents through standard input. Here is an example in Python::
+
+    #!/usr/bin/env python
+    import json
+    from sys import stdin
+
+    # Load the LVAlert message contents into a dictionary
+    streamdata = json.loads(stdin.read())
+
+    # Do something with new events having FAR below threshold
+    alert_type = streamdata['alert_type']
+
+    if alert_type == 'new':
+        # The object is a serialized event. Get the FAR
+        far = streamdata['object']['far']
+
+        if far < 1.e-6:
+            # Do some interesting processing
+            pass
 
 Further reading on LVAlert
 =====================================================
 
-.. links to LVAlert documentation
-
 Further information on using LVAlert can be found on the
 `LVAlert Project Page <https://www.lsc-group.phys.uwm.edu/daswg/projects/lvalert.html>`_
 and the `LVAlert Howto <https://www.lsc-group.phys.uwm.edu/daswg/docs/howto/lvalert-howto.html>`_.

doc/source/lvem.rst

@@ -77,3 +77,7 @@ uploading observation records:
 
 - by email (not yet availabe, but in the works)
 
+For more on the GraceBD event page and creating EM observation records, see 
+`this <https://www.youtube.com/watch?v=oIJE4dTISs4>`_  helpful video
+by Roy Williams.  There is a companion video on the SkymapViewer 
+`here <https://www.youtube.com/watch?v=ydXUD9KIN98>`_.

doc/source/rest.rst

@@ -43,8 +43,8 @@ fully featured.
 
 .. NOTE::
     Before using the REST client, credentials for authentication must be available.
-    Run ligo-proxy-init or, if using a robot certificate, set the appropriate envronment 
-    variables (for more infomation, see :ref:`auth`).
+    Run ligo-proxy-init or, if using a robot certificate, set the appropriate environment 
+    variables (for more information, see :ref:`auth`).
 
 The REST client is typically used in the Python interpreter or in a script to 
 accomplish a specific task, such as retrieving information about events matching
@@ -97,7 +97,7 @@ Searching for events
 Suppose you are working on a script to search for all events matching a 
 specific query and retrieve a piece of information about each event in
 the search results. For example, the following code retrieves the chirp 
-mass for each gstlal event during ER5 with FAR less than 1.0E-4::
+mass for each ``gstlal`` event during ER5 with FAR less than 1.0E-4::
 
     from ligo.gracedb.rest import GraceDb
     client = GraceDb()
@@ -116,7 +116,7 @@ mass for each gstlal event during ER5 with FAR less than 1.0E-4::
 Note that the ``events`` method on the client returns an iterator on 
 event dictionaries rather than a list. The chirp mass is an attribute
 specific the inspiral event subclass, hence the difference between accessing
-the graceid and the chirp mass.
+the ``graceid`` and the chirp mass.
 
 But how did I know the structure of the event dictionary so that I could
 pull out the chirp mass? The best way is to look at the structure of an
@@ -240,7 +240,7 @@ Coding against the GraceDB REST API
 
 Some users may wish to code directly against the GraceDB REST API rather
 than use the Python or command-line clients. In order to do this, the user
-will need to know which resources are exposed by which URLS, and which HTTP
+will need to know which resources are exposed by which URLs, and which HTTP
 methods those URLs allow. Fortunately, the 
 `Django REST Framework <http://www.django-rest-framework.org>`_ (on which
 the GraceDB API is built) provides

doc/source/web.rst

@@ -10,11 +10,15 @@ Under construction.
 Understanding the event page
 ===============================
 
-.. links to Roy's videos
+Under construction.
 
 .. include a bit on tagging annotations
 
-Under construction.
+For more on the GraceDB event page, see 
+`this <https://www.youtube.com/watch?v=oIJE4dTISs4>`_  helpful video
+by Roy Williams, which is geared toward LV-EM users.  There is a 
+companion video on the SkymapViewer 
+`here <https://www.youtube.com/watch?v=ydXUD9KIN98>`_.
 
 Signing up for email alerts (LVC only)
 =======================================================