Dyalog v20.0: Mantis 21315 – 00333 An improved version of ⎕SH

[FionaDyalog]

Mantis 21315 details the changes needed for this project (https://mantis.dyalog.com/view.php?id=21315)

Documents impacted in this project:

• Language Reference Guide
• Release Notes

[xpqz]

[Adding Peter's comments here]

I have written the ⎕SHELL documentation now, and created a pull request with you as the reviewer.
I don't know what the process is going to be for selecting reviewers.

A couple of notes I wrote down while writing the docs:

• I cannot get the { .example} syntax to work. It simply renders as it is written.
• The guidelines show examples of a windows-specific info box, introduced by !!! windows, but when I render it, it just looks like any other info box.
• The current set of files and directories are sometimes confusing to navigate.

For example, I wanted to add a reference to Language Reference > System Functions > System Functions Categorised > Introduction, so I assumed the file to edit would be in the system-functions/system-functions-categorised directory, but that entire directory seems not to be used? It contains a bunch of files which are also found elsewhere: For example, there is a file for ⎕R called r.md, but it exists elsewhere as well:

• ./language-reference-guide/docs/system-functions/system-functions-categorised/tools-and-access-to-external-facilities/tools-and-access-to-external-utilities/r.md
• ./language-reference-guide/docs/system-functions/r.md

• Knowing where to add references to new content on old pages is tricky, but the list you put on the mantis issue helped. But adding a reference to ⎕SHELL from ⎕CMD for example, is tricky as ⎕CMD's docs are spread across multiple pages.

I find the order of navigation menus confusing in a number of cases:

• For I-beams (Language reference > The I-Beam operator), I think they are ordered by number, but the number isn't shown, and the ordering of the names makes no sense, so it is tricky to navigate.
• For system functions (Language reference > System functions > System functions A-Z), the ordering is alphabetical, but based on the spelling of the system functions themselves, not their "names". For example, ⎕NQ is after ⎕NPUT, but their names in the menu are "Enqueue Event" and "Write Text File".
• The same problem might exist elsewhere.

Also, I have chosen to call ⎕SHELL "Execute External Program" instead of "Shell", but that hasn't been discussed anywhere else.

[xpqz]

I have raised a separate issue for the directory structure problem: #57

[xpqz]

As to the attr_list syntax for examples, this is badly explained in the guidelines. The purpose of { .example } is to add the CSS-class example to a heading, which excludes it from the right-hand side navigation panel. This is because having reams of entries just saying "Example" in the nav is meaningless/unhelpful:

• Example
• Example
• Example

Hence, changing your example from

Example (Windows)
{ .example}

to

### Example (Windows) { .example }

has the desired effect. The other alternatives are to not use headings at all for examples, which I think is better semantically -- headings are for document hierarchical structure, but here it's really used for layout. This practice was too pervasive in the old documentation for me to want to tackle in the conversion.

I'll update the guidelines on this.

[pmikkelsen]

Thanks, I have pushed a commit with the proposed changes.