On Fri, Aug 19, 2011 at 07:32:20AM +0200, Werner LEMBERG wrote: > > > 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. I mean, if I were writing any docs these days, I would not personally bother with the /@/ format. With that in mind, I can't find it in myself to reject other doc-patches for not using /@/. 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. > Actually, slashes should be completely avoided within normal prose, ... > Maybe there is a native speaker who could remove many of the > `/@/' stuff by reformulating the affected phrases if possible? Hmm. I agree for the more formal "technical reference" sections, but I would prefer to leave them in the "chattier" Learning manual. > 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? Our pool of possible doc editors would instantly shrink by 90%; I do not think that is a good plan for long-term *maintained* documentation. 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. Yes, his background is windows rather than linux -- but approximately half of our new developers in the past 4 years come from that background. Our docs are stagnating badly. I've been hoping to have the Grand Documentation Project 2 in the "near future", but at the moment it looks like it's a choice of GLISS vs. GDP 2. There's just too many emergencies that keep on cropping up. :( Cheers, - Graham _______________________________________________ lilypond-devel mailing list [email protected] https://lists.gnu.org/mailman/listinfo/lilypond-devel
