Pass on basically all documentation pages

Author: pavpanchekha

www/doc.html

@@ -35,6 +35,7 @@ <h2>Documentation</h2>
   <ul>
     <li><a href="doc/latest/input.html">Input format</a>: what sorts of expressions Herbie supports.</li>
     <li><a href="doc/latest/options.html">Command-line flags</a>: modifying Herbie's behavior.</li>
+    <li><a href="doc/latest/error.html">What is error?</a>: how Herbie measures floating-point error.</li>
     <li><a href="doc/latest/faq.html">FAQ</a>: troubleshooting Herbie.</li>
     <li><a href="doc/latest/release-notes.html">Release Notes</a>: the biggest and latest changes to Herbie.</li>
   </ul>

www/doc/2.0/docker.html

@@ -48,10 +48,11 @@ <h2>Installing Herbie via Docker</h2>
 
   <pre>docker run -it uwplse/herbie shell</pre>
 
-  <p>This will read input from the standard input.</p>
+  <p>This will download the Herbie image and then run
+  its <a href="options.html">shell tool</a>.</p>
 
-  <p>Note that Herbie in Docker is more limited; for example, it will
-  not recognize plugins installed outside the Docker container.</p>
+  <p>Herbie in Docker is more limited; for example, it will not
+  recognize plugins installed outside the Docker container.</p>
 
   <h2>Running the web interface</h2>
 
@@ -113,30 +114,51 @@ <h2>Generating files and reports</h2>
     have the correct permissions set.
   </p>
 
-  <h2>For developers: updating the Docker image + Dockerfile</h2>
+  <h2>Building the Docker image</h2>
+
+  <p>This section is primarily of interest for the Herbie developers.</p>
 
   <p>
-    For building and testing, first clone the repo and confirm that Herbie builds correctly with <code>make install</code>.
+    Clone the repo and confirm that Herbie builds correctly
+    with <code>make install</code>.
   </p>
+
   <p>
-    Next, examine the Dockerfile and Makefile together. The Dockerfile should follow a process exactly like the Makefile, except a clean initial environment is assumed. The build may be split into 2 or more stages to limit the size of the resulting image. Each stage consists of a <code>FROM</code> command and a series of further commands to build up the desired environment, and later stages can refer to earlier stages by name--for example, <code>COPY --from=earlier-stage ...</code> can copy files compiled in earlier images. You may need to do things like bumping the version of Rust used for binary compilation or the version of Racket used in production, or adjusting paths to match the newest version of the repo.
-  </p>
-    <p>
-    Once you are ready to build:
-    <pre class="shell">docker build -t herbie-testbuild .</pre>
-    from the repo's main directory will build a new test image with the tag <code>herbie-testbuild</code>. You can run this image with
-    <pre class="shell">docker run -p 8000:80 -it herbie-testbuild</pre>
-    and see the web demo in the host machine's browser at <code>http://localhost:8000</code>.
+    Next, examine the Dockerfile and Makefile together. The Dockerfile
+    should follow a process exactly like the Makefile, except a clean
+    initial environment is assumed. The build may be split into 2 or
+    more stages to limit the size of the resulting image. Each stage
+    consists of a <code>FROM</code> command and a series of further
+    commands to build up the desired environment, and later stages can
+    refer to earlier stages by name&mdash;for example, <code>COPY
+    --from=earlier-stage ...</code> can copy files compiled in earlier
+    images. You may need to do things like bumping the version of Rust
+    used for binary compilation or the version of Racket used in
+    production, or adjusting paths to match the newest version of the
+    repo.
   </p>
+
+  <p>Once you are ready to build, run this command from the repository root:</p>
+
+  <pre class="shell">docker build -t uwplse/herbie:test .</pre>
+
+  <p>This builds a new test image and tags
+  it <code>uwplse/herbie:test</code>. You can run this image with:</p>
+
+  <pre class="shell">docker run -p 8000:80 -it uwplse/herbie:test</pre>
+
+  <p>The web demo should now be visiable at <code>http://localhost:8000</code>.</p>
 
-  <p>
-  To open a shell in a running container for testing, first get the container ID with
+  <p>To open a shell in a running container for testing, first get the container ID with:</p>
+
   <pre class="shell">docker ps</pre>
