Add a cross-platform Dyalog Configuration Guide - #950
Open
abrudz wants to merge 54 commits into
Open
Conversation
Add a new cross-platform guide subsite dyalog-configuration-guide/ (mkdocs.yml at version 21.0, About page) and register it under a new "Cross-platform Environment" category in the root nav, after "Core Reference". Implements #5 and #6. Part of Dyalog#719 (Step One).
Add the Introduction page and the "How to Set Configuration Parameters" section (Overview, Order of Precedence, Command Line, Application Configuration Files, Environment Variables, User Configuration Files, Windows Registry, Built-in Defaults, and Configuration File Structure), synthesised from the Windows and Unix Installation & Configuration guides so the precedence and file-format material is stated once, cross-platform. Implements #7 and #8. Part of Dyalog#719 (Step One).
Move all 148 Windows configuration-parameter pages (including the AutoComplete and ValueTips groups) into the new Dyalog Configuration Guide with git mv, preserving history, and move their nav block from the Windows guide into the new guide. Repair every affected link: repoint the ~26 inbound cross-guide references and the Windows guide's own internal references to the new location, rewrite the moved pages' relative links to the Windows Configuration Dialog and other Windows pages as cross-guide links, and copy the two images the moved pages use. All guide links resolve and the Windows guide no longer references the removed pages. This is the relocation and link-repair pass; the per-parameter template and per-OS annotation follow per category tranche. Implements #11 and the link repair of #23. Part of Dyalog#719.
First Session-category tranche: rework Log_File, Log_File_InUse, Log_Size, History_Size, Input_Size, PFKey_Size, and Session_File to the standard template (Description, Valid values, Default, Related parameters), folding in the Unix and macOS defaults where known. The per-OS Log_File default and the Session_File default are stated explicitly; defaults not present in the migrated source carry a grep-able "REVIEW(default)" marker for accuracy confirmation. Part of #27 and Dyalog#719 (Step Three, applied during migration).
Rework Default_DIV, Default_IO, Default_ML, Default_PP, Default_RTL, Default_WX, Default_PW, and Auto_PW to the standard template. Each links its ⎕-system-variable page for the valid values, states the clear-workspace default where the migrated source gives it, and notes the per-OS behaviour of Auto_PW/Default_PW and the UNIX/macOS ⎕SE effect of Default_WX. Defaults absent from the source (⎕PW, ⎕WX) carry a grep-able REVIEW(default) marker. Part of #28 and Dyalog#719.
Rework the editor-behaviour parameters to the standard template: Confirm_Abort, Confirm_Close, Confirm_Fix, AutoFormat, AutoIndent, TabStops, DockableEditWindows, DoubleClickEdit, WrapSearch, WrapSearchMsgBox, DYALOG_DISCARD_FN_SOURCE, and APLAN_FOR_EDITOR. Each has Valid values and a Default (all present in the source except WrapSearch and WrapSearchMsgBox, which carry a REVIEW(default) marker), with related-parameter cross-links. Part of #29 and Dyalog#719.
Rework the tracer parameters to the standard template: Trace_On_Error, Trace_Level_Warn, SingleTrace, SkipLines, SessionOnTop, AddClassHeaders, and the Trace window geometry (Trace_First_X/Y, Trace_Offset_X/Y). Trace_On_Error carries a genuine per-OS default (Windows 0, UNIX/macOS 1); SkipLines documents its 1/2/4 bitmask; ClassicMode/SingleTrace conditions are noted with cross-links. Defaults absent from the source carry a REVIEW(default) marker. Part of #30 and Dyalog#719.
Rework the edit-window and stand-alone ⎕SM window geometry parameters to the standard template: Edit_Cols, Edit_Rows, Edit_First_X/Y, Edit_Offset_X/Y, SM_Cols, and SM_Rows. All take an integer number of character units; the ClassicMode condition on the edit-window positions is noted, and SM_Cols/SM_Rows link ⎕SM. Defaults are not in the source and carry a REVIEW(default) marker. Part of #29 and Dyalog#719.
Rework APLAN_FOR_OUTPUT, DYALOG_GUTTER_ENABLE, Confirm_Session_Delete, URLHighlight, StatusOnEdit, ToolBarsOnEdit, AutoDPI, Dyalog_Pixel_Type, ClassicMode, and ClassicModeSavePosition to the standard template. AutoDPI and Dyalog_Pixel_Type carry a Microsoft Windows-only restriction admonition; DYALOG_GUTTER_ENABLE notes its interface- dependent default (0 for TTY, 1 otherwise). Defaults absent from the source carry a REVIEW(default) marker. Part of #27 and Dyalog#719.
Rework the keyboard/input parameters to the standard template: APLK, APLKeys, APLT, APLTrans, InitialKeyboardLayout(+InUse/ShowAll), OverstrikesPopup, ResolveOverstrikes, UseXCV, UnicodeToClipboard, KeyboardInputDelay, WantsSpecialKeys, and mapchars. Each carries the relevant restriction admonition (Classic edition, Unicode edition, or Microsoft Windows). Defaults are stated where the source gives them (APLKeys/APLTrans install sub-directories, APLT WIN.DOT on Windows, UnicodeToClipboard 0) and flagged otherwise. Part of abrudz/documentation#719.
Rework Load, LX, MaxWS, WSPath, WSEXT, CFEXT, ConfigFile, UserConfigFile, DyalogStartup, DyalogStartupSE, and DyalogStartup_X to the standard template. Records the per-OS WSEXT/CFEXT defaults, the Raspberry Pi MaxWS default, and the LX Unicode/development restriction; repoints ConfigFile/UserConfigFile to the guide's own How to Set pages. Part of abrudz/documentation#719.
Rework MaxAplCores, qcmd_timeout, SaveContinueOnExit, SaveSessionOnExit, SaveLogOnExit, RunAsService, Dyalog_NETCore, Enable_CEF, APL_MAX_THREADS, CMD_PREFIX/CMD_POSTFIX, Serial, and DYALOG_SERIAL to the standard template. Windows-only restrictions on qcmd_timeout, RunAsService and CMD_PREFIX/POSTFIX; a .NET restriction and per-OS default on Dyalog_NETCore; a Legacy admonition on Serial; Enable_CEF documents its desktop-dependent default and the registry/config caveat. Part of abrudz/documentation#719.
Rework Dyalog, localdyalogdir, DyalogInstallDir, ProgramFolder, DyalogLink, DyalogHelpDir, DyalogWebSite, DyalogEmailAddress, ExternalHelpURL, and UseExternalHelpURL to the standard template. ProgramFolder, ExternalHelpURL, and UseExternalHelpURL carry a Microsoft Windows-only restriction; Dyalog and DyalogLink state their defaults. Remaining defaults flagged for confirmation. Part of abrudz/documentation#719.
Rework APL_FCREATE_PROPS_C/J, APL_FAST_FCHK, APL_CODE_E_MAGNITUDE, APL_COMPLEX_AS_V12, File_Stack_Size, AplCoreName, APL_TextInAplCore, DMXOutputOnError, PassExceptionsToOpSys, ErrorOnExternalException, and ShowStatusOnError to the standard template. APL_COMPLEX_AS_V12 carries a Legacy admonition; PassExceptionsToOpSys a Windows-only restriction; confirmed defaults recorded (checksum/journaling 1, APL_FAST_FCHK 0, APL_CODE_E_MAGNITUDE 0, APL_TextInAplCore 1) and the rest flagged. Part of abrudz/documentation#719.
Rework the twelve AutoComplete parameters (CancelKey1/2, Cols, CommonKey1, CompleteKey1/2, Enabled, History, HistorySize, PrefixSize, Rows, ShowFiles) to the standard template, with key/size/boolean values and related-parameter cross-links. Defaults are not in the source and carry a REVIEW(default) marker. Also corrected the source "Auto Cancel" and "Completeion" typos. Part of abrudz/documentation#719.
Rework ValueTips/ColourScheme/Delay/Enabled, DYALOG_EVENTLOGGINGLEVEL, DYALOG_EVENTLOGNAME, TraceStopMonitor, Ride_Spawned, UCMDCacheFile, IniFile, and Greet_Bitmap to the standard template. Windows-only restrictions on the event-log pair and IniFile; a Ride restriction on Ride_Spawned. UCMDCacheFile and IniFile record their (macro-derived) defaults; the rest are flagged, and DYALOG_EVENTLOGGINGLEVEL flags its values pending confirmation of Boolean vs multi-level. Part of abrudz/documentation#719.
Rework the final parameters to the standard template: aplnid (with its per-OS split), Dyalog_LineEditor_Mode, DYALOG_NOPOPUPS, EditorState, InitFullScriptNormal/Susp, PropertyExposeRoot/SE, XPLookAndFeel, and yy_window; and add the Ride restriction to RIDE_Init. Windows-only restrictions on DYALOG_NOPOPUPS and XPLookAndFeel. This completes the per-parameter template pass across all 147 parameters. Part of abrudz/documentation#719.
Replace the Windows-specific intro (precedence list and Registry-editing instructions, now covered by Introduction and How to Set Configuration Parameters) with a concise section overview: what a parameter page contains, a pointer to the by-category listing and to How to Set, and the size-unit syntax as a table. Refs Dyalog#719
Add a by-category page modelled on system-functions-by-category, grouping all 147 configuration parameters into 18 subject categories with a one-line description and a link to each parameter's page, and register it in the guide navigation after the Introduction. Refs Dyalog#719
Merge the linear Dyalog#719 branch stack (scaffold, migration, per-category template tranches, landing page, and by-category listing) onto the current main. This is the single integration branch for the guide. Two configuration-parameter pages (aplan-for-editor, aplan-for-output) were edited on main after the stack was branched; the stack has moved and retemplated them into the Configuration Guide, where the equivalent link fix is already present, so the old Windows-guide copies stay deleted. The edits to display-of-arrays.md merged cleanly, keeping both the moved-page link and main's table-link fixes. Refs Dyalog#719
Do not run the source lists on as a single sentence: drop the trailing semicolons and full stop in the Overview list, and drop the "settings, which override" connectives and final full stop in the Order of Precedence list. The lead-in line already states that each source overrides those below it. Refs Dyalog#719
The migration repointed links to and from the moved configuration-parameter pages but kept the .md extension on the cross-guide forms, which the site-urls plugin does not rewrite, so they resolved to nonexistent .md URLs. Drop the .md on those cross-guide links (183 links across 101 pages: the moved pages' links to the Windows Configuration Dialog and other Windows pages, and the Windows guide's repointed references into the Configuration Guide). Also correct two language-reference links (system, dt) that were one ../ short of the Configuration Guide. Verified with a local mkdocs build: every affected link now resolves, and no link into or out of the Configuration Guide is broken. Refs Dyalog#719
Migrate the parameters that exist only on UNIX and macOS from the UNIX guide's environment-variables page into the Configuration Guide, each on its own page with an availability admonition: APLSTATUSFD, DYALOG_SERIALFILE, DYALOG_SHELL_SUBPROCESS (AIX), EDITOR_COLUMNS, and the Classic-edition translate-table overrides APLK0 and APLTn. Add them to the navigation and a new "UNIX and macOS specific" section of the by-category listing, and repoint language-reference-guide/shell.md at the new DYALOG_SHELL_SUBPROCESS page. TERM and LIBPATH are deliberately not migrated: they are standard operating- system environment variables (whose names vary by platform) that Dyalog merely respects, not Dyalog configuration parameters. Defaults that were not recorded in the migrated source are flagged with REVIEW comments. Refs Dyalog#719
Most per-OS behaviour was already captured when the parameters were templated (aplnid, Dyalog_NETCore, Enable_CEF, MaxWS, Default_WX, Log_File, Auto_PW, Session_File). Fill the last gaps from the UNIX guide: the Dyalog parameter is set by the mapl startup script on UNIX and macOS (with the reliable way to locate the executable); APL_TextInAplCore is 0 in the interpreter but set to 1 by the startup script; and APLKeys and APLTrans fall back to the Dyalog directory, then /usr/dyalog, on UNIX and macOS. The APLKeys/APLTrans per-OS defaults are flagged for reconciliation. Refs Dyalog#719
The Windows and UNIX guides restated the configuration-file syntax, precedence order, and environment-variable list that the Configuration Guide now documents cross-platform. Replace that duplicated material with a short summary and links into the Configuration Guide: the Windows configuration-files page, and the UNIX configuration-parameters, configuration-files, and environment-variables pages. Everything removed has an equivalent in the Configuration Guide, including the Windows credentials warning and the Configuration Dialog/Registry interaction. The one exception was the rule that a back-slash in a parameter name becomes an underscore in the equivalent environment variable, which is added to the Configuration Guide's environment-variables page. Verified with a local mkdocs build: the pointer links resolve and the repository's broken-link count is unchanged. Refs Dyalog#719
An unescaped back-slash in a path is accepted rather than reported as an error, so the corruption is silent. State that, and add the case where the character following the back-slash does form an escape sequence: "c:\temp" yields c:, a tab, then emp. The existing example only drops the back-slash, which understates the hazard. Refs Dyalog#719
The notes about component files with both journalling and checksum properties set to 0 were written in the future tense, from before 21.0. State the position now: such files cannot be created, and existing ones are read-only. Amend the notes on FCREATE, FAPPEND, FREPLACE, FRESIZE, FSTAC and FPROPS accordingly, noting on FPROPS that the properties of an existing file can still be changed, and on the two component-file creation parameters APL_FCREATE_PROPS_C and APL_FCREATE_PROPS_J that such files cannot be created. Apply the same correction to Integrity and Security in the Programming Reference Guide, found by scanning for other pages that discuss journalling and checksumming. Record that external variables are read-only and cannot be created, on Set External Variable and Query External Variable. Document the two new configuration parameters, DYALOG_EXTVAR_SUPPORTED and DYALOG_S32_SUPPORTED, in the Windows guide with navigation entries, and in the UNIX guide's environment-variable tables. Setting either to 0 disables support, which identifies whether an application still depends on the deprecated feature. The emergency reset switches are deliberately not documented, and the release notes are covered by Dyalog#618. Refs Dyalog#949
The notes on FTIE and FSTIE record that small-span component files are read-only and that support is scheduled for removal, but not that the support can be turned off now. Mention DYALOG_S32_SUPPORTED, so that a reader looking at either tie function can find out whether an application still depends on small-span files. Refs Dyalog#949
…uide Merge the Dyalog#949 work and place its configuration-parameter changes where this branch puts them. The two new parameters, DYALOG_EXTVAR_SUPPORTED and DYALOG_S32_SUPPORTED, move from the Windows guide into the Configuration Guide, rewritten to the template used there, and are added to the navigation and to the component-files section of the by-category listing. The deprecation note for component files with both journalling and checksum properties set to 0 goes on the Configuration Guide copies of APL_FCREATE_PROPS_C and APL_FCREATE_PROPS_J, since the Windows copies no longer exist here. The rows Dyalog#949 added to the UNIX environment-variable tables are dropped, because this branch reduces that page to a summary and a reference, and the parameters are documented in the Configuration Guide instead. The references to DYALOG_S32_SUPPORTED from FTIE and FSTIE are repointed accordingly. Refs Dyalog#719, Dyalog#949
This was referenced Sep 8, 2026
Closed
Closed
Closed
Closed
Default_PW is 76 on Microsoft Windows and 79 on UNIX and macOS; Default_WX is 3 on all platforms. Both were confirmed by Adam, so the REVIEW markers on the two pages are resolved and removed. The ⎕PW page gave the assignable range but never the value in a clear workspace, so it now names Default_PW and gives it per platform.
The guidelines give "Unix" as the generic term for non-Windows systems, so naming macOS alongside it is redundant, and "UNIX" is a trademark that names the certified operating system rather than the family. Behaviour peculiar to macOS keeps its own macos admonition where it arises. Covers 31 files: the Configuration Guide's parameter pages and its by-category and how-to-set pages, plus the pages this branch already touched. Pre-existing bare "UNIX" in prose this branch did not otherwise change is left alone.
The guidelines require the full term when a configuration parameter is introduced. The same sentence was corrected on main in review of Dyalog#1104; this branch carries its own copy, pointing at the Configuration Guide instead.
John Daintree confirmed these against the interpreter source, answering the REVIEW markers they carried. APLKeys and APLTrans fall back to the aplkeys and apltrans sub-directories of the Dyalog directory on every platform, so the Unix wording that claimed a different fallback is wrong and goes. The /usr/dyalog fallback it named belongs to the Dyalog parameter, whose own page carries it. APLK and APLT fall back to the terminal type, or to utf8 or redirected when input and output are a file. On Microsoft Windows the extension is appended and TERM is itself win, which is where the documented WIN.DOT comes from. DYALOG_EVENTLOGGINGLEVEL is Boolean in effect: any value above zero writes every entry, and the default is 0. The interpreter carries comments for a multi-level setting that was never implemented, so the values stay as they behave rather than as the comments describe. Session_File has no interpreter default at all; unset means no session file is loaded, and it is the installation that points it at default.dse.
Fixes Dyalog#1092 on this branch too, so the migrated page does not lose the restriction when this guide replaces the one in the Windows guide. Dyalog reads the parameter before it loads any configuration file, so a setting made in one is silently ignored.
MkDocs resolves only a target ending in .md, so the bare and trailing-slash forms were passed to the rendered HTML unchecked and cost the reader a redirect. The repository was normalised in Dyalog#1123; this brings the links on this branch into the same form so they are validated at build time.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Implements #719.
Configuration information was duplicated across the Windows and UNIX Installation and Configuration Guides. That caused drift, left per-platform gaps, and gave no single place that states the differences between platforms. This adds a cross-platform Dyalog Configuration Guide as the single source of truth, and reduces the OS guides to summaries that reference it.
The new guide
dyalog-configuration-guide/, targeting version 21.0, registered in the root navigation under a new "Cross-platform Environment" category.
Per-platform behaviour is stated on the parameter pages themselves. For example the differing defaults of Trace_On_Error, Dyalog_NETCore, MaxWS, and Auto_PW; that aplnid is not used on UNIX and macOS, where the user number comes from the UID; and that Dyalog and APL_TextInAplCore are set by the startup script on UNIX and macOS.
TERM and LIBPATH are deliberately not included. They are standard operating-system environment variables that Dyalog respects, not Dyalog configuration parameters, and their names vary by platform.
The OS guides
The Windows configuration-files page and the three UNIX configuration pages now carry a short summary and links into the new guide, removing about 350 lines of duplicated prose. Windows-only material stays where it was: the Registry, the Configuration Dialog, and registry-subfolders.
Two details that existed in only one of the OS guides were carried into the new guide rather than dropped:
Verification
Built locally with the pinned toolchain from tools/requirements-docs.txt, then checked by resolving every href in the rendered HTML against the build output, since the site-urls plugin rewrites cross-guide links at build time and static inspection of the Markdown is unreliable.
What still needs a technical review
86 pages carry a REVIEW(...) HTML comment marking a default value that the migrated source did not state, so it could not be confirmed while applying the template. Run grep -rn 'REVIEW(' dyalog-configuration-guide/ to list them.
These mark pre-existing gaps rather than regressions: the original pages did not give those defaults either. Where a page did state a default, it is retained.
Four of the comments ask something more specific:
Resolving these is better done as a follow-up than by holding up the restructuring.