From 1d1d84451d24d7eb51ccb27ddf565cd5c1569281 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ad=C3=A1m?= <10961427+abrudz@users.noreply.github.com> Date: Mon, 10 Aug 2026 15:59:41 +0100 Subject: [PATCH 1/6] Generalise configuration-setting substitution across the guides Substitution parameters apply to all configuration settings, not only those defined in configuration files. In the Unix guide, move the References to other Configuration Parameters section up from the configuration files page to the general configuration parameters page. In the Windows guide, note the pre-defined [=DOCUMENTS] substitution. Part of #988. --- .../docs/configuration-parameters/configuration-files.md | 8 -------- .../configuration-parameters/configuration-parameters.md | 8 ++++++++ .../docs/configuration-files.md | 2 ++ 3 files changed, 10 insertions(+), 8 deletions(-) diff --git a/unix-installation-and-configuration-guide/docs/configuration-parameters/configuration-files.md b/unix-installation-and-configuration-guide/docs/configuration-parameters/configuration-files.md index bf67263ef94..e88c7a488d0 100644 --- a/unix-installation-and-configuration-guide/docs/configuration-parameters/configuration-files.md +++ b/unix-installation-and-configuration-guide/docs/configuration-parameters/configuration-files.md @@ -40,14 +40,6 @@ If the same name is defined multiple times within a configuration file then the An array can be used to define file paths, for example, `WSPATH: ["/dir1", "/dir2"]`. The only parameters which can be defined as arrays are **WSPATH**, **WSEXT** and **CFEXT**. -## References to other Configuration Parameters - -Configuration parameters that are string values can include references to other configuration parameters (irrespective of where they are defined) using square bracket delimiters. For example, `MySetting: "[DYALOG]/MyFile"` will replace `[DYALOG]` with the value of the **DYALOG** configuration parameter. - -If the referenced configuration parameter is not defined then no substitution will take place; the reference, including the square bracket delimiters, will remain in place. - -To include literal square brackets in a string, prefix them with a `\` character. - ## Nested Structures Configuration files support nested parameter structures by defining an object that corresponds to the structure. For example: diff --git a/unix-installation-and-configuration-guide/docs/configuration-parameters/configuration-parameters.md b/unix-installation-and-configuration-guide/docs/configuration-parameters/configuration-parameters.md index 155b53a9e62..3a8c4bc2a95 100644 --- a/unix-installation-and-configuration-guide/docs/configuration-parameters/configuration-parameters.md +++ b/unix-installation-and-configuration-guide/docs/configuration-parameters/configuration-parameters.md @@ -11,3 +11,11 @@ Dyalog can be customised using configuration parameters. These can be set in var This provides a great deal of flexibility, enabling a user to override one setting with another. For example, a "usual" workspace size (**MAXWS**) can be defined in the user configuration file, but be temporarily superseded by entering a different value when starting a Dyalog Session from the command line. For more information on configuration files, see [Configuration Files](configuration-files.md). For more information on environment variables, see [Environment Variables](environment-variables.md). + +## References to other Configuration Parameters + +Configuration parameters that are string values can include references to other configuration parameters (irrespective of where they are defined) using square bracket delimiters. For example, `MySetting: "[DYALOG]/MyFile"` will replace `[DYALOG]` with the value of the **DYALOG** configuration parameter. + +If the referenced configuration parameter is not defined then no substitution will take place; the reference, including the square bracket delimiters, will remain in place. + +To include literal square brackets in a string, prefix them with a `\` character. diff --git a/windows-installation-and-configuration-guide/docs/configuration-files.md b/windows-installation-and-configuration-guide/docs/configuration-files.md index 2c0103246ba..842b56257f3 100644 --- a/windows-installation-and-configuration-guide/docs/configuration-files.md +++ b/windows-installation-and-configuration-guide/docs/configuration-files.md @@ -132,6 +132,8 @@ Note that: - If the referenced configuration parameter is not defined then no substitution will take place; the reference, including square bracket delimiters, will remain in place. - To include square brackets in a string, prefix the '[' with a '\' character. +`[=DOCUMENTS]` is a pre-defined substitution parameter that is replaced with the location of the user's Documents folder (for example, `C:\Users\Bob\Documents`). + #### Nested Structures Some parameters are stored in sub-folders in the Windows Registry. Currently, all such parameters used by Dyalog APL itself relate to the Windows IDE, but you can create your own application-specific structures.. From abd1b1040d4d8cde7bd7075cebb307f6fb5f60ca Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ad=C3=A1m?= <10961427+abrudz@users.noreply.github.com> Date: Mon, 10 Aug 2026 16:51:10 +0100 Subject: [PATCH 2/6] Drop "string values" qualifier from the substitution text All configuration parameters are string values, so the qualifier is redundant; strike it in both the Unix and Windows guides, per review. --- .../docs/configuration-parameters/configuration-parameters.md | 2 +- .../docs/configuration-files.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/unix-installation-and-configuration-guide/docs/configuration-parameters/configuration-parameters.md b/unix-installation-and-configuration-guide/docs/configuration-parameters/configuration-parameters.md index 3a8c4bc2a95..065721081db 100644 --- a/unix-installation-and-configuration-guide/docs/configuration-parameters/configuration-parameters.md +++ b/unix-installation-and-configuration-guide/docs/configuration-parameters/configuration-parameters.md @@ -14,7 +14,7 @@ For more information on configuration files, see [Configuration Files](configura ## References to other Configuration Parameters -Configuration parameters that are string values can include references to other configuration parameters (irrespective of where they are defined) using square bracket delimiters. For example, `MySetting: "[DYALOG]/MyFile"` will replace `[DYALOG]` with the value of the **DYALOG** configuration parameter. +Configuration parameters can include references to other configuration parameters (irrespective of where they are defined) using square bracket delimiters. For example, `MySetting: "[DYALOG]/MyFile"` will replace `[DYALOG]` with the value of the **DYALOG** configuration parameter. If the referenced configuration parameter is not defined then no substitution will take place; the reference, including the square bracket delimiters, will remain in place. diff --git a/windows-installation-and-configuration-guide/docs/configuration-files.md b/windows-installation-and-configuration-guide/docs/configuration-files.md index 842b56257f3..93a51068650 100644 --- a/windows-installation-and-configuration-guide/docs/configuration-files.md +++ b/windows-installation-and-configuration-guide/docs/configuration-files.md @@ -113,7 +113,7 @@ The only parameters which may be defined as arrays are **WSPATH**, **WSEXT** and #### References to other Configuration Parameters -Configuration parameters which are string values may include references to other configuration parameters (regardless of where they are defined) using square bracket delimiters. For example: +Configuration parameters may include references to other configuration parameters (regardless of where they are defined) using square bracket delimiters. For example: ```apl MySetting: "[DYALOG]/MyFile" ``` From 75bb746e7060fe361faff00a30e7bd80cfd6fd92 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ad=C3=A1m?= <10961427+abrudz@users.noreply.github.com> Date: Mon, 10 Aug 2026 17:14:58 +0100 Subject: [PATCH 3/6] Move the Windows substitution section up a level Per review, the relocation of References to other Configuration Parameters is pertinent to Windows too: move it from the configuration files page up to the general configuration parameters page, matching the Unix guide, since substitution applies to all configuration settings regardless of how they are defined. --- .../docs/configuration-files.md | 23 ------------------- .../configuration-parameters.md | 23 +++++++++++++++++++ 2 files changed, 23 insertions(+), 23 deletions(-) diff --git a/windows-installation-and-configuration-guide/docs/configuration-files.md b/windows-installation-and-configuration-guide/docs/configuration-files.md index 93a51068650..0b91af6abb8 100644 --- a/windows-installation-and-configuration-guide/docs/configuration-files.md +++ b/windows-installation-and-configuration-guide/docs/configuration-files.md @@ -111,29 +111,6 @@ WSPATH: ["/dir1", "/dir2"] The only parameters which may be defined as arrays are **WSPATH**, **WSEXT** and **CFEXT**. -#### References to other Configuration Parameters - -Configuration parameters may include references to other configuration parameters (regardless of where they are defined) using square bracket delimiters. For example: -```apl -MySetting: "[DYALOG]/MyFile" -``` - -will replace `[DYALOG`] with the value of the **DYALOG** configuration value. - -If the string inside the `[]` delimiters is "`.`", the "`.`" is replaced is replaced with the path of the directory containing the configuration file itself. Therefore, -```apl -FILENAME: "[.]/x.txt" -``` - -will set the parameter **FILENAME** to a value which is a reference to a file called `x.txt` in the same directory as the configuration file defining it. - -Note that: - -- If the referenced configuration parameter is not defined then no substitution will take place; the reference, including square bracket delimiters, will remain in place. -- To include square brackets in a string, prefix the '[' with a '\' character. - -`[=DOCUMENTS]` is a pre-defined substitution parameter that is replaced with the location of the user's Documents folder (for example, `C:\Users\Bob\Documents`). - #### Nested Structures Some parameters are stored in sub-folders in the Windows Registry. Currently, all such parameters used by Dyalog APL itself relate to the Windows IDE, but you can create your own application-specific structures.. diff --git a/windows-installation-and-configuration-guide/docs/configuration-parameters/configuration-parameters.md b/windows-installation-and-configuration-guide/docs/configuration-parameters/configuration-parameters.md index 06fd7dede0f..cead55e8013 100644 --- a/windows-installation-and-configuration-guide/docs/configuration-parameters/configuration-parameters.md +++ b/windows-installation-and-configuration-guide/docs/configuration-parameters/configuration-parameters.md @@ -39,3 +39,26 @@ You can change parameters in the Registry in one of two ways: - Using the Configuration dialog box that is obtained by selecting *Configure* from the *Options* menu on the Dyalog APL/W session. See ["The Configuration Dialog Box"](../configuring-the-ide/configuration-dialog/configuration-dialog-general-tab.md) for details. - By directly editing the Windows Registry using `REGEDIT.EXE` or `REGEDIT32.EXE`. This is necessary for parameters that are not editable via the Configuration dialog box. + +## References to other Configuration Parameters + +Configuration parameters may include references to other configuration parameters (regardless of where they are defined) using square bracket delimiters. For example: +```apl +MySetting: "[DYALOG]/MyFile" +``` + +will replace `[DYALOG`] with the value of the **DYALOG** configuration value. + +If the string inside the `[]` delimiters is "`.`", the "`.`" is replaced is replaced with the path of the directory containing the configuration file itself. Therefore, +```apl +FILENAME: "[.]/x.txt" +``` + +will set the parameter **FILENAME** to a value which is a reference to a file called `x.txt` in the same directory as the configuration file defining it. + +Note that: + +- If the referenced configuration parameter is not defined then no substitution will take place; the reference, including square bracket delimiters, will remain in place. +- To include square brackets in a string, prefix the '[' with a '\' character. + +`[=DOCUMENTS]` is a pre-defined substitution parameter that is replaced with the location of the user's Documents folder (for example, `C:\Users\Bob\Documents`). From 20fbf02f2e9e9bf4d449b0fbc44a3d277d2ea7ce Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ad=C3=A1m?= <10961427+abrudz@users.noreply.github.com> Date: Mon, 10 Aug 2026 17:18:02 +0100 Subject: [PATCH 4/6] Fix duplicated words in the substitution description --- .../docs/configuration-parameters/configuration-parameters.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/windows-installation-and-configuration-guide/docs/configuration-parameters/configuration-parameters.md b/windows-installation-and-configuration-guide/docs/configuration-parameters/configuration-parameters.md index cead55e8013..a9d32d06077 100644 --- a/windows-installation-and-configuration-guide/docs/configuration-parameters/configuration-parameters.md +++ b/windows-installation-and-configuration-guide/docs/configuration-parameters/configuration-parameters.md @@ -49,7 +49,7 @@ MySetting: "[DYALOG]/MyFile" will replace `[DYALOG`] with the value of the **DYALOG** configuration value. -If the string inside the `[]` delimiters is "`.`", the "`.`" is replaced is replaced with the path of the directory containing the configuration file itself. Therefore, +If the string inside the `[]` delimiters is "`.`", the "`.`" is replaced with the path of the directory containing the configuration file itself. Therefore, ```apl FILENAME: "[.]/x.txt" ``` From 70772492c21a9418d6d620522a131ac91948f22e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ad=C3=A1m?= <10961427+abrudz@users.noreply.github.com> Date: Mon, 17 Aug 2026 04:02:37 +0100 Subject: [PATCH 5/6] Apply documentation writing guidelines --- .../configuration-parameters.md | 2 +- .../configuration-parameters.md | 10 +++++----- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/unix-installation-and-configuration-guide/docs/configuration-parameters/configuration-parameters.md b/unix-installation-and-configuration-guide/docs/configuration-parameters/configuration-parameters.md index 065721081db..9222b6cdff3 100644 --- a/unix-installation-and-configuration-guide/docs/configuration-parameters/configuration-parameters.md +++ b/unix-installation-and-configuration-guide/docs/configuration-parameters/configuration-parameters.md @@ -12,7 +12,7 @@ This provides a great deal of flexibility, enabling a user to override one setti For more information on configuration files, see [Configuration Files](configuration-files.md). For more information on environment variables, see [Environment Variables](environment-variables.md). -## References to other Configuration Parameters +## References to Other Configuration Parameters Configuration parameters can include references to other configuration parameters (irrespective of where they are defined) using square bracket delimiters. For example, `MySetting: "[DYALOG]/MyFile"` will replace `[DYALOG]` with the value of the **DYALOG** configuration parameter. diff --git a/windows-installation-and-configuration-guide/docs/configuration-parameters/configuration-parameters.md b/windows-installation-and-configuration-guide/docs/configuration-parameters/configuration-parameters.md index a9d32d06077..a38f88a86e5 100644 --- a/windows-installation-and-configuration-guide/docs/configuration-parameters/configuration-parameters.md +++ b/windows-installation-and-configuration-guide/docs/configuration-parameters/configuration-parameters.md @@ -40,25 +40,25 @@ You can change parameters in the Registry in one of two ways: - Using the Configuration dialog box that is obtained by selecting *Configure* from the *Options* menu on the Dyalog APL/W session. See ["The Configuration Dialog Box"](../configuring-the-ide/configuration-dialog/configuration-dialog-general-tab.md) for details. - By directly editing the Windows Registry using `REGEDIT.EXE` or `REGEDIT32.EXE`. This is necessary for parameters that are not editable via the Configuration dialog box. -## References to other Configuration Parameters +## References to Other Configuration Parameters -Configuration parameters may include references to other configuration parameters (regardless of where they are defined) using square bracket delimiters. For example: +Configuration parameters can include references to other configuration parameters (regardless of where they are defined) using square bracket delimiters. For example: ```apl MySetting: "[DYALOG]/MyFile" ``` -will replace `[DYALOG`] with the value of the **DYALOG** configuration value. +will replace `[DYALOG]` with the value of the **DYALOG** configuration parameter. If the string inside the `[]` delimiters is "`.`", the "`.`" is replaced with the path of the directory containing the configuration file itself. Therefore, ```apl FILENAME: "[.]/x.txt" ``` -will set the parameter **FILENAME** to a value which is a reference to a file called `x.txt` in the same directory as the configuration file defining it. +will set the parameter **FILENAME** to a value that is a reference to a file called `x.txt` in the same directory as the configuration file defining it. Note that: - If the referenced configuration parameter is not defined then no substitution will take place; the reference, including square bracket delimiters, will remain in place. -- To include square brackets in a string, prefix the '[' with a '\' character. +- To include square brackets in a string, prefix the `[` with a `\` character. `[=DOCUMENTS]` is a pre-defined substitution parameter that is replaced with the location of the user's Documents folder (for example, `C:\Users\Bob\Documents`). From 1e7d5d836fa890c80318b9ec38f22574397d0370 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ad=C3=A1m?= <10961427+abrudz@users.noreply.github.com> Date: Tue, 25 Aug 2026 12:34:41 +0100 Subject: [PATCH 6/6] Action Richard's #993 review The substitution feature is now general, so drop the redundant '(regardless/ irrespective of where they are defined)' qualifier on both the Windows and UNIX pages. The '[.]' current-directory reference applies to configuration files only, so move it out of the general configuration-parameters page and back into the Windows configuration-files page under its own heading, cross-referenced to the general references section. --- .../configuration-parameters/configuration-parameters.md | 2 +- .../docs/configuration-files.md | 9 +++++++++ .../configuration-parameters/configuration-parameters.md | 9 +-------- 3 files changed, 11 insertions(+), 9 deletions(-) diff --git a/unix-installation-and-configuration-guide/docs/configuration-parameters/configuration-parameters.md b/unix-installation-and-configuration-guide/docs/configuration-parameters/configuration-parameters.md index 9222b6cdff3..cf5eff7f03f 100644 --- a/unix-installation-and-configuration-guide/docs/configuration-parameters/configuration-parameters.md +++ b/unix-installation-and-configuration-guide/docs/configuration-parameters/configuration-parameters.md @@ -14,7 +14,7 @@ For more information on configuration files, see [Configuration Files](configura ## References to Other Configuration Parameters -Configuration parameters can include references to other configuration parameters (irrespective of where they are defined) using square bracket delimiters. For example, `MySetting: "[DYALOG]/MyFile"` will replace `[DYALOG]` with the value of the **DYALOG** configuration parameter. +Configuration parameters can include references to other configuration parameters using square bracket delimiters. For example, `MySetting: "[DYALOG]/MyFile"` will replace `[DYALOG]` with the value of the **DYALOG** configuration parameter. If the referenced configuration parameter is not defined then no substitution will take place; the reference, including the square bracket delimiters, will remain in place. diff --git a/windows-installation-and-configuration-guide/docs/configuration-files.md b/windows-installation-and-configuration-guide/docs/configuration-files.md index 0b91af6abb8..22658f01c10 100644 --- a/windows-installation-and-configuration-guide/docs/configuration-files.md +++ b/windows-installation-and-configuration-guide/docs/configuration-files.md @@ -111,6 +111,15 @@ WSPATH: ["/dir1", "/dir2"] The only parameters which may be defined as arrays are **WSPATH**, **WSEXT** and **CFEXT**. +## References Relative to the Configuration File + +Within a configuration file, a [reference to another configuration parameter](configuration-parameters/configuration-parameters.md#references-to-other-configuration-parameters) can also refer to the location of the file itself. If the string inside the `[]` delimiters is "`.`", the "`.`" is replaced with the path of the directory containing the configuration file. For example: +```apl +FILENAME: "[.]/x.txt" +``` + +will set the parameter **FILENAME** to a value that is a reference to a file called `x.txt` in the same directory as the configuration file defining it. + #### Nested Structures Some parameters are stored in sub-folders in the Windows Registry. Currently, all such parameters used by Dyalog APL itself relate to the Windows IDE, but you can create your own application-specific structures.. diff --git a/windows-installation-and-configuration-guide/docs/configuration-parameters/configuration-parameters.md b/windows-installation-and-configuration-guide/docs/configuration-parameters/configuration-parameters.md index a38f88a86e5..ff856ba4dde 100644 --- a/windows-installation-and-configuration-guide/docs/configuration-parameters/configuration-parameters.md +++ b/windows-installation-and-configuration-guide/docs/configuration-parameters/configuration-parameters.md @@ -42,20 +42,13 @@ You can change parameters in the Registry in one of two ways: ## References to Other Configuration Parameters -Configuration parameters can include references to other configuration parameters (regardless of where they are defined) using square bracket delimiters. For example: +Configuration parameters can include references to other configuration parameters using square bracket delimiters. For example: ```apl MySetting: "[DYALOG]/MyFile" ``` will replace `[DYALOG]` with the value of the **DYALOG** configuration parameter. -If the string inside the `[]` delimiters is "`.`", the "`.`" is replaced with the path of the directory containing the configuration file itself. Therefore, -```apl -FILENAME: "[.]/x.txt" -``` - -will set the parameter **FILENAME** to a value that is a reference to a file called `x.txt` in the same directory as the configuration file defining it. - Note that: - If the referenced configuration parameter is not defined then no substitution will take place; the reference, including square bracket delimiters, will remain in place.