Re: not all doc "clean-ups" are good

[Werner LEMBERG]

> Please read:
> http://lilypond.org/doc/v2.15/Documentation/contributor/lilypond-formatting
> in particular the point about #.

I did that.  And there I can find

  Try to avoid using #' or #` within when describing context or layout
  properties outside of an @example or @lilypond, unless the
  description explicitly requires it.

This paragraph

  All context or layout object strings should be prefaced with #.
  Again, LilyPond does not strictly require this, but it is helpful to
  get users accustomed to this scheme construct, i.e. \set
  Staff.instrumentName = #"cello"

I interpret as being used for inline samples and the like.

Please be more specific what I'm missing.  In particular, many
locations which I've fixed (at least in my opinion) were talking
about, say, `#t' and `#foo' at the same time, which I consider *very*
confusing.  There are two possiblities to fix it: Either by saying
`#t' and `foo', or by saying `##t' and `#foo'.  I've decided to use
the former, following the advice in the paragraph I've cited first in
this email.

> I'm also not convinced that the "insert breakpoints after slashes"
> is a great change.  This makes the documentation source look
> really cludgy; is there no way that the breakpoints could be
> specified automatically?

No, there isn't.  This would ask for making the `/' character `active'
(using the technical term from TeX), and such issues are very fragile
within texinfo.tex.  Additionally, there are situations where you
don't want a break after `/', like in `4/4'.  How to tell that to
texinfo.tex?

Actually, slashes should be completely avoided within normal prose,
AFAIK, but I did it the quick way to improve PDF layout.  This is
debatable, of course.  Maybe there is a native speaker who could
remove many of the `/@/' stuff by reformulating the affected phrases
if possible?

In my opinion, the primary goal is to produce excellent documentation
in the *target output*, right?  This means that the resulting PDF and
HTML should be excellent, and we should do everything to reach this
goal.  To do so, I accept some cludginess in the documentation...

For example, this is one of the main reasons I very much dislike
documentation in DocBook format, since it is extremely hard (and
sometimes even impossible) to produce good looking PDF output without
postprocessing which is acceptable from a typographical point of view.

BTW, a newer texinfo.tex version does automatic breaks within links.
We can use this as soon as the recently reported slash bug in indices
has been fixed -- Karl Berry is already working on this.  If this gets
installed, we can then remove all occurrences of @/ within @url and
@uref.


    Werner