Small changes to the AnalysisPrograms manual

docs/cli.md

@@ -61,7 +61,7 @@ For example:
 $ AnalysisPrograms.exe help audio2csv
 ```
 
-In this command line, ‘help’ is an *command* and the command-name, *audio2csv*, is
+In this command line, ‘help’ is a *command* and the command-name, *audio2csv*, is
 an option.
 
 ## Options
@@ -116,7 +116,7 @@ Alternatively, you can append one of the following switches to the command line:
 ## Beware these Syntax Gotchas**
 
 -   **Never** finish a double quoted string argument with a backslash (\\). In
-    particular, do not end directory names like this:
+    particular, do *not* end directory names like this:
     “C:\\\\Path\\OutputDirectory\\”. The parsing rules for such cases are
     complicated and outside of our control. See
     [here](https://msdn.microsoft.com/en-us/library/system.environment.getcommandlineargs.aspx)

docs/commands.md

@@ -2,7 +2,7 @@
 
 ## Types
 
-There are, in broad terms, these types of sub-programs (commands):
+The following four categories of sub-programs (commands) are available:
 
 -   Main commands
     -   Process large amounts of information (like `audio2csv`)
@@ -24,20 +24,20 @@ There are, in broad terms, these types of sub-programs (commands):
 Processes large audio recording with the specified analysis. Can run recognizers,
 calculate indices, or do other things, for very long recordings.
 
-See [details on Analyze Long Recordings](./commands/analyze_long_recording.md)
+See details here [Analyze Long Recordings](./commands/analyze_long_recording.md)
 
 ### Colour Spectrogram
 
 This command produces a single false-colour (FC) spectrogram, taking as input
 the spectral indices produced by the _Acoustic Indices_ analysis on a single
 audio file.
 
-See [details on Colour Spectrogram](./commands/colour_spectrogram.md)
+See details here [Colour Spectrogram](./commands/colour_spectrogram.md)
 
 ### Concatenate Index Files
 
 This command joins together the results of several _Acoustic Indices_ analysis
 result sets to produce data and images for 24-hour blocks of data.
 
-See [details on Concatenate Index Files](./commands/concatenate_index_files.md)
+See details here [Concatenate Index Files](./commands/concatenate_index_files.md)
 

docs/commands/analyze_long_recording.md

@@ -4,14 +4,14 @@
 - **Config file**: \<any compatible config file\>
 
 This command applies an analysis to a long recording. It works well with recordings
-that are up 1440 minutes long.
+that are up to 1440 minutes (i.e. 24-hours) long.
 
 This command takes a single long-duration audio recording as input, splits it
 into segments and calculates results and writes the output to several .csv files.
 This analysis process supports **parallel** processing.
 
 Analyze long recordings can run many types of analyses. The provided config file
-determines what analyses is run.
+determines what kind of analysis is run.
 
 To see a list of all analyses that can be used by _audio2csv_, execute:
 
@@ -43,8 +43,7 @@ Here is an example of a command line with abbreviated path names:
 $ AnalysisPrograms.exe audio2csv "audioPath\fileName.wav" "configPath\fileName.yml" "outputPath\directoryName"
 ```
 
-The above three paths are required arguments (the program will fail if they are
-not found on the command line). 
+The above three paths are required arguments in that order. The program will fail if they are not found on the command line. 
 
 >Reminder: All path names should be double quoted, BUT make sure you use plain
 >double quotes (`".."`) and NOT so called _smart quotes_ (`“..”`).
@@ -62,16 +61,12 @@ Here is more detail about the command line options:
 - `Source`: The path to the audio file to process
 - `Output`: The output will be placed the directory provided
 - `Config`:
- - **IMPORTANT**: The name of the config file chosen will determine the
-   analysis that is run
- - The config file contains parameters that are unique for the chosen analysis
- - If the config file cannot be found, _AP.exe_ will try and use a default
+ - **IMPORTANT**: The name of the config file chosen will determine the kind of analysis that is run.
+ - The config file contains parameters that are unique for the chosen analysis. If the config file cannot be found, _AP.exe_ will try and use a default. 
  - Typically, if a required parameter is not found in the config file, 
    a default value will be used or in certain cases, a fatal error may result.
-- `--channels`:
- - The default value is nothing (not specified) which means that all channels
-   are used.
- - _AP.exe_ can process files with up to 8 channels.
+- `--channels`: The default value is nothing (not specified) which means that all channels
+   are used.  _AP.exe_ can process files with up to 8 channels.
  - [TODO: CHECK THIS] Channels are numbered, 0, 1, 2, … In the usual case of 
    stereo, left channel = 0 and right channel = 1. Note that, although the
    software should be able to accept recordings where channel number is greater

docs/commands/colour_spectrogram.md

@@ -16,13 +16,13 @@ This section describes the command line arguments required to draw a false-colou
 spectrogram derived from matrices of spectral acoustic indices extracted from 
 single long-duration audio recording.
 
-To run the analysis, type:
+To run the command, type:
 
 ```
 $ AnalysisPrograms.exe DrawLongDurationSpectrograms [options];
 ```
 
-The output of this analysis is a set of false-colour and grey-scale
+The output of this command is a set of false-colour and grey-scale
 long-duration index spectrograms.
 
 Here is an example of a command line with abbreviated path names:
@@ -68,5 +68,5 @@ Here is some additional information about the more important parameters:
         -   Linear125Octaves30Nyquist11025
         -   Octaves24Nyquist32000
         -   Linear125Octaves28Nyquist32000
-    - [TODO: Update] Only "Linear", "Linear125Octaves7Tones28Nyquist32000" work at present.
--   `YAxisTicInterval`: 1000. Horizontal grid lines will be placed every 1kHz interval.
+    - [TODO: Update] Only "Linear", "Mel", and "Linear125Octaves7Tones28Nyquist32000" are available at present.
+-   `YAxisTicInterval`: 1000. Horizontal grid lines will be placed every 1kHz interval. This can be set to 5000, if the recording sample rate is 96 kHz, or to 2000 if the recording sample rate is 44.1 kHz.

docs/commands/concatenate_index_files.md

@@ -10,17 +10,16 @@ multiple runs of the *audio2csv* command, and concatenates them to produce one
 or more concatenated false-colour index spectrograms.
 
 Typically, this command is used to produce a sequence of one or more 24-hour
-false-colour spectrograms. 24-hour false-colour spectrograms are easier to
+false-colour spectrograms, where the original recordings can be anything from 30 minutes to 24 hours duration. 24-hour false-colour spectrograms are much easier to
 interpret because sound-marks, such as the morning chorus, evening chorus, and
-insect tracks are easier to identify. Typically, environmental recordings are
-anything from 30 minutes to 24 hours in duration. False-colour index spectrograms
+insect tracks, are easier to identify. False-colour index spectrograms
 shorter than about 3 hours are difficult to interpret due to the lack of
 soundscape context.
 
 There is also an option with this command to concatenate the false-colour
 spectrograms of every audio recording that can be found in a specified directory
-into one large dataset/image. Due to memory constraints however, one would not
-usually concatenate more than about 48 hours of recordings.
+into one large data-set and image. Due to memory constraints however, one would not
+usually attempt to concatenate more than about 48 hours of recordings.
 
 It is **strongly** recommended you only run this command on files from a single
 acoustic sensor deployment - don't mix recordings from different sites or

docs/faq.md

@@ -4,16 +4,16 @@
 
 Short answer: computers.
 
-_AP.exe_ is designed primarily to be used by people that have significant computing
+_AP.exe_ is designed primarily to be used by people who have significant computing
 expertise. It designed specifically to be used by **other programs** for any real workloads.
 It is not designed to be human friendly.
 
 We encourage anyone to give it a go--don't be daunted by these docs--but keep in
 mind the target audience. You're in the right ballpark if:
 
-- If your workload involves thousands of files
-- If you need to use a script just to use _AP.exe_
-- If you have more RAM or CPU than you know what to do with
+- your workload involves hundreds/thousands of files; or
+- you need to use a script just to use _AP.exe_; or
+- you have more RAM or CPU than you know what to do with!
 
 More than likely if you're stuck we can help 😊.
 
@@ -33,9 +33,9 @@ is no longer readable text--rather it is just blobs of binary instructions that
 
 Binaries that can be run as programs are often called _executables_.
 
-## What is ~~an _action_~~ a _command_?
+## What is a _command_?
 
 Our program is a monolith--a very large structure. To support doing different
 things we have various sub-programs that can be run by themselves. We call each
-of these sub-programs a _command_. If you run _AP.exe_ with no arguments it will
-list the available command that you can run.
+of these sub-programs a _command_. If you run _AP.exe_ with no arguments, it will
+list the available commands (sub-programs) that you can run.

docs/supported_platforms.md

@@ -8,7 +8,7 @@ The _AP.exe_ binary will run on any Windows computer with v4.6.2 of the .NET
 Framework installed.
 Practically, it means that these variants are supported:
 
-- Client SKUs
+- Client SKUs (stock keeping unit)
     - ✓ 10 Anniversary Update
     - \+ 10 November Update 
     - \+ 10