Merge pull request #27 from Dyalog/v0.4.2

Fix issues with "Data and Variables" chapter.
Dyalog · Feb 9, 2022 · 0cb4e21 · 0cb4e21
2 parents 3b2a1b1 + 093a80b
commit 0cb4e21
Show file tree

Hide file tree

Showing 3 changed files with 41 additions and 28 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,6 +7,13 @@ In the first instance, it lists the changes between consecutive releases of this
 However, because this book is a rework of the first edition by Bernard Legrand,
 this changelog also marks with [n] content that is new in this rework.
 
+## 0.4.2
+
+  - Fix #24 by improving preprocessing script.
+  - Improve formatting and wording in the chapter (fix #23 and #26).
+  - Fix typos (fix #23).
+  - Fix #21.
+
 ## 0.4.1
 
   - Fix typos.

diff --git a/Data-and-Variables.ipynb b/Data-and-Variables.ipynb
@@ -36,7 +36,7 @@
     {
      "data": {
       "text/html": [
-       "<span style=\"white-space:pre; font-family: monospace\">80\n",
+       "<span style=\"white-space:pre; font-family: monospace\">81\n",
        "</span>"
       ]
      },
@@ -46,7 +46,7 @@
     }
    ],
    "source": [
-    "27 + 53"
+    "27 + 54"
    ]
   },
   {
@@ -59,7 +59,7 @@
     {
      "data": {
       "text/html": [
-       "<span style=\"white-space:pre; font-family: monospace\">563\n",
+       "<span style=\"white-space:pre; font-family: monospace\">463\n",
        "</span>"
       ]
      },
@@ -69,7 +69,7 @@
     }
    ],
    "source": [
-    "1271 - 708"
+    "1171 - 708"
    ]
   },
   {
@@ -80,7 +80,7 @@
     {
      "data": {
       "text/html": [
-       "<span style=\"white-space:pre; font-family: monospace\">¯188\n",
+       "<span style=\"white-space:pre; font-family: monospace\">¯198\n",
        "</span>"
       ]
      },
@@ -90,7 +90,7 @@
     }
    ],
    "source": [
-    "644 - 832"
+    "634 - 832"
    ]
   },
   {
@@ -132,7 +132,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 5,
+   "execution_count": 1,
    "metadata": {},
    "outputs": [
     {
@@ -142,7 +142,7 @@
        "</span>"
       ]
      },
-     "execution_count": 5,
+     "execution_count": 1,
      "metadata": {},
      "output_type": "execute_result"
     }
@@ -3622,7 +3622,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "The Jupyter notebook puts boxes around the items of the vector to make it easier to interpret the result. If the expression above were to be ran in the Dyalog APL interpreter session, the result would be\n",
+    "The Jupyter notebook puts boxes around the items of the vector to make it easier to interpret the result. If the expression above were to be run in the Dyalog APL interpreter session, the result would be\n",
     "\n",
     "```\n",
     "87 24  John  51  78 45 23  95  8 6  69\n",
@@ -5533,23 +5533,23 @@
     " \n",
     "| Command | Usage |\n",
     "| :- | :- |\n",
-    "| )vars | Lists the variables in the active workspace. |\n",
-    "| )fns | Lists the user-defined functions in the active workspace. |\n",
-    "| )erase *names* | Deletes the named objects from the active workspace. |\n",
-    "| )clear | Deletes everything and leaves the active workspace empty. |\n",
-    "| )save | Saves the active workspace under its current name, or: opens the File Save dialog box if the WS has no name yet. |\n",
-    "| )save *wsname* | Saves the active WS under the given path/name/extension. |\n",
-    "| )lib | Gives the list of all workspaces in the *workspace search path*. |\n",
-    "| )lib *path* | Gives the list of all workspaces in the specified path. |\n",
-    "| )drop *wsname* | Deletes a saved WS from disk. |\n",
-    "| )load | Opens the File Open dialog box, from which a workspace can be selected. It will replace the active WS. |\n",
-    "| )load *wsname* | Replaces the contents of the active WS with the referenced WS. |\n",
-    "| )copy *wsname* *names* | Imports the named items from the specified WS into the active WS, where they may overwrite objects identically named. |\n",
-    "| )copy *wsname* | Imports all contents of the specified WS. |\n",
-    "| )pcopy *wsname* {*names*} | Similar to `)copy`, but does not overwrite existing objects. |\n",
-    "| )wsid | Displays the name of the current (active) WS. |\n",
-    "| )off | Closes the APL session. |\n",
-    "| )continue | Saves a _continue WS_ and closes the APL session. |"
+    "| `)vars` | Lists the variables in the active workspace. |\n",
+    "| `)fns` | Lists the user-defined functions in the active workspace. |\n",
+    "| `)erase *names*` | Deletes the named objects from the active workspace. |\n",
+    "| `)clear` | Deletes everything and leaves the active workspace empty. |\n",
+    "| `)save` | Saves the active workspace under its current name, or: opens the File Save dialog box if the WS has no name yet. |\n",
+    "| `)save *wsname*` | Saves the active WS under the given path/name/extension. |\n",
+    "| `)lib` | Gives the list of all workspaces in the *workspace search path*. |\n",
+    "| `)lib *path*` | Gives the list of all workspaces in the specified path. |\n",
+    "| `)drop *wsname*` | Deletes a saved WS from disk. |\n",
+    "| `)load` | Opens the File Open dialog box, from which a workspace can be selected. It will replace the active WS. |\n",
+    "| `)load *wsname*` | Replaces the contents of the active WS with the referenced WS. |\n",
+    "| `)copy *wsname* *names*` | Imports the named items from the specified WS into the active WS, where they may overwrite objects identically named. |\n",
+    "| `)copy *wsname*` | Imports all contents of the specified WS. |\n",
+    "| `)pcopy *wsname* {*names*}` | Similar to `)copy`, but does not overwrite existing objects. |\n",
+    "| `)wsid` | Displays the name of the current (active) WS. |\n",
+    "| `)off` | Closes the APL session. |\n",
+    "| `)continue` | Saves a _continue WS_ and closes the APL session. |"
    ]
   },
   {

diff --git a/scripts/preprocess.py b/scripts/preprocess.py
@@ -161,6 +161,9 @@ def create_admonitions(lines):
     and end with <!-- end -->. The sections can optionally be completely offset
     with " > " to produce a blockquote that gives a visual cue for readers of
     the plain notebooks.
+    
+    Inside those sections, we look for code blocks or other formatting done with
+    backticks (`), to ensure that the outer admonition is nested correctly.
 
     Here, `name` is the name of the admonition and an optional `style=stylename`
     can be used to style the admonition as described in
@@ -195,11 +198,14 @@ def create_admonitions(lines):
                 content_lines = [match.group(2) + "\n" for match in bq_matches]
             else:
                 content_lines = intermediate_lines
+            # How deep must the admonition nesting be?
+            backtick_nesting = max(map(len, re.findall(r"`+", "\n".join(content_lines))), default=0)
+            backticks = "`" * max(3, 1 + backtick_nesting)
             lines = (
                 lines[:i] +
-                [f"```{{admonition}} {text} \n", f":class: {style}\n"] +
+                [f"{backticks}{{admonition}} {text} \n", f":class: {style}\n"] +
                 content_lines +
-                ["```\n"] +
+                [f"{backticks}\n"] +
                 lines[matching_line+1:]
             )
             # after doing the maths, this is exactly where we want to resume processing: