Split the ambivalent system functions into monadic and dyadic pages - #964
Draft
abrudz wants to merge 59 commits into
Draft
Split the ambivalent system functions into monadic and dyadic pages#964abrudz wants to merge 59 commits into
abrudz wants to merge 59 commits into
Conversation
Create a monadic and a dyadic page for each of the 40 system functions documented in their ambivalent form, taking the page titles from the disambiguation spec, and give each the syntax of its own form rather than the ambivalent one. Add a disambiguation page for each, modelled on the existing pages for the already-split ⎕FMT and ⎕DR, which is excluded from search and from the navigation and directs the reader to whichever form they meant. Replace each navigation entry with one for each form. This commit is the mechanical part: the two pages of each pair still carry the prose of the ambivalent page, and the cross-references still point at the removed pages. Both follow. Refs Dyalog#957
Rework the prose of 30 of the 40 pairs so that the monadic page describes only the monadic form and the dyadic page only the dyadic one: state the behaviour that applied when the left argument was omitted as the plain behaviour of the monadic form, drop the tables and lists of left-argument values from the monadic pages, and stop describing the left argument as optional on the dyadic pages. Where a page carried an example of the other form, remove it. ⎕AT, ⎕CLASS and ⎕UCS already had separate monadic and dyadic sections, so those split along the existing headings. Refs Dyalog#957
Complete the prose split for the remaining ten pairs, whose left argument selects between several behaviours rather than sitting in one removable paragraph: ⎕CSV and ⎕JSON, ⎕FCHK and ⎕XML, whose left argument is the older alternative to the Variant operator, ⎕NINFO, ⎕NS, ⎕PROFILE, ⎕SIGNAL, ⎕TALLOC and ⎕WC. Correct the titles of ⎕EXPORT, which the specification had the wrong way round: the monadic form queries the export type and the dyadic form sets it, as the page itself states. No monadic page now refers to a left argument, and no dyadic page describes one as optional. Refs Dyalog#957
Repoint the 179 links to the split pages at whichever form the referring text describes, rather than at the disambiguation pages. The GUI functions are referred to in their dyadic form, since that is how an object is named when it is created or queried; the file, token and namespace functions are mostly referred to monadically. Where the link addressed a particular section, it follows that section: File Encodings is now on the dyadic ⎕NGET page and the token pool query on the dyadic ⎕TALLOC page. The ⎕UCS links lose a fragment that no longer names a heading. List both forms of each function in System Functions and System Functions (by Category), rather than choosing one. Refs Dyalog#957
Follow the pattern of the existing ⎕FMT and ⎕DR disambiguation pages by showing each form in use, for the four functions whose difference a single expression demonstrates: ⎕C, ⎕UCS, ⎕JSON and ⎕NS. Each example was run against the interpreter and shows its actual output. Refs Dyalog#957
⎕AT, ⎕NL, ⎕VFI and ⎕NPARTS. The ⎕AT, ⎕NL and ⎕VFI examples were run against the interpreter and show its actual output, with a plausible user name in place of the one the run reported. The dyadic ⎕NPARTS example is the Windows form, which this platform cannot produce. Refs Dyalog#957
The examples were carried over wholesale when the pages were copied, so most pairs demonstrated both forms. Keep on each page only those examples that use the form it documents, together with the blocks that set a stage without calling the function at all. Where an example block mixed the two, keep the expressions of the relevant form with their output and drop the rest, along with the error carets left behind. The equivalence identities that define dyadic ⎕PROFILE in terms of the monadic form stay on the dyadic page only. Refs Dyalog#957
Eleven of the repointed cross-references had their first letter doubled, giving targets such as nns-dyadic and wwc-dyadic. The links concerned ended with a separator, and the rewrite measured the name to replace from the end of the target, so it removed the separator and the last letter of the name instead of the name itself. Restore the intended name and the separator. Refs Dyalog#957
Dropping the braces that marked the left argument as optional left `X` hard against the `⎕` in 29 of the dyadic syntax lines. That parses, but the usual way of writing a dyadic system function separates the two. Refs Dyalog#957
Filtering the examples by form left the surrounding prose pointing at code that is no longer on the page: 85 paragraphs introducing an absent example, 12 example headings with nothing under them, and a stray closing fence on xml-monadic whose opening fence went with the paragraph that was removed. Where the example matched the page's own form it was removed in error, so restore it: 8 blocks across fix-dyadic, json-dyadic, ninfo-dyadic and na-monadic. On json-monadic every example carried an explicit direction, so the page was left with prose and no code at all. Give it the same examples in monadic form, verified to produce identical output. Where the example belongs to the sibling page, drop the paragraph that introduces it, or trim just the clause that points at it when the rest of the paragraph stands on its own. Move the recommendation to state the direction explicitly to the monadic page, where it applies, and link it to the dyadic form. Refs Dyalog#957
The dyadic page names each result an informal title (valences, fix times, execution properties); carry those onto the corresponding result elements of the monadic page. Turn the valence syntax listing on the monadic page into a table under an Example heading, and put the same table on the dyadic page for the `X` is 1 case, where a defined result and an ambivalent function both report a positive value rather than the monadic negative. The monadic result element for the fix time named only `⎕TS`, while the dyadic page spelled out the seven elements; give each page both, so the timestamp is described in full on either side. Refs Dyalog#957
Show the valence and fix-time listings without a header row, name the author result element, link the ⎕LOCK reference, and render the display example with the current box-drawing characters. Add worked examples to the dyadic page for the valences and fix times that `X` 1 and 2 report. Refs Dyalog#957
The result element reports the lock state, which is what monadic ⎕LOCK queries. Refs Dyalog#957
Monadic ⎕C only folds case, so drop the claim in its opening that it also maps to upper or lowercase. Say uppercase and lowercase throughout, link the dyadic page's reference to monadic ⎕C, and fold the single trailing Example into the Examples section on both pages. Rewrite the dyadic Sigma example around mapping rather than folding: both lowercase forms map to the one uppercase Σ, and lowercasing the uppercased text restores the final form, ίσως. Refs Dyalog#957
The second line mapped to lowercase what had just been mapped to uppercase, a roundabout fold that does not belong on the mapping page. Map the original lowercase text to lowercase, which leaves it unchanged and so shows each form keeping its shape. Refs Dyalog#957
Open the dyadic page with a sentence saying what the function returns, in the same shape as the monadic page. It comes from the paragraph that began "In this case", which no longer had a case to refer to once the forms were on separate pages. Link the Penguin Class example directly on its name rather than in a trailing parenthesis, and drop the "Once again" that tied the dyadic mention to the monadic one. Make the first example heading the standard Examples heading and fold the second example in under it, on both pages. Refs Dyalog#957
These are common nouns in the running text, so write them in lowercase. The page titles keep their title case, and the code, identifiers and links are untouched. Refs Dyalog#957
FionaDyalog
approved these changes
Aug 3, 2026
FionaDyalog
left a comment
FionaDyalog
left a comment
Contributor
There was a problem hiding this comment.
Approved, although suggested changes should be implemented before merging.
It is not possible to review all the changes, and this issue has not been raised for that –subsequent issues will review the content and formatting on each page – this is only to look at the splitting of ambivalent into separate pages for their monadic and dyadic forms. As such, the review is pragmatic rather than thorough, and many issues have been ignored. Note that help_urls.h must be updated at the same time that this is merged (failing to do this will break the build).
| # <span>Update Function Time and User Stamp</span> `{R}←X(1159⌶)Y`{{key}} | ||
|
|
||
| `Y` is an array of function names in the same format as the right argument of `⎕AT`. For further information, see [Attributes](../../system-functions/at.md). | ||
| `Y` is an array of function names in the same format as the right argument of `⎕AT`. For further information, see [Attributes](../../system-functions/at-monadic.md). |
Contributor
There was a problem hiding this comment.
Suggested change
| `Y` is an array of function names in the same format as the right argument of `⎕AT`. For further information, see [Attributes](../../system-functions/at-monadic.md). | |
| `Y` is an array of function names in the same format as the right argument of [`⎕AT`](../../system-functions/at-monadic.md). |
| | ([`⎕FMT`](../../../../language-reference-guide/system-functions/format-monadic/)) | Character matrix similar to session display using `⍞←` | Yes | | ||
| | [`⎕JSON`](../../../../language-reference-guide/system-functions/json/) export | Conversion to a JSON character vector | No | | ||
| | [`⎕CSV`](../../../../language-reference-guide/system-functions/csv/) export | Conversion to a CSV array or file | No | | ||
| | [`⎕JSON`](../../../../language-reference-guide/system-functions/json-monadic/) export | Conversion to a JSON character vector | No | |
Contributor
There was a problem hiding this comment.
Is the "export" needed here? Might be better to remove it and amend the description.
| | [`⎕JSON`](../../../../language-reference-guide/system-functions/json/) export | Conversion to a JSON character vector | No | | ||
| | [`⎕CSV`](../../../../language-reference-guide/system-functions/csv/) export | Conversion to a CSV array or file | No | | ||
| | [`⎕JSON`](../../../../language-reference-guide/system-functions/json-monadic/) export | Conversion to a JSON character vector | No | | ||
| | [`⎕CSV`](../../../../language-reference-guide/system-functions/csv-monadic/) export | Conversion to a CSV array or file | No | |
Contributor
There was a problem hiding this comment.
Is the "export" needed here? Might be better to remove it and amend the description.
|
|
||
| |---|---| | ||
| |[PName](../properties/pname.md)|A character vector containing the name of the font face. The default is `'System'` . Note that case is ignored when you specify the name, although it will be returned correctly by [`⎕WG`](../../../language-reference-guide/system-functions/wg) .| | ||
| |[PName](../properties/pname.md)|A character vector containing the name of the font face. The default is `'System'` . Note that case is ignored when you specify the name, although it will be returned correctly by [`⎕WG`](../../../language-reference-guide/system-functions/wg-dyadic) .| |
Contributor
There was a problem hiding this comment.
Suggested change
| |[PName](../properties/pname.md)|A character vector containing the name of the font face. The default is `'System'` . Note that case is ignored when you specify the name, although it will be returned correctly by [`⎕WG`](../../../language-reference-guide/system-functions/wg-dyadic) .| | |
| |[PName](../properties/pname.md)|A character vector containing the name of the font face. The default is `'System'` . Note that case is ignored when you specify the name, although it will be returned correctly by [`⎕WG`](../../../language-reference-guide/system-functions/wg-dyadic).| |
| @@ -40,7 +34,6 @@ Name value pairs: | |||
| 1 2 hello | |||
|
|
|||
| (ns1 ns2 ns3)←()()() | |||
Contributor
There was a problem hiding this comment.
Delete this line (unless it does something useful!)
Member
Author
There was a problem hiding this comment.
It was creating the target namespaces until that (the next) line was removed. This example needs rework — will get there.
|
|
||
| ### DLL function Non-result-returning | ||
|
|
||
| ### DLL function Result-returning |
Contributor
There was a problem hiding this comment.
Two consectuive4 headings at the same level, no content on first one. Either remove/merge one or add some content.
Open each page with the one form it documents rather than describing both, and keep the note about ⎕PP only on export, where there is output to format. Under Internal Format, keep the clause for the page's direction, and keep the note about assumed character fields only on import, where it applies. Move the MetaCharacters section down to just before Variant Options on both pages, drop the stray syntax line left in the import text, and capitalise the Variant Options heading. Even out the indentation of the first two lines of the export example. Refs Dyalog#957
The argument description had been sitting under the Internal Format heading. Let the argument description follow the opening directly, and place Internal Format after the argument and result discussions, just before the examples that show those structures. Refs Dyalog#957
The argument description leads, then Internal Format sits immediately before MetaCharacters rather than down by the examples. Refs Dyalog#957
Set "zoomed" and "only" in italics rather than capitals, and write the Hello and World the reader double-clicks as code. Give the dyadic page the shared examples with a `'⋄'` left argument, so they edit the array as array notation, linked to its description; correct the condition on the left argument to `(≢X)∊1,≢Y`. Refs Dyalog#957
Write "read-only" rather than "ReadOnly" in the running text, keeping the capitalised form only for the variant option name. The import example edits a read-only character array; the export example, opened with `'⋄'`, edits read-only array notation. Refs Dyalog#957
Monadic ⎕ED assumes an undefined name is a function or operator; say so, and point to dyadic ⎕ED for the other types. Mark function/operator as the default in the dyadic type table, linking back to monadic ⎕ED. Refs Dyalog#957
Link "the function's export type" on each page to its counterpart: from the query page to where the type is set, and from the set page to where it is queried. Call the type-1 value the initial value rather than the default. Refs Dyalog#957
Note in the opening that the export type is set by dyadic ⎕EXPORT, and drop the link lower down that pointed the same way. Refs Dyalog#957
Make the Boolean-result caveat a Warning and the archaic-feature note a Legacy admonition on both pages. Carry the "current version" sentence onto the query page's warning, and replace the commented code block with a running-text example that both pages now share. Refs Dyalog#957
The shared example queried with monadic ⎕EXPORT, which does not belong on the set page. Verify a set instead: check that `0=0 ⎕EXPORT Y` succeeded. Refs Dyalog#957
Drop the trailing full stops from the table entries and write "access matrix" in lowercase like the others. Refs Dyalog#957
Make the Examples heading level 2 on both pages. Spell timeout as one word on the dyadic page and link its reference to the monadic case. On the monadic page, point to dyadic ⎕FHOLD for a timeout. Refs Dyalog#957
Both: drop the no-longer-needed file:// prefix, set the slash and backslash as code, gather the examples into one Examples section (renumbered) and add an Examples heading before the InjectReferences examples, code every variant option value and mark each option's default, write "can"/"might" for "may", and lowercase class, namespace and interface in the prose. Monadic: remove the series-of-namespaces case, which only the dyadic form supports, and the "What Y may contain" and "If so" split artefacts. Dyadic: replace the X-value prose with a lead-in (noting 1 is the default, equivalent to monadic ⎕FIX) and an X/Y/R table, the X of 2 row carrying the series case down to the atomicity note. Refs Dyalog#957
Write "will fix" rather than "will fixes" on both pages. Retitle the dyadic table's Y column "Y value or content of file Y" and drop the "or a file containing such a definition" phrasing from its cells, which the heading now covers. Refs Dyalog#957
Monadic ⎕FRESIZE only compacts, so state that as its purpose rather than a side effect, link "maximum size" to the dyadic form that sets it, carry over the deprecation note, and add an example showing a dropped component reclaimed by compaction. Dyadic: link "compacted" to the monadic form. Refs Dyalog#957
The paragraph already says ⎕FRESIZE compacts the file, so the closing "The file is compacted and its maximum size remains unchanged" adds nothing. Refs Dyalog#957
The variant option examples called ⎕JSON dyadically. The direction each already matches its argument, so remove the leading 0 and 1 to call monadic ⎕JSON, which gives the same result. Refs Dyalog#957
Monadic ⎕LOCK always locks to extent 3, so say the code is hidden and suspension prevented rather than listing the extents, and link "lock state" to the dyadic form that sets it. Add the monadic example to the dyadic page with a left argument of 3. Refs Dyalog#957
Monadic ⎕MAP maps APL files, so drop the description, update rule, compatibility note and type distinction for raw files. Dyadic ⎕MAP maps raw files, so drop the APL-file description, the ∆MPUT example that prepares one, and the APL-file compatibility note. Refs Dyalog#957
With only one file type left on each page, APL and raw no longer contrast anything, so set them in plain text. Refs Dyalog#957
An APL mapped file always carries a header, so it is never zero length; the note belongs only on the dyadic page for raw files. Refs Dyalog#957
The opening example modified a mapped matrix left over from the raw examples, where the matrix is never defined here. Copy in the ∆MPUT utility that the next example needs instead. Refs Dyalog#957
Say "a simple Dyalog APL array" in the monadic intro and "collection of raw data bytes" in the dyadic intro, rather than repeating the point in a separate line. Refs Dyalog#957
Replace the shaded Unique default cell with a trailing "(default)" on both pages. On the dyadic page, drop the shaded marker from the X table and say in the lead-in that the default is 0, equivalent to monadic ⎕MKDIR. On the monadic page, note that an existing base name or a missing path segment signals an error, and point to dyadic ⎕MKDIR for those cases. Refs Dyalog#957
Unique was described twice, once by a result table and once by an effect table. Drop the Variant Options and Unique Option headings and the "no primary option" paragraph between them, and fold the two tables into one three-column table of Unique, Effect on Behaviour and Result R. Refs Dyalog#957
Give the result its own column for a single name and for a vector of names, rather than describing both in one cell, and state once in the lead-in that the result is shy. Refs Dyalog#957
Simplify the examples and drop the stray error carets, point the existence note at Native File Exists, capitalise "Names" in the result heading, and state the default only in the table. Correct "Already" in the error message. Refs Dyalog#957
The FILE NAME ERROR reports the offending path, so include it in the example. Refs Dyalog#957
Reinstate the worked examples for each form, cross-link monadic and dyadic ⎕NA, show the C-to-⎕NA correspondence as a table, and render the display output with the current box-drawing characters. Fix an accidental U+2223 in place of the pipe separator in the quadna listing, the FindWindow call name, and a few wording slips. Refs Dyalog#957
Passing the null pointer by value uses P, which is what the example codes; the text said I4, a leftover from the 32-bit-only form. Corrected on both pages. Refs Dyalog#957
Cross-link monadic and dyadic ⎕NDELETE, mark the Wildcard default in text rather than shading, code the X table's 0, drop stray error carets and even out the example indentation. Supply the missing target on the dyadic link. Refs Dyalog#957
Say the text file is specified within Y, not X, cross-link the two forms for manual versus automatic encoding, and set the byte values as code. Refs Dyalog#957
Monadic ⎕NINFO returns only the name and is equivalent to 0 ⎕NINFO, so say that, link to dyadic ⎕NINFO for other file properties, and drop the property-oriented wording, the property-setting "touch" example and the timestamp note. Remove the Follow option, which affects only the other properties and not the name. Add a Hints and Recommendations note on obtaining a filename's canonical capitalisation. Refs Dyalog#957
abrudz
marked this pull request as draft
August 5, 2026 06:47
Carry the shaded-to-(default) change onto the dyadic Wildcard, Recurse and Follow tables. Fix a garbled clause in the monadic result description. Refs Dyalog#957
Add a link from dyadic ⎕NINFO to monadic for obtaining just the name, and show the parts reference as ⎕NPARTS rather than "NParts" on both pages. Refs Dyalog#957
Write the wildcard characters * and ? and the directory names . and .. as code rather than in quotes on both pages. Fold the monadic equivalence into the name row of the dyadic property table. Refs Dyalog#957
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
2 participants
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.
Create a monadic and a dyadic page for each of the 40 system functions
documented in their ambivalent form, taking the page titles from the
disambiguation spec, and give each the syntax of its own form rather than
the ambivalent one. Add a disambiguation page for each, modelled on the
existing pages for the already-split ⎕FMT and ⎕DR, which is excluded from
search and from the navigation and directs the reader to whichever form
they meant. Replace each navigation entry with one for each form.
This commit is the mechanical part: the two pages of each pair still carry
the prose of the ambivalent page, and the cross-references still point at
the removed pages. Both follow.
Fixes #957