-  and then open a shell in the container as root with
+
+  <p>Then open a root shell in that container with</p>
+
   <pre class="shell">docker exec -it &lt;CONTAINER ID&gt; sh</pre>
 
-  The code and egg-herbie binaries should be under <code>/src</code>.
-  </p>
+  <p>The code and egg-herbie binaries should be
+  under <code>/src</code>.</p>
 
 </body>
 </html>

www/doc/2.0/error.html

@@ -20,21 +20,21 @@ <h1>What is Error?</h1>
 <p>
   <a href="../../">Herbie</a> helps you identify and correct floating
   point error in your numeric programs. But what is floating point
-  error, how does Herbie measure it, and how does it address it?
+  error, and how does Herbie measure it?
 </p>
 
 <h2>The summary</h2>
 
-When Herbie reports a "percentage accuracy" number like 92.3%, it's
+<p>When Herbie reports a "percentage accuracy" number like 92.3%, it's
 usually best to think of that as the percentage of floating-point
-inputs where the expression is reasonably accurate.
+inputs where the expression is reasonably accurate.</p>
 
-What exactly that means can vary: the impact of this error on your
-application will depend a lot on <em>which</em> 7.7% of points have
-error, and what kind of error that is. If you have more information
-about which types of points are important, the best way to communicate
-that to Herbie is by using ranges or preconditions to restrict the
-inputs Herbie is considering.
+<p>The impact of this error on your application will depend a lot
+on <em>which</em> 7.7% of inputs are inaccurate, and what kind of
+error that is. You can find this out using
+the <a href="report.html">accuracy graph in Herbie reports</a>. You
+can also use preconditions to restrict the inputs Herbie is
+considering.</p>
 
 <h2>Why rounding matters</h2>
 
@@ -46,11 +46,10 @@ <h2>Why rounding matters</h2>
 be <em>rounded</em> to a representable one.</p>
 
 <p>Take an extreme example: the code <code>1e100 + 1</code>, which
-increments a huge number, in IEEE 754 double-precision floating-point
-(which Herbie calls <code>binary64</code>). There's an exact
-real-number answer to this (a one followed by 99 zeros and then
-another 1), but the closest <em>floating-point</em> value is the same
-as for <code>1e100</code>.</p>
+increments a huge number in IEEE 754 double-precision floating-point.
+There's an exact real-number answer, a one followed by 99 zeros and
+then another 1, but the closest <em>floating-point</em> value is the
+same as <code>1e100</code>.</p>
 
 <p>Errors like this can cause problems. In the example above, the
 answers differ by one part per googol, which is pretty small. But the
@@ -110,38 +109,39 @@ <h2>Percentage accuracy</h2>
 percentage across many randomly-sampled valid inputs.</p>
 
 <p>Typically, inputs points are either very accurate or not accurate
-at all. So when computing average error, Herbie's averaging a lot of
-points with near-100% accuracy and a lot of points with near-0%
-accuracy. In that sense, you can think of average error as measuring
-mostly what percentage <em>of inputs</em> are accurate. If Herbie says
-your computation is 75% accurate what it's really saying is that about
-a quarter of inputs produce usable outputs.</p>
-
-<p>Interpreting average error also requires understanding which inputs
-are valid and how they are sampled.</p>
+at all. So when computing percentage accuracy, Herbie's averaging a
+lot of points with near-100% accuracy and a lot of points with near-0%
+accuracy. In that sense, you can think of percentage accuracy as
+measuring mostly what percentage <em>of inputs</em> are accurate. If
+Herbie says your computation is 75% accurate what it's really saying
+is that about a quarter of inputs produce usable outputs.</p>
 
 <h2>Valid inputs</h2>
 
-<p>Herbie considers an input valid if its true, real-number output 1)
-exists; 2) rounds to a finite number; 3) can be computed; and 4)
-satisfies the user's precondition. Let's dive into each
-requirement.</p>
+<p>Since percentage accuracy averages over many points, it depends on
+what points it is averaging over, and how is samples among them.
+Herbie samples among <em>valid</em> inputs, uniformly distributed.</p>
+
+<p>Herbie considers an input valid if it is a floating-point value in
+the appropriate precision and its true, real-number output 1) exists;
+2) satisfies the user's precondition; and 3) can be computed. Let's
+dive into each requirement.</p>
 
 <ol>
   <li>An output can fail to exist for an input if that input does
     something like divide by zero or take the square root of a
     negative number. Then that input is invalid.</li>
