├── .gitignore ├── docs ├── styles │ └── style-guide.css ├── img │ ├── favicon-32.png │ ├── os_linux_note.svg │ └── dyalog-white.svg ├── images.md ├── css.md ├── print.md ├── index.md ├── tables.md ├── rules.md └── style.md ├── .gitmodules ├── requirements.txt ├── .gitattributes ├── .github ├── dependabot.yml └── workflows │ └── mkdocs-publish.yml ├── Dockerfile ├── README.md └── mkdocs.yml /.gitignore: -------------------------------------------------------------------------------- 1 | /Dyalog-icons-final 2 | /Dyalog-icons-final.zip 3 | site/ 4 | -------------------------------------------------------------------------------- /docs/styles/style-guide.css: -------------------------------------------------------------------------------- 1 | .example-output { 2 | padding: 1em; 3 | background-color: #f5f5f5 4 | } 5 | -------------------------------------------------------------------------------- /docs/img/favicon-32.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Dyalog/documentation-guidelines/trunk/docs/img/favicon-32.png -------------------------------------------------------------------------------- /.gitmodules: -------------------------------------------------------------------------------- 1 | [submodule "documentation-assets"] 2 | path = documentation-assets 3 | url = https://github.com/Dyalog/documentation-assets 4 | -------------------------------------------------------------------------------- /requirements.txt: -------------------------------------------------------------------------------- 1 | mike==2.1.3 2 | mkdocs-caption 3 | mkdocs-material==9.5.39 4 | mkdocs-material-extensions 5 | markdown_tables_extended 6 | -------------------------------------------------------------------------------- /.gitattributes: -------------------------------------------------------------------------------- 1 | # Windows line endings: diaf 2 | * text=auto eol=lf 3 | *.py text eol=lf 4 | *.md text eol=lf 5 | *.yml text eol=lf 6 | *.jpg binary 7 | *.png binary 8 | *.gif binary 9 | *.apl? linguist-language=APL -------------------------------------------------------------------------------- /.github/dependabot.yml: -------------------------------------------------------------------------------- 1 | # Please see the documentation for all configuration options: 2 | # https://docs.github.com/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file 3 | 4 | version: 2 5 | updates: 6 | - package-ecosystem: "gitsubmodule" # See documentation for possible values 7 | directory: "/" # Location of package manifests 8 | schedule: 9 | interval: "daily" 10 | -------------------------------------------------------------------------------- /Dockerfile: -------------------------------------------------------------------------------- 1 | FROM python:3.11-slim 2 | 3 | # Install required system dependencies 4 | RUN apt-get update && apt-get install -y \ 5 | build-essential \ 6 | git 7 | 8 | # Copy the requirements.txt file into the Docker image 9 | COPY requirements.txt . 10 | 11 | # Install Python dependencies from the requirements.txt file 12 | RUN pip install --no-cache-dir -r requirements.txt 13 | 14 | # Set the working directory (optional) 15 | WORKDIR /docs 16 | 17 | # Expose port 8000 for serving documentation 18 | EXPOSE 8000 19 | 20 | # Set ENTRYPOINT to 'mike' to allow passing arguments at runtime 21 | ENTRYPOINT ["mike"] 22 | 23 | # Default CMD as fallback if no arguments are passed 24 | CMD ["--help"] 25 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Documentation Guidelines 2 | Style guide and how-to for writing documentation using Material for MkDocs in Dyalog projects. 3 | 4 | ## How to Develop Docs 5 | We use Git submodules to include [centralised styles and assets](https://github.com/Dyalog/documentation-styles) to ensure consistent styles and enable updates from a single location that pervade all of our MkDocs-based documentation. 6 | 7 | To make sure you have these, use the `--recurse-submodules` flag when you clone the repository: 8 | 9 | ```console 10 | git clone git@github.com:Dyalog/documentation-guidelines.git --recurse-submodules 11 | ``` 12 | 13 | If you do a normal clone, you can still get the submodules afterwards: 14 | 15 | ```console 16 | git submodule init 17 | git submodule update 18 | ``` 19 | 20 | The build system takes a fresh checkout, so published documentation will get the latest updates from [Dyalog/documentation-styles](https://github.com/Dyalog/documentation-styles). However, when writing documentation, you might need to manually update the submodule. 21 | 22 | ```console 23 | git submodule update 24 | ``` 25 | -------------------------------------------------------------------------------- /docs/images.md: -------------------------------------------------------------------------------- 1 | # Figures with Captions 2 | 3 | !!! Info "Information" 4 | We use the [caption](https://github.com/tobiasah/mkdocs-caption#readme) plugin to automatically number and cross-reference figures and tables in Material for MkDocs. 5 | 6 | The Markdown way to add an image is a Markdown link preceded by an exclamation mark: 7 | 8 | ```other 9 | ![alt text here](image url) 10 | ``` 11 | 12 | By using the [attribute list](https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown/#attribute-lists) syntax we can add CSS classes, id, attributes etc, without resorting to HTML. 13 | 14 | ```other 15 | ![caption text here](image url){ width=300px #MyImgId } 16 | ``` 17 | 18 | Here is an example: 19 | 20 | ```other 21 | ![An elephant at sunset](https://interactive-examples.mdn.mozilla.net/media/cc0-images/elephant-660-480.jpg){ width=300px #MyElephant} 22 | ``` 23 | 24 | ![An elephant at sunset](https://interactive-examples.mdn.mozilla.net/media/cc0-images/elephant-660-480.jpg){ width=300px #MyElephant} 25 | 26 | Like with [tables](tables.md), we reference the image by its id by an "empty" link: 27 | 28 | ``` 29 | The beautiful specimen in [](#MyElephant) is a bull with the name of Kevin. 30 | ``` 31 | 32 | The beautiful specimen in [](#MyElephant) is a bull with the name of Kevin. -------------------------------------------------------------------------------- /mkdocs.yml: -------------------------------------------------------------------------------- 1 | site_name: Dyalog Documentation Guidelines 2 | repo_url: https://github.com/Dyalog/documentation-guidelines 3 | 4 | copyright: Copyright © 2015-2025 Dyalog, LTD 5 | theme: 6 | name: material 7 | favicon: documentation-assets/images/favicon-32.png 8 | language: en 9 | logo: documentation-assets/images/dyalog-logo_white.svg 10 | plugins: 11 | - caption: 12 | table: 13 | enable: true 14 | start_index: 1 15 | increment_index: 1 16 | position: bottom 17 | markdown_extensions: 18 | - admonition 19 | - pymdownx.highlight: 20 | use_pygments: false 21 | - md_in_html 22 | - pymdownx.details 23 | - pymdownx.superfences 24 | - attr_list 25 | - pymdownx.emoji: 26 | emoji_index: !!python/name:material.extensions.emoji.twemoji 27 | emoji_generator: !!python/name:material.extensions.emoji.to_svg 28 | - markdown_tables_extended 29 | - toc: 30 | title: On this page 31 | extra_css: 32 | - documentation-assets/css/main.css 33 | - documentation-assets/css/extra.css 34 | - styles/style-guide.css 35 | nav: 36 | - Home: index.md 37 | - Rules for Writing Documentation: rules.md 38 | - Style Guide: style.md 39 | - Images: images.md 40 | - Tables: tables.md 41 | - CSS: css.md 42 | -------------------------------------------------------------------------------- /docs/css.md: -------------------------------------------------------------------------------- 1 | # CSS 2 | 3 | CSS, or [Cascading Style Sheets](https://en.wikipedia.org/wiki/CSS), define the presentation layer of a website. Our aim at Dyalog is that as a documentation contributor, you should not need to get your hands dirty at this level. Moreover, any CSS changes need to be discussed as a wider group, as there are more aspects (beyond MkDocs) to the documentation build pipeline that rely on the CSS, like the CHM and PDF versions of the documentation. CSS that you write is not automatically picked up (paged media CSS is very different). 4 | 5 | ## Dyalog MkDocs CSS 6 | 7 | The CSS defining the Dyalog-specific customisations are found in the locations specified in the `mkdocs.yml` file. Typically, that means `docs/style`. In there, you'll see two files of interest: 8 | 9 | 1. **main.css** 10 | 2. **extra.css** 11 | 12 | These are not mandated by MkDocs, but any CSS files found in the directories specified in the `mkdocs.yml` file will be included. Note, however, that there is a lot more CSS injected as part of the rendering pipeline, specific to the [MkDocs Material](https://github.com/squidfunk/mkdocs-material) theme, defining things like navigation panels etc. There _are_ ways to hook into that, but this is not something we should encourage. 13 | 14 | As a "run of the mill" documentation contributor, you should rarely need to consider the CSS. -------------------------------------------------------------------------------- /docs/print.md: -------------------------------------------------------------------------------- 1 | # Making Documents Work for Print 2 | Some experimentation has been done to produce usable PDFs, primarily for the purpose of printing documentation to paper. 3 | 4 | [Dyalog/RP-Jenkins-Test]() produces the Link User Guide as a PDF ([dyalog.github.io/RP-Jenkins-Test/3.7/Link%20User%20Guide.pdf](https://dyalog.github.io/RP-Jenkins-Test/3.7/Link%20User%20Guide.pdf)). 5 | 6 | The HttpCommand documentation has a [print page (dyalog.github.io/HttpCommand/5.3/print_page)](https://dyalog.github.io/HttpCommand/5.3/print_page/) which simply puts the entire site content in a single HTML document which can be printed in the browser's **File → Print** menu item. 7 | 8 | ## Cross referencing 9 | References which are inline as part of prose do not work when printed. 10 | 11 | The [with-pdf](https://github.com/orzih/mkdocs-with-pdf) plugin adds section numbers, but we need to see if it is possible to have automatic referencing. 12 | 13 | ## Extra styles 14 | 15 | ### keepTogether 16 | A class should be created which can be used to wrap elements which should not be split across pages in a printed document. 17 | 18 | ```css 19 | .keepTogether { page-break-inside: avoid; } 20 | ``` 21 | 22 | ### keepWithNext 23 | apply to text that must be kept with the following element 24 | 25 | ### pageBreakBefore 26 | apply to text that should be at the top of a page 27 | 28 | ## Figures and tables 29 | - can we refer to an image/figure/table using anchor tags? can figures be numbered automatically? 30 | -------------------------------------------------------------------------------- /docs/index.md: -------------------------------------------------------------------------------- 1 | # Dyalog Documentation Style Guide 2 | 3 | ## To Do 4 | - references in HTML vs. PDF 5 | - consider linking to specific document versions in references to other documents 6 | 7 | ## Markdown and HTML 8 | This document, and the documentation to which it refers, is written in Markdown. 9 | 10 | Markdown is a markup language for formatting text documents. It is designed to be simple and legible even in raw form. For example, compare 11 | 12 | ```markdown 13 | # My Heading 14 | This is some **bold** text with [a link](#). 15 | ``` 16 | 17 | and 18 | 19 | ```HTML 20 |

My Heading

21 | This is some bold text with a link. 22 | ``` 23 | 24 | For more examples of markdown and equivalent HTML, see the [basic syntax page on markdownguide.org](https://www.markdownguide.org/basic-syntax/_). 25 | 26 | Not only does Markdown render to HTML so that it can be viewed on any web browser, but you can also use HTML inside Markdown documents in order to apply custom styling with CSS or to create layouts which aren't possible with just Markdown. 27 | 28 | In general, it is best to try and stick to just Markdown where possible because maintaining a set of custom CSS classes and styles can be cumbersome. Sometimes it is convenient to [include markdown inside HTML tags](./style.md#markdown-inside-html). 29 | 30 | ## Resources 31 | 32 | * [MkDocs](https://www.mkdocs.org/) 33 | * [MkDocs Material](https://squidfunk.github.io/mkdocs-material/) theme 34 | * [Markdown extensions](https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown/) available in Material 35 | * [Attribute lists](https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown/?h=attribute+lists#attribute-lists) 36 | * [GitHub Flavored Markdown Spec](https://github.github.com/gfm/) 37 | * [Extended Markdown tables](https://github.com/fumbles/tables_extended) 38 | * [Captions](https://github.com/tobiasah/mkdocs-caption#readme) 39 | -------------------------------------------------------------------------------- /docs/tables.md: -------------------------------------------------------------------------------- 1 | # Tables 2 | 3 | !!! note "Tables are not standard Markdown" 4 | Tables were not part of the original Markdown specification, but was popularised by the widely used [GitHub-Flavoured Markdown](https://github.github.com/gfm/) (GFM) dialect. 5 | 6 | GFM table syntax only allows for the most basic of tables. To remedy this, we use the [Tables-Extended](https://github.com/fumbles/tables_extended) Markdown extension to allow for more elaborate tables, and the [caption](https://github.com/tobiasah/mkdocs-caption#readme) plugin for captions, automatic numbering and references. 7 | 8 | In its most basic form, a GFM table must have a header row: 9 | 10 | ```other 11 | | heading 1 | heading 2 | 12 | | --------- | --------- | 13 | | content 1 | content 2 | 14 | | content 3 | content 4 | 15 | ``` 16 | 17 | which renders as: 18 | 19 | | heading 1 | heading 2 | 20 | | --------- | --------- | 21 | | content 1 | content 2 | 22 | | content 3 | content 4 | 23 | 24 | With the extension, we can make headerless tables in a natural way: 25 | 26 | ```other 27 | | --------- | --------- | 28 | | content 1 | content 2 | 29 | | content 3 | content 4 | 30 | ``` 31 | 32 | which renders as: 33 | 34 | | --------- | --------- | 35 | | content 1 | content 2 | 36 | | content 3 | content 4 | 37 | 38 | You can also create row-, and col-spans with easily accessible syntax. See the [Tables-Extended](https://github.com/fumbles/tables_extended) documentation for details. 39 | 40 | !!! note "Tables are for data, not layout" 41 | Tables should be used for data, not document structure or layout. Unless you have a good reason not to, do name your columns. Complex tables are hard to read on a screen. If you find yourself reaching for more complex table layouts, consider if there are better ways to present the information. 42 | 43 | ## Captions and References 44 | 45 | To caption a table, add a line beginning with "Table: " just before the table, and assign an id using an attribute list: 46 | 47 | 
48 | Table: Cells with content { #MyTable }
49 | 
50 | | heading 1 | heading 2 | 
51 | | --------- | --------- | 
52 | | content 1 | content 2 |
53 | | content 3 | content 4 | 
54 |
55 | 56 | which should render as: 57 | 58 | Table: Cells with content { #MyTable } 59 | 60 | | heading 1 | heading 2 | 61 | | --------- | --------- | 62 | | content 1 | content 2 | 63 | | content 3 | content 4 | 64 | 65 | You, the author, are responsible for choosing a unique table id (the `#MyTable` in this case) which is unique and appropriate for the table. 66 | 67 | To reference a table based on its id, insert a Markdown link to the id, with an empty anchor: 68 | 69 | 
70 | As shown in [](#MyTable), yadda yadda.
71 |
72 | 73 | where the anchor text should be filled in by the extension: 74 | 75 | As shown in [](#MyTable), yadda yadda. -------------------------------------------------------------------------------- /.github/workflows/mkdocs-publish.yml: -------------------------------------------------------------------------------- 1 | name: Publish MkDocs Documentation 2 | 3 | on: 4 | workflow_dispatch: 5 | inputs: 6 | version: 7 | description: 'Version to deploy (e.g. 20.0)' 8 | required: true 9 | default: '20.0' 10 | type: string 11 | update_latest: 12 | description: 'Update this as latest version?' 13 | required: true 14 | default: true 15 | type: boolean 16 | 17 | permissions: 18 | contents: write 19 | pages: write 20 | 21 | jobs: 22 | deploy: 23 | runs-on: ubuntu-latest 24 | 25 | steps: 26 | - uses: actions/checkout@v4 27 | with: 28 | submodules: recursive 29 | fetch-depth: 0 # Required for mike to work properly 30 | - name: Update Assets 31 | run: git submodule update --remote --recursive documentation-assets 32 | - name: Set up Python 33 | uses: actions/setup-python@v5 34 | with: 35 | python-version: '3.11' 36 | 37 | - name: Set up Git 38 | run: | 39 | git config --global user.name "github-actions[bot]" 40 | git config --global user.email "github-actions[bot]@users.noreply.github.com" 41 | 42 | - name: Install dependencies 43 | run: | 44 | python -m pip install --upgrade pip 45 | pip install \ 46 | mike \ 47 | mkdocs-material \ 48 | mkdocs-macros-plugin \ 49 | mkdocs-monorepo-plugin \ 50 | mkdocs-site-urls \ 51 | mkdocs-caption \ 52 | markdown-tables-extended 53 | 54 | - name: Get Git Info 55 | id: git-info 56 | run: | 57 | BRANCH=$(git rev-parse --abbrev-ref HEAD) 58 | HASH=$(git rev-parse --short HEAD) 59 | echo "GIT_INFO=${BRANCH}:${HASH}" >> $GITHUB_OUTPUT 60 | echo "DATE=$(date +'%Y-%m-%d')" >> $GITHUB_OUTPUT 61 | echo "CURRENT_YEAR=$(date +'%Y')" >> $GITHUB_OUTPUT 62 | 63 | - name: Substitute env variables in mkdocs.yml 64 | env: 65 | GIT_INFO: ${{ steps.git-info.outputs.GIT_INFO }} 66 | BUILD_DATE: ${{ steps.git-info.outputs.DATE }} 67 | CURRENT_YEAR: ${{ steps.git-info.outputs.CURRENT_YEAR }} 68 | run: | 69 | # Create backup 70 | cp mkdocs.yml mkdocs.yml.bak 71 | # Substitute variables 72 | envsubst '$BUILD_DATE $GIT_INFO $CURRENT_YEAR' < mkdocs.yml.bak > mkdocs.yml 73 | # Display substituted content for debugging 74 | echo "--- Checking substituted content ---" 75 | cat mkdocs.yml | grep -A5 copyright 76 | 77 | - name: Move Assets into docs 78 | run: | 79 | mv documentation-assets docs 80 | 81 | - name: Deploy documentation 82 | run: | 83 | mike deploy --push ${{ inputs.version }} 84 | if [ "${{ inputs.update_latest }}" = "true" ]; then 85 | mike deploy --push --update-aliases ${{ inputs.version }} latest 86 | fi 87 | -------------------------------------------------------------------------------- /docs/img/os_linux_note.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 19 | 21 | 44 | 46 | 47 | 49 | image/svg+xml 50 | 52 | 53 | 54 | 55 | 56 | 61 | 65 | 69 | 73 | 76 | 81 | 86 | 91 | 96 | 101 | 106 | 107 | 108 | 109 | 110 | 111 | 112 | -------------------------------------------------------------------------------- /docs/rules.md: -------------------------------------------------------------------------------- 1 | # Rules for Writing Documentation 2 | 3 | ## Language 4 | 5 | The documentation uses U.K. English for spellings and grammar. 6 | 7 | Abbreviations should not be used (for example, shouldn't, can't, won't) and neither should emoticons. 8 | 9 | Although the documents are not currently translated, they should be written as if they could be. That means consideration of the language used...can it be understood and translated unambiguously? For example, "configure" should be used rather than "set up" as "set up" can be misunderstood. This might sound silly, but translation is not always done in context, and people can put single words into Google Translate (for example) and get random results! Idioms, colloquialisms, and foreign expressions (including Latin) should also be avoided. 10 | 11 | Language style will vary between documents. For example, the Language Reference Guide needs to be very precise and official whereas a User Guide can include less formal statements such as "You might notice that...". 12 | 13 | Do **not** use an apostrophe when pluralising an acronym ("CPU's today are..." = WRONG) 14 | 15 | Try to make documents future-proof (especially with respect to dates/version numbers, "coming soon", and so on). Variables can help with this! 16 | 17 | ## Terminology 18 | 19 | The following table lists correct terminology and terms to avoid. A complete list of the [approved names for glyphs and primitive functions/operators](https://docs.dyalog.com/latest/CheatSheet%20-%20Nomenclature%20-%20Functions%20and%20Operators.pdf) is also available. 20 | 21 | **NOTE:** Although these terms are the correct ones to use, the documentation must always reflect the software. For example, if a field in the software uses "pdf" then the documentation should also use "pdf" when referring to that field content; the software usage always takes precedence. 22 | 23 | |**Use**|**Avoid**| 24 | |---|---| 25 | |large-span file|64-bit file| 26 | |small-span file|32-bit file| 27 | |Dyalog (referring to the product)|Dyalog APL| 28 | |Dyalog Ltd (referring to the company)|Dyalog| 29 | |PDF|pdf| 30 | |.NET|.Net, .net, any other variation| 31 | |dfn (Dfn when starting a sentence)|d-fn, D-fn, Dfn (unless starting a sentence), etc.| 32 | |Trace Window|Tracer, Debugger| 33 | |Edit Window|Editor| 34 | |for example|eg, e.g., eg.| 35 | |that is|ie, i.e., ie.| 36 | |note|NB, N.B.| 37 | |Boolean|boolean| 38 | |UNIX|Unix, unix| 39 | |configuration parameter|environment variable| 40 | 41 | 42 | Best practice: 43 | 44 | |**Use**|**Avoid**| 45 | |---|---| 46 | |can, might|may| 47 | |want|wish| 48 | 49 | ## Dyalog-specific Terms 50 | 51 | "Dyalog": 52 | 53 | - Dyalog = the product 54 | - Dyalog APL = the language 55 | - Dyalog Ltd = the company 56 | 57 | Syntax: 58 | 59 | - System functions should be written in upper case, for example, ⎕OFF 60 | - System commands should be written in upper case, for example, )CLEAR 61 | - User commands should be written in upper camel case, with user command groups wtirren in upper case, for example, ]LINK.GetItemName 62 | - Configuration parameters should be written in upper case if cross-platform; some of them are written in mixed case on Microsoft Windows, although this not case sensitive so upper case works there too. See the appropriate _Dyalog for `` Installation and Configuration Guide_ for operating-system-specific casing if you're documenting a configuration parameter on a particular platform. 63 | 64 | ## Acronyms 65 | 66 | Industry-standard abbreviations and acronyms can be used without explanation, for example, HTTP or XML. 67 | 68 | When you use an acronym that is not an industry standard for the first time, write the full word or phrase in its entirety and then enclose its abbreviation or acronym in parentheses. Afterwards, use the abbreviation or acronym alone. For example, "...the Dyalog Remote Communicator (DRC). The DRC can be...". 69 | 70 | ## Ordinal Numbers 71 | 72 | **NOTE:** The documentation, like the default Dyalog Session, uses an index origin of 1. 73 | 74 | Ordinal numbers: 75 | 76 | - should have postscripts rather than superscripts as superscripts can be hard to read, for example, 3rd. 77 | - should be written as numbers rather than words when referring to something that is 11 or greater OR that is in a list, for example, "the 75th element in the vector" or "the 4th line of code" 78 | - should be written as words rather than numbers when referring to something that is 10 or smaller AND not part of a list, for example, "the first time you do this" or "on the sixth day". 79 | 80 | If an algebraic term is being used instead of the number, then it should be italicised to distinguish it from the postscript, for example, "the _i_th term" or "the _n_th time". 81 | 82 | ## Imaginary Numbers 83 | 84 | The imaginary part should be prefixed with a capital letter J (that is how the session returns it), for example, 0J4. 85 | 86 | ## Lists 87 | 88 | Lists can ordered or unordered. You should: 89 | 90 | - use an ordered (numbered) list when the order in which steps are taken is important. 91 | - use an unordered (bulleted) list when the order does not matter. 92 | 93 | Lists can be nested to a depth of three. 94 | 95 | Use full stops for your list items if they complete a sentence (in this situation the list items should start with lower case letters), otherwise leave them without a full stop. In all ordered lists and most unordered lists, full stops will usually be appropriate. 96 | 97 | ## Third-party Products 98 | 99 | Legally, the owner of the product ought to be included the first time that a product is mentioned - this applies to every paragraph. For example, when writing about something that's on the Windows system, "Microsoft Windows" must be used the first time in the paragraph and just "Windows" can be used after that. However, if Windows is referred to in the subsequent paragraph, it needs to be "Microsoft Windows" again. 100 | 101 | ## Notes 102 | 103 | Various icons are used in the documentation to emphasise specific material. Notes are also used to differentiate between operating-system-specific behaviour in cross-platform documents. See [Notes](./style.md#notes). 104 | 105 | ## Miscellaneous 106 | 107 | Full stops should be followed by a single space, not a double space. 108 | 109 | When using a dash in a sentence, use an en-dash not a hyphen. 110 | 111 | ## Libraries: Operating System Differences 112 | 113 | - Microsoft Windows: Dynamic Link Library (.dll) 114 | - Linux/UNIX: Shared/static library (.so) 115 | - macOS: Shared/static library (.a) 116 | -------------------------------------------------------------------------------- /docs/img/dyalog-white.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 18 | 20 | 23 | 27 | 28 | 31 | 35 | 36 | 37 | 59 | 61 | 62 | 64 | image/svg+xml 65 | 67 | 68 | 69 | 70 | 71 | 77 | 80 | 83 | 88 | 89 | 92 | 97 | 98 | 101 | 106 | 107 | 110 | 115 | 116 | 119 | 124 | 125 | 128 | 133 | 134 | 135 | 136 | 142 | 146 | 150 | 155 | 156 | 160 | 165 | 166 | 170 | 175 | 176 | 180 | 185 | 186 | 191 | 196 | 197 | 198 | 199 | -------------------------------------------------------------------------------- /docs/style.md: -------------------------------------------------------------------------------- 1 | # Style Guide 2 | When using [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) 3 | 4 | ## Document Structure and General Style Guidelines 5 | 6 | !!! Info "Information" 7 | [Style_Guide_and_Best_Practice](https://wiki.bramley.dyalog.com/index.php/Style_Guide_and_Best_Practice) on the internal wiki covers: 8 | 9 | - The structure to use for documents 10 | - General rules to follow when writing, including language-related guidelines such as the use of Dyalog-specific terms, how to mention third-party products, and the use of abbreviations and acronyms. 11 | 12 | Please make sure you follow these as well as the styles detailed on this page. 13 | 14 | Some aspects have been adapted in this document for use with Material for MkDocs: 15 | 16 | - [Headings](#headings) 17 | - [Code](#code) 18 | - [Notes](#notes) 19 | 20 | ## Document structure 21 | 22 | In a MkDocs site, the left panel is defined by the organisation of the documentation source files and directories. Strive to keep this simple, and aim for fewer, larger files, instead of many smaller ones. The right panel is defined by each document's internal semantic structure (its headings sequence). We want a balance between the left and right navigation panels for several reasons: 23 | 24 | 1. Fewer HTTP requests means a decrease in perceived latency. 25 | 2. The MkDocs Material theme is designed with the two-panel navigation in mind. This means that if you write many, small documents with no internal sections, the presentation lools weird with large areas of whitespace. 26 | 3. Especially for large sites, a large, multi-tiered left side is harder to operate, as opening large folded sections soon becomes confusing. 27 | 28 | Aim for a flatish structure, grouping logically related aspects into single Markdown documents. 29 | 30 | ## Headings 31 | Headings are denoted by a number of octothorpes (hashes) corresponding to the heading level. 32 | 33 | ``` 34 | # Heading 1 (H1) 35 | ## Heading 2 (H2) 36 | ###### Heading 6 (H6) 37 | ``` 38 | 39 | Headings should be written in [title case](https://en.wikipedia.org/wiki/Title_case#Chicago_Manual_of_Style). 40 | 41 | Try to avoid multiple consecutive headings with no intervening text. 42 | 43 | Crucially, every document *must* start with an H1, and the heading sequence should never have gaps: when increasing nesting depth, an H{X} should only be followed by H{X+1}. Headings describe the semantic (the "meaning") structure of the document, not the layout. MkDocs rely on the semantic structure to lay out its left, and right navigational panels. 44 | 45 | Additionally, the MkDocs source may be used to render the documentation in different formats, such as CHM and PDF, and these conversions may depend on the correct semantic documentation structure. 46 | 47 | ## Italics 48 | Use italics when: 49 | 50 | - introducing a new term 51 | - naming a function or operator 52 | - an algebraic term is being used instead of the number, then it should be italicised to distinguish it from the postscript, for example, "the ith term" or "the nth time". 53 | 54 | Italics are denoted by single asterisks or underscores surrounding the text. 55 | 56 | ``` { .example} 57 | The word *asterisks* is italicised. 58 | 59 | The word _asterisks_ is italicised. 60 | ``` 61 | 62 | The word *asterisks* is italicised. 63 | { .example-output } 64 | 65 | ## Bold 66 | Bold text is denoted by double asterisks surrounding text. 67 | 68 | Bold text is used for: 69 | 70 | - file names 71 | - file paths 72 | - directory and folder names 73 | - file extensions 74 | - UI components (not buttons) 75 | 76 | ``` { .example } 77 | Go to the **file** menu 78 | ``` 79 | 80 | Go to the **file** menu 81 | { .example-output} 82 | 83 | ## Hyperlinks 84 | Used to create links to other parts of the same document, [other documents](#references) or external sources. 85 | 86 | Link text is surrounded by square brackets and the link URL is in round parentheses. 87 | 88 | ### Internal links 89 | Links can use text other than the URL when linking to: 90 | 91 | - a place within the same page 92 | - a page within the same document 93 | - a page or document within the same project 94 | - another document in a different Dyalog project 95 | 96 |

Example

97 | 98 | ``` 99 | See the [Link User Guide](https://dyalog.github.io/link) and... 100 | ``` 101 | 102 |
103 | See the [Link User Guide](https://dyalog.github.io/link) and... 104 |
105 | 106 | ### Other links 107 | Other links should be phrased so that the link is the URL for clarity. 108 | 109 | ``` 110 | Link can be downloaded from [https://github.com/Dyalog/link](https://github.com/Dyalog/link) 111 | ``` 112 | 113 |
114 | Link can be downloaded from [https://github.com/Dyalog/link](https://github.com/Dyalog/link) 115 |
116 | 117 | ## Mixing HTML and Markdown 118 | 119 | All HTML is valid Markdown, which on occasion provides a helpful escape hatch to create more elaborate constructs not supported directly in Markdown. However, avoid this unless absolutely necessary. The justifications for this are: 120 | 121 | 1. It's rarely required, and usually a sign that what you're doing can be simplified. 122 | 2. It represents a contribution barrier. Markdown is designed to be read and written by humans first; HTML is not. 123 | 124 | We have added extensions to make the use of HTML avoidable: 125 | 126 | * Extended table syntax to allow the use of headerless [tables](./tables.md) with row-, and col-spans. 127 | * Attribute lists, such as `{ .example}` to allow for assigning CSS classes and IDs to elements without encasing them in HTML tags. 128 | 129 | ## Markdown inside HTML 130 | Sometimes it might be useful to use Markdown inside HTML tags. For example, when including links inside a table. 131 | 132 | Set `markdown="1"` inside the opening tag. 133 | 134 |

Example

135 | 136 | ``` 137 |

138 | Markdown renders in here. For example, *italicised text*. 139 |

140 | ``` 141 | 142 |
143 |

144 | Markdown renders in here. For example, *italicised text*. 145 |

146 |
147 | 148 | ## Notes 149 | 150 | ### Creating a Note 151 | Notes are implemented as MkDocs [admonitions](https://squidfunk.github.io/mkdocs-material/reference/admonitions/). 152 | 153 | They are denoted by three exclamation marks followed by the note type and title text. On subsequent lines, note content is indented by four spaces. 154 | 155 | We use a fixed set of admonition types for consistency. 156 | 157 | **Do not forget** to include the title text. The title text must be as shown below. 158 | 159 | ### Note types 160 | 161 | #### General Notes for Emphasis 162 | Notes are used to highlight important information. 163 | 164 | - Hints and Recommendations 165 | 166 | Hints, tips, best practice and recommendations from Dyalog Ltd 167 | 168 | ``` { .example} 169 | !!! Hint "Hints and Recommendations" 170 | If both DOSLimit and BufferSize are set, then the smaller value applies. Dyalog Ltd recommends using a modest BufferSize and not setting EnableBufferSizeHttp to ensure that abnormally large headers are not processed, then setting an appropriate DOSLimit to accommodate the expected size messages. 171 | ``` 172 | 173 |
174 | 175 | !!! Hint "Hints and Recommendations" 176 | If both DOSLimit and BufferSize are set, then the smaller value applies. Dyalog Ltd recommends using a modest BufferSize and not setting EnableBufferSizeHttp to ensure that abnormally large headers are not processed, then setting an appropriate DOSLimit to accommodate the expected size messages. 177 | 178 |
179 | 180 | - Information 181 | 182 | Highlighting material of particular significance or relevance 183 | 184 |

example

185 | 186 | ``` 187 | !!! Info "Information" 188 | The .NET interface only works with the Unicode edition of Dyalog; Classic edition is not supported. 189 | ``` 190 | 191 |
192 | 193 | !!! Info "Information" 194 | The .NET interface only works with the Unicode edition of Dyalog; Classic edition is not supported. 195 | 196 |
197 | 198 | - Warning 199 | 200 | Warnings about actions that can impact the behaviour of Dyalog or have unforeseen consequences 201 | 202 |

example

203 | 204 | ``` 205 | !!! Warning "Warning" 206 | The structure under the SALT directory must not be modified and the five sub-directories must not be renamed. 207 | ``` 208 | 209 |
210 | 211 | !!! Warning "Warning" 212 | The structure under the SALT directory must not be modified and the five sub-directories must not be renamed. 213 | 214 |
215 | 216 | - Legacy 217 | 218 | Legacy information pertaining to behaviour in earlier releases of Dyalog or to functionality that still exists but has been superseded and is no longer recommended 219 | 220 |

example

221 | 222 | ``` 223 | !!! Legacy "Legacy" 224 | Although .dyapp files are supported for backwards compatibility, Dyalog Ltd recommends launching the interpreter directly from any APL source or configuration file (functionality introduced with Dyalog version 18.0) rather than through the now-superseded .dyapp file mechanism. 225 | ``` 226 | 227 |
228 | 229 | !!! Legacy "Legacy" 230 | Although .dyapp files are supported for backwards compatibility, Dyalog Ltd recommends launching the interpreter directly from any APL source or configuration file (functionality introduced with Dyalog version 18.0) rather than through the now-superseded .dyapp file mechanism. 231 | 232 |
233 | 234 | #### Operating-system-specific Behaviour 235 | Notes are also used to differentiate between operating-system-specific behaviour in cross-platform documents: 236 | 237 | - Dyalog on Linux 238 | 239 | Behaviour specific to Dyalog on Linux 240 | 241 |

example

242 | 243 | ``` 244 | !!! linux "Dyalog on Linux" 245 | The MyUCMDs directory is located directly under the **$HOME** directory 246 | ``` 247 | 248 |
249 | 250 | !!! linux "Dyalog on Linux" 251 | The MyUCMDs directory is located directly under the **$HOME** directory 252 | 253 |
254 | 255 | - Dyalog on UNIX 256 | 257 | Behaviour specific to Dyalog on UNIX 258 | 259 |

example

260 | 261 | ``` 262 | !!! unix "Dyalog on UNIX" 263 | By default, the cache file is located in **$HOME/.dyalog/** 264 | ``` 265 | 266 |
267 | 268 | !!! unix "Dyalog on UNIX" 269 | By default, the cache file is located in **$HOME/.dyalog/** 270 | 271 |
272 | 273 | - Dyalog on macOS 274 | 275 | Behaviour specific to Dyalog on macOS 276 | 277 |

example

278 | 279 | ``` 280 | !!! macos "Dyalog on macOS" 281 | By default, the cache file is located in **Users//.dyalog/** 282 | ``` 283 | 284 |
285 | 286 | !!! macos "Dyalog on macOS" 287 | By default, the cache file is located in **Users//.dyalog/** 288 | 289 |
290 | 291 | - Dyalog on Microsoft Windows 292 | 293 | Behaviour specific to Dyalog on Microsoft Windows 294 | 295 |

example

296 | 297 | ``` 298 | !!! windows "Dyalog on Microsoft Windows" 299 | By default, the cache file is located in **Documents\\Dyalog APL Files\\** 300 | ``` 301 | 302 |
303 | 304 | !!! windows "Dyalog on Microsoft Windows" 305 | By default, the cache file is located in **Documents\\Dyalog APL Files\\** 306 | 307 |
308 | 309 | ## Actions and Instructions 310 | Instructions are used when there is a logical sequence of steps to do something. 311 | 312 | Instructions are written as an ordered list. Blocks that contain instructions should be surrounded by horizontal rules. The introductory line ("To do...") should be **bold** and should not end with any punctuation. 313 | 314 | Example 315 | 316 | ```markdown 317 | --- 318 | 319 | **To do this thing** 320 | 321 | 1. Do this thing 322 | 2. Then do this thing 323 | 324 | --- 325 | ``` 326 | 327 |
328 | 329 | --- 330 | 331 | **To do this thing** 332 | 333 | 1. Do this thing 334 | 2. Then do this thing 335 | 336 | --- 337 | 338 |
> 339 | 340 | ## Examples 341 | Examples are used to demonstrate the functionality discussed. 342 | 343 | Introduce full examples with: 344 | 345 | ``` 346 | Example 347 | ``` 348 | 349 | Where `` is a heading one level below the containing section. You must use an HTML `` tag, both to include the `example` class and because headings written in HTML will not appear in the table of contents. 350 | 351 | Exception – if there are several consecutive examples illustrating different things, they can each be introduced with "Example: " if that helps to clarify things for the reader. 352 | 353 | !!! Info "Information" 354 | The examples in this document use `
` to provide a grey background that distinguishes examples from normal text. However, we do not use this convention in our actual documentation. 355 | ``` 356 |

Example

357 | 358 | This is an example 359 | ``` 360 | 361 |

Example

362 | 363 | This is an example 364 | 365 | ## Code 366 | Inline code and code blocks render in APL font unless the class "language-nonAPL" is used. 367 | 368 | Syntax highlighting is not enabled. 369 | 370 | #### Inline code 371 | Inline, use `[your code here]` or single backticks `` `[your code here]` ``. 372 | 373 |

Example: APL code

374 | 375 | ```html 376 | The average of a vector (`+⌿÷≢`) is the sum divided by the tally. 377 | ``` 378 | 379 |
380 | 381 | The average of a vector (`+⌿÷≢`) is the sum divided by the tally. 382 | 383 |
> 384 | 385 |

Example: non-APL code

386 | 387 | ```html 388 | getpid() is common to all UNIX platforms. 389 | ``` 390 | 391 |
392 | 393 | getpid() is common to all UNIX platforms. 394 | 395 |
> 396 | 397 | #### APL Code blocks 398 | Code blocks use triple backticks with "apl" (lowercase) to denote the language. 399 | 400 | 401 | ```apl 402 | 3+⍳10 403 | 4 5 6 7 8 9 10 11 12 13 404 | ``` 405 | 406 |

Example: Using backticks

407 | 408 | ``````` 409 | ```apl 410 | 3+⍳10 411 | 4 5 6 7 8 9 10 11 12 13 412 | ``` 413 | ``````` 414 | 415 | ```apl 416 | 3+⍳10 417 | 4 5 6 7 8 9 10 11 12 13 418 | ``` 419 | 420 | #### Non-APL Code Blocks 421 | Use triple backticks with "nonAPL". 422 | 423 |

Example: Using backticks

424 | 425 | `````` 426 | ```nonAPL 427 | >>> print("hello") # Code block example 428 | hello 429 | ``` 430 | `````` 431 | 432 | ```nonAPL 433 | >>> print("hello") # Code block example 434 | hello 435 | ``` 436 | 437 | ### APL Code +⌿÷≢⌹ in Titles 438 | Try to avoid using APL code in headings – although it is rendered in APL font on the page, it is not rendered correctly in the navigation menus. 439 | 440 | If it is essential, use `` to add code to titles. 441 | 442 |

Example

443 | 444 | ```markdown 445 | ### APL Code +⌿÷≢⌹ in Titles 446 | ``` 447 | 448 | ## References 449 | Always use meaningful link text. Never use "see [here](#)". 450 | 451 | ### Within the same document 452 | Reference to another section within the same document. 453 | 454 | ``` 455 | See [Note Types](#note-types) 456 | ``` 457 | 458 |
459 | See [Note Types](#note-types) 460 |
> 461 | 462 | ### To another document 463 | References to other documents should correctly name the document and be italicised. Ideally they should link to the document. 464 | 465 |

Example

466 | 467 | ``` 468 | For more information on the _Clean_ function, see the [_SALT User Guide_](https://docs.dyalog.com/latest/SALT%20User%20Guide.pdf). 469 | ``` 470 | 471 |
472 | 473 | For more information on the _Clean_ function, see the [_SALT User Guide_](https://docs.dyalog.com/latest/SALT%20User%20Guide.pdf). 474 | 475 |
> 476 | 477 | ## Command Codes and Keys 478 | When referring to keyboard shortcuts, such as those controlled by `⎕KL` on Microsoft Windows, put the code in angle brackets. 479 | 480 | Closing angle brackets must be escaped with a backslash (e.g. ``). 481 | 482 | Example 483 | { .example} 484 | 485 | ``` 486 | is the command code for trace. 487 | ``` 488 | 489 | is the command code for trace. 490 | { .example-output} 491 | 492 | ## Keyboard keys 493 | Use the `` tag to refer to keys. This is a case where using HTML markup is unavoidable. 494 | 495 | example 496 | { .example} 497 | 498 | ``` 499 | Press the Enter key. 500 | ``` 501 | 502 | Press the Enter key. 503 | { .example-output} 504 | 505 | ## Icons 506 | Sometimes it is relevant to include an icon. For example, when describing a combination of key presses. 507 | 508 | Icons are included using a special name surrounded by colons. 509 | 510 | Here is the list of icons used in our documentation. 511 | 512 | - Apple icons: 513 | - Apple key: :material-apple: (`:material-apple:`) 514 | - Command Key: :material-apple-keyboard-command: (`:material-apple-keyboard-command:`) 515 | - Option key: :material-apple-keyboard-option: (`:material-apple-keyboard-option:`) 516 | - Windows Key: :fontawesome-brands-windows: (`:fontawesome-brands-windows:`) 517 | 518 |

Example

519 | 520 | ``` 521 | Use :material-apple-keyboard-command: + C to copy text 522 | ``` 523 | 524 |
525 | Use :material-apple-keyboard-command: + C to copy text 526 |
> 527 | --------------------------------------------------------------------------------