Make a small book
=================

A site is a graph of documents. A book needs a reading order.
A ``toctree`` supplies both.

Add a chapter
-------------

Create ``notes/measurement.rst``:

.. code-block:: rst

   Measurement
   ===========

   A measurement has a value and a unit.
   Write both. A bare number leaves the reader guessing.

   .. _measurement-units:

   Units
   -----

   Keep one unit within a comparison.

Replace the contents of ``notes/index.rst`` with:

.. code-block:: rst

   Field Notes
   ===========

   These notes explain how to make a comparison that another person can check.

   .. toctree::
      :maxdepth: 2
      :numbered:

      measurement

   Begin with :doc:`measurement`.
   For the unit rule, see :ref:`measurement-units`.

The document name omits ``.rst``. The label names an idea within a document.
Use a document link for a chapter. Use a label for a particular argument.

Add a diagram
-------------

Put this in ``measurement.rst``:

.. code-block:: rst

   .. graphviz::
      :caption: A comparison needs a common unit.
      :alt: Values are converted to one unit before they are compared.

      digraph comparison {
        rankdir=LR;
        "values" -> "common unit" -> "comparison";
      }

Guidedog uses its linked Graphviz library. The result is an SVG in HTML
and an image in the PDF. No browser diagram interpreter is needed.
A caption explains the conclusion. Alternative text explains the drawing.

Build the book
--------------

.. code-block:: sh

   guidedog build html notes -W
   guidedog build pdf notes -W

The chapter is in the sidebar and in the book's contents.
Follow the section link in the browser. Inspect its destination in the PDF.

The next useful step is :doc:`../topics/writing`.
Keep chapters small enough to explain one subject.