From 900dd5d5825e14d93706ca58b7d9ae97fd98a68b Mon Sep 17 00:00:00 2001
From: Jamie Hardt <jamiehardt@me.com>
Date: Fri, 18 Nov 2022 15:37:02 -0800
Subject: [PATCH] More doc work

---
 docs/source/cli_reference.rst | 74 +++++++++++++++++++++++++++++++++++
 docs/source/for_adr.rst       |  2 +
 docs/source/index.rst         |  7 +++-
 docs/source/tagging.rst       |  2 +
 4 files changed, 84 insertions(+), 1 deletion(-)
 create mode 100644 docs/source/cli_reference.rst

diff --git a/docs/source/cli_reference.rst b/docs/source/cli_reference.rst
new file mode 100644
index 0000000..0a4136f
--- /dev/null
+++ b/docs/source/cli_reference.rst
@@ -0,0 +1,74 @@
+Command-Line Reference
+======================
+
+Usage Form
+-----------
+
+Invocations of ptulsconv take the following form:
+
+    ptulsconv [options] IN_FILE
+
+
+Flags
+-----
+
+`-h`, `--help`:
+    Show the help message.
+
+`f FMT`, `--format=FMT`:
+    Select the output format. By default this is `doc`, which will 
+    generate :ref:`ADR reports<adr-reports>`.
+
+    The :ref:`other available options<alt-output-options>` 
+    are `raw` and `tagged`.
+
+
+Informational Options
+"""""""""""""""""""""
+
+These options display information and exit without processing any
+input documents.
+
+`--show-formats`:
+    Display information about available output formats.
+
+`--show-available-tags`:
+    Display information about tags that are used by the 
+    report generator.
+
+
+.. _alt-output-options:
+
+Alternate Output Formats
+------------------------
+
+.. _raw-output:
+
+`raw` Output
+""""""""""""
+
+The "raw" output format is a JSON document of the parsed input data.
+
+The document is a top-level dictionary with keys for the main sections of the text export: `header`,
+`files`, `clips`, `plugins`, `tracks` and `markers`, and the values for these are a list of section
+entries, or a dictionary of values, in the case of `header`.
+
+The text values of each record and field in the text export is read and output verbatim, no further 
+processing is done.
+
+.. _tagged-output:
+
+`tagged` Output:
+""""""""""""""""
+
+The "tagged" output format is also a JSON document based on the parsed input data, after the additional 
+step of processing all of the :ref:`tags<tags>` in the document.
+
+The document is a top-level array of dictionaries, one for each recognized ADR spotting clip in the 
+session. Each dictionary has a `clip_name`, `track_name` and `session_name` key, a `tags` key that
+contains a dictionary of every parsed tag (after applying tags from all tracks and markers), and a 
+`start` and `end` key. The `start` and `end` key contain the parsed timecode representations of these
+values in rational number form, as a dictionary with `numerator` and `denominator` keys. 
+
+
+
diff --git a/docs/source/for_adr.rst b/docs/source/for_adr.rst
index 32543e2..0b38091 100644
--- a/docs/source/for_adr.rst
+++ b/docs/source/for_adr.rst
@@ -1,3 +1,5 @@
+.. _adr-reports:
+
 For ADR Report Generation
 =========================
 
diff --git a/docs/source/index.rst b/docs/source/index.rst
index c9fdd0b..d8d1f87 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -6,17 +6,22 @@
 Welcome to ptulsconv's documentation!
 =====================================
 
+`ptulsconv` is a tool for converting Pro Tools text exports into PDF
+reports for ADR spotting. It can also be used for converting text
+exports into JSON documents for processing by other applications.
+
 .. toctree::
+   :numbered:
    :maxdepth: 2
    :caption: Contents:
 
    quickstart
    tagging
    for_adr
+   cli_reference
 
 Indices and tables
 ==================
 
 * :ref:`genindex`
-* :ref:`modindex`
 * :ref:`search`
diff --git a/docs/source/tagging.rst b/docs/source/tagging.rst
index 17a488c..8df652a 100644
--- a/docs/source/tagging.rst
+++ b/docs/source/tagging.rst
@@ -1,3 +1,5 @@
+.. _tags:
+
 Tagging
 =======