MBX Tip #1.  Use cheat sheets

This is the first of an irregular series of (hopefully) helpful
advice about using MathBook XML.

Looking back at the April workshop at AIM, it struck me that
the most difficult activity for many people was learning to
use git.  If I had to lead that session again, there are two
things I would have done differently.

The first is to make sure everyone was really using the git
cheat sheet.  Appendix D of the "Git for authors" document is
a cheat sheet for the typical steps you use to contribute to
a large project on GitHub.  As I replay that day in my mind,
I do not recall seeing most people using the cheat sheet.
As an experienced programmer, I understand the value of a cheat
sheet, and I used my own hand-written GitHub cheat sheet for
at least a year.  It wasn't until I started helping other people
to use git that I stopped needing it -- and that was only because
I had memorized it from repetition.

Note that I said "memorize," not "understand."  I still don't feel
that I really understand git, and if I encounter a situation
outside the usual development cycle then I need to look things up
or ask an expert.  But I don't need to understand git: I just need
to repeatedly do the same routine steps.

So, use a cheat sheet.  Start with the version in Git For Authors,
and then annotate it for your own use.  For example, if using the
terminal (command line prompt) is new to you, then you may need to
add some additional notes about using the command line.

What is the other thing I would do differently?  That will be the
topic of my next MBX Tip.

===============

MBX Tip #2.  Arrange your windows like a pro

Most of you work on a large computer screen.  Even most laptops have
enough room that you can have two windows open at once.  As I am typing
this in one terminal window, next to it I can part of a web browser,
and just below this terminal window I can see the bottom few lines
of another terminal window.

You could have a similar arrangements of windows when you are
writing a document in MBX.  If you are in the habit of "maximizing"
the window you are working in -- making it fill the screen, then you
are adding a huge amount of overhead to your work.  Every time you
have to switch tasks it adds a few seconds and some extra mouse clicks.
Those add up to a lot of wasted time and mental fatigue.

Consider the cycle:
1) Modify MBX file
2) Re-run xsltproc
3) Look at new HTML version of document (recall the advice to use the
   HTML version instead of the PDF version for development!)
4) Go back to 1)

If you have the windows arranged as I described above, then going from
1) to 2) just involves clicking your mouse on a large target, hitting
"up arrow" and "return".  Going from 2) to 3) just involves clicking
on a large target, and then clicking "reload".  And doing 4) is just
one click on a large target.

Those steps are much faster than anything that involves pulling down
a menu or typing a command.

You should also figure out how to have multiple "desktops" on you
computer.  That way you can have your windows set up for MBX
development, and those can stay set up always.  Those windows don't
add clutter when you are doing other work, and your MBX desktop is
clean and just has the minimum needed for writing your book.


===============

MBX Tip #3. Theorems often have introductions or conclusions

Consider these fictional extracts from math textbooks:

Example 1 ------------

The following is a generalization of Theorem~\ref{thm:abcd}.

\begin{theorem}
If $a$ is even and $b$ is odd then $a+b$ is odd.
\end{theorem}

Example 2 -------------

\begin{definition}
We say that $f$ is \emph{continuous at} $a$ if
$\lim_{x\to a} f(x) = f(a)$.
\end{definition}

Note that the limit in the definition is equivalent to three
things:
\begin{enumerate}
\item $\lim_{x\to a} f(x)$ exists,
\item $f(a)$ exists, and
\item those two values are equal.
\end{enumerate}

Also recall also that the existence of $\lim_{x\to a} f(x)$ means
that the limits from both the left and the right exist, and those
two limits are equal.

------------------

What the examples have in common is material that is closely
associated to the theorem/definition, even though it is not part
of the statement of the theorem/definition.  That situation is
captured by the "introduction" or the "conclusion" in MBX.
The first example could be translated to MBX as

-------

<theorem>
<introduction>
<p>
The following is a generalization of <xref ref="thm_abcd">Theorem</xref>.
</p>
</introduction>
<statement>
<p>
If $a$ is even and $b$ is odd then $a+b$ is odd.
</p>
</statement>
</theorem>

------

The second example would have a statement and a conclusion (and
\emph{continuous at} would become <term>continuous at</term>).

How do you know if you should put some material in the introduction
or the conclusion?

1) If you were going to move that theorem/definition to another location
in your book, would you also need to move the paragraph before or after
that theorem/definition?

2) If someone were going to assemble a new document from pieces of
several other documents, would they find it helpful to include
those other paragraphs?

3) When in doubt, put material in an introduction or conclusion,
instead of having it in disembodied paragraphs that just happen to
appear before or after the theorem/definition.  The visual appearance
in the current LaTeX or HTML version will probably be the same, but you
are adding valuable semantic information to the document, and that
will be useful in the future.