[racket-dev] New error messages for *SL

At Wed, 6 Jul 2011 05:59:30 -0400, Guillaume Marceau wrote:
> [3]    There is a layout problem in my new documentation I need help with.
>  I
>       tried to abstract the common text between the documentation of the
>       different levels.

It's possible that the HtDP languages should be different in this
respect than the rest of the documentation, but duplicating text during
a document build is generally against our documentation style
guidelines.

When text is duplicated programmatically, the content has a single
point of control, but readers of the documentation have to read
everything multiple times. For example, the fact that ISL's `cond' is
the same as BSL's `cond' is probably interesting to a reader of the
documentation, but this fact now can be determined only by comparing
the copied text of the two `cond' documentations. More generally, it's
now more difficult to determine how the languages differ.

For typical documentation, short boilerplate is ok to duplicate, such
as "Strong muon fields interefere with this function's result; see
section 5 for more information." Otherwise, if X is the same as Y, it's
better to put literally "X is the same as Y" in the documentation and
let a hyperlink do its job, instead of duplicating the description of
X.

In the case of the HtDP languages, was the choice to duplicate all the
text deliberate, or was it a side-effect of some other change?