[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: not all doc "clean-ups" are good
From: |
Werner LEMBERG |
Subject: |
Re: not all doc "clean-ups" are good |
Date: |
Sun, 21 Aug 2011 07:13:30 +0200 (CEST) |
>> > 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