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

2011-09-05 Thread Graham Percival
On Tue, Aug 23, 2011 at 07:57:32AM +0200, Werner LEMBERG wrote: > > > This is a paragraph with some text which states that it might be a > > good idea for a user to look in: > > > > @example > > /usr/local/share/lilypond/foo.bar > > @end example > > I strongly disagree. While it might be OK for

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

2011-08-23 Thread Janek Warchoł
2011/8/21 Graham Percival : > On Fri, Aug 19, 2011 at 07:32:20AM +0200, Werner LEMBERG wrote: >> 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

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

2011-08-22 Thread Werner LEMBERG
>> Well, it helps in situations like this > ... >> 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. > > Really?!

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

2011-08-22 Thread Graham Percival
On Sun, Aug 21, 2011 at 07:13:30AM +0200, Werner LEMBERG wrote: > Well, it helps in situations like this ... > 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 sh

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

2011-08-21 Thread Werner LEMBERG
>> 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 sensible,

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

2011-08-21 Thread Trevor Daniels
David Kastrup wrote Sunday, August 21, 2011 9:33 AM "Trevor Daniels" writes: changing "and/or" to "and/@/or" is bad (one you changed recently.) Splitting such short strings will make little difference to the layout, and I would argue that placing the "/or" at the start of a new line render

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

2011-08-21 Thread David Kastrup
"Trevor Daniels" writes: > Werner LEMBERG wrote Sunday, August 21, 2011 6:13 AM > >> 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 backsl

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

2011-08-21 Thread Trevor Daniels
Werner LEMBERG wrote Sunday, August 21, 2011 6:13 AM 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 afte

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

2011-08-20 Thread Werner LEMBERG
>> So we need either #foo and ##t or foo and #t. We should never mix those. > > Don't tell me; tell the documentation. It's already there. > Or are there any other volunteers? Obviously, I volunteered to walk over all instances to clean this up... Werner ___

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

2011-08-20 Thread 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

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

2011-08-20 Thread Trevor Daniels
Graham Percival wrote Saturday, August 20, 2011 11:29 PM So we need either #foo and ##t or foo and #t. We should never mix those. Don't tell me; tell the documentation. It's already partially covered: http://www.lilypond.org/doc/v2.15/Documentation/learning/modifying-context-properties T

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

2011-08-20 Thread Graham Percival
On Sat, Aug 20, 2011 at 04:21:38PM -0600, Carl Sorensen wrote: > On 8/20/11 4:16 PM, "Graham Percival" wrote: > > > Hmm. I still have no clue about the difference between #t and > > #foo, which certainly emphasizes that there *is* confusion. > > #t is a Scheme value, as is foo > > ##t is a lil

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

2011-08-20 Thread Graham Percival
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? >

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

2011-08-20 Thread Carl Sorensen
On 8/20/11 4:16 PM, "Graham Percival" wrote: > Hmm. I still have no clue about the difference between #t and > #foo, which certainly emphasizes that there *is* confusion. #t is a Scheme value, as is foo ##t is a lilypond input value to get the scheme value #t #foo is a lilypond input value t

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

2011-08-20 Thread Graham Percival
On Fri, Aug 19, 2011 at 07:32:20AM +0200, Werner LEMBERG wrote: > > > Please read: > > http://lilypond.org/doc/v2.15/Documentation/contributor/lilypond-formatting > > in particular the point about #. ... > I interpret as being used for inline samples and the like. Ah, good point! I glanced at th

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

2011-08-18 Thread Trevor Daniels
Werner LEMBERG wrote Friday, August 19, 2011 6:38 AM 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', o

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

2011-08-18 Thread Werner LEMBERG
> 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 us

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

2011-08-18 Thread 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

not all doc "clean-ups" are good

2011-08-18 Thread Graham Percival
Hi Werner, Please read: http://lilypond.org/doc/v2.15/Documentation/contributor/lilypond-formatting in particular the point about #. I am willing to reconsider this policy if you make a good argument against it, but please revert 2763b2de261e4f6263e2d4751b45d7c40f1ef7ea until/unless there is an