Skip to content

Commit

Permalink
HTML folder added
Browse files Browse the repository at this point in the history
  • Loading branch information
@aplteam
aplteam committed Feb 25, 2018
1 parent e0bee32 commit 7f721b0
Show file tree
Hide file tree
Showing 81 changed files with 23,860 additions and 289 deletions.
24 changes: 24 additions & 0 deletions .gitignore
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
# Exclude all this:

# LOGs
*.log

# EXEs, APLCOREs, ZIPs
aplcore
*.exe
*.zip

# URLs, DLLs
*.url
*.dll

# crash files, reports
code/v??/*.dcf
code/v??/*.html
code/v??/Errors/*.dcf
code/v??/Errors/*.dws
code/v??/Errors/*.html
code/v???/*

# these folders
manuscript/images/originals
186 changes: 186 additions & 0 deletions HTML/01 Introduction.html
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,186 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta charset="utf-8">
<title>Introduction</title>
<link href="./CSS/BlackOnWhite_screen.css" rel="stylesheet" media="screen">
<link href="./CSS/Cookbook_Chapter_screen.css" rel="stylesheet" media="screen">
<link href="./CSS/snap.css" rel="stylesheet" media="screen">
<link href="./CSS/BlackOnWhite_print.css" rel="stylesheet" media="print">
<link href="./CSS/Cookbook_Chapter_print.css" rel="stylesheet" media="print">
<script src="./JavaScript/snap.js"></script>
</head>
<body>
<div class="snap-drawers">
<div class="snap-drawer snap-drawer-left">
<div class="h_tag">
<h3>Chapters</h3>
</div>
<ol>
<li><a href="./01%20Introduction.html" class="external_link">Introduction</a></li>
<li><a href="./02%20Structure.html" class="external_link">Structure</a></li>
<li><a href="./03%20Package%20MyApp%20as%20an%20executable.html" class="external_link">Package MyApp as an executable</a></li>
<li><a href="./04%20Logging%20what%20happens%20.html" class="external_link">Logging what happens </a></li>
<li><a href="./05%20Configuration%20settings.html" class="external_link">Configuration settings</a></li>
<li><a href="./06%20Debugging%20a%20stand-alone%20EXE.html" class="external_link">Debugging a stand-alone EXE</a></li>
<li><a href="./07%20Handling%20errors.html" class="external_link">Handling errors</a></li>
<li><a href="./08%20Testing%20—%20the%20sound%20of%20breaking%20glass.html" class="external_link">Testing<br>The sound of breaking glass</a></li>
<li><a href="./09%20Documentation%20—%20the%20Doc%20is%20in.html" class="external_link">Documentation<br>The Doc is in</a></li>
<li><a href="./10%20Make%20me.html" class="external_link">Make me</a></li>
<li><a href="./11%20Providing%20help.html" class="external_link">Providing help</a></li>
<li><a href="./12%20Scheduled%20Tasks.html" class="external_link">Scheduled Tasks</a></li>
<li><a href="./13%20Windows%20Services.html" class="external_link">Windows Services</a></li>
<li><a href="./14%20The%20Windows%20Event%20Log.html" class="external_link">The Windows Event Log</a></li>
<li><a href="./15%20The%20Windows%20Registry.html" class="external_link">The Windows Registry</a></li>
<li><a href="./16%20Creating%20SetUp.exe%20with%20Inno.html" class="external_link">Creating SetUp.exe with Inno</a></li>
<li><a href="./17%20RegularExpressions.html" class="external_link">RegularExpressions</a></li>
<li><a href="./18%20GUI.html" class="external_link">GUI</a></li>
</ol>
<div class="h_tag">
<h3>Appendices</h3>
</div>
<ol>
<li><a href="./50%20Appendix%201%20—%20Windows%20environment%20variables.html" class="external_link">Windows environment variables</a></li>
<li><a href="./51%20Appendix%202%20—%20User%20commands.html" class="external_link">User commands</a></li>
<li><a href="./52%20Appendix%203%20—%20aplcores%20and%20WS%20integrity.html" class="external_link">aplcores and WS integrity</a></li>
<li><a href="./53%20Appendix%204%20—%20The%20development%20environment.html" class="external_link">The development environment</a></li>
<li><a href="./54%20Appendix%205%20—%20Special%20characters.html" class="external_link">Special characters</a></li>
</ol>
<div class="h_tag">
<h3>Misc</h3>
</div>
<ul>
<li><a title="There is no previous chapter" class="inactive">Previous chapter</a></li>
<li><a href="02%20Structure.html">Next chapter;</a></li>
<li><a href="./Dyalog_Cookbook.html" class="external_link">Single document<br>(All chapters, for printing)</a></li>
</ul>
</div>
</div>
<div id="mainmenu">
<a href=#><p><span id="mainmenu_match">≡</span></p></a>
<p><span id="mainmenu_title">The Dyalog Cookbook</span></p>
<nav id="main_nav">
<input type="checkbox" id="hide_toc">
<label id="hide_toc_label" for="hide_toc"></label>
<div class="toc-container">
<ul>
<li><a href="#Method">Method</a></li>
<li><a href="#What-you-need-to-use-the-Dyalog-Cookbook">What you need to use the Dyalog Cookbook</a></li>
<li><a href="#Conventions">Conventions</a></li>
<li><a href="#Acknowledgements">Acknowledgements</a>
</ul>
</div>
</nav>
</div>
<div id="content" class="snap-content">
<div id="cookbook_content">
<div class="h_tag">
<a href="#1-Introduction" id="1-Introduction" class="autoheader_anchor">
<h1>1. Introduction</h1>
</a>
</div>
<p>You want to write a Windows [<a href="#fnref1" class="footnote_link"><sup>1</sup></a>] application in Dyalog APL. You have already learned enough of the language to put some of your specialist knowledge into functions you can use in your work. The code works for you. Now you want to turn it into an application others can use. Perhaps even sell it.</p>
<p>This is where you need professional programming skills. How to install your code into an unknown computer. Have it catch, handle and log errors. Manage the different versions of your software as it evolves. Provide online help.</p>
<p>You are not necessarily a professional programmer. Perhaps you don't have those skills. Perhaps you need a professional programmer to turn your code into an application. But you’ve come a long way already. Perhaps you can get there by yourself - with <em>The Dyalog Cookbook</em>. Alternatively, you might be a professional programmer wondering how to solve these familiar problems in Dyalog APL.</p>
<p><em>The Dyalog Cookbook</em> is about how to turn your Dyalog code into an application. We’ll cover packaging your code into a robust environment. And we’ll introduce some software development tools you’ve managed without so far, which will make your life easier.</p>
<p>You might continue as the sole developer of your application for a long time yet. But if it becomes a successful product you will eventually want other programmers collaborating on it. So we’ll set up your code in a source-control system that will accommodate that. Even while you remain a sole developer, a source-control system will also allow you to roll back and recover from your own mistakes.</p>
<p>Not so long ago it was sufficient for an application to be packaged as an <abbr title="Executable file with the extension 'exe'">EXE</abbr> that could be installed and run on other PCs. Nowadays many corporate clients run programs in terminal servers or in private clouds. So we’ll look at how to organise your program to run as tasks that communicate with each other.</p>
<p>Many applications written in Dyalog focus on some kind of numerical analysis, and can have CPU-intensive tasks. We'll look at how such tasks can be packaged to run either in background or on remote machines.</p>
<div class="h_tag">
<a href="#Method" id="Method" class="autoheader_anchor">
<h2>Method</h2>
</a>
</div>
<p>It’s conventional in this context for authors to assure readers that the techniques expounded here have been hammered out, proven and tested in many successful applications. That is true of individual components here, particularly of scripts and applications from the APLTree [<a href="#fnref2" class="footnote_link"><sup>2</sup></a>] library.</p>
<p>But the development tools introduced by Dyalog in recent years are still finding their places with development teams. Some appear here in print for the first time. This book is the first sustained attempt to combine all the current Dyalog tools into an integrated approach.</p>
<p>Many of the issues addressed here are entangled with each other. We’ll arrive at our best solutions by way of interim solutions. Proposing some wickedly intricate ‘complete solution’ framework does little to illuminate the problems it solves. So we’ll add features – <abbr title="File with the extension 'ini' containing configuration data">INI</abbr> files, error handling, and so on – one at a time, and as we go we’ll find ourselves revisiting the code that embeds the earlier features.</p>
<p>We will also improve the code along the way, while explaining why exactly the changes are improvements.</p>
<p>That is the method for chapters 1 – 14. Later chapters stand on their own.</p>
<p>If you are an experienced Dyalog developer, you may be able to improve on what is described here. For this reason <em>The Dyalog Cookbook</em> remains for now <a href="https://github.com/5jt/dyalog-cookbook" class="external_link">an open-source project on GitHub</a>.</p>
<p>Working through the book, you get to understand how the implementation issues, and the solutions to them, work. In the first chapters you will find ‘framework’ code for your application, growing more complex as the book progresses. You can find scripts for these interim versions in the <code>code</code> folder on the book website. Watch out: they are <em>interim</em> solutions, constantly improved along the way.</p>
<p>You are of course welcome simply to copy and use the last version of the scripts. But there is much to be learned while stumbling.</p>
<p>Later on we’ll introduce some professional writing techniques that might make maintaining your code easier – in what we hope will be a long useful future for it. This includes third-party tools, configuring your development environment and discussing user commands.</p>
<div class="h_tag">
<a href="#What-you-need-to-use-the-Dyalog-Cookbook" id="What-you-need-to-use-the-Dyalog-Cookbook" class="autoheader_anchor">
<h2>What you need to use the Dyalog Cookbook</h2>
</a>
</div>
<ul>
<li>The Dyalog Version 16.0 Unicode interpreter or later.</li>
<li>Microsoft Windows 10</li>
<li>Good knowledge of APL – the Cookbook is by no means an introduction.</li>
<li>To know how to use namespaces, classes and instances. The utility code in the Cookbook is packaged as namespaces and classes. This is the form in which it is easiest for you to slide the code into your app without name conflicts.
<p>We recommend you use classes to organise your own code [<a href="#fnref3" class="footnote_link"><sup>3</sup></a>]. But even if you don’t, you need to know at least how to use classes. This is a deep subject, but all you need to know is the basics: how to call the static methods of a class (sufficient in most cases) or how to create an instance of a class and use its methods and properties.</p>
<p>See <em>Dyalog Programmer’s Reference Guide</em> for an introduction.</p></li>
<li>A good understanding of SALT, Dyalog’s built-in code-management system that allows you to load and save scripts either automatically in the background or at will.</li>
<li>Internet access. Not necessarily all the time, but probably most of the time. Not only because it gives you access to the <a href="http://aplwiki.com" class="external_link">APL wiki</a> and the Dyalog forum (see below) but mainly for accessing the APLTree tools and this book’s web site: <a href="https://cookbook.dyalog.com" class="external_link">https://cookbook.dyalog.com</a>.
<p>However, we have also tried to write the book so that you can just read it – if that works better for you.</p></li>
</ul>
<p>We have not attempted to ‘dumb down’ our use of the language for readers with less experience. In some cases we stop to discuss linguistic features; mostly not.</p>
<p>If you see an expression you cannot read, a little experimentation and consultation of the reference material should show you how it works.</p>
<p>But we have not tried to be smart either. Code should be as terse as reasonable, but should always be readable, maintainable and traceable.</p>
<p>We encourage you to take the time to do this. Generally speaking – not invariably – short, crisp expressions are less work for you and the interpreter to read. Learn them and prefer them.</p>
<p>In case you still need help the <a href="http://forum.dyalog.com" class="external_link">Dyalog Forum</a> provides access to a competent and friendly community around Dyalog.</p>
<div class="h_tag">
<a href="#Conventions" id="Conventions" class="autoheader_anchor">
<h2>Conventions</h2>
</a>
</div>

<div class="leanpub">
<img src="https://download.aplwiki.com/LeanPub/Images/information.png" alt="Information">
<div>
<p>Note that we assume <code>⎕IO←1</code> and <code>⎕ML←1</code>, not because we are making a statement, but because that’s the Dyalog default. That keeps the Cookbook in sync with the Dyalog documentation.</p>
</div>
</div>

<div class="leanpub_A">
<h3>Getting deeper</h3>
<p>In case we want to discuss a particular issue in more detail but we are not sure whether the reader is ready for this, now or ever, we format the information this way.</p>
</div>

<div class="leanpub">
<img src="https://download.aplwiki.com/LeanPub/Images/warning.png" alt="Warning">
<div>
<p>Sometimes we need to warn you, for example in order to avoid common traps. This is how that would look like.</p>
</div>
</div>

<div class="leanpub">
<img src="https://download.aplwiki.com/LeanPub/Images/tip.png" alt="Tip">
<div>
<p>Sometimes we want to provide a tip, and this is how that looks.</p>
</div>
</div>

<p>When we refer to a text file, e.g. something with the extension <code>.txt</code>, we refer to it as a <abbr title="File with the extension 'txt' containing text">TXT</abbr>. We refer to a dyalog script (<code>*.dyalog</code>) as a <abbr title="File with the extension 'dyalog' holding APL code">DYALOG</abbr>. We refer to a dyapp script (<code>*.dyapp</code>) as a <abbr title="File with the extension 'dyapp' that contains 'Load' and 'Run' commands in order to put together an APL application">DYAPP</abbr>. You get the pattern.</p>
<div class="h_tag">
<a href="#Acknowledgements" id="Acknowledgements" class="autoheader_anchor">
<h2>Acknowledgements</h2>
</a>
</div>
<p>We are deeply grateful for contributions, ideas, comments and outright help from our colleagues, particularly from (in alphabetical order) Gil Athoraya, Morten Kromberg, Paul Mansour, Nick Nickolov, Andy Shiers and Richard Smith.</p>
<p>We jealously claim any errors as entirely our own work.</p>
<p>Kai Jaeger &amp; Stephen Taylor</p>
<div id="footnotes_div">
<hr>
<p><strong>Footnotes</strong></p>
<ol>
<li id="fnref1"><p>Perhaps one day you would like it to ship on multiple platforms. Perhaps one day we’ll write that book too. Meanwhile, Microsoft Windows.</p><p>You will however find that whenever possible we keep the code platform independent. If we use platform-dependent utilities we mention it and explain why; we might also mention alternatives available on other platforms.</p><a href="#fnref1" class="footnote_anchor"></a>
<li id="fnref2"><p><em>APLTree</em> is the name of an open-source library that offers robust, tested and well documented solutions to many everyday problems you face when addressing the tasks discussed in this book.</p><p>We will use this library extensively and discuss it in detail. More at the source:<br><a href="https://aplteam.github.io/apltree" class="external_link">https://aplteam.github.io/apltree</a>. You can also search for “apltree” on <a href="https://github.com" class="external_link">GitHub</a>.</p><a href="#fnref2" class="footnote_anchor"></a>
<li id="fnref3"><p>These days seasoned programmers often have strong opinions about whether to use an object-oriented approach or a functional approach, or to mix them both.</p><p>We have seen friendships broken on these issues. In this book we take a mixed approach.</p><a href="#fnref3" class="footnote_anchor"></a>
</ol>
</div>
</div>
</div>
<script>
var snapper = new Snap({
element: document.getElementById('content')
});
document.getElementById('mainmenu_match').onclick = function(){
snapper.state().state==='closed'?snapper.open('left'):snapper.close();
}
</script>
</body>
</html>
Loading

0 comments on commit 7f721b0

Please sign in to comment.