Merge pull request #3 from xpqz/2-flare2mkdocs

Add info relating to the flare → mkdocs conversion

docs/css.md

@@ -0,0 +1,14 @@
+# CSS
+
+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).
+
+## Dyalog MkDocs CSS
+
+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:
+
+1. **main.css**
+2. **extra.css**
+
+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.
+
+As a "run of the mill" documentation contributor, you should rarely need to consider the CSS.

docs/images.md

@@ -0,0 +1,32 @@
+# Figures with Captions
+
+!!! Info "Information"
+    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.
+
+The Markdown way to add an image is a Markdown link preceded by an exclamation mark:
+
+```other
+![alt text here](image url)
+```
+
+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.
+
+```other
+![caption text here](image url){ width=300px #MyImgId }
+```
+
+Here is an example:
+
+```other
+![An elephant at sunset](https://interactive-examples.mdn.mozilla.net/media/cc0-images/elephant-660-480.jpg){ width=300px #MyElephant}
+```
+
+![An elephant at sunset](https://interactive-examples.mdn.mozilla.net/media/cc0-images/elephant-660-480.jpg){ width=300px #MyElephant}
+
+Like with [tables](tables.md), we reference the image by its id by an "empty" link:
+
+```
+The beautiful specimen in [](#MyElephant) is a bull with the name of Kevin.
+```
+
+The beautiful specimen in [](#MyElephant) is a bull with the name of Kevin.

docs/index.md

@@ -3,7 +3,6 @@
 ## To Do
 - references in HTML vs. PDF
 - consider linking to specific document versions in references to other documents
-- what is happening with [figures with captions](./style.md#figures-with-captions) (and tables)
 
 ## Markdown and HTML
 This document, and the documentation to which it refers, is written in Markdown.
@@ -27,3 +26,13 @@ For more examples of markdown and equivalent HTML, see the [basic syntax page on
 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.
 
 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).
+
+## Resources
+
+* [MkDocs](https://www.mkdocs.org/)
+* [MkDocs Material](https://squidfunk.github.io/mkdocs-material/) theme
+* [Markdown extensions](https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown/) available in Material
+* [Attribute lists](https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown/?h=attribute+lists#attribute-lists)
+* [GitHub Flavored Markdown Spec](https://github.github.com/gfm/)
+* [Extended Markdown tables](https://github.com/fumbles/tables_extended)
+* [Captions](https://github.com/tobiasah/mkdocs-caption#readme)

docs/style.md

@@ -4,7 +4,7 @@ When using [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/)
 ## Document Structure and General Style Guidelines
 
 !!! Info "Information"
-    [Style_Guide_and_Best_Practice](http://wiki.dyalog.bramley/index.php/Style_Guide_and_Best_Practice) on the internal wiki covers:
+    [Style_Guide_and_Best_Practice](https://wiki.bramley.dyalog.com/index.php/Style_Guide_and_Best_Practice) on the internal wiki covers:
 
     - The structure to use for documents
     - 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.
@@ -17,19 +17,33 @@ Some aspects have been adapted in this document for use with Material for MkDocs
 - [Code](#code)
 - [Notes](#notes)
 
+## Document structure
+
+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:
+
+1. Fewer HTTP requests means a decrease in perceived latency.
+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.
+3. Especially for large sites, a large, multi-tiered left side is harder to operate, as opening large folded sections soon becomes confusing.
+
+Aim for a flatish structure, grouping logically related aspects into single Markdown documents.
+
 ## Headings
-Headings are denoted by a number of octothorpes corresponding to the heading level.
+Headings are denoted by a number of octothorpes (hashes) corresponding to the heading level.
 
 ```
-# Heading 1
-## Heading 2
-###### Heading 6
+# Heading 1 (H1)
+## Heading 2 (H2)
+###### Heading 6 (H6)
 ```
 
 Headings should be written in [title case](https://en.wikipedia.org/wiki/Title_case#Chicago_Manual_of_Style).
 
 Try to avoid multiple consecutive headings with no intervening text.
 
+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. 
+
+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.
+
 ## Italics
 Use italics when:
 
@@ -39,15 +53,12 @@ Use italics when:
 
 Italics are denoted by single asterisks surrounding the text.
 
-<p class="example">example</p>
-
-```
+``` { .example}
 The word *asterisks* is italicised.
 ```
 
-<div class="example-output" markdown="1">
 The word *asterisks* is italicised.
-</div>>
+{ .example-output }
 
 ## Bold
 Bold text is denoted by double asterisks surrounding text.
@@ -60,43 +71,44 @@ Bold text is used for:
 - file extensions
 - UI components (not buttons)
 
-<p class="example">example</p>
-
-```
+``` { .example }
 Go to the **file** menu
 ```
 
-<div class="example-output" markdown="1">
 Go to the **file** menu
-</div>>
+{ .example-output}
 
 ## Hyperlinks
 Used to create links to other parts of the same document, [other documents](#references) or external sources.
 
 Link text is surrounded by square brackets and the link URL is in round parentheses.
 
-<p class="example">Example: link text is URL</p>
+- <span class="example">Example: link text is URL</span>
+    ```
+    Link can be downloaded from [https://github.com/Dyalog/link](https://github.com/Dyalog/link)
+    ```
+    Link can be downloaded from [https://github.com/Dyalog/link](https://github.com/Dyalog/link)
 
-```
-Link can be downloaded from [https://github.com/Dyalog/link](https://github.com/Dyalog/link)
-```
+- <span class="example">Example: alternative link text</span>
+    ```
+    Download [Link](https://github.com/Dyalog/link) and...
+    ```
+    Download [Link](https://github.com/Dyalog/link) and...
 
-<div class="example-output" markdown="1">
-Link can be downloaded from [https://github.com/Dyalog/link](https://github.com/Dyalog/link)
-</div>>
+## Mixing HTML and Markdown
 
-<p class="example">Example: alternative link text</p>
+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:
 
-```
-Download [Link](https://github.com/Dyalog/link) and...
-```
+1. It's rarely required, and usually a sign that what you're doing can be simplified. 
+2. It represents a contribution barrier. Markdown is designed to be read and written by humans first; HTML is not.
 
-<div class="example-output" markdown="1">
-Download [Link](https://github.com/Dyalog/link) and...
-</div>>
+We have added extensions to make the use of HTML avoidable:
+
+* Extended table syntax to allow the use of headerless [tables](./tables.md) with row-, and col-spans. 
+* Attribute lists, such as `{ .example}` to allow for assigning CSS classes and IDs to elements without encasing them in HTML tags.
 
 ## Markdown inside HTML
-Sometimes it might be useful to use markdown inside HTML tags. For example, when including links inside a table.
+Sometimes it might be useful to use Markdown inside HTML tags. For example, when including links inside a table.
 
 Set `markdown="1"` inside the opening tag.
 
@@ -112,7 +124,7 @@ Markdown renders in here. For example, *italicised text*.
 <p class="myclass" markdown="1">
 Markdown renders in here. For example, *italicised text*.
 </p>
-</div>>
+</div>
 
 ## Notes
 
@@ -134,9 +146,7 @@ Notes are used to highlight important information.
     
     Hints, tips, best practice and recommendations from Dyalog Ltd
 
-    <p class="example">example</p>
-
-    ```
+    ``` { .example}
     !!! Tip "Hints and Recommendations"
         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.
     ```
@@ -311,23 +321,35 @@ Instructions are written as an ordered list. Blocks that contain instructions sh
 ## Examples
 Examples are used to demonstrate the functionality discussed.
 
-Introduce full examples with `<p class="example">Example</p>` (or "Examples") so that it is on a line by itself.
+Introduce full examples with:
+
+```
+example (or examples)
+{ .example}
+```
+
+which renders as `<p class="example">example</p>`.
 
 Exception – if there are several consecutive examples illustrating different things, they can each be introduced with "Example: <text\>" if that helps to clarify things for the reader.
 
-<p class="example">example</p>
+!!! Info "Information"
+    The examples in this document use `<div class="example-output" markdown="1">` to provide a grey background that distinguishes examples from normal text. However, we do not use this convention in our actual documentation.
 
 ```
-<p class="example">example</p>
+example
+{ .example}
+
 This is an example
 ```
 
 <div class="example-output" markdown="1">
 
-<p class="example">example</p>
+example
+{ .example}
+
 This is an example
 
-</div>>
+</div>
 
 ## Code
 Inline code and code blocks render in APL font unless the class "language-other" is used.
@@ -362,15 +384,8 @@ The average of a vector (<code class="language-apl">+⌿÷≢</code>) is the sum
 </div>>
 
 #### APL Code blocks
-Code blocks use `<pre><code class="language-apl"></code></pre>` or triple backticks with "apl" (lowercase) to denote the language.
+Code blocks use triple backticks with "apl" (lowercase) to denote the language.
 
-<p class="example">Example: Using HTML</p>
-
-```
-<pre><code class="language-apl">      3+⍳10
-4 5 6 7 8 9 10 11 12 13
-</code></pre>
-```
 
 ```apl
       3+⍳10
@@ -392,30 +407,18 @@ Code blocks use `<pre><code class="language-apl"></code></pre>` or triple backti
 ```
 
 #### Non-APL Code Blocks
-Use `<code class="language-other">[your code here]</code>` or triple backticks with "other" (lowercase).
-
-<p class="example">Example: Using HTML</p>
-
-```
-<pre><code class="language-other">>>> print("hello")   # Code block example
-hello</code></pre>
-```
-
-```other
->>> print("hello")   # Code block example
-hello
-```
+Use triple backticks with the name of the language or format, or "other" (lowercase).
 
 <p class="example">Example: Using backticks</p>
 
 ``````
-```other
+```python
 >>> print("hello")   # Code block example
 hello
 ```
 ``````
 
-```other
+```pythom
 >>> print("hello")   # Code block example
 hello
 ```
@@ -465,39 +468,28 @@ When referring to keyboard shortcuts, such as those controlled by `⎕KL` on Mic
 
 Closing angle brackets must be escaped with a backslash (e.g. `<keycode\>`).
 
-<p class="example">Example</p>
+Example
+{ .example}
 
 ```
 <TC\> is the command code for trace.
 ```
 
-<div class="example-output" markdown="1">
 <TC\> is the command code for trace.
-</div>>
+{ .example-output}
 
 ## Keyboard keys
-Use the `<kbd>` tag to refer to keys.
+Use the `<kbd>` tag to refer to keys. This is a case where using HTML markup is unavoidable.
 
-<p class="example">Example</p>
+example
+{ .example}
 
 ```
 Press the <kbd>Enter</kbd> key.
 ```
 
-<div class="example-output" markdown="1">
 Press the <kbd>Enter</kbd> key.
-</div>>
-
-## Figures with Captions
-!!! Info "Information"
-    There is currently no way to automatically number and cross-reference figures in Material for MkDocs.
-
-<figure>
-<img width="300px" src="https://interactive-examples.mdn.mozilla.net/media/cc0-images/elephant-660-480.jpg" />
-<figcaption>
-An elephant at sunset
-</figcaption>
-</figure>
+{ .example-output}
 
 ## Icons
 Sometimes it is relevant to include an icon. For example, when describing a combination of key presses.
@@ -515,7 +507,7 @@ Here is the list of icons used in our documentation.
 <p class="example">Example</p>
 
 ```
-Use <kbd markdown="1">:material-apple-keyboard-command: + C</kbd> to copy text
+Use <kbd markdown="1">:material-apple-keyboard-command:</kbd> + <kbd>C</kbd> to copy text
 ```
 
 <div class="example-output" markdown="1">