#17 Changes to Documentation Section 3

[Charles Brockman]

I suggest that the items in section 3.5, Hint & Tips,
be distributed to other parts of the documentation
where they may be found with related text.

1. The first item, "MSS comes with a few documented
sample programs..." should be moved to a new part of
section 3, which might be, called "Samples and Test
Programs."

2. The "Keep in mind that all the values.." item should
be moved to a new part of section 3 called "Output
Generated by MSS." That new part should also contain
the last paragraph now in section 3.1 starting with
"Every call to new..." which is not about configuring a
program to use MSS.

3. The next two items in section 3.5, "Be careful about
disk space..." and "Always remember what options..."
should be in the "Output Generated by MSS" section or
perhaps a new section titled "Cautions to Observe When
Examining MSS Output."

4. The next two items, "If you only want to discover
hidden bugs..." and "If your program crashes..." might
be placed in a new "Interpreting the MSS Output" section.

5. The item beginning with "Remember, you must put the
#include <mss.h>..." is really a mess. The first
sentence belongs in section 3.1. Reading the rest of
the item is like slogging through a tropical rain
forest with a machete. I would create a new section
titled "Removing MSS" or "Disabling MSS." In that
subsection there should be two divisions: one for C and
another for C++.

Here's my first draft:
3.x Disabling MSS. If you want to stop using MSS,
either delete all occurrences of #include <mss.h> or
remove the #define MSS.
3.x.1 C Programs. Removing the link to the MSS library
is optional. To disable MSS, remove the #define MSS.
3.x.2 C++ Programs. In addition to removing all
appearances of #include <mss.h> or the #define MSS, be
sure to remove the link to the MSS library from your
project.

It might be less confusing to the user if there are
fewer options. Something like:
3.x Disabling MSS. If you want to temporarily disable
MSS, comment out the #define MSS and remove the link to
the library. To permanently remove MSS, also remove all
occurrences of #include <mss.h>.

The remaining sentences of this item beginning with "If
you forget putting #include <mss.h>..." should be moved
to the "How to Make a Program Use MSS" section.

The last item of section 3.5 ("Please, if you use
MSS...") might be better in section 6.1, Contacting the
Authors.