-  <li>An output can fail to satisfy the user's precondition.
+  <li>An input can fail to satisfy the user's precondition.
     Preconditions can be basically anything, but most often they
     specify a range of inputs. For example, if the precondition
     is <code>(&lt; 1 x 2)</code>, then the input <code>x = 3</code> is
     invalid.</li>
-  <li>Finally, and most rarely, an output can fail to be computed in
-    some rare situations. For example, the computation <code>(/ (exp
+  <li>Finally, and most rarely, Herbie can fail to compute the output
+    for a particular input. For example, the computation <code>(/ (exp
     1e9) (exp 1e9))</code>, which divides two identical but gargantuan
-    numbers, does have an exact real-number answer (one) but that
-    exact answer can't be computed by Herbie because the intermediate
-    steps are too large. This input is also invalid.</li>
+    numbers, does have an exact real-number answer (one), but Herbie
+    can't compute that exact answer because the intermediate steps are
+    too large. This input is also invalid.</li>
 </ol>
 
 <p>Herbie's percentage accuracy metric only averages over valid

www/doc/2.0/input.html

@@ -26,10 +26,21 @@ <h1>The Input Format</h1>
     input program, and has extensive options for precisely describing
     its context.
   </p>
+
+  <h2>Math format</h2>
+
+  <p>The Herbie web shell takes input in a subset of
+  the <a href="https://mathjs.org/docs/expressions/syntax.html">math.js
+  syntax</a>. The web shell automatically checks for syntax errors,
+  and provides a graphical user interface for specifying the input
+  domain. The web shell converts the mathematical expression and input
+  ranges into FPCore before sending it to Herbie.</p>
 
-  <h2 id="sec1">General format</h2>
+  <h2 id="sec1">FPCore format</h2>
 
-  <p><a href="http://fpbench.org">FPCore</a> format looks like this:</p>
+  <p>Herbie's command-line and batch-mode tools
+  use <a href="http://fpbench.org">FPCore</a> format to describe
+  mathematical expressions. FPCore looks like this:</p>
 
   <pre>(FPCore (<var>inputs ...</var>) <var>properties ...</var> <var>expression</var>)</pre>
   <pre>(FPCore <var>name</var> (<var>inputs ...</var>) <var>properties ...</var> <var>expression</var>)</pre>
@@ -38,7 +49,6 @@ <h2 id="sec1">General format</h2>
     Each <var>input</var> is a variable name, like <code>x</code>,
     used in the <var>expression</var>. Properties are used to specify
     additional information about the <var>expression</var>'s context.
-    As of version 1.5, Herbie supports named functions.
     If <var>name</var> is specified, the function can be referenced in
     subsequent FPCore declarations in the file.
   </p>
@@ -90,13 +100,9 @@ <h2>Supported functions</h2>
 
   <p>Herbie links against your computer's <code>libm</code> to
   evaluate these functions. So, each function has the same behavior in
-  Herbie as in your code.</p>
-
-  <p>On Windows, the Bessel functions are not available in the
-  system <code>libm</code>, so Herbie will use a fallback
-  implementation and print a warning. Turn off the
-  the <kbd>precision:fallback</kbd> <a href="options.html">option</a>
-  to disable those functions instead.</p>
+  Herbie as in your code. You can instead use
+  the <a href="#precisions"><code>racket</code> precision</a> if you
+  instead want reproducible behavior.</p>
 
   <h2 id="conditionals">Conditionals</h2>
 
@@ -117,14 +123,15 @@ <h2 id="conditionals">Conditionals</h2>
     <dd>The two boolean values</dd>
   </dl>
 
-  <p>The comparison functions implement chained comparisons with more than two arguments.</p>
+  <p>The comparison functions support chained comparisons with more than two arguments.</p>
 
   <h2 id="intermediates">Intermediate variables</h2>
 
   <p>Intermediate variables can be defined
     using <code>let</code> and <code>let*</code>:</p>
 
   <pre>(let ([<var>variable</var> <var>value</var>] <var>...</var>) <var>body</var>)</pre>
+  <pre>(let* ([<var>variable</var> <var>value</var>] <var>...</var>) <var>body</var>)</pre>
 
   <p>In both <code>let</code> and <code>let*</code>,
   each <var>variable</var> is bound to its <var>value</var> and can be
@@ -145,10 +152,31 @@ <h2 id="intermediates">Intermediate variables</h2>
       values can refer to earlier variables.</dd>
   </dl>
 
-  <p>Note that Herbie treats intermediate values only as a notational
-  convenience, and inlines their values before improving the formula's
-  accuracy. Using intermediate variables will not help Herbie improve
-  a formula's accuracy or speed up its run-time.</p>
+  <p>Unless you have a lot of Lisp experience, you'll probably
+  find <code>let*</code> more intuitive.</p>
+
+  <p>Internally, Herbie treats intermediate values only as a
+  notational convenience, and inlines their values before improving
+  the formula's accuracy. Using intermediate variables will therefore
+  not produce a more accurate result or help Herbie run faster.</p>
+
+  <h2 id="specs">Specifications</h2>
+
+  <p>In some cases, your input program is an approximation of some
+  more complex mathematical expression. The <code>:spec</code> (for
+  “specification”) lets you specify the more complex ideal case.
+  Herbie will then try to modify the input program to make it more
+  accurately evaluate the specification.</p>
+
+  <p>For example, suppose you want to evaluate <code>sin(1/x)</code>
+  via a series expansion. Write:</p>
+
+  <pre>(FPCore (x)
+  :spec (sin (/ 1 x))
+  (+ (/ 1 x) (/ 1 (* 6 (pow x 3)))))</pre>
+
+  <p>Herbie will only use the <code>:spec</code> expression to
+  evaluate error, not to search for accurate expressions.</p>
 
   <h2 id="preconditions">Preconditions</h2>
 
@@ -186,41 +214,19 @@ <h2 id="precisions">Precisions</h2>
   a <a href="plugins.html">plugin system</a> to load additional
   precisions.</p>
 
-  <h2 id="conversions">Conversions</h2>
-
-  <p>Herbie supports conversions between different precisions.
-  All conversions are assumed to be bi-directional. You can
-  specify conversions with the <code>:herbie-conversions</code>
-  property.</p>
+  <p>Herbie won't produce mixed-precision code unless you allow it to
+  do so, using the <code>:herbie-conversions</code> property:</p>
 
   <dl class="function-list">
     <dt><code>:herbie-conversions<br/>([<var>prec1</var> <var>prec2</var>] ...)</code></dt>
-    <dd>If an expression is computed with precision <code>prec1</code>,
-    Herbie is allowed to rewrite all (or some) of the expression so it
-    is computed with precision <code>prec2</code> and vice versa.</dd>
+    <dd>Expressions in precision <code>prec1</code>, can be rewriten
+    to use precision <code>prec2</code>, and vice versa.</dd>
   </dl>
 
-  <p>For example, to let Herbie introduce single-precision
-  code when <code>:precision</code> is set to <code>binary64</code> or vice versa,
-  specify <code>:herbie-conversions ((binary64 binary32))</code></p>
-
-  <h2 id="specs">Specifications</h2>
-
-  <p>In some cases, your input program is an approximation of some
-  more complex mathematical expression. The <code>:spec</code> (for
-  “specification”) lets you specify the more complex ideal case.
-  Herbie will then try to modify the input program to make it more
-  accurately evaluate the specification.</p>
-
-  <p>For example, suppose you want to evaluate <code>sin(1/x)</code>
-  via a series expansion. Write:</p>
-
-  <pre>(FPCore (x)
-  :spec (sin (/ 1 x))
-  (+ (/ 1 x) (/ 1 (* 6 (pow x 3)))))</pre>
-
-  <p>Herbie will only use the <code>:spec</code> expression to
-  evaluate error, not to search for accurate expressions.</p>
+  <p>All conversions are assumed to be bidirectional. For example, if
+  you specify <code>:herbie-conversions ([binary64 binary32])</code>,
+  Herbie will be able to add conversions between single- and
+  double-precision floating-point.</p>
 
   <h2 id="properties">Miscellaneous Properties</h2>
 
@@ -245,7 +251,7 @@ <h2 id="properties">Miscellaneous Properties</h2>
 
   <p>Herbie's benchmark suite also uses properties such
   as <code>:herbie-target</code> for continuous integration, but these
-  are not supported and their use is discouraged.</p>
+  are not officially supported and their use is discouraged.</p>
 
 </body>
 </html>