Changing title

software-tools-books · Jan 30, 2022 · fcab986 · fcab986
1 parent 7b58bb0
commit fcab986
Show file tree

Hide file tree

Showing 35 changed files with 103 additions and 64 deletions.
diff --git a/README.md b/README.md
@@ -1,4 +1,5 @@
-# Software Tools in JavaScript
+# Software Design by Example
+## A Tool-Based Introduction with JavaScript
 
 The best way to learn design in any field is to study examples,
 and some of the best examples of software design come from the tools programmers use in their own work.
@@ -24,11 +25,13 @@ for more information about what we assume you already know.
     [the acknowledgments](https://stjs.tech/#who-helped-us-and-inspired-us);
     anyone who writes a chapter will be added to [the authors' list](https://stjs.tech/authors/).
 
+Note: this book was originally titled *Software Tools in JavaScript*.
+The title has been changed to better reflect its content and intention.
+
 ## FAQ
 
 -   **Is this done yet?**
-    No: what we have now is the first complete draft,
-    but we think it's in a reviewable state.
+    Almost: what we have now is a complete, usable draft.
 
 -   **Why did you start this project?**
     Because most books with the words "software design" or "software architecture" in their titles
@@ -76,6 +79,11 @@ for more information about what we assume you already know.
         at the third- or fourth-year level.
         Students can tackle the exercises at the end of each chapter
         or write and explain small tools of their own.
+    3.  If you're interested, I'm very happy to chat.
+        I'm also happy to give a guest lecture in your software engineering class
+	about software design,
+	[how to run a meeting](https://www.youtube.com/watch?v=PtewOjRy-1U),
+	and/or life in industry.
 
 -   **Do you want a chapter on X?**
     Possibly:
@@ -87,3 +95,17 @@ for more information about what we assume you already know.
     an issue tracker,
     and so on.
     If you are interested, please [get in touch](mailto:gvwilson@third-bit.com).
+
+-   **Why are you using your own formatting tool?**
+    Believe me, I've tried the alternatives.
+    Static site generators like Jekyll, Pelican, and Hugo don't support numbered cross-references,
+    so I've built several pre-processors to collect that information;
+    by the time that's done,
+    taking full control over the formatting pipeline actually reduces complexity.
+    Meanwhile, tools like Bookdown and Jupyter Book have complex tech stacks:
+    figuring out whether a problem is in the source document,
+    a Pandoc template,
+    a LaTeX template,
+    or somewhere else entirely is very frustrating.
+    [McCole](https://gvwilson.github.io/mccole/) doesn't do nearly as much as those tools,
+    but its lack of features makes it easier to use.
diff --git a/_template/index.html b/_template/index.html
@@ -8,6 +8,7 @@
   <body>
     <main>
       <h1>{site.title()}</h1>
+      {site.subtitle()}
       {page.content()}
       <nav>
 	{site.toc()}

diff --git a/docs/async-programming/index.html b/docs/async-programming/index.html
@@ -7,11 +7,11 @@
 <script defer data-domain="stjs.tech" src="https://plausible.io/js/plausible.js"></script>
 
     <link href="../static/mccole.css" rel="stylesheet" type="text/css">
-    <title>Software Tools in JavaScript: <h1 id="async-programming">Asynchronous Programming</h1></title>
+    <title>Software Design by Example: <h1 id="async-programming">Asynchronous Programming</h1></title>
   </head>
   <body>
     <main>
-      <p class="home"><a href="../">Software Tools in JavaScript</a></p>
+      <p class="home"><a href="../">Software Design by Example</a></p>
       <h1 id="async-programming">Asynchronous Programming</h1>
       <div class="lede"><p>Using promises to manage delayed computation</p></div>
       <nav>

diff --git a/docs/authors/index.html b/docs/authors/index.html
@@ -7,11 +7,11 @@
 <script defer data-domain="stjs.tech" src="https://plausible.io/js/plausible.js"></script>
 
     <link href="../static/mccole.css" rel="stylesheet" type="text/css">
-    <title>Software Tools in JavaScript: <h1 id="authors">Authors</h1></title>
+    <title>Software Design by Example: <h1 id="authors">Authors</h1></title>
   </head>
   <body>
     <main>
-      <p class="home"><a href="../">Software Tools in JavaScript</a></p>
+      <p class="home"><a href="../">Software Design by Example</a></p>
       <h1 id="authors">Authors</h1>
 
       <nav>

diff --git a/docs/bibliography/index.html b/docs/bibliography/index.html
@@ -7,11 +7,11 @@
 <script defer data-domain="stjs.tech" src="https://plausible.io/js/plausible.js"></script>
 
     <link href="../static/mccole.css" rel="stylesheet" type="text/css">
-    <title>Software Tools in JavaScript: <h1 id="bibliography">Bibliography</h1></title>
+    <title>Software Design by Example: <h1 id="bibliography">Bibliography</h1></title>
   </head>
   <body>
     <main>
-      <p class="home"><a href="../">Software Tools in JavaScript</a></p>
+      <p class="home"><a href="../">Software Design by Example</a></p>
       <h1 id="bibliography">Bibliography</h1>
       <div class="bibliography">
 <p id="Binkley2012" class="bib"><span class="bibkey">Binkley2012</span>: <span class="bibentry">Dave Binkley, Marcia Davis, Dawn Lawrie, Jonathan I. Maletic, Christopher Morrell, and Bonita Sharif: "The Impact of Identifier Style on Effort and Comprehension". <em>ESE</em>, 18(2), 2012, , <a href="https://doi.org/10.1007/s10664-012-9201-4">10.1007/s10664-012-9201-4</a>.</span></p>

diff --git a/docs/build-manager/index.html b/docs/build-manager/index.html
@@ -7,11 +7,11 @@
 <script defer data-domain="stjs.tech" src="https://plausible.io/js/plausible.js"></script>
 
     <link href="../static/mccole.css" rel="stylesheet" type="text/css">
-    <title>Software Tools in JavaScript: <h1 id="build-manager">Build Manager</h1></title>
+    <title>Software Design by Example: <h1 id="build-manager">Build Manager</h1></title>
   </head>
   <body>
     <main>
-      <p class="home"><a href="../">Software Tools in JavaScript</a></p>
+      <p class="home"><a href="../">Software Design by Example</a></p>
       <h1 id="build-manager">Build Manager</h1>
       <div class="lede"><p>Updating files that depend on other files</p></div>
       <nav>

diff --git a/docs/code-generator/index.html b/docs/code-generator/index.html
@@ -7,11 +7,11 @@
 <script defer data-domain="stjs.tech" src="https://plausible.io/js/plausible.js"></script>
 
     <link href="../static/mccole.css" rel="stylesheet" type="text/css">
-    <title>Software Tools in JavaScript: <h1 id="code-generator">Code Generator</h1></title>
+    <title>Software Design by Example: <h1 id="code-generator">Code Generator</h1></title>
   </head>
   <body>
     <main>
-      <p class="home"><a href="../">Software Tools in JavaScript</a></p>
+      <p class="home"><a href="../">Software Design by Example</a></p>
       <h1 id="code-generator">Code Generator</h1>
       <div class="lede"><p>Modifying code to track coverage and execution times</p></div>
       <nav>

diff --git a/docs/conclusion/index.html b/docs/conclusion/index.html
@@ -7,11 +7,11 @@
 <script defer data-domain="stjs.tech" src="https://plausible.io/js/plausible.js"></script>
 
     <link href="../static/mccole.css" rel="stylesheet" type="text/css">
-    <title>Software Tools in JavaScript: <h1 id="conclusion">Conclusion</h1></title>
+    <title>Software Design by Example: <h1 id="conclusion">Conclusion</h1></title>
   </head>
   <body>
     <main>
-      <p class="home"><a href="../">Software Tools in JavaScript</a></p>
+      <p class="home"><a href="../">Software Design by Example</a></p>
       <h1 id="conclusion">Conclusion</h1>
       <div class="lede"><p>Where we have been and where you could go next</p></div>
       <nav>

diff --git a/docs/conduct/index.html b/docs/conduct/index.html
@@ -7,11 +7,11 @@
 <script defer data-domain="stjs.tech" src="https://plausible.io/js/plausible.js"></script>
 
     <link href="../static/mccole.css" rel="stylesheet" type="text/css">
-    <title>Software Tools in JavaScript: <h1 id="conduct">Code of Conduct</h1></title>
+    <title>Software Design by Example: <h1 id="conduct">Code of Conduct</h1></title>
   </head>
   <body>
     <main>
-      <p class="home"><a href="../">Software Tools in JavaScript</a></p>
+      <p class="home"><a href="../">Software Design by Example</a></p>
 
 <h1>Code of Conduct</h1>
 <p>In the interest of fostering an open and welcoming environment, we as

diff --git a/docs/contributing/index.html b/docs/contributing/index.html
@@ -7,11 +7,11 @@
 <script defer data-domain="stjs.tech" src="https://plausible.io/js/plausible.js"></script>
 
     <link href="../static/mccole.css" rel="stylesheet" type="text/css">
-    <title>Software Tools in JavaScript: <h1 id="contributing">Contributing</h1></title>
+    <title>Software Design by Example: <h1 id="contributing">Contributing</h1></title>
   </head>
   <body>
     <main>
-      <p class="home"><a href="../">Software Tools in JavaScript</a></p>
+      <p class="home"><a href="../">Software Design by Example</a></p>
 
 <h1>Contributing</h1>
 <p>All contributors must abide by our <span i="Code of Conduct">Code of Conduct</span>.</p>

diff --git a/docs/data-table/index.html b/docs/data-table/index.html
@@ -7,11 +7,11 @@
 <script defer data-domain="stjs.tech" src="https://plausible.io/js/plausible.js"></script>
 
     <link href="../static/mccole.css" rel="stylesheet" type="text/css">
-    <title>Software Tools in JavaScript: <h1 id="data-table">Data Tables</h1></title>
+    <title>Software Design by Example: <h1 id="data-table">Data Tables</h1></title>
   </head>
   <body>
     <main>
-      <p class="home"><a href="../">Software Tools in JavaScript</a></p>
+      <p class="home"><a href="../">Software Design by Example</a></p>
       <h1 id="data-table">Data Tables</h1>
       <div class="lede"><p>Storing and manipulating tables efficiently</p></div>
       <nav>

diff --git a/docs/debugger/index.html b/docs/debugger/index.html
@@ -7,11 +7,11 @@
 <script defer data-domain="stjs.tech" src="https://plausible.io/js/plausible.js"></script>
 
     <link href="../static/mccole.css" rel="stylesheet" type="text/css">
-    <title>Software Tools in JavaScript: <h1 id="debugger">Debugger</h1></title>
+    <title>Software Design by Example: <h1 id="debugger">Debugger</h1></title>
   </head>
   <body>
     <main>
-      <p class="home"><a href="../">Software Tools in JavaScript</a></p>
+      <p class="home"><a href="../">Software Design by Example</a></p>
       <h1 id="debugger">Debugger</h1>
       <div class="lede"><p>Running programs under the control of a breakpointing debugger</p></div>
       <nav>

diff --git a/docs/doc-generator/index.html b/docs/doc-generator/index.html
@@ -7,11 +7,11 @@
 <script defer data-domain="stjs.tech" src="https://plausible.io/js/plausible.js"></script>
 
     <link href="../static/mccole.css" rel="stylesheet" type="text/css">
-    <title>Software Tools in JavaScript: <h1 id="doc-generator">Documentation Generator</h1></title>
+    <title>Software Design by Example: <h1 id="doc-generator">Documentation Generator</h1></title>
   </head>
   <body>
     <main>
-      <p class="home"><a href="../">Software Tools in JavaScript</a></p>
+      <p class="home"><a href="../">Software Design by Example</a></p>
       <h1 id="doc-generator">Documentation Generator</h1>
       <div class="lede"><p>Generating documentation from comments embedded in code</p></div>
       <nav>

diff --git a/docs/file-backup/index.html b/docs/file-backup/index.html
@@ -7,11 +7,11 @@
 <script defer data-domain="stjs.tech" src="https://plausible.io/js/plausible.js"></script>
 
     <link href="../static/mccole.css" rel="stylesheet" type="text/css">
-    <title>Software Tools in JavaScript: <h1 id="file-backup">File Backup</h1></title>
+    <title>Software Design by Example: <h1 id="file-backup">File Backup</h1></title>
   </head>
   <body>
     <main>
-      <p class="home"><a href="../">Software Tools in JavaScript</a></p>
+      <p class="home"><a href="../">Software Design by Example</a></p>
       <h1 id="file-backup">File Backup</h1>
       <div class="lede"><p>Archiving files with directory structure</p></div>
       <nav>

diff --git a/docs/file-interpolator/index.html b/docs/file-interpolator/index.html
@@ -7,11 +7,11 @@
 <script defer data-domain="stjs.tech" src="https://plausible.io/js/plausible.js"></script>
 
     <link href="../static/mccole.css" rel="stylesheet" type="text/css">
-    <title>Software Tools in JavaScript: <h1 id="file-interpolator">File Interpolator</h1></title>
+    <title>Software Design by Example: <h1 id="file-interpolator">File Interpolator</h1></title>
   </head>
   <body>
     <main>
-      <p class="home"><a href="../">Software Tools in JavaScript</a></p>
+      <p class="home"><a href="../">Software Design by Example</a></p>
       <h1 id="file-interpolator">File Interpolator</h1>
       <div class="lede"><p>Managing source files that have been broken into pieces</p></div>
       <nav>

diff --git a/docs/glossary/index.html b/docs/glossary/index.html
@@ -7,11 +7,11 @@
 <script defer data-domain="stjs.tech" src="https://plausible.io/js/plausible.js"></script>
 
     <link href="../static/mccole.css" rel="stylesheet" type="text/css">
-    <title>Software Tools in JavaScript: <h1 id="glossary">Glossary</h1></title>
+    <title>Software Design by Example: <h1 id="glossary">Glossary</h1></title>
   </head>
   <body>
     <main>
-      <p class="home"><a href="../">Software Tools in JavaScript</a></p>
+      <p class="home"><a href="../">Software Design by Example</a></p>
       <h1 id="glossary">Glossary</h1>
       <dl>
 <dt><span class="glosskey" id="absolute_error">absolute error</span></dt>

diff --git a/docs/index.html b/docs/index.html
@@ -7,11 +7,12 @@
 <script defer data-domain="stjs.tech" src="https://plausible.io/js/plausible.js"></script>
 
     <link href="./static/mccole.css" rel="stylesheet" type="text/css">
-    <title>Software Tools in JavaScript</title>
+    <title>Software Design by Example</title>
   </head>
   <body>
     <main>
-      <h1>Software Tools in JavaScript</h1>
+      <h1>Software Design by Example</h1>
+      <h2 class="subtitle">A Tool-Based Introduction with JavaScript</h2>
       <div class="announcement">
   <p>
     <em>Software Tools in JavaScript</em>

diff --git a/docs/introduction/index.html b/docs/introduction/index.html
@@ -7,11 +7,11 @@
 <script defer data-domain="stjs.tech" src="https://plausible.io/js/plausible.js"></script>
 
     <link href="../static/mccole.css" rel="stylesheet" type="text/css">
-    <title>Software Tools in JavaScript: <h1 id="introduction">Introduction</h1></title>
+    <title>Software Design by Example: <h1 id="introduction">Introduction</h1></title>
   </head>
   <body>
     <main>
-      <p class="home"><a href="../">Software Tools in JavaScript</a></p>
+      <p class="home"><a href="../">Software Design by Example</a></p>
       <h1 id="introduction">Introduction</h1>
       <div class="lede"><p>Who you are and where we're going</p></div>
       <nav>

diff --git a/docs/layout-engine/index.html b/docs/layout-engine/index.html
@@ -7,11 +7,11 @@
 <script defer data-domain="stjs.tech" src="https://plausible.io/js/plausible.js"></script>
 
     <link href="../static/mccole.css" rel="stylesheet" type="text/css">
-    <title>Software Tools in JavaScript: <h1 id="layout-engine">Layout Engine</h1></title>
+    <title>Software Design by Example: <h1 id="layout-engine">Layout Engine</h1></title>
   </head>
   <body>
     <main>
-      <p class="home"><a href="../">Software Tools in JavaScript</a></p>
+      <p class="home"><a href="../">Software Design by Example</a></p>
       <h1 id="layout-engine">Layout Engine</h1>
       <div class="lede"><p>Figuring out what goes where in a web page</p></div>
       <nav>

diff --git a/docs/license/index.html b/docs/license/index.html
@@ -7,11 +7,11 @@
 <script defer data-domain="stjs.tech" src="https://plausible.io/js/plausible.js"></script>
 
     <link href="../static/mccole.css" rel="stylesheet" type="text/css">
-    <title>Software Tools in JavaScript: <h1 id="license">Licensing</h1></title>
+    <title>Software Design by Example: <h1 id="license">Licensing</h1></title>
   </head>
   <body>
     <main>
-      <p class="home"><a href="../">Software Tools in JavaScript</a></p>
+      <p class="home"><a href="../">Software Design by Example</a></p>
 
 <h1>License</h1>
 <p>All of the written material on this site is made available under the Creative

diff --git a/docs/links/index.html b/docs/links/index.html
@@ -7,11 +7,11 @@
 <script defer data-domain="stjs.tech" src="https://plausible.io/js/plausible.js"></script>
 
     <link href="../static/mccole.css" rel="stylesheet" type="text/css">
-    <title>Software Tools in JavaScript: <h1 id="links">Links</h1></title>
+    <title>Software Design by Example: <h1 id="links">Links</h1></title>
   </head>
   <body>
     <main>
-      <p class="home"><a href="../">Software Tools in JavaScript</a></p>
+      <p class="home"><a href="../">Software Design by Example</a></p>
       <h1 id="links">Links</h1>
       <table class="links">
 <tr><th>Title</th><th>URL</th></tr>

diff --git a/docs/module-bundler/index.html b/docs/module-bundler/index.html
@@ -7,11 +7,11 @@
 <script defer data-domain="stjs.tech" src="https://plausible.io/js/plausible.js"></script>
 
     <link href="../static/mccole.css" rel="stylesheet" type="text/css">
-    <title>Software Tools in JavaScript: <h1 id="module-bundler">Module Bundler</h1></title>
+    <title>Software Design by Example: <h1 id="module-bundler">Module Bundler</h1></title>
   </head>
   <body>
     <main>
-      <p class="home"><a href="../">Software Tools in JavaScript</a></p>
+      <p class="home"><a href="../">Software Design by Example</a></p>
       <h1 id="module-bundler">Module Bundler</h1>
       <div class="lede"><p>Turning many files into one</p></div>
       <nav>

diff --git a/docs/module-loader/index.html b/docs/module-loader/index.html
@@ -7,11 +7,11 @@
 <script defer data-domain="stjs.tech" src="https://plausible.io/js/plausible.js"></script>
 
     <link href="../static/mccole.css" rel="stylesheet" type="text/css">
-    <title>Software Tools in JavaScript: <h1 id="module-loader">Module Loader</h1></title>
+    <title>Software Design by Example: <h1 id="module-loader">Module Loader</h1></title>
   </head>
   <body>
     <main>
-      <p class="home"><a href="../">Software Tools in JavaScript</a></p>
+      <p class="home"><a href="../">Software Design by Example</a></p>
       <h1 id="module-loader">Module Loader</h1>
       <div class="lede"><p>Loading source files as modules</p></div>
       <nav>

diff --git a/docs/package-manager/index.html b/docs/package-manager/index.html
@@ -7,11 +7,11 @@
 <script defer data-domain="stjs.tech" src="https://plausible.io/js/plausible.js"></script>
 
     <link href="../static/mccole.css" rel="stylesheet" type="text/css">
-    <title>Software Tools in JavaScript: <h1 id="package-manager">Package Manager</h1></title>
+    <title>Software Design by Example: <h1 id="package-manager">Package Manager</h1></title>
   </head>
   <body>
     <main>
-      <p class="home"><a href="../">Software Tools in JavaScript</a></p>
+      <p class="home"><a href="../">Software Design by Example</a></p>
       <h1 id="package-manager">Package Manager</h1>
       <div class="lede"><p>Getting and installing packages</p></div>
       <nav>

diff --git a/docs/page-templates/index.html b/docs/page-templates/index.html
@@ -7,11 +7,11 @@
 <script defer data-domain="stjs.tech" src="https://plausible.io/js/plausible.js"></script>
 
     <link href="../static/mccole.css" rel="stylesheet" type="text/css">
-    <title>Software Tools in JavaScript: <h1 id="page-templates">Page Templates</h1></title>
+    <title>Software Design by Example: <h1 id="page-templates">Page Templates</h1></title>
   </head>
   <body>
     <main>
-      <p class="home"><a href="../">Software Tools in JavaScript</a></p>
+      <p class="home"><a href="../">Software Design by Example</a></p>
       <h1 id="page-templates">Page Templates</h1>
       <div class="lede"><p>Generating HTML pages from templates</p></div>
       <nav>

diff --git a/docs/pattern-matching/index.html b/docs/pattern-matching/index.html
@@ -7,11 +7,11 @@
 <script defer data-domain="stjs.tech" src="https://plausible.io/js/plausible.js"></script>
 
     <link href="../static/mccole.css" rel="stylesheet" type="text/css">
-    <title>Software Tools in JavaScript: <h1 id="pattern-matching">Pattern Matching</h1></title>
+    <title>Software Design by Example: <h1 id="pattern-matching">Pattern Matching</h1></title>
   </head>
   <body>
     <main>
-      <p class="home"><a href="../">Software Tools in JavaScript</a></p>
+      <p class="home"><a href="../">Software Design by Example</a></p>
       <h1 id="pattern-matching">Pattern Matching</h1>
       <div class="lede"><p>Using patterns to find things in data</p></div>
       <nav>