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

[Werner LEMBERG]

>> > 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.
> 
> Hmm.  The next question would be "how important is it to avoid (or
> permit?  I've lost track of what we're doing here) line-breaks for
> slashes"?  I'm not certain that it's worth fiddling with this.

Well, it helps in situations like this

     This is a  paragraph with  some text to
     demonstrate  that  a  path  name   like
     /usr/local/share/lilypond/foo.bar
     should be split after backslashes.

which looks better with a break after the backslash:

     This is a  paragraph with  some text to
     demonstrate that a path name like /usr/
     local/share/lilypond/foo.bar should  be
     split after backslashes.

The much worse situation is this

     This is a  paragraph with  some text to
     demonstrate  that  a  path  name   like
     /usr/local/share/lilypond/longfilename.itely
     should be split after backslashes.

which gets improved to

     This is a  paragraph with  some text to
     demonstrate that a path name like /usr/
     local/share/lilypond/longfilename.itely
     should be split after backslashes.

> I mean, if I were writing any docs these days, I would not
> personally bother with the /@/ format.

Alas, most people don't care about formatting, and this can be seen in
zillion badly aformatted documents in the internet.  Is this desired?

> With that in mind, I can't find it in myself to reject other
> doc-patches for not using /@/.

Of course not!  It's an additional means to improve legibility in the
PDF.  Ragged-right documents don't really need this.

> If that's the case, then is it really a step forward to half
> inconsistent doc source in this respect?  That would confuse
> inexperienced (i.e. less than 2 years) doc editors.

Look, I'm walking over the docs to fix such instances.  I haven't said
that adding `@/' is a mandatory thing.  If an inexperienced doc editor
stumbles across `@/', she will look it up once, the she knows what it
is good for.  If she forgets to use it, it doesn't matter.  Where's
the problem?

>> 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...
> 
> I don't accept this as a general principle.  What if we could
> produce excellent-looking documentation by moving to raw tex?

This is a bad argument, and you know that :-)  We want good HTML at
the same time.

> I think it's already a bit too hard to get involved in doc work.  I
> mean, just look at James!  He's spent almost two years learning this
> stuff, but he still doesn't feel terribly confident.

You are mixing apples and oranges.  Most issues I see discussed here
are related to producing good contents, and this is OK.  My main
concern with my recent patches is *not* contents but formatting.


    Werner