Minor improvements

5jt · May 20, 2019 · 16a036d · 16a036d
1 parent a1f9a51
commit 16a036d
Show file tree

Hide file tree

Showing 29 changed files with 341 additions and 112 deletions.
diff --git a/HTML/01-Introduction.html b/HTML/01-Introduction.html
@@ -1,5 +1,5 @@
 <!DOCTYPE html>
-<html lang="en" style="scroll-behavior:smooth" >
+<html lang="en">
 <head>
 <meta http-equiv="X-UA-Compatible" content="IE=edge">
 <meta charset="utf-8">
@@ -130,6 +130,7 @@ <h2>What you need to use the Dyalog Cookbook</h2>
 <h2>Conventions</h2>
 </a>
 </div>
+
 <div class="leanpub">
 <img src="https://download.aplwiki.com/LeanPub/Images/information.png" alt="Information">
 <div>

diff --git a/HTML/02-Structure.html b/HTML/02-Structure.html
diff --git a/HTML/03-Packaging.html b/HTML/03-Packaging.html
@@ -1,5 +1,5 @@
 <!DOCTYPE html>
-<html lang="en" style="scroll-behavior:smooth" >
+<html lang="en">
 <head>
 <meta http-equiv="X-UA-Compatible" content="IE=edge">
 <meta charset="utf-8">
@@ -92,6 +92,7 @@ <h2>Output to the session log</h2>
 </a>
 </div>
 <p>In a runtime interpreter or an <abbr title="Executable file with the extension 'exe'">EXE</abbr>, there is no APL session, and output to the session which would have been visible in a development system will simply disappear.</p>
+
 <div class="leanpub">
 <img src="https://download.aplwiki.com/LeanPub/Images/information.png" alt="Information">
 <div>
@@ -101,6 +102,7 @@ <h2>Output to the session log</h2>
 </div>
 
 <p>If we want to see this output, we need to write it to a log file. But how do we find out where we need to make changes? We recommend you think about this from the start, and ensure that all <em>intentional</em> output goes through a log function, or at least use an explicit <code>⎕←</code> so that output can easily be identified in the source.</p>
+
 <div class="leanpub_A">
 <h3>Unwanted output to the session</h3>
 <p>What can you do if you have output appearing in the session and you don’t know where in your application it is being generated? The easiest way is to associate a callback function with the <code>SessionPrint</code> event as in:</p>
@@ -196,6 +198,7 @@ <h2>Conclusions</h2>
 <p>The reason: we want to ensure when we create a namespace with <code>#.⎕NS ''</code> those system variables have the expected values.</p>
 <p>Alternatively you could ensure you execute <code>⎕NS ''</code> within a namespace that is known to have system variables with the right values.</p></li>
 </ul>
+
 <div class="leanpub">
 <img src="https://download.aplwiki.com/LeanPub/Images/warning.png" alt="Warning">
 <div>
@@ -224,6 +227,7 @@ <h2>Exporting the application</h2>
 </ol>
 <p>You should see a message: <em>File Z:\code\v03\MyApp.exe successfully created.</em> This occasionally (rarely) fails for no obvious reason. If it does fail just try again and you should be fine.</p>
 <p>If it keeps failing then the by far most common reason is that the <abbr title="Executable file with the extension 'exe'">EXE</abbr> is running – you cannot replace an <abbr title="Executable file with the extension 'exe'">EXE</abbr> while it is running.</p>
+
 <div class="leanpub">
 <img src="https://download.aplwiki.com/LeanPub/Images/information.png" alt="Information">
 <div>
@@ -247,6 +251,7 @@ <h3>The “Command line” field</h3>
 <p>Note that you cannot really debug a console application with Ride; for details see the <em>Debugging a stand-alone <abbr title="Executable file with the extension 'exe'">EXE</abbr></em> chapter.</p>
 <p>If you do not check <em>Console application</em>, the program is started as a separate process and you cannot catch the return code.</p>
 <p>We therefore recommend you clear the <em>Console application</em> checkbox unless you have a good reason to do otherwise.</p>
+
 <div class="leanpub">
 <img src="https://download.aplwiki.com/LeanPub/Images/tip.png" alt="Tip">
 <div>

diff --git a/HTML/04-Logging .html b/HTML/04-Logging .html
@@ -1,5 +1,5 @@
 <!DOCTYPE html>
-<html lang="en" style="scroll-behavior:smooth" >
+<html lang="en">
 <head>
 <meta http-equiv="X-UA-Compatible" content="IE=edge">
 <meta charset="utf-8">
@@ -92,14 +92,15 @@ <h1>4. Logging what happens</h1>
 <pre><code>Z:\code\v03\MyApp.exe Z:\texts\Does_not_exist</code></pre>
 <p>We see an alert message: <em>This Dyalog APL runtime application has attempted to use the APL session and will therefore be closed.</em></p>
 <p><code>MyApp</code> failed because there is no file or folder <code>Z:\texts\Does_not_exist</code>. That triggered an error in the APL code. The interpreter tried to display an error message and looked for input from a developer from the session. But a runtime task has no session, so at that point the interpreter popped the alert message and <code>MyApp</code> died.</p>
+
 <div class="leanpub_A">
 <h3>CONTINUE workspaces</h3>
 <p>Prior to version 17.0, as soon as you close the message box a CONTINUE workspace was created in the current directory. Such a CONTINUE <abbr title="Short for Workspaces">WS</abbr> can be loaded and investigated, making it easy to figure out what the problem is. (However, this is true only if it is a single-threaded application, since workspaces cannot be saved when more than one thread is running.)</p>
 <p>With version 17.0 you can still force the interpreter to drop a CONTINUE workspace by enabling the old behaviour with <code>2704⌶ 1</code>, while <code>2704⌶ 0</code> would disable it again.</p>
 <p>For analysis, load a CONTINUE workspace in an already running Dyalog session – don’t double-click a CONTINUE! The reason is that <code>⎕DM</code> and <code>⎕DMX</code> are overwritten in the process of booting SALT, meaning that you lose the error message.</p>
 <p>You <em>might</em> recreate them by re-executing the failing line – but that has other dangers, or might fail in a new way.</p>
 <p>Note also that the CONTINUE is always saved in the current directory; in version 17.0 there is no way to tell the interpreter to save the CONTINUE workspace elsewhere.</p>
-<p>That is limiting, as it will fail for your own stand-alone EXEs if they are installed in the standard folders for executables under Windows, <code>C:\Program Files</code> (64-bit programs) and <code>C:\Program Files (x86)</code> (32-bit programs): even as an admin you cannot write to those folders or subfolders.</p>
+<p>That is limiting, as it will fail for your own stand-alone <abbr title="Executable file with the extension 'exe'">EXE</abbr>s if they are installed in the standard folders for executables under Windows, <code>C:\Program Files</code> (64-bit programs) and <code>C:\Program Files (x86)</code> (32-bit programs): even as an admin you cannot write to those folders or subfolders.</p>
 <p>But Windows saves it anyway! If a program attempts to write to a banned location Windows tells them “Sure, no problem” but saves them in a e.g. <code>"C:\Users\kai\AppData\Local\VirtualStore\Program Files\Dyalog\Dyalog APL-64 17.0 Unicode\CONTINUE.dws"</code> where you are running Dyalog APL 64-bit Unicode version 17.0.</p>
 </div>
 
@@ -121,6 +122,7 @@ <h2>Include the “Logger” class</h2>
 Load MyApp
 Run #.MyApp.SetLX ⍬</code></pre>
 <p>and run the <abbr title="File with the extension 'dyapp' that contains 'Load' and 'Run' commands in order to put together an APL application">DYAPP</abbr> to recreate the <code>MyApp</code> workspace.</p>
+
 <div class="leanpub_A">
 <h3>Help for the APLTree namespaces</h3>
 <p>You can get detailed documentation on an APLTree class or namespace by executing e.g.:</p>
@@ -335,6 +337,7 @@ <h2>Improvements to our code</h2>
 2016-04-06 13:42:43 (0) Target: Z:\texts\en.csv
 2016-04-06 13:42:43 (0) 244 bytes written to Z:\texts\en.csv
 2016-04-06 13:42:43 (0) All done</code></pre>
+
 <div class="leanpub">
 <img src="https://download.aplwiki.com/LeanPub/Images/information.png" alt="Information">
 <div>
@@ -372,6 +375,7 @@ <h2>Improvements to our code</h2>
 2017-02-26 10:54:35 (0) 9 files processed.
 2017-02-26 10:58:07 (0) Z:/texts/en/ageofinnocence.txt
 ...</code></pre>
+
 <div class="leanpub">
 <img src="https://download.aplwiki.com/LeanPub/Images/information.png" alt="Information">
 <div>
@@ -417,6 +421,7 @@ <h2>Where are we</h2>
 </div>
 <p>We now have <code>MyApp</code> logging its work in a subfolder of the application folder and reporting any problems it has anticipated.</p>
 <p>Next we need to consider how to handle and report errors we have <em>not</em> anticipated. We should also return some kind of error code to Windows. If <code>MyApp</code> encounters an error, any process calling it needs to know. But before we are doing this we will discuss how to configure <code>MyApp</code>.</p>
+
 <div class="leanpub_A">
 <h3>Destructors versus the Tracer</h3>
 <p>When you trace through <code>TxtToCsv</code>, the moment you leave the function the Tracer shows the function <code>Cleanup</code> of the <code>Logger</code> class. The function is declared as a destructor.</p>

diff --git a/HTML/05-Configuration.html b/HTML/05-Configuration.html
@@ -1,5 +1,5 @@
 <!DOCTYPE html>
-<html lang="en" style="scroll-behavior:smooth" >
+<html lang="en">
 <head>
 <meta http-equiv="X-UA-Compatible" content="IE=edge">
 <meta charset="utf-8">
@@ -103,6 +103,7 @@ <h2>The Windows Registry</h2>
 <p>Settings needed by Windows itself <em>have</em> to be stored in the Registry. For example, associating a file extension with your application, so that double-clicking on its icon launches your application.</p>
 <p>The APLTree classes <a href="http://aplwiki.com/WinReg" class="external_link">WinRegSimple</a> and <a href="http://aplwiki.com/WinReg" class="external_link">WinReg</a> provide methods for handling the Windows Registry. We will discuss them in their own chapter.</p>
 <p>MyApp doesn’t need the Windows Registry at this point. We’ll store its configurations in configuration files.</p>
+
 <div class="leanpub">
 <img src="https://download.aplwiki.com/LeanPub/Images/information.png" alt="Information">
 <div>
@@ -291,6 +292,7 @@ <h3>Initialising the workspace</h3>
 </span>  r←TxtToCsv arg~''''
 ∇</code></pre>
 <p>Although both <code>MyLogger</code> and <code>Config</code> are global and not passed as arguments, it’s good practice to assign them this way rather than bury their creation somewhere down the stack. This way it’s easy to see where they are set.</p>
+
 <div class="leanpub_A">
 <h3>Specifying an <abbr title="File with the extension 'ini' containing configuration data">INI</abbr> file on the command line</h3>
 <p>We could pass the command line parameters as arguments to <code>Initial</code> and investigate whether it carries any <code>INI=</code> statement. If so the <abbr title="File with the extension 'ini' containing configuration data">INI</abbr> file specified this way should take precedence over any other <abbr title="File with the extension 'ini' containing configuration data">INI</abbr> file. However, we keep it simple here.</p>

diff --git a/HTML/06-Debugging-EXEs.html b/HTML/06-Debugging-EXEs.html
@@ -1,5 +1,5 @@
 <!DOCTYPE html>
-<html lang="en" style="scroll-behavior:smooth" >
+<html lang="en">
 <head>
 <meta http-equiv="X-UA-Compatible" content="IE=edge">
 <meta charset="utf-8">
@@ -105,6 +105,7 @@ <h2>Going for a ride</h2>
 <p>If that's something you need to avoid, you have to find other ways to make the <abbr title="Executable file with the extension 'exe'">EXE</abbr> communicate with Ride, perhaps by making temporary changes to the code.</p>
 <p>The approach would be the same in both cases. In MyApp we keep things simple and allow the <abbr title="File with the extension 'ini' containing configuration data">INI</abbr> file to rule whether the user may ride into the application or not.</p>
 <p>Copy <code>Z:\code\v05</code> to <code>Z:\code\v06</code> and then run the <abbr title="File with the extension 'dyapp' that contains 'Load' and 'Run' commands in order to put together an APL application">DYAPP</abbr> to recreate the <code>MyApp</code> workspace.</p>
+
 <div class="leanpub">
 <img src="https://download.aplwiki.com/LeanPub/Images/information.png" alt="Information">
 <div>
@@ -248,6 +249,7 @@ <h2>DLLs required by Ride</h2>
 <p>Since 3.0 Conga can serve several applications in parallel. We suggest you copy the 32-bit and the 64-bit DLLs as siblings of your <abbr title="Executable file with the extension 'exe'">EXE</abbr>.</p>
 <p>If you forgot to copy the DLLs you will see an error <em>Can't find Conga DLL</em>. This is because the OS does not bother to tell you about dependencies.</p>
 <p>You need a tool like DependencyWalker for finding out exactly what’s missing. (We said <em>OS</em> because this is <em>not</em> a Windows-only problem.)</p>
+
 <div class="leanpub_A">
 <h3>Restartable functions</h3>
 <p>Not only do we try to exit functions at the bottom, we also like them to be restartable.</p>

diff --git a/HTML/07-Handling-errors.html b/HTML/07-Handling-errors.html
@@ -1,5 +1,5 @@
 <!DOCTYPE html>
-<html lang="en" style="scroll-behavior:smooth" >
+<html lang="en">
 <head>
 <meta http-equiv="X-UA-Compatible" content="IE=edge">
 <meta charset="utf-8">
@@ -165,6 +165,7 @@ <h2>Foreseen errors</h2>
 <pre><code>      EXIT.GetName EXIT.INVALID_SOURCE
 INVALID_SOURCE</code></pre>
 <p>This is useful when we want to log an error code: the name is telling while the number is meaningless.</p>
+
 <div class="leanpub">
 <img src="https://download.aplwiki.com/LeanPub/Images/information.png" alt="Information">
 <div>
@@ -205,6 +206,7 @@ <h3>The function <code>Off</code></h3>
       ⎕OFF exitCode
   :EndIf
 ∇</code></pre>
+
 <div class="leanpub">
 <img src="https://download.aplwiki.com/LeanPub/Images/information.png" alt="Information">
 <div>
@@ -311,6 +313,7 @@ <h3>Trapping errors</h3>
   r,←E.FILE_SYSTEM_NO_SPACE
   r,←E.FILE_ACCESS_ERROR_CONVERTING_FILE
 ∇</code></pre>
+
 <div class="leanpub_A">
 <h3>Why don’t we just <code>:Trap</code> all errors?</h3>
 <p><code>:Trap 0</code> would trap all errors - way easier to read and write, so why don’t we do this?</p>
@@ -352,6 +355,7 @@ <h3>Why don’t we just <code>:Trap</code> all errors?</h3>
 </span>      :EndIf
     ∇</code></pre>
 <p>Note that the exit code is tested against <code>EXIT.OK</code>. Testing <code>0=exit</code> would work and read as well, but relies on <code>EXIT.OK</code> being 0. The point of defining the codes in <code>EXIT</code> is to make the functions relate to the exit codes only by their names.</p>
+
 <div class="leanpub_A">
 <h3>Logging file-related errors</h3>
 <p>Logging errors related to files in a real-world application requires more attention to detail: <code>⎕DMX</code> provides more information that can be very useful:</p>
@@ -383,6 +387,7 @@ <h3>Global trapping</h3>
 <span class="leanpub_code">    APPLICATION_CRASHED←104
 </span>    INVALID_SOURCE←111
     ...</code></pre>
+
 <div class="leanpub">
 <img src="https://download.aplwiki.com/LeanPub/Images/information.png" alt="Information">
 <div>
@@ -511,6 +516,7 @@ <h3>Test the global trap</h3>
 <li>An open edit or trace window</li>
 <li>More than one thread running at the moment of the crash</li>
 </ul>
+
 <div class="leanpub_A">
 <p>This is not strictly true. When <code>HandleError</code> detects multiple threads it tries to kill all of them. By definition that won’t work because (a) it cannot kill the main thread (0) and (b) it cannot kill its own thread.</p>
 <p>However, if it happens to run in the main thread at that very moment it will get rid of all other running threads and be able to save a crash workspace afterwards as a result.</p>
@@ -522,8 +528,8 @@ <h3>Test the global trap</h3>
 <p>We also find evidence in the log file that something broke; see LogDog:</p>
 <p><img src="Images/LogDog2.png" alt="The log file" title="The log file"></p>
 <p>This is done for us automatically by the <code>HandleError</code> class because we provided the name of a logging function, and a ref pointing to the instance where that log function lives.</p>
-<p>We also have an HTM with a crash report, an eponymous <abbr title="Dyalog workspace">DWS</abbr> containing the workspace saved at the time it broke, and an eponymous DCF whose single component is a namespace of all the variables visible at the moment of the crash. Some of this has got to help.</p>
-<p>Note that the crash file names are simply the WSID and the timestamp prefixed by an underscore:</p>
+<p>We also have an HTM with a crash report, an eponymous <abbr title="Dyalog workspace">D<abbr title="Short for Workspaces">WS</abbr></abbr> containing the workspace saved at the time it broke, and an eponymous DCF whose single component is a namespace of all the variables visible at the moment of the crash. Some of this has got to help.</p>
+<p>Note that the crash file names are simply the <abbr title="Short for Workspaces">WS</abbr>ID and the timestamp prefixed by an underscore:</p>
 <pre><code>      ⍪{⊃,/1↓⎕NPARTS⍵}¨⊃#.FilesAndDirs.Dir #.ErrorParms.errorFolder,'\'
  MyApp_20170307111141.dcf
  MyApp_20170307111141.dws
@@ -599,7 +605,7 @@ <h3>The crash files</h3>
 isDev
 tbl
 tgt</code></pre>
-<p>The <abbr title="Dyalog workspace">DWS</abbr> is the crash workspace. Load it. The Latent Expression has been disabled to ensure <code>MyApp</code> does not attempt to start up again.</p>
+<p>The <abbr title="Dyalog workspace">D<abbr title="Short for Workspaces">WS</abbr></abbr> is the crash workspace. Load it. The Latent Expression has been disabled to ensure <code>MyApp</code> does not attempt to start up again.</p>
 <pre><code>      ⎕LX
 ⎕TRAP←0 'S' ⍝#.MyApp.StartFromCmdLine</code></pre>
 <p>The state indicator shows the workspace captured at the moment the <code>HandleError</code> object saved the workspace. Your real problem – the full stop in <code>MyApp.TxtToCsv</code> – is some levels down in the stack.</p>
@@ -669,6 +675,7 @@ <h3>Very early errors</h3>
 </span>  #.⎕SHADOW'ErrorParms'
   ....</code></pre>
 <p>Note that we use the <code>SetTrap</code> function in <code>HandleError</code>. It accepts a parameter space as right argument, but it also accepts an empty vector, when it falls back to the defaults.</p>
+
 <div class="leanpub_A">
 <h3>Resetting the diagnostic message and the event number</h3>
 <p>We take the opportunity to initialize both <code>⎕DM</code> and <code>⎕EN</code>: with <code>⎕SIGNAL 0</code> we ensure</p>
@@ -683,7 +690,7 @@ <h3>Resetting the diagnostic message and the event number</h3>
 2
      ⎕SIGNAL 0
      ⎕DM
-&nbsp;
+
      ⎕EN
 0</code></pre>
 </div>