Merge pull request #14 from mongodb/snooty-tweaks-1

snooty: add feature teaser and Optional Configuration section

Author: skerschb

source/snooty.txt

@@ -26,6 +26,15 @@ a fluid and integrated writing experience.
    Snooty is currently in an early testing stage. Expect bugs and gaps
    in functionality.
 
+Some features:
+
+* Realtime diagnostics.
+* When hovering over a ``include``, ``literalinclude``, or ``figure`` directive path,
+  a tooltip will appear showing the path to the requested file, which you may click to
+  open.
+
+  Note that this will NOT currently work for files generated by Giza (e.g. steps and extracts).
+
 Installation
 ------------
 
@@ -77,7 +86,7 @@ is loaded into Visual Studio Code with a ``snooty.toml`` file in the root.
    its root, so VSCode will launch Snooty.
 
 Once Snooty is launched, Snooty will highlight problematic source lines
-as you type. By default, *green* underlines indicate a warning, and *red*
+as you type. By default, *yellow* underlines indicate a warning, and *red*
 underlines indicate an error.
 
 Prepare an Existing Giza Project to Use Snooty
@@ -101,8 +110,9 @@ You can use the following example to start your project:
    package-name-org = "mongodb-org"
    pgp-version = "{+version+}"
 
-Once this file is created, run ``code .`` in the project directory
-to start Visual Studio Code.
+Once this file is created, run Visual Studio Code and open the in the project directory.
+If you are using the terminal, the ``code <path>`` command will open Visual Studio Code
+in the given path.
 
 Currently, Snooty accepts the following fields in ``snooty.toml``:
 
@@ -148,6 +158,24 @@ Snooty offers the following commands:
        you change your ``snooty.toml`` configuration file. Eventually, this
        will be automatic.
 
+Optional Configuration
+----------------------
+
+Preview Mode
+  Visual Studio Code has a behavior which some users find undesirable: by default
+  after opening a file, it is placed in *preview* mode until either you change the
+  file or you double-click on the tab header.
+
+  When in *preview mode*, any additional files that you open will be opened in the
+  current tab rather than opening a new tab.
+
+  You can disable this behavior with the following steps:
+
+  * Open the command palette (Command-Shift-P),
+  * Choose ``Open User Settings``,
+  * Search for ``preview``, and
+  * Uncheck :guilabel:`Workbench > Editor: Enable Preview`
+
 Bugs
 ----
 
@@ -157,14 +185,11 @@ deficiencies:
 * Diagnostics have wildly wrong line numbers in YAML content.
 * The Snooty project is not automatically reloaded after changes to the
   configuration file.
-* Snooty will not show diagnostics for files which have not been opened
-  in the current project.
 * Snooty should be able to automatically create a ``snooty.toml`` given
   an existing Giza project. This is currently manual.
-* If the snooty download fails, the extension may be left in an inconsistent
-  state.
 * Non-macOS systems are not yet officially supported.
 * Some valid content may show diagnostics.
-* Steps and Extracts are the only supported YAML files.
+* Steps, Extracts, and Release are the only supported YAML files.
+* Hovering to open Steps, Extracts, and Release files will not work correctly .
 * Only a single Snooty project at a time may be opened. Opening more than one
   project is currently undefined behavior.