Removed article tags as they are not valid xhtml tags. Fixed `block…

…quote` tags by moving them outside of `p` tags and adding `p` tags to the content of `blockquote` when they were missing. Passes epubcheck 4.0.1. Fixes #3.
tmciver · Oct 25, 2015 · 6988fb4 · 6988fb4
1 parent 76e5667
commit 6988fb4
Show file tree

Hide file tree

Showing 15 changed files with 71 additions and 279 deletions.
diff --git a/Makefile b/Makefile
@@ -23,8 +23,8 @@ EPUB_FILES = 	mimetype \
 		OEBPS/figure2.png
 EPUB_ARCHIVE = out-of-the-tar-pit.epub
 
-#test : $(EPUB_ARCHIVE)
-#	java -jar lib/epubcheck-3.0.1.jar $(EPUB_ARCHIVE)
+# test : $(EPUB_ARCHIVE)
+# 	java -jar lib/epubcheck-4.0.1/epubcheck.jar $(EPUB_ARCHIVE)
 
 $(EPUB_ARCHIVE) : $(EPUB_FILES)
 	zip -X $@ $^

diff --git a/OEBPS/abstract.html b/OEBPS/abstract.html
@@ -10,12 +10,10 @@
   </head>
   <body>
     <h2 style="text-align: center;">Abstract</h2>
-    <article class="abstract">
-    <p>
+    <p class="abstract">
       Complexity is the single major difficulty in the successful development of large-scale software systems.
       Following Brooks we distinguish <em>accidental</em> from <em>essential</em> difficulty, but disagree with his premise that most complexity remaining in contemporary systems is essential.
       We identify common causes of complexity and discuss general approaches which can be taken to eliminate them where they are accidental in nature.
       To make things more concrete we then give an outline for a potential complexity-minimizing approach based on <em>functional programming</em> and <em>Codd’s relational model of data.</em></p>
-    </article>
   </body>
 </html>
diff --git a/OEBPS/section-1.html b/OEBPS/section-1.html
@@ -10,7 +10,6 @@
   </head>
   <body>
     <h2 id="section-1">1 Introduction</h2>
-    <article>
 
     <p>
       The “software crisis” was first identified in 1968 [<a href="references.html#NR69" class="reference">NR69</a>] and in the intervening decades has deepened rather than abated.
@@ -45,6 +44,5 @@ <h2 id="section-1">1 Introduction</h2>
     <p>
       Finally we contrast our approach with others in <a href="section-11.html#section-11" class="section">section 11</a> and then give conclusions in <a href="section-12.html#section-12" class="section">section 12</a>.
     </p>
-    </article>
   </body>
 </html>
diff --git a/OEBPS/section-10.html b/OEBPS/section-10.html
@@ -12,7 +12,6 @@
 
     <h2 id="section-10">10 Example of an FRP system</h2>
 
-    <article>
 
     <p>
       We now examine a simple example FRP system.
@@ -36,11 +35,9 @@ <h2 id="section-10">10 Example of an FRP system</h2>
       The example will use syntax from a hypothetical FRP infrastructure (which supports not only the relational algebra but also some of the common extensions from <a href="section-8.html#section-8.5" class="section">section 8.5</a>) — typewriter font is used for this.
     </p>
 
-    </article>
 
     <h3 id="section-10.1">10.1 User-defined Types</h3>
 
-    <article>
 
     <p>
       The example system makes use of a small number of custom types (see <a href="section-9.html#section-9.3" class="section">section 9.3</a>), some of which are just aliases for types provided by the infrastructure:
@@ -57,11 +54,9 @@ <h3 id="section-10.1">10.1 User-defined Types</h3>
 def enum speedBand : VERY_FAST | FAST | MEDIUM | SLOW | VERY_SLOW
     </pre>
 
-    </article>
 
     <h3 id="section-10.2">10.2 Essential State</h3>
 
-    <article>
 
     <p>
       The essential state (see <a href="section-9.html#section-9.1.1" class="section">section 9.1.1</a>) consists of the definitions of the <em>types</em> of the base relvars (the types of the attributes are shown in <em>italics</em>).
@@ -125,21 +120,17 @@ <h3 id="section-10.2">10.2 Essential State</h3>
       The commission fees are assigned on the basis of sale <em>prices</em> divided into different <em>priceBand</em>s, Property <em>addresses</em> categorized into <em>areaCodes</em> and ratings of the <em>saleSpeed</em>. (The decision has been made to represent commission rates as a base relation — rather than as a function — so that the commission fees can be queried and easily adjusted).
     </p>
 
-    </article>
 
     <h3 id="section-10.3">10.3 Essential Logic</h3>
 
-    <article>
 
     <p>
       This is the heart of the system (see <a href="section-9.html#section-9.1.2" class="section">section 9.1.2</a>) and corresponds to the “business logic”.
     </p>
 
-    </article>
 
     <h4>10.3.1 Functions</h4>
 
-    <article>
 
     <p>
       We do not give the actual function definitions here, we just describe their operation informally.
@@ -155,11 +146,9 @@ <h4>10.3.1 Functions</h4>
       <dd>Converts a pair of dates into a <em>speedBand</em> (reflecting the speed of sale after taking into account the time of year)</dd>
     </dl>
 
-    </article>
 
     <h4>10.3.2 Derived Relations</h4>
 
-    <article>
 
     <p>
       There are thirteen derived relations in the system.
@@ -172,11 +161,9 @@ <h4>10.3.2 Derived Relations</h4>
       In reality these types would be derived (or checked) by an infrastructure-provided type inference mechanism.
     </p>
 
-    </article>
 
     <h5>Internal</h5>
 
-    <article>
 
     <p>
       The ten <em>internal</em> derived relations exist mainly to help with the later definition of the three <em>external</em> ones.
@@ -311,11 +298,9 @@ <h5>Internal</h5>
       This gives the amount of <em>commission</em> due to each <em>agent</em> on each Property (represented by <em>address</em>).
     </p>
 
-    </article>
 
     <h5>External</h5>
 
-    <article>
 
     <p>
       Having now defined all the <em>internal</em> derived relations, we are now in a position to define the <em>external</em> derived relations — these are the ones which will be of most direct interest to the users of the system.
@@ -360,11 +345,9 @@ <h5>External</h5>
       Finally, the total commission due to each agent is calculated by simply summing up the <em>commission</em> attribute of the SalesCommissions relation on a per <em>agent</em> basis to give the <em>totalCommission</em> attribute.
     </p>
 
-    </article>
 
     <h4>10.3.3 Integrity</h4>
 
-    <article>
 
     <p>
       Integrity constraints are given in the form of relational algebra or relational calculus expressions.
@@ -454,11 +437,9 @@ <h4>10.3.3 Integrity</h4>
       Once the system is deployed, the FRP infrastructure will reject any state modification attempts which would violate any of these integrity constraints.
     </p>
 
-    </article>
 
     <h3 id="section-10.4">10.4 Accidental State and Control</h3>
 
-    <article>
 
     <p>
       The <em>accidental state and control</em> component of an FRP system consists solely of a set of declarations which represent performance hints for the infrastructure (see <a href="section-9.html#section-9.1.3" class="section">section 9.1.3</a>).
@@ -489,11 +470,9 @@ <h3 id="section-10.4">10.4 Accidental State and Control</h3>
       Larger systems would probably also include <em>accidental control</em> specifications for performance reasons.
     </p>
 
-    </article>
 
     <h3 id="section-10.5">10.5 Other</h3>
 
-    <article>
 
     <p>
       The <em>feeders</em> and <em>observers</em> for this system would be fairly simple — <em>feeding</em> user input into Decisions, Offers etc., and directly <em>observing</em> and displaying the various derived relations as output (e.g. OpenOffers, PropertyForWebSite and CommisionDue).
@@ -506,7 +485,6 @@ <h3 id="section-10.5">10.5 Other</h3>
     <p>
       One extension which might require a custom <em>observer</em> would be a requirement to connect CommissionDue into an external payroll system.
     </p>
-    </article>
 
   </body>
 </html>
diff --git a/OEBPS/section-11.html b/OEBPS/section-11.html
@@ -12,7 +12,6 @@
 
     <h2 id="section-11">11 Related Work</h2>
 
-    <article>
 
     <p>
       FRP draws some influence from the ideas of [<a href="references.html#DD00" class="reference">DD00</a>].
@@ -23,6 +22,5 @@ <h2 id="section-11">11 Related Work</h2>
     <p>
       There are also some similarities to Backus’ Applicative State Transition systems [<a href="references.html#Bac78" class="reference">Bac78</a>], and to the Aldat project at McGill [<a href="references.html#Mer85" class="reference">Mer85</a>] which investigated general purpose applications of relational algebra.
     </p>
-    </article>
   </body>
 </html>
diff --git a/OEBPS/section-12.html b/OEBPS/section-12.html
@@ -10,7 +10,6 @@
   </head>
   <body>
     <h2 id="section-12">12 Conclusions</h2>
-    <article>
 
     <p>
       We have argued that <em>complexity</em> causes more problems in large software systems than anything else.
@@ -30,6 +29,5 @@ <h2 id="section-12">12 Conclusions</h2>
     <p>
       So, what is the way out of the tar pit? What is the silver bullet? … it may not be FRP, but we believe there can be no doubt that it is <em>simplicity</em>.
     </p>
-    </article>
   </body>
 </html>
diff --git a/OEBPS/section-2.html b/OEBPS/section-2.html
@@ -10,7 +10,6 @@
   </head>
   <body>
     <h2 id="section-2">2 Complexity</h2>
-    <article>
     <p>
       In his classic paper — “No Silver Bullet” Brooks [<a href="references.html#Bro86" class="reference">Bro86</a>] identified four properties of software systems which make building software hard: Complexity, Conformity, Changeability and Invisibility.
       Of these we believe that Complexity is the <em>only</em> significant one — the others can either be <em>classified as</em> forms of complexity, or be seen as problematic solely <em>because</em> of the complexity in the system.
@@ -25,10 +24,10 @@ <h2 id="section-2">2 Complexity</h2>
     <p>
       The relevance of complexity is widely recognised.
       As Dijkstra said [<a href="references.html#Dij97" class="reference">Dij97</a>, EWD1243]
-	    <blockquote>
-        “…we have to keep it crisp, disentangled, and simple if we refuse to be crushed by the complexities of our own making…”
-      </blockquote>
     </p>
+    <blockquote>
+      <p>“…we have to keep it crisp, disentangled, and simple if we refuse to be crushed by the complexities of our own making…”</p>
+    </blockquote>
 
     <p>
       …and the Economist devoted a whole article to software complexity [<a href="references.html#Eco04" class="reference">Eco04</a>] — noting that by some estimates software problems cost the American economy $59 billion annually.
@@ -38,38 +37,38 @@ <h2 id="section-2">2 Complexity</h2>
       Being able to think and reason about our systems (particularly the effects of changes to those systems) is of <em>crucial</em> importance.
       The dangers of complexity and the importance of simplicity in this regard have also been a popular topic in ACM Turing award lectures.
       In his 1990 lecture Corbato said [<a href="references.html#Cor91" class="reference">Cor91</a>]:
-	    <blockquote>
-        “The general problem with ambitious systems is complexity.”, “…it is important to emphasize the value of simplicity and elegance, for complexity has a way of compounding difficulties”
-      </blockquote>
     </p>
+    <blockquote>
+      <p>“The general problem with ambitious systems is complexity.”, “…it is important to emphasize the value of simplicity and elegance, for complexity has a way of compounding difficulties”</p>
+    </blockquote>
 
     <p>
       In 1977 Backus [<a href="references.html#Bac78" class="reference">Bac78</a>] talked about the “complexities and weaknesses” of traditional languages and noted:
-	    <blockquote>“there is a desperate need for a powerful methodology to help us think about programs. … conventional languages create unnecessary confusion in the way we think about programs”</blockquote>
     </p>
+    <blockquote>
+      <p>“there is a desperate need for a powerful methodology to help us think about programs. … conventional languages create unnecessary confusion in the way we think about programs”</p>
+    </blockquote>
+
 
     <p>
       Finally, in his Turing award speech in 1980 Hoare [<a href="references.html#Hoa81" class="reference">Hoa81</a>] observed:
-	    <blockquote>
-        “…there is one quality that cannot be purchased … — and that is reliability.
-        The price of reliability is the pursuit of the utmost simplicity”
-      </blockquote>
     </p>
+    <blockquote>
+      <p>“…there is one quality that cannot be purchased … — and that is reliability.
+        The price of reliability is the pursuit of the utmost simplicity”</p>
+    </blockquote>
 
-    <p>
-      and
-	    <blockquote>
-        “I conclude that there are two ways of constructing a software design: One way is to make it so simple that there are <em>obviously</em> no deficiencies and the other way is to make it so complicated that there are no <em>obvious</em> deficiencies.
-        The first method is far more difficult.”
-      </blockquote>
-    </p>
+    <p>and</p>
+    <blockquote>
+      <p>“I conclude that there are two ways of constructing a software design: One way is to make it so simple that there are <em>obviously</em> no deficiencies and the other way is to make it so complicated that there are no <em>obvious</em> deficiencies. The first method is far more difficult.”</p>
+    </blockquote>
 
     <p>
       This is the unfortunate truth:
     </p>
 
     <blockquote class="centred">
-      Simplicity is <em>Hard</em>
+      <p>Simplicity is <em>Hard</em></p>
     </blockquote>
 
     <p>
@@ -86,6 +85,5 @@ <h2 id="section-2">2 Complexity</h2>
     <p>
       We shall look at what we consider to be the major common causes of complexity (things which make understanding difficult) after first discussing exactly how we normally attempt to <em>understand</em> systems.
     </p>
-    </article>
   </body>
 </html>
diff --git a/OEBPS/section-3.html b/OEBPS/section-3.html
@@ -10,7 +10,6 @@
   </head>
   <body>
     <h2 id="section-3">3 Approaches to Understanding</h2>
-    <article>
     <p>
       We argued above that the danger of complexity came from its impact on our attempts to <em>understand</em> a system.
       Because of this, it is helpful to consider the mechanisms that are commonly used to try to understand systems.
@@ -39,26 +38,26 @@ <h2 id="section-3">3 Approaches to Understanding</h2>
       This is because — as we shall see below — there are inherent limits to what can be achieved by testing, and because informal reasoning (by virtue of being an inherent part of the development process) is <em>always</em> used.
       The other justification is that improvements in informal reasoning will lead to <em>less errors being created</em> whilst all that improvements in testing can do is to lead to <em>more errors being detected</em>.
       As Dijkstra said in his Turing award speech [<a href="references.html#Dij72" class="reference">Dij72</a>, EWD340]:
-      <blockquote>
-        “Those who want really reliable software will discover that they must find means of avoiding the majority of bugs to start with.”
-      </blockquote>
     </p>
+    <blockquote>
+      <p>“Those who want really reliable software will discover that they must find means of avoiding the majority of bugs to start with.”</p>
+    </blockquote>
 
     <p>
       and as O’Keefe (who also stressed the importance of “<em>understanding your problem</em>” and that “<em>Elegance is not optional</em>”) said [<a href="references.html#OK90" class="reference">O’K90</a>]:
-      <blockquote>
-        “Our response to mistakes should be to look for ways that we can avoid making them, not to blame the nature of things.”
-      </blockquote>
     </p>
+    <blockquote>
+      <p>“Our response to mistakes should be to look for ways that we can avoid making them, not to blame the nature of things.”</p>
+    </blockquote>
 
     <p>
       The key problem with testing is that a test (of any kind) that uses one particular set of inputs tells you <em>nothing at all</em> about the behaviour of the system or component when it is given a different set of inputs.
       The huge number of different possible inputs usually rules out the possibility of testing them all, hence the unavoidable concern with testing will always be — <em>have you performed the </em>right<em> tests</em>?.
       The only certain answer you will ever get to this question is an answer in the negative — when the system breaks.  Again, as Dijkstra observed [<a href="references.html#Dij71" class="reference">Dij71</a>, EWD303]:
-      <blockquote>
-        “testing is hopelessly inadequate.…(it) can be used very effectively to show the presence of bugs but never to show their absence.”
-      </blockquote>
     </p>
+    <blockquote>
+      <p>“testing is hopelessly inadequate.…(it) can be used very effectively to show the presence of bugs but never to show their absence.”</p>
+    </blockquote>
 
     <p>
       We agree with Dijkstra. <em>Rely</em> on testing at your peril.
@@ -75,6 +74,5 @@ <h2 id="section-3">3 Approaches to Understanding</h2>
       When considered next to testing and reasoning, simplicity is more important than either.
       Given a stark choice between investment in testing and investment in simplicity, the latter may often be the better choice because it will facilitate <em>all</em> future attempts to understand the system — attempts of any kind.
     </p>
-    </article>
   </body>
 </html>