arrays (#633)

* fix indentation, and elaborate a bit on apla

* Update Arrays.md

docs/ReleaseNotes40.md

@@ -12,20 +12,20 @@ This page describes the most important enhancements to Link, delivered in versio
 
 ## New Features
 
-The following features have been implemented in the master branch:
+The following features have been implemented:
 
 * [Configuration files](Usage/ConfigFiles.md):
-  - A user configuration file for recording preferences that apply to all links, for example link creation options like -watch=
-  - Directory configuration files store options that should be re-applied when the directory is subsequently linked, including stop and trace settings
-  - If you are investigating problems in Link, you can turn off error trapping within Link API functions, or receive notification in the APL session each time Link performs an action related to external files.
+    - A user configuration file for recording preferences that apply to all links, for example link creation options like -watch=
+    - Directory configuration files store options that should be re-applied when the directory is subsequently linked, including stop and trace settings
+    - If you are investigating problems in Link, you can turn off error trapping within Link API functions, or receive notification in the APL session each time Link performs an action related to external files.
 
 !!! Note
      Link.Create, Import and Export have a new switch -ignoreconfig, which allows you
      to ignore a damaged or otherwise inappropriate configuration file.
 
 * Creating a Link from single class or namespace files in addition to linking directories.
 
-  - Note that configuration files cannot be created for single-file links
+    - Note that configuration files cannot be created for single-file links
 
 * Link.Create, Import and Export will default to the current namespace if no namespace is specified. For example,
 
@@ -43,7 +43,7 @@ The following features have been implemented in the master branch:
 Imported: #.HttpCommand ← C:\Program Files\Dyalog\Dyalog APL-64 19.0 Unicode\Library\Conga\HttpCommand.dyalog
 ```
 
-- Multi-line character data stored in character vectors, character matrices, and vectors of character vectors can optionally be stored in "flat" text files (as opposed to using APL Array Notation). See [Array Formats](Usage/Arrays.md) for more information.
+- Multi-line character data stored in character vectors, character matrices, and vectors of character vectors can optionally be stored in plain text files (as opposed to using APL Array Notation). See [Array Formats](Usage/Arrays.md) for more information.
 
 - When defining functions or operators in the active workspace, `Link.Create` will update information about the most recent change using file information reported by the operating system. This information is reported by `⎕AT`, `20 21 22 ⎕ATX`, and the Workspace Explorer. 
 

docs/Usage/Arrays.md

@@ -1,18 +1,21 @@
 # Array Formats
 
-By default, Link uses *APL Array Notation (APLAN)* to store arrays in text files. While APLAN is a good format for describing numeric data, nested arrays and many high rank arrays, it is not ideal for storing character data. Link 4.0 introduces experimental support for storing multi-line character data in simple text files.
+By default, Link uses *APL Array Notation (APLAN)* to store arrays in text files. While APLAN is a good format for describing numeric data, nested arrays and many high rank arrays, it is not ideal for storing text data. Link 4.0 introduces experimental support for storing multi-line character data in simple text files.
 
-The configuration setting `noTextFiles` can be used to disable this support: If `noTextFiles` is set to 1, all arrays will be store using APLAN. You can set this option when a link is created, or using [`Link.Configure`](../API/Link.Configure).
+The configuration setting `text` can be used to enable this feature: If `text` is set to `'aplan'` (the default) then all arrays will be store using APLAN. If `text` is set to `'plain'` (the default) then text arrays that adhere to a set of very specific criteria will instead be stored in plain text files. You can set this option when a link is created, or using [`Link.Configure`](../API/Link.Configure).
 
-## File Extensions for Simple Text Files
+Text files which are not in APLAN format will have a penultimate "sub-extension" section in the file name which records the format of the original array in the workspace. The below table describes the array file extensions, what the content represents, and the specific criteria for storage in plain text file.
 
-Text files which are not in APLAN format will have a penultimate section in the file name which records the format of the original array in the workspace:
+For all plain text types, the array must be non-empty.
 
-| File Extension | Array format                         |
-| -------------- | ------------------------------------ |
-| .nl.apla       | Simple Vector delimited by ⎕UCS 10   |
-| .cr.apla       | Simple vector delimited by ⎕UCS 13   |
-| .vec.apla      | Vector of enclosed character vectors |
-| .mat.apla      | Character matrix                     |
-|  .apla         |Without one of the above extensions, the file is in APLAN and could represent any APL array.|
+| File Extension | Array Characteristics                                  | Prohibited characters (`⎕UCS`)
+| -------------- | ------------------------------------------------------ | ------------------------------
+| .CR.apla       | Simple vector with each line terminated by `⎕UCS 13`   | `10 11 12 133 8232 8233`
+| .LF.apla       | Simple vector with each line terminated by `⎕UCS 10`   | `11 12 13 133 8232 8233`
+| .CRLF.apla     | Simple vector with each line terminated by `⎕UCS 13 10`| `11 12 133 8232 8233`<sup>*</sup>
+| .vec.apla      | Vector of simple character vectors (no scalar elements)| `11 12 13 133 8232 8233`
+| .mat.apla      | Simple character matrix                                | `10 11 12 13 133 8232 8233`
 
+<sup>* In addition, every occurring `⎕UCS 10` must be immediately preceded by a `⎕UCS 13` and every occurring `⎕UCS 13` must be immediately followed by `⎕UCS 10`.</sup>
+
+In all other cases, the extension will be just `.apla` and the file will contain APLAN that can represent any APL array.