Add a cross-platform Dyalog Configuration Guide - #950
Open
abrudz wants to merge 43 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
The docking layout of the Session is now held in a Session layout file, which is loaded at start-up and written back on exit, so a layout chosen from the Layout menu survives a restart without the session file being saved. Document the new LAYOUT_FILE configuration parameter, including its default in the user's Documents directory and the layout files supplied in the Dyalog installation directory. Bring the Layout menu up to date: it offers Open..., Classic, Debugger at the bottom, and Classic with Vertical Inline Tracing. Debugger on the left has gone, the menu governs the whole Session rather than just the Debugger, and the selected layout now persists. Classic Dyalog mode is selected from that menu rather than from the Configuration dialog box, so correct The Editor accordingly and remove the ClassicMode, ClassicModeSavePosition and SessionOnTop parameters, which no longer have any effect, together with their navigation entries and their rows on the Trace/Edit tab. Parameters that remain effective in Classic Dyalog mode referred to ClassicMode being 1, and in two cases linked to its page; state that they apply in Classic Dyalog mode instead. Refs Dyalog#939
The Documents folder name omits the width for the 32-bit interpreter and omits the edition for the Classic edition, so the 32-bit Classic edition of Dyalog 19.0 uses Dyalog APL 19.0 Files. State the rule and give an example of each form, rather than implying that both parts are always present. Also record that the .layout extension has to be given; unlike the session file, it is not assumed. Refs Dyalog#939
There is no longer a single Trace window setting, in Classic Dyalog mode or otherwise. Remove the SingleTrace parameter, its navigation entry and its row on the Trace/Edit tab, and drop the condition from the trace window stagger and warning-level parameters, which now depend only on Classic Dyalog mode. The Layout menu items are managed by the interpreter rather than by APL callbacks, so leave their Action column empty, as the View menu does. Refs Dyalog#939
Merge the Dyalog#939 work and place its configuration-parameter changes where this branch puts them. LAYOUT_FILE moves into the Configuration Guide, rewritten to the template used there, and is added to the navigation and to the by-category listing. ClassicMode, ClassicModeSavePosition, SessionOnTop and SingleTrace, which no longer have any effect, are removed from the guide, its navigation and that listing, and the parameters that referred to them now state that they apply in Classic Dyalog mode. The four corresponding rows go from the Trace/Edit tab, whose remaining rows keep this branch's links into the Configuration Guide. Refs Dyalog#719, Dyalog#939
The width is omitted for the 32-bit interpreter and the edition for the Classic edition, so the folder is Dyalog APL 19.0 Files for the 32-bit Classic edition, not Dyalog APL-32 19.0 Classic Files. Mark both parts optional instead of implying that each is always present, in the current guide and in the copy carried by the v19.0 release notes. While here, add the separator between the major and minor version numbers in the current guide, which the example already shows. Refs Dyalog#959
Merge the Dyalog#959 fix. The correction to the Windows guide's Log_File page applies here to the Configuration Guide's copy, which states the default per operating system, and the copy carried by the v19.0 release notes comes across unchanged. Refs Dyalog#719, Dyalog#959
DYALOG_S32_SUPPORTED was dropped from the project and never implemented, so remove the parameter page, its navigation entry, its row in the UNIX environment-variable table, and the references to it added to FTIE and FSTIE, which return to their earlier wording. DYALOG_EXTVAR_SUPPORTED defaults to 0, not 1: external variables are not supported at all by default, and setting the parameter to 1 reinstates them for the time being. Correct the parameter page and the UNIX table, and say so on Set External Variable and Query External Variable, which described them as read-only instead. Refs Dyalog#949
Merge the corrections from Dyalog#949. DYALOG_S32_SUPPORTED goes from the Configuration Guide, its navigation and the by-category listing, since the parameter was never implemented. DYALOG_EXTVAR_SUPPORTED defaults to 0 here too, with the note that external variables are not supported by default and that the parameter reinstates them, and the references from Set External Variable and Query External Variable point at the Configuration Guide copy. Refs Dyalog#719, Dyalog#949
Move the References to Other Configuration Parameters section out of the configuration file structure page into the general How to Set overview, since substitution applies to all configuration settings regardless of how they are defined, and note the pre-defined [=DOCUMENTS] substitution on Microsoft Windows. Part of Dyalog#988.
Document the parameter that governs Session Initialisation on start-up: default 1 for interactive sessions, 0 for executable scripts and run-time versions. Register it in the navigation and list it under Start-up and workspace loading.
Link DYALOG_SERIAL to DYALOG_SERIALFILE, and note on the DYALOG_SERIALFILE page the default location $HOME/.dyalog/serial, how DYALOG_SERIAL is populated from the file, and the multi-user use. Part of Dyalog#898.
Only one * can be used. If AplCoreName contains more than one *, the setting is ignored and the aplcore is named aplcore, rather than the string being used as is. Part of Dyalog#884; aligns with the single-* valid values already stated on the page.
…RIALFILE DYALOG_SERIALFILE is only relevant on UNIX and macOS, so the cross-platform DYALOG_SERIAL page no longer references it. The DYALOG_SERIALFILE page still links back to DYALOG_SERIAL. Part of Dyalog#898.
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.