From 2ff78f22c54d34d02d3797e7a70eea53786ef045 Mon Sep 17 00:00:00 2001 From: Stephen Taylor Date: Sun, 15 Sep 2024 15:19:50 +0100 Subject: [PATCH 1/4] - enabled MkDocs features and extensions - revised installation instructions **Not ready to merge** First, revise Step 4 for Windows. --- docs/Usage/Installation.md | 157 +++++++++++++++++++++++++++++++------ mkdocs.yml | 16 +++- 2 files changed, 148 insertions(+), 25 deletions(-) diff --git a/docs/Usage/Installation.md b/docs/Usage/Installation.md index a793b107..9c1d803b 100644 --- a/docs/Usage/Installation.md +++ b/docs/Usage/Installation.md @@ -1,39 +1,150 @@ # Installation -Link 4.0 is included with Dyalog version 19.0 or later, and is supported for use with version 18.2. +Link 4.0 is included with Dyalog version 19.0 and later, and is supported for use with version 18.2. +It depends on .NET. -!!!Note - 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. +Use these instructions to - 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 version 4 and .NET versions 6 and 8, and is expected to work with any later version of .NET. +- use a different release from that distributed with your version of Dyalog APL, or +- install Link with Dyalog 18.2 -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. +Link is maintained as an open-source project at [github.com/dyalog/link](https://github.com/dyalog/link). -!!!Note - If you use a non-standard Dyalog session (.dse file), contact support@dyalog.com for guidance on enabling Link. +!!! warning "Non-standard session file" -## Instructions + If you use a non-standard Dyalog session (`.dse`) file, contact [support@dyalog.com](mailto:support@dyalog.com) for guidance on enabling Link. -Link is maintained as an open source project at [github.com/dyalog/link](https://github.com/dyalog/link). -**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. +## Required: .NET Framework -**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. +.NET allows Dyalog to update workspace contents automatically when you use external editors or source code management systems to edit the files. -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. +Link 4.0 has been tested with the .NET Framework version 4 and .NET versions 6 and 8, and is expected to work with any later version of .NET. -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 parameter `DYALOGLINK` (v19.0 or later), or `DYALOGSTARTUPSE` (v18.2). You can add it to the command line when you start APL, but it is probably easier to use one of the following alternatives: +=== ":fontawesome-brands-windows:" Microsoft Windows" -- **Set the `DYALOGLINK` or `DYALOGSTARTUPSE` environment variable** to identify the location of Link. Unfortunately the way this is done -changed between 18.2 and 19.0: + The .NET Framework is already installed; there is nothing for you to do. -- **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.182U64.dcfg` for a specific version, to include the line: - - `DYALOGLINK: "/Users/mkrom/link"` (version 19.0 or later - point to the parent of StartupSession) - `DYALOGSTARTUPSE: "/Users/mkrom/link/StartupSession"` (version 18.2 - point to StartupSession itself) +=== ":fontawesome-brands-linux: :fontawesome-brands-apple: Linux and macOS" -Note that you should use the full name of the path. + Download .NET and follow the installation instructions. -**Finally, refresh the User Command Cache** using the `]ureset` user command, to pick up any changes to user command definitions. + :fontawesome-brands-windows: + [dotnet.microsoft.com/download](https://dotnet.microsoft.com/download) + + +## Step 2: Download Link ZIP + +To use a **different** Link release from that distributed with your version of Dyalog APL, download the corresponding ZIP. + +:fontawesome-brands-github: +[github.com/Dyalog/link/releases](https://github.com/Dyalog/link/releases) + +=== "Dyalog 19.0+" + + link-v4.0.nn.zip + +=== "Dyalog 18.2" + + link-v4.0.nn-v182.zip + +where `nn` is a patch number. + +Extract subfolder `StartupSession/Link`. + + +## Step 3: Install your Link folder + +By default, your Link folder is contained in your home folder in: + +=== "Dyalog 19.0+" + + dyalog.190UC64.files/StartupSession + +=== "Dyalog 18.2" + + dyalog.182UC64.files/StartupSession + +**If you have write access to this folder** + +- rename its existing child `Link` folder as a fallback +- copy the extracted `Link` folder here + +For example, if your user name is `judy` the full filepath of the extracted folder would be + +=== "Dyalog 19.0+" + + /Users/judy/dyalog.190UC64.files/StartupSession/Link + +=== "Dyalog 18.2" + + /Users/judy/dyalog.180UC64.files/StartupSession/Link + + +**If you do not have write access to this folder** + +- Make a new folder, e.g. `my.dyalog.files` in your home folder +- Copy the extracted `StartupSession` folder to it + + That would create the filepath + + /Users/judy/my.dyalog.files/StartupSession/Link + + +## Step 4: Declare the location of your Link folder + +### :fontawesome-brands-windows: Microsoft Windows + +In the Windows Registry… + +==FIXME== + +### :fontawesome-brands-linux: :fontawesome-brands-apple: Linux and macOS + +Select a configuration file. + +For all versions of Dyalog + + ~/.dyalog/dyalog.config + +For a specific version, such as 18.2 + + ~/.dyalog/dyalog.182U64.dcfg + +In your configuration file, declare the Link filepath: + + +=== "Dyalog 19.0+" + + Declare the filepath that contains the `StartupSession` folder. + Some examples: + + DYALOGLINK: "[HOME]/dyalog.190U64.files", + DYALOGLINK: "[HOME]/my.dyalog.files", + DYALOGLINK: "/Users/mkrom/link", + +=== "Dyalog 18.2" + + Declare the filepath of the `StartupSession` folder. + For example: + + DYALOGSTARTUPSE: "/Users/mkrom/link/StartupSession", + +## Step 5: Refresh user commands + +```apl + ]ureset +153 commands reloaded +``` + +## Step 6: Query Link version + +Test your installation by querying the Link version. + +Quit and restart APL. +Confirm you see the Link version you intended to install. + +```apl + ⎕SE.Link.Version +4.0.20 +``` diff --git a/mkdocs.yml b/mkdocs.yml index 555ee900..119f4adf 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -47,10 +47,11 @@ theme: favicon: 'img/favicon-32.png' logo: 'img/dyalog-white.svg' features: + - content.tabs.link - navigation.sections - navigation.instant name: material - + extra: version: provider: mike @@ -63,5 +64,16 @@ plugins: - search markdown_extensions: + - abbr + - attr_list + - def_list - admonition - - abbr \ No newline at end of file + - pymdownx.caret + - pymdownx.emoji: + emoji_index: !!python/name:material.extensions.emoji.twemoji + emoji_generator: !!python/name:material.extensions.emoji.to_svg + - pymdownx.mark + - pymdownx.superfences + - pymdownx.tabbed: + alternate_style: true + - pymdownx.tilde \ No newline at end of file From 20148516682a0dc040cb1c606dc2396eb7f65299 Mon Sep 17 00:00:00 2001 From: Stephen Taylor Date: Mon, 16 Sep 2024 12:20:33 +0100 Subject: [PATCH 2/4] Other operating systems include more than macOS and Linux --- docs/Usage/Installation.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/Usage/Installation.md b/docs/Usage/Installation.md index 9c1d803b..df4a824f 100644 --- a/docs/Usage/Installation.md +++ b/docs/Usage/Installation.md @@ -25,7 +25,7 @@ Link 4.0 has been tested with the .NET Framework version 4 and .NET versions 6 a The .NET Framework is already installed; there is nothing for you to do. -=== ":fontawesome-brands-linux: :fontawesome-brands-apple: Linux and macOS" +=== "Other operating systems" Download .NET and follow the installation instructions. @@ -99,7 +99,7 @@ In the Windows Registry… ==FIXME== -### :fontawesome-brands-linux: :fontawesome-brands-apple: Linux and macOS +### Other operating systems Select a configuration file. From df46ce10911158e72978a1c6aa9f3564d02546a9 Mon Sep 17 00:00:00 2001 From: Stephen Taylor Date: Tue, 24 Sep 2024 13:17:22 +0100 Subject: [PATCH 3/4] - added Footnotes and Details to MkDocs config - revised installation to include Windows --- docs/Usage/Installation.md | 143 ++++++++++++++++++++++--------------- mkdocs.yml | 5 +- 2 files changed, 89 insertions(+), 59 deletions(-) diff --git a/docs/Usage/Installation.md b/docs/Usage/Installation.md index df4a824f..a8ca5ce0 100644 --- a/docs/Usage/Installation.md +++ b/docs/Usage/Installation.md @@ -1,21 +1,33 @@ # Installation -Link 4.0 is included with Dyalog version 19.0 and later, and is supported for use with version 18.2. -It depends on .NET. +Link 4.0[^opensource] is + +- **included** with Dyalog version 19.0 and later +- **supported** for use with version 18.2 + +It depends on the .NET Framework – see below. + +[^opensource]: Link is maintained as an open-source project at [github.com/dyalog/link](https://github.com/dyalog/link). Use these instructions to -- use a different release from that distributed with your version of Dyalog APL, or -- install Link with Dyalog 18.2 +- **Install Link** with Dyalog 18.2 or + +- Install a **different release** from that distributed with your version of Dyalog APL + + ??? detail "How to display your installed Link version" -Link is maintained as an open-source project at [github.com/dyalog/link](https://github.com/dyalog/link). + ```apl + ⎕SE.Link.Version + 4.0.17 + ``` !!! warning "Non-standard session file" If you use a non-standard Dyalog session (`.dse`) file, contact [support@dyalog.com](mailto:support@dyalog.com) for guidance on enabling Link. -## Required: .NET Framework +## Required: the .NET Framework .NET allows Dyalog to update workspace contents automatically when you use external editors or source code management systems to edit the files. @@ -25,119 +37,134 @@ Link 4.0 has been tested with the .NET Framework version 4 and .NET versions 6 a The .NET Framework is already installed; there is nothing for you to do. -=== "Other operating systems" +=== ":fontawesome-brands-linux: :fontawesome-brands-apple: Linux, macOS" Download .NET and follow the installation instructions. :fontawesome-brands-windows: [dotnet.microsoft.com/download](https://dotnet.microsoft.com/download) +=== "Other operating systems" -## Step 2: Download Link ZIP - -To use a **different** Link release from that distributed with your version of Dyalog APL, download the corresponding ZIP. + Download .NET and follow the installation instructions. -:fontawesome-brands-github: -[github.com/Dyalog/link/releases](https://github.com/Dyalog/link/releases) + :fontawesome-brands-windows: + [dotnet.microsoft.com/download](https://dotnet.microsoft.com/download) -=== "Dyalog 19.0+" - link-v4.0.nn.zip +## Step 2: Download a Link ZIP -=== "Dyalog 18.2" +:fontawesome-solid-download:  +[Download the ZIP](https://github.com/Dyalog/link/releases) for your version - link-v4.0.nn-v182.zip + link-v4.0.nn.zip ⍝ Dyalog 19.0+ + link-v4.0.nn-v182.zip ⍝ Dyalog 18.2 -where `nn` is a patch number. +where `nn` is a Link patch number. Extract subfolder `StartupSession/Link`. ## Step 3: Install your Link folder -By default, your Link folder is contained in your home folder in: +### In the default location + +The Link folder belongs in the `StartupSession` folder. +By default, this is + +=== ":fontawesome-brands-windows: Microsoft Windows" -=== "Dyalog 19.0+" + where Dyalog is installed, e.g. - dyalog.190UC64.files/StartupSession + C:\Program Files\Dyalog\Dyalog APL-64 19.0 Unicode\StartupSession -=== "Dyalog 18.2" +=== ":fontawesome-brands-linux: :fontawesome-brands-apple: Linux, macOS" + + within your home folder, e.g. + + ~/dyalog.190UC64.files/StartupSession ⍝ Dyalog 19.0+ + ~/dyalog.182UC64.files/StartupSession ⍝ Dyalog 18.2 + +=== "Other operating systems" - dyalog.182UC64.files/StartupSession + ==FIXME== -**If you have write access to this folder** +If you have write access to the default location -- rename its existing child `Link` folder as a fallback -- copy the extracted `Link` folder here +- move the `Link` folder outside it (as a fallback) +- copy into it the extracted `Link` folder -For example, if your user name is `judy` the full filepath of the extracted folder would be -=== "Dyalog 19.0+" +### In a custom location - /Users/judy/dyalog.190UC64.files/StartupSession/Link +If you do not have write access to the default location -=== "Dyalog 18.2" +1. Make a new folder in your home directory +1. Copy the extracted `StartupSession` folder to it - /Users/judy/dyalog.180UC64.files/StartupSession/Link + E.g. + === ":fontawesome-brands-windows: Microsoft Windows" -**If you do not have write access to this folder** + C:\Users\mkrom\mydyalogfiles\StartupSession\Link -- Make a new folder, e.g. `my.dyalog.files` in your home folder -- Copy the extracted `StartupSession` folder to it + === ":fontawesome-brands-linux: :fontawesome-brands-apple: Linux, macOS" - That would create the filepath + ~/mydyalogfiles/StartupSession/Link - /Users/judy/my.dyalog.files/StartupSession/Link + === "Other operating systems" + ==FIXME== -## Step 4: Declare the location of your Link folder +1. Declare the custom location of your Link folder -### :fontawesome-brands-windows: Microsoft Windows + === ":fontawesome-brands-windows: Microsoft Windows" -In the Windows Registry… + In the Windows Registry, [set the environment variable](https://superuser.com/questions/284342/what-are-path-and-other-environment-variables-and-how-can-i-set-or-use-them) as below. -==FIXME== + === ":fontawesome-brands-linux: :fontawesome-brands-apple: Linux, macOS" -### Other operating systems + Select a configuration file. -Select a configuration file. + ~/.dyalog/dyalog.config ⍝ all versions of Dyalog + ~/.dyalog/dyalog.182U64.dcfg ⍝ specific version, such as 18.2 -For all versions of Dyalog + In your configuration file, set the environment variable as below. - ~/.dyalog/dyalog.config + === "Other operating systems" -For a specific version, such as 18.2 + ==FIXME== - ~/.dyalog/dyalog.182U64.dcfg + The relevant environment variable changed after Dyalog 18.2. -In your configuration file, declare the Link filepath: + === "Dyalog 19.0+" + Declare as `DYALOGLINK` the filepath that **contains** the `StartupSession` folder. + Some examples: -=== "Dyalog 19.0+" + DYALOGLINK C:\Users\mkrom\mydyalogfiles - Declare the filepath that contains the `StartupSession` folder. - Some examples: + DYALOGLINK: "[HOME]/dyalog.190U64.files", + DYALOGLINK: "[HOME]/mydyalogfiles", + DYALOGLINK: "/Users/mkrom/", - DYALOGLINK: "[HOME]/dyalog.190U64.files", - DYALOGLINK: "[HOME]/my.dyalog.files", - DYALOGLINK: "/Users/mkrom/link", + === "Dyalog 18.2" -=== "Dyalog 18.2" + Declare as `DYALOGSTARTUPSE` the filepath of the `StartupSession` folder. + For example: - Declare the filepath of the `StartupSession` folder. - For example: + DYALOGSTARTUPSE C:\Users\mkrom\StartupSession", - DYALOGSTARTUPSE: "/Users/mkrom/link/StartupSession", + DYALOGSTARTUPSE: "/Users/mkrom/StartupSession", -## Step 5: Refresh user commands +## Step 4: Refresh the user commands ```apl ]ureset 153 commands reloaded ``` -## Step 6: Query Link version +## Step 5: Display the Link version Test your installation by querying the Link version. diff --git a/mkdocs.yml b/mkdocs.yml index 119f4adf..127271a2 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -65,10 +65,13 @@ plugins: markdown_extensions: - abbr + - admonition - attr_list - def_list - - admonition + - footnotes + - md_in_html - pymdownx.caret + - pymdownx.details - pymdownx.emoji: emoji_index: !!python/name:material.extensions.emoji.twemoji emoji_generator: !!python/name:material.extensions.emoji.to_svg From 00b722ec7bb9ec4a5e32f52fc27e9e0f63656df9 Mon Sep 17 00:00:00 2001 From: Stephen Taylor Date: Tue, 24 Sep 2024 13:25:51 +0100 Subject: [PATCH 4/4] fixed typo in example --- docs/Usage/Installation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Usage/Installation.md b/docs/Usage/Installation.md index a8ca5ce0..52425e3c 100644 --- a/docs/Usage/Installation.md +++ b/docs/Usage/Installation.md @@ -153,7 +153,7 @@ If you do not have write access to the default location Declare as `DYALOGSTARTUPSE` the filepath of the `StartupSession` folder. For example: - DYALOGSTARTUPSE C:\Users\mkrom\StartupSession", + DYALOGSTARTUPSE C:\Users\mkrom\StartupSession DYALOGSTARTUPSE: "/Users/mkrom/StartupSession",