5704

Minor tweaks based on feedback from Max Bernstein.

3 files changed, 93 insertions, 71 deletions

diff --git a/000organization.cc b/000organization.cc
index 87004af5..1bbaa057 100644
--- a/000organization.cc
+++ b/000organization.cc
@@ -87,6 +87,8 @@
 //: Programmers shouldn't need to understand everything about a program to
 //: hack on it. But they shouldn't be prevented from a thorough understanding
 //: of each aspect either. The goal of layers is to reward curiosity.
+//:
+//: More information: http://akkartik.name/post/wart-layers
 
 // Includes
 // End Includes
diff --git a/Readme.md b/Readme.md
index c75ed72b..f3200914 100644
--- a/Readme.md
+++ b/Readme.md
@@ -817,6 +817,24 @@ To falsify these hypotheses, here's a roadmap of the next few planned features:
 
 * Gradually streamline the bundled kernel, stripping away code we don't need.
 
+---
+
+If you're still reading, here are some more things to check out:
+
+a) Try running the tests:
+
+  ```shell
+  $ ./test_apps
+  ```
+
+b) Try skimming the source code. You should be able to get a pretty good sense
+for how things work just by skimming the files in order, skimming the top of
+each file and ignoring details lower down.
+[Some details on my unconventional approach to organizing projects.](http://akkartik.name/post/four-repos)
+
+c) Try working on [the starter exercises](https://github.com/akkartik/mu/pulls)
+(labelled `hello`).
+
 ## Credits
 
 Mu builds on many ideas that have come before, especially:
diff --git a/html/000organization.cc.html b/html/000organization.cc.html
index ca68e197..f53b0f5d 100644
--- a/html/000organization.cc.html
+++ b/html/000organization.cc.html
@@ -145,79 +145,81 @@ if ('onhashchange' in window) {
 <span id="L87" class="LineNr"> 87 </span><span class="Comment">//: Programmers shouldn't need to understand everything about a program to</span>
 <span id="L88" class="LineNr"> 88 </span><span class="Comment">//: hack on it. But they shouldn't be prevented from a thorough understanding</span>
 <span id="L89" class="LineNr"> 89 </span><span class="Comment">//: of each aspect either. The goal of layers is to reward curiosity.</span>
-<span id="L90" class="LineNr"> 90 </span>
-<span id="L91" class="LineNr"> 91 </span><span class="Comment">// Includes</span>
-<span id="L92" class="LineNr"> 92 </span><span class="Comment">// End Includes</span>
-<span id="L93" class="LineNr"> 93 </span>
-<span id="L94" class="LineNr"> 94 </span><span class="Comment">// Types</span>
-<span id="L95" class="LineNr"> 95 </span><span class="Comment">// End Types</span>
-<span id="L96" class="LineNr"> 96 </span>
-<span id="L97" class="LineNr"> 97 </span><span class="Comment">// Function prototypes are auto-generated in the 'build' script; define your</span>
-<span id="L98" class="LineNr"> 98 </span><span class="Comment">// functions in any order. Just be sure to declare each function header all on</span>
-<span id="L99" class="LineNr"> 99 </span><span class="Comment">// one line, ending with the '{'. Our auto-generation scripts are too minimal</span>
-<span id="L100" class="LineNr">100 </span><span class="Comment">// and simple-minded to handle anything else.</span>
-<span id="L101" class="LineNr">101 </span><span class="PreProc">#include </span><span class="Constant">&quot;function_list&quot;</span>  <span class="Comment">// by convention, files ending with '_list' are auto-generated</span>
-<span id="L102" class="LineNr">102 </span>
-<span id="L103" class="LineNr">103 </span><span class="Comment">// Globals</span>
-<span id="L104" class="LineNr">104 </span><span class="Comment">//</span>
-<span id="L105" class="LineNr">105 </span><span class="Comment">// All statements in this section should always define a single variable on a</span>
-<span id="L106" class="LineNr">106 </span><span class="Comment">// single line. The 'build' script will simple-mindedly auto-generate extern</span>
-<span id="L107" class="LineNr">107 </span><span class="Comment">// declarations for them. Remember to define (not just declare) constants with</span>
-<span id="L108" class="LineNr">108 </span><span class="Comment">// extern linkage in this section, since C++ global constants have internal</span>
-<span id="L109" class="LineNr">109 </span><span class="Comment">// linkage by default.</span>
-<span id="L110" class="LineNr">110 </span><span class="Comment">//</span>
-<span id="L111" class="LineNr">111 </span><span class="Comment">// End Globals</span>
-<span id="L112" class="LineNr">112 </span>
-<span id="L113" class="LineNr">113 </span><span class="Normal">int</span> <a href='000organization.cc.html#L113'>main</a><span class="Delimiter">(</span><span class="Normal">int</span> argc<span class="Delimiter">,</span> <span class="Normal">char</span>* argv[]<span class="Delimiter">)</span> <span class="Delimiter">{</span>
-<span id="L114" class="LineNr">114 </span>  atexit<span class="Delimiter">(</span><a href='000organization.cc.html#L148'>reset</a><span class="Delimiter">);</span>
-<span id="L115" class="LineNr">115 </span>  <span class="Comment">// we require a 32-bit little-endian system</span>
-<span id="L116" class="LineNr">116 </span>  assert<span class="Delimiter">(</span><span class="Normal">sizeof</span><span class="Delimiter">(</span><span class="Normal">int</span><span class="Delimiter">)</span> == <span class="Constant">4</span><span class="Delimiter">);</span>
-<span id="L117" class="LineNr">117 </span>  assert<span class="Delimiter">(</span><span class="Normal">sizeof</span><span class="Delimiter">(</span><span class="Normal">float</span><span class="Delimiter">)</span> == <span class="Constant">4</span><span class="Delimiter">);</span>
-<span id="L118" class="LineNr">118 </span>  <a href='000organization.cc.html#L152'>assert_little_endian</a><span class="Delimiter">();</span>
-<span id="L119" class="LineNr">119 </span>
-<span id="L120" class="LineNr">120 </span>  <span class="Comment">// End One-time Setup</span>
+<span id="L90" class="LineNr"> 90 </span><span class="Comment">//:</span>
+<span id="L91" class="LineNr"> 91 </span><span class="Comment">//: More information: <a href="http://akkartik.name/post/wart-layers">http://akkartik.name/post/wart-layers</a></span>
+<span id="L92" class="LineNr"> 92 </span>
+<span id="L93" class="LineNr"> 93 </span><span class="Comment">// Includes</span>
+<span id="L94" class="LineNr"> 94 </span><span class="Comment">// End Includes</span>
+<span id="L95" class="LineNr"> 95 </span>
+<span id="L96" class="LineNr"> 96 </span><span class="Comment">// Types</span>
+<span id="L97" class="LineNr"> 97 </span><span class="Comment">// End Types</span>
+<span id="L98" class="LineNr"> 98 </span>
+<span id="L99" class="LineNr"> 99 </span><span class="Comment">// Function prototypes are auto-generated in the 'build' script; define your</span>
+<span id="L100" class="LineNr">100 </span><span class="Comment">// functions in any order. Just be sure to declare each function header all on</span>
+<span id="L101" class="LineNr">101 </span><span class="Comment">// one line, ending with the '{'. Our auto-generation scripts are too minimal</span>
+<span id="L102" class="LineNr">102 </span><span class="Comment">// and simple-minded to handle anything else.</span>
+<span id="L103" class="LineNr">103 </span><span class="PreProc">#include </span><span class="Constant">&quot;function_list&quot;</span>  <span class="Comment">// by convention, files ending with '_list' are auto-generated</span>
+<span id="L104" class="LineNr">104 </span>
+<span id="L105" class="LineNr">105 </span><span class="Comment">// Globals</span>
+<span id="L106" class="LineNr">106 </span><span class="Comment">//</span>
+<span id="L107" class="LineNr">107 </span><span class="Comment">// All statements in this section should always define a single variable on a</span>
+<span id="L108" class="LineNr">108 </span><span class="Comment">// single line. The 'build' script will simple-mindedly auto-generate extern</span>
+<span id="L109" class="LineNr">109 </span><span class="Comment">// declarations for them. Remember to define (not just declare) constants with</span>
+<span id="L110" class="LineNr">110 </span><span class="Comment">// extern linkage in this section, since C++ global constants have internal</span>
+<span id="L111" class="LineNr">111 </span><span class="Comment">// linkage by default.</span>
+<span id="L112" class="LineNr">112 </span><span class="Comment">//</span>
+<span id="L113" class="LineNr">113 </span><span class="Comment">// End Globals</span>
+<span id="L114" class="LineNr">114 </span>
+<span id="L115" class="LineNr">115 </span><span class="Normal">int</span> <a href='000organization.cc.html#L115'>main</a><span class="Delimiter">(</span><span class="Normal">int</span> argc<span class="Delimiter">,</span> <span class="Normal">char</span>* argv[]<span class="Delimiter">)</span> <span class="Delimiter">{</span>
+<span id="L116" class="LineNr">116 </span>  atexit<span class="Delimiter">(</span><a href='000organization.cc.html#L150'>reset</a><span class="Delimiter">);</span>
+<span id="L117" class="LineNr">117 </span>  <span class="Comment">// we require a 32-bit little-endian system</span>
+<span id="L118" class="LineNr">118 </span>  assert<span class="Delimiter">(</span><span class="Normal">sizeof</span><span class="Delimiter">(</span><span class="Normal">int</span><span class="Delimiter">)</span> == <span class="Constant">4</span><span class="Delimiter">);</span>
+<span id="L119" class="LineNr">119 </span>  assert<span class="Delimiter">(</span><span class="Normal">sizeof</span><span class="Delimiter">(</span><span class="Normal">float</span><span class="Delimiter">)</span> == <span class="Constant">4</span><span class="Delimiter">);</span>
+<span id="L120" class="LineNr">120 </span>  <a href='000organization.cc.html#L154'>assert_little_endian</a><span class="Delimiter">();</span>
 <span id="L121" class="LineNr">121 </span>
-<span id="L122" class="LineNr">122 </span>  <span class="Comment">// Commandline Parsing</span>
-<span id="L123" class="LineNr">123 </span>  <span class="Comment">// End Commandline Parsing</span>
-<span id="L124" class="LineNr">124 </span>
-<span id="L125" class="LineNr">125 </span>  <span class="Comment">// End Main</span>
+<span id="L122" class="LineNr">122 </span>  <span class="Comment">// End One-time Setup</span>
+<span id="L123" class="LineNr">123 </span>
+<span id="L124" class="LineNr">124 </span>  <span class="Comment">// Commandline Parsing</span>
+<span id="L125" class="LineNr">125 </span>  <span class="Comment">// End Commandline Parsing</span>
 <span id="L126" class="LineNr">126 </span>
-<span id="L127" class="LineNr">127 </span>  <span class="Identifier">return</span> <span class="Constant">0</span><span class="Delimiter">;</span>
-<span id="L128" class="LineNr">128 </span><span class="Delimiter">}</span>
-<span id="L129" class="LineNr">129 </span>
-<span id="L130" class="LineNr">130 </span><span class="Comment">// Unit Tests</span>
-<span id="L131" class="LineNr">131 </span><span class="Comment">// End Unit Tests</span>
-<span id="L132" class="LineNr">132 </span>
-<span id="L133" class="LineNr">133 </span><span class="Comment">//: our first directive; insert the following headers at the start of the program</span>
-<span id="L134" class="LineNr">134 </span><span class="Delimiter">:(before &quot;End Includes&quot;)</span>
-<span id="L135" class="LineNr">135 </span><span class="PreProc">#include </span><span class="Constant">&lt;assert.h&gt;</span>
-<span id="L136" class="LineNr">136 </span><span class="PreProc">#include </span><span class="Constant">&lt;stdlib.h&gt;</span>
-<span id="L137" class="LineNr">137 </span>
-<span id="L138" class="LineNr">138 </span><span class="Comment">//: Without directives or with the :(code) directive, lines get added at the</span>
-<span id="L139" class="LineNr">139 </span><span class="Comment">//: end.</span>
-<span id="L140" class="LineNr">140 </span><span class="Comment">//:</span>
-<span id="L141" class="LineNr">141 </span><span class="Comment">//: Regardless of where functions are defined, we can call them anywhere we</span>
-<span id="L142" class="LineNr">142 </span><span class="Comment">//: like as long as we format the function header in a specific way: put it</span>
-<span id="L143" class="LineNr">143 </span><span class="Comment">//: all on a single line without indent, end the line with ') {' and no</span>
-<span id="L144" class="LineNr">144 </span><span class="Comment">//: trailing whitespace. As long as functions uniformly start this way, our</span>
-<span id="L145" class="LineNr">145 </span><span class="Comment">//: 'build' script contains a little command to automatically generate</span>
-<span id="L146" class="LineNr">146 </span><span class="Comment">//: declarations for them.</span>
-<span id="L147" class="LineNr">147 </span><span class="Delimiter">:(code)</span>
-<span id="L148" class="LineNr">148 </span><span class="Normal">void</span> <a href='000organization.cc.html#L148'>reset</a><span class="Delimiter">()</span> <span class="Delimiter">{</span>
-<span id="L149" class="LineNr">149 </span>  <span class="Comment">// End Reset</span>
-<span id="L150" class="LineNr">150 </span><span class="Delimiter">}</span>
-<span id="L151" class="LineNr">151 </span>
-<span id="L152" class="LineNr">152 </span><span class="Normal">void</span> <a href='000organization.cc.html#L152'>assert_little_endian</a><span class="Delimiter">()</span> <span class="Delimiter">{</span>
-<span id="L153" class="LineNr">153 </span>  <span class="Normal">const</span> <span class="Normal">int</span> x = <span class="Constant">1</span><span class="Delimiter">;</span>
-<span id="L154" class="LineNr">154 </span>  <span class="Normal">const</span> <span class="Normal">char</span>* y = <span class="Normal">reinterpret_cast</span>&lt;<span class="Normal">const</span> <span class="Normal">char</span>*&gt;<span class="Delimiter">(</span>&amp;x<span class="Delimiter">);</span>
-<span id="L155" class="LineNr">155 </span>  <span class="Normal">if</span> <span class="Delimiter">(</span>*y != <span class="Constant">1</span><span class="Delimiter">)</span> <span class="Delimiter">{</span>
-<span id="L156" class="LineNr">156 </span>    cerr &lt;&lt; <span class="Constant">&quot;SubX requires a little-endian processor. Do you have Intel (or AMD or Atom) inside?\n&quot;</span><span class="Delimiter">;</span>
-<span id="L157" class="LineNr">157 </span>    exit<span class="Delimiter">(</span><span class="Constant">1</span><span class="Delimiter">);</span>
-<span id="L158" class="LineNr">158 </span>  <span class="Delimiter">}</span>
-<span id="L159" class="LineNr">159 </span><span class="Delimiter">}</span>
-<span id="L160" class="LineNr">160 </span><span class="Delimiter">:(before &quot;End Includes&quot;)</span>
-<span id="L161" class="LineNr">161 </span><span class="PreProc">#include</span><span class="Constant">&lt;iostream&gt;</span>
-<span id="L162" class="LineNr">162 </span><span class="Normal">using</span> std::cerr<span class="Delimiter">;</span>
+<span id="L127" class="LineNr">127 </span>  <span class="Comment">// End Main</span>
+<span id="L128" class="LineNr">128 </span>
+<span id="L129" class="LineNr">129 </span>  <span class="Identifier">return</span> <span class="Constant">0</span><span class="Delimiter">;</span>
+<span id="L130" class="LineNr">130 </span><span class="Delimiter">}</span>
+<span id="L131" class="LineNr">131 </span>
+<span id="L132" class="LineNr">132 </span><span class="Comment">// Unit Tests</span>
+<span id="L133" class="LineNr">133 </span><span class="Comment">// End Unit Tests</span>
+<span id="L134" class="LineNr">134 </span>
+<span id="L135" class="LineNr">135 </span><span class="Comment">//: our first directive; insert the following headers at the start of the program</span>
+<span id="L136" class="LineNr">136 </span><span class="Delimiter">:(before &quot;End Includes&quot;)</span>
+<span id="L137" class="LineNr">137 </span><span class="PreProc">#include </span><span class="Constant">&lt;assert.h&gt;</span>
+<span id="L138" class="LineNr">138 </span><span class="PreProc">#include </span><span class="Constant">&lt;stdlib.h&gt;</span>
+<span id="L139" class="LineNr">139 </span>
+<span id="L140" class="LineNr">140 </span><span class="Comment">//: Without directives or with the :(code) directive, lines get added at the</span>
+<span id="L141" class="LineNr">141 </span><span class="Comment">//: end.</span>
+<span id="L142" class="LineNr">142 </span><span class="Comment">//:</span>
+<span id="L143" class="LineNr">143 </span><span class="Comment">//: Regardless of where functions are defined, we can call them anywhere we</span>
+<span id="L144" class="LineNr">144 </span><span class="Comment">//: like as long as we format the function header in a specific way: put it</span>
+<span id="L145" class="LineNr">145 </span><span class="Comment">//: all on a single line without indent, end the line with ') {' and no</span>
+<span id="L146" class="LineNr">146 </span><span class="Comment">//: trailing whitespace. As long as functions uniformly start this way, our</span>
+<span id="L147" class="LineNr">147 </span><span class="Comment">//: 'build' script contains a little command to automatically generate</span>
+<span id="L148" class="LineNr">148 </span><span class="Comment">//: declarations for them.</span>
+<span id="L149" class="LineNr">149 </span><span class="Delimiter">:(code)</span>
+<span id="L150" class="LineNr">150 </span><span class="Normal">void</span> <a href='000organization.cc.html#L150'>reset</a><span class="Delimiter">()</span> <span class="Delimiter">{</span>
+<span id="L151" class="LineNr">151 </span>  <span class="Comment">// End Reset</span>
+<span id="L152" class="LineNr">152 </span><span class="Delimiter">}</span>
+<span id="L153" class="LineNr">153 </span>
+<span id="L154" class="LineNr">154 </span><span class="Normal">void</span> <a href='000organization.cc.html#L154'>assert_little_endian</a><span class="Delimiter">()</span> <span class="Delimiter">{</span>
+<span id="L155" class="LineNr">155 </span>  <span class="Normal">const</span> <span class="Normal">int</span> x = <span class="Constant">1</span><span class="Delimiter">;</span>
+<span id="L156" class="LineNr">156 </span>  <span class="Normal">const</span> <span class="Normal">char</span>* y = <span class="Normal">reinterpret_cast</span>&lt;<span class="Normal">const</span> <span class="Normal">char</span>*&gt;<span class="Delimiter">(</span>&amp;x<span class="Delimiter">);</span>
+<span id="L157" class="LineNr">157 </span>  <span class="Normal">if</span> <span class="Delimiter">(</span>*y != <span class="Constant">1</span><span class="Delimiter">)</span> <span class="Delimiter">{</span>
+<span id="L158" class="LineNr">158 </span>    cerr &lt;&lt; <span class="Constant">&quot;SubX requires a little-endian processor. Do you have Intel (or AMD or Atom) inside?\n&quot;</span><span class="Delimiter">;</span>
+<span id="L159" class="LineNr">159 </span>    exit<span class="Delimiter">(</span><span class="Constant">1</span><span class="Delimiter">);</span>
+<span id="L160" class="LineNr">160 </span>  <span class="Delimiter">}</span>
+<span id="L161" class="LineNr">161 </span><span class="Delimiter">}</span>
+<span id="L162" class="LineNr">162 </span><span class="Delimiter">:(before &quot;End Includes&quot;)</span>
+<span id="L163" class="LineNr">163 </span><span class="PreProc">#include</span><span class="Constant">&lt;iostream&gt;</span>
+<span id="L164" class="LineNr">164 </span><span class="Normal">using</span> std::cerr<span class="Delimiter">;</span>
 </pre>
 </body>
 </html>