[e-lang] 'E in a Walnut': minor problems

[Kevin Reid]

- http://www.skyhunter.com/marcs/ewalnut.html#BuildGuards

   The Updoc here has three occurrences of angle-bracketed <...> being 
inappropriately followed by </...>. (Searching for &lt;/ in the HTML 
will find all of them and one actual tag.)

- The section numbering creates fragile links.

   If a section is added in the middle, all existing links to sections 
after it will now be pointing to the section before the intended one.

   (The "BuildGuards" section is named instead of numbered, which is a 
suitably non-fragile link, but does not appear in the TOC.)

- In "Oblivious Claim Checks as Guards":

   - 'E.isBroken' should be 'Ref.isBroken'

   - There is no definition of the variable 'claim' in the method 
'lookAtHPMDoc'.

   - The guard as defined later throws as a guard usually does, whereas 
the text states:

      "As a guard, it is better style to return a broken reference than 
to throw an exception if something goes wrong. In the parameter guard, 
if an exception were thrown, the recipient would have no chance to do 
anything with the problem, the exception would be thrown directly back 
to the sender before the recipient was even aware there was an issue."

     - Additionally, I believe the above, if actually implemented, would 
be very bad style, if done for the reason given.

       Guards should always use the optEjector path for 
failure-to-coerce, as it allows distinguishing that specific failure 
from other kinds, and the use of (for example) UnionGuards. Also, the 
existing code obscures that it is the guard which produces the broken 
reference.

       Using such a guard with explicit failure handling is a simple 
matter of "if (claim =~ doc :CheckedClaim[...]) {", or using an 
'escape' block, and this makes explicit that it is the guard which is 
failing, as opposed to an entirely generic Ref.isBroken().

-- 
Kevin Reid                            <http://homepage.mac.com/kpreid/>