Merge pull request #582 from Dyalog/v4-docs

Update Installation.md and Configuration.md

docs/Usage/ConfigFiles.md

@@ -6,7 +6,9 @@ Link Configuration files are in [JSON5 format](https://json5.org/), which is the
 When performing an action that is related to a directory, Link will read both the user and directory configurations. If a setting is found in both places, the more specific directory setting will override the general user settting.
 
 ### User Configuration Files
-You can have a user configuration file which allows you to record preferences that apply to all links, for example link creation options like -watch= or the `notify` setting. A simple example of a user configuration file would be:
+You can have a user configuration file called `.linkconfig` , which records preferences that apply to all links, for example link creation options like -watch= or the `notify` setting. Under Microsoft Windows, this file is stored in the `Documents` folder, on other systems in the user's home directory.
+
+A simple example of a user configuration file would be:
 
 ```
 {
@@ -18,7 +20,7 @@ You can have a user configuration file which allows you to record preferences th
   },
 }
 ```
-With the above user configuration file contents, Link will display notifications when processing changes to the source (notify:1), and use default to only propagating changes from the namespace to source files (watch:ns), unless a call to [Link.Create](..API/Link.Create.md) includes an explicit setting of that option .
+With the above user configuration file contents, Link will display notifications when processing changes to the source (notify:1), and default to only propagating changes from the namespace to source files (watch:ns). If a call to [Link.Create](..API/Link.Create.md) includes an explicit setting of the `watch` option, that will override the default.
 
 ### Directory Configuration Files
 Each linked directory may contain a `.linkconfig` file containing defaults that will apply when a link is created to that directory, or if the directory is imported. When [Link.Create](..API/Link.Create.md) or [Link.Export](..API/Link.Export.md) create a directory and create files in it, any non-default switch settings provided to tha API function will be recorded in a configuration file within the directory. This means that you no longer need to remember the options used to re-create the original link when continuing work, or importing the link into a runtime environment.
@@ -131,7 +133,7 @@ An example of a configuration file with information in all three sections is:
 ```
 
 ### The `ignoreconfig` switch
-If you manually edit a `.linkconfig` file and damage it so that it either becomes invalid JSON5 so that Link is unable to read it, or if Link is able to read it but complains that it has invalid contents, or if you simply want to ignore the configuration, several API functions including Create, Import and Export have an `ignoreconfig` option:
+If you manually edit a `.linkconfig` file and damage it so that it either becomes invalid JSON5 so that Link is unable to read it, or if Link is able to read it but complains that it has invalid contents, or if you simply want to ignore the configuration for other reasons, several API functions including Create, Import and Export have an `ignoreconfig` option:
 
 ```
       ]link.create linkdemo c:\tmp\linkdemo

docs/Usage/Installation.md

@@ -1,47 +1,34 @@
 # Installation
 
-Link 4.0 is included with Dyalog version 19.0 or later, and is supported under version 18.2.
+Link 4.0 is included with Dyalog version 19.0 or later, and is supported for use with version 18.2.
 
 !!!Note
-	For Dyalog to automatically update workspace contents due to file changes requires Microsoft .NET.
-	
+	For Dyalog to automatically update workspace contents in response to changes to files made using external editors or source code management systems, .NET must be installed.
+
 	The .NET Framework is included with Microsoft windows. For other platforms, .NET can be downloaded from [dotnet.microsoft.com/download](https://dotnet.microsoft.com/download).
 
-	Link 4.0 has been tested with the .NET Framework v4.0 and .NET 6.0, and is expected to work with any later version of .NET.
+	Link 4.0 has been tested with the .NET Framework and .NET 6.0, and is expected to work with any later version of .NET.
 
-The instructions on this page only apply if you want to work with a different version that which is distributed with your version of Dyalog APL, for example to test a pre-release.
+The instructions on this page only apply if you want to user a different release than that which is distributed with your version of Dyalog APL.
 
-If you use a non-standard Dyalog session (.dse file), contact support@dyalog.com for guidance on enabling Link.
+!!!Note
 
-Link is maintained as an open source project at [github.com/dyalog/link](https://github.com/dyalog/link).
+​	If you use a non-standard Dyalog session (.dse file), contact support@dyalog.com for guidance on enabling Link.
 
-!!!Note
-    The installation instructions below have not been updated for Link 4.0.
+## Instructions
 
-	DO NOT try to use the instructions below, they WILL NOT WORK.
+Link is maintained as an open source project at [github.com/dyalog/link](https://github.com/dyalog/link).
 
-	Please come back soon!
+**Start by downloading** one of the zip files included with the latest release of Link 4.0 from [github.com/Dyalog/link/releases](https://github.com/Dyalog/link/releases). If you are using Dyalog version 19.0 or later, use the file named `link-v4.0.nn.zip`; Extract the subfolder called `StartupSession`, which contains the code required to run Link. 
 
-**Start by downloading** the latest release from [github.com/Dyalog/link/releases](https://github.com/Dyalog/link/releases) and extracting the subfolder called `StartupSession`. This folder contains the code required to run Link.
+**If you have version 18.2**, follow the same instructions, but use the zip file with the suffix `-v182`. This file also contains code that is used to populate the `⎕SE.Dyalog` namespace, it is required because Link 3.0 included this code, which has moved to a separate repository.
 
 If you have the necessary permissions, you can **OVERWRITE the installed version of Link** by replacing the `StartupSession` folder that already exists in the main Dyalog program folder with the downloaded folder.
 
-If you do not have permission to partially overwrite the Dyalog installation, you can keep the code outside the main program folder. You will need to declare the location of the folder by setting the `DYALOGSTARTUPSE` parameter. You can add it to the command line when you start APL, but it is probably easier to use one of the following alternatives:
+If you do not have permission to overwrite the Dyalog installation, or you do not wish to overwrite the original version of Link that was included with the interpreter (Dyalog recommends keeping the original code in case you need to fall back), you can keep the code outside the main program folder. In this case, you will need to declare the location of the folder by setting the `DYALOGSTARTUPSE` parameter. You can add it to the command line when you start APL, but it is probably easier to use one of the following alternatives:
 
 - **Set the `DYALOGSTARTUPSE` environment variable** to point to the StartupSession folder.
 
 - **Update the configuration file (or the Windows registry) **, to set the parameter there. Typically, you would edit `~/.dyalog/dyalog.config` to make the change for all versions, or a specific file such as `~/.dyalog/dyalog.180U64.dcfg` for a specific version, to include the line:  
 
 		    `DYALOGSTARTUPSE: "/Users/mkrom/link/StartupSession"`
-				
-
-**If you are using Dyalog version 18.0**, you will also need to update the user command file used to invoke Link user commands. This only needs to be done once, because the new user command file is designed to pick user command definitions up from the current copy of Link.
-
-The user command file is **SALT/spice/Link.dyalog**. If you have not done a complete checkout or clone of the repository, you will need to download this file from GitHub, as it is not included in the normal release package file.
-
-- If you have permission, you can overwrite the installed version of the Link user commands by copying the file into **$DYALOG/SALT/spice/Link.dyalog**.
-
-- Alternatively you can place a copy of the file in your **MyUCMDs** folder. This will cause it to take priority over the installed copy. Under Linux or Mac, you may need to create the folder yourself, under Windows the installation of Dyalog APL should have created it for you.
-
-
-You will need to restart Dyalog APL each time you update any of the files mentioned above.