Line breaks in @file{} entries?
Valentin, I'm a little puzzled by your recent patch 1b832d7 "Doc: clean up @file{} entries". In the commit description, you say you're "escaping such characters as `.', `/' or `-'." But the only thing I see in the diff are some 900 additions of @/ which is the texinfo command to allow line breaks. So now we'll get things like blah blah blah texi-langutils .py. instead of blah blah blah texi-langutils.py. So either I'm missing something, or something else is going on. Was this change discussed on -devel? If so, somehow I missed it. Thanks. - Mark ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: Line breaks in @file{} entries?
On Wed, Nov 24, 2010 at 11:30 PM, Mark Polesky wrote: > I'm a little puzzled by your recent patch 1b832d7 > "Doc: clean up @file{} entries". In the commit description, > you say you're "escaping such characters as `.', `/' or > `-'." But the only thing I see in the diff are some 900 > additions of > @/ ... Yes, I did notice that... It took me long enough :) > which is the texinfo command to allow line breaks. So now > we'll get things like > > blah blah blah texi-langutils > .py. > > instead of > > blah blah blah > texi-langutils.py. Oh, that's unfortunate indeed. I did do my homework and have a look at the texinfo manual, but I thought this was just escaped characters. Either way, the syntax wasn't quite consistent since there were some refs with @/ "escaping", others without and this wasn't mentioned in the CG at all. (dots are even "escaped" in some @uref as well!) > So either I'm missing something, or something else is going > on. Was this change discussed on -devel? If so, somehow I > missed it. No, I did consider discussing it but since the diff was almost 400Ko I couldn't send it so I just pushed it on the translations/ branch. Ok, what do we do now? We could revert my commit but it will leave the docs source code with the inconsistency I was trying to address... Another (possibly more clever?) solution is to remove all @/ before file extensions, so that such line breaks as what you mentioned can't occur anymore. Here's a patch against lilypond/translation that does just that. Can you have a look? http://dl.free.fr/hAoeLyyJq (It's too heavy for the list so I had to upload it elsewhere) Either way, we need to have a doc policy about that. Cheers, Valentin. ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: Line breaks in @file{} entries?
Valentin Villenave wrote: > I did do my homework and have a look at the texinfo > manual, but I thought this was just escaped characters. > Either way, the syntax wasn't quite consistent since there > were some refs with @/ "escaping", others without and this > wasn't mentioned in the CG at all. (dots are even > "escaped" in some @uref as well!) Keep in mind that these texinfo @-commands may not mean what you think they mean (see @. for example) : http://www.gnu.org/software/texinfo/manual/texinfo/html_node/Command-List.html >> So either I'm missing something, or something else is >> going on. Was this change discussed on -devel? If so, >> somehow I missed it. > > No, I did consider discussing it but since the diff was > almost 400Ko I couldn't send it so I just pushed it on the > translations/ branch. Can you post to Rietveld? That's the preferred code sharing location. > Ok, what do we do now? We could revert my commit but it > will leave the docs source code with the inconsistency I > was trying to address... Another (possibly more clever?) > solution is to remove all @/ before file extensions, so > that such line breaks as what you mentioned can't occur > anymore. Personally, I wouldn't want @/ anywhere in a @file, but I think the right thing to do is to revert the patch and start a discussion about what our policy should be for this case. Other developers will have their own ideas too, and we should try to agree on something before making such a change. - Mark ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: Line breaks in @file{} entries?
On Thu, Nov 25, 2010 at 07:30:20AM -0800, Mark Polesky wrote: > Valentin Villenave wrote: > > No, I did consider discussing it but since the diff was > > almost 400Ko I couldn't send it so I just pushed it on the > > translations/ branch. > > Can you post to Rietveld? That's the preferred code sharing > location. +1 also, Rietveld isn't magic. Google doesn't [yet, afaik at least] read your emails to determine if you like them or not, and cause rietveld to stop working for you if you dislike large commercial companies. If it doesn't work, then either there's something wonky with their servers, or with your client stuff. What if you tried removing git-cl and/or your lilypond directory, and starting with a fresh git checkout and a new git-cl ? What if you tried a new "throw-away" gmail account ? etc. ... then again, -1. At the moment, we're just at the "discussing policy" stage; seeing a patch which added or removed @/ in a thousand places doesn't help to clarify the discussion. > > Ok, what do we do now? We could revert my commit but it > > will leave the docs source code with the inconsistency I > > was trying to address... Another (possibly more clever?) > > solution is to remove all @/ before file extensions, so > > that such line breaks as what you mentioned can't occur > > anymore. > > Personally, I wouldn't want @/ anywhere in a @file, but I > think the right thing to do is to revert the patch and start > a discussion about what our policy should be for this case. I don't think that @/ is appropriate. Certainly not for a short @file{filename.ext}. I'm willing to entertain the notion of using them inside a @file{long/directory/location/with/filename.ext}, although my preferred solution to those would be to put them in a separate @example or @smallexample. Also, given the amount of docs which have never been reviewed with respect to the doc policy, I don't see this particular inconsistency as important. Given that the topic has been forced upon us, I guess we might as well deal with it now, but please don't go searching around for other doc syntax stuff to ask about. A lot of people have been saving up other doc syntax inconsistencies until we have a chance to discuss them all in an organzied fashion. Cheers, - Graham ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: Line breaks in @file{} entries?
On Fri, Nov 26, 2010 at 1:11 AM, Graham Percival wrote: > On Thu, Nov 25, 2010 at 07:30:20AM -0800, Mark Polesky wrote: >> Can you post to Rietveld? That's the preferred code sharing >> location. Let me see... A 300-Ko patch that affects >100 files? No way. I'm barely able to upload a 15-lines patch... > also, Rietveld isn't magic. Google doesn't [yet, afaik at least] > read your emails to determine if you like them or not, and cause > rietveld to stop working for you if you dislike large commercial > companies. I dislike large commercial companies so much that I've just uploaded my patch on a commercial file-sharing service. Yuck. > If it doesn't work, then either there's something wonky with their > servers, or with your client stuff. What if you tried removing > git-cl and/or your lilypond directory, and starting with a fresh > git checkout and a new git-cl ? What if you tried a new > "throw-away" gmail account ? etc. I've updated my git-cl and config files, but that's about as far as I'm willing to go. > then again, -1. At the moment, we're just at the "discussing > policy" stage; seeing a patch which added or removed @/ in a > thousand places doesn't help to clarify the discussion. Certainly. That was just in case Mark would have been eager to address this newline problem. > I don't think that @/ is appropriate. Certainly not for a short > @file{filename.ext}. I'm willing to entertain the notion of using > them inside a @file{long/directory/location/with/filename.ext}, > although my preferred solution to those would be to put them in a > separate @example or @smallexample. Removing them is way easier than adding them (besides adding @/ everywhere, my commit actually _added_ quite a bunch of @file entries whenever these were missing, e.g. in the CG. "programming work". > Also, given the amount of docs which have never been reviewed with > respect to the doc policy, I don't see this particular > inconsistency as important. I never said it was. Which is why I wanted to address it as quickly and discretely as possible, and pushed it elsewhere than master. > Given that the topic has been forced > upon us, I always appreciate the way you're putting things. If anything, me working solo on this was *precisely* about letting serious people deal with more important things. I'd hate to see you being "forced" into anything. If that's the way you see things, then just revert this commit already, get on with proper development topics and quit making a fuss. > I guess we might as well deal with it now, but please > don't go searching around for other doc syntax stuff to ask about. > A lot of people have been saving up other doc syntax > inconsistencies until we have a chance to discuss them all in an > organzied fashion. This looked pretty harmless to me (to be honest, it still does). The rationale was: if we're to decide that @/ can't be tolerated in @file entries, removing these will be quite easy. If we decide, however, that this is the way these must be written,... well, you get my point. (And yes, I know, Lily's source code is no bloody wiki, yadda yadda. C'mon, it's not like I'd use my git access to put pink unicorns on the home page or rewrite the tweak-engraver.cc in LOLCODE -- not that I haven't been tempted :-) Cheers, Valentin. ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: Line breaks in @file{} entries?
On Fri, Nov 26, 2010 at 02:40:35AM +0100, Valentin Villenave wrote: > On Fri, Nov 26, 2010 at 1:11 AM, Graham Percival > wrote: > > On Thu, Nov 25, 2010 at 07:30:20AM -0800, Mark Polesky wrote: > >> Can you post to Rietveld? That's the preferred code sharing > >> location. > > Let me see... A 300-Ko patch that affects >100 files? No way. I'm > barely able to upload a 15-lines patch... The problem is the network connection? That sounds very weird. I'd expect you to either not be able to connect at all, or be able to upload megabytes without problem. > > Also, given the amount of docs which have never been reviewed with > > respect to the doc policy, I don't see this particular > > inconsistency as important. > > I never said it was. Which is why I wanted to address it as quickly > and discretely as possible, and pushed it elsewhere than master. > > This looked pretty harmless to me (to be honest, it still does). Trying to sneak patches into git isn't the answer. Have you forgotten the unfortunate events with the doc input syntax patches over the summer? I haven't. > The rationale was: if we're to decide that @/ can't be tolerated > in @file entries, removing these will be quite easy. If we > decide, however, that this is the way these must be written,... > well, you get my point. I see. Well, it would have been more clear if that rationale had been in the commit message, and it would have been nice if the patch had been put up for review first. In the past few months, we've all been trying to avoid surprises in git by putting more and more things up for review. Mark: you're more familiar with texinfo than me, so could I leave the final judgement on this topic up to you? - Graham ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: Line breaks in @file{} entries?
Valentin Villenave wrote Friday, November 26, 2010 1:40 AM On Fri, Nov 26, 2010 at 1:11 AM, Graham Percival I don't think that @/ is appropriate. Certainly not for a short @file{filename.ext}. I'm willing to entertain the notion of using them inside a @file{long/directory/location/with/filename.ext}, although my preferred solution to those would be to put them in a separate @example or @smallexample. Removing them is way easier than adding them (besides adding @/ everywhere, my commit actually _added_ quite a bunch of @file entries whenever these were missing, e.g. in the CG. "programming work". I'd prefer this patch to be reverted. That way the information about the long filenames that previously contained @/s is retained, making it easier to change these to @examples (if this is indeed desirable). I never said it was. Which is why I wanted to address it as quickly and discretely as possible, and pushed it elsewhere than master. It's already been merged into master :( Trevor ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: Line breaks in @file{} entries?
On Fri, Nov 26, 2010 at 8:44 AM, Trevor Daniels wrote: > I'd prefer this patch to be reverted. That way the information about > the long filenames that previously contained @/s is retained, making > it easier to change these to @examples (if this is indeed desirable). Hmm, tricky. I get your point: in some sense, information has been lost. How really relevant was that information, however? There were some long filenames with @/ others without, and it wasn't even consistent between translations of a same file. In many files, slashes and dashes were "escaped" in the @seealso section, *but* not in the main text where these are actually needed! Besides, as I said, this patch doesn't just add @/ everywhere, it also adds quite a bunch of @file{} items (in many places where @code{} was previously used, or even nothing at all -- for example, have a look at the modifications in input.itely: http://git.savannah.gnu.org/gitweb/?p=lilypond.git;a=commitdiff;h=1b832d794f1444033f10465971e97d33f76fe310#patch42). I'm sure I can remove @/ and filter "long-ish" filenames with a regexp if needed. As Graham said, we're at the "discussing policy" stage, so I'd rather keep my commit and then bake a regexp that will apply said policy consistenly throughout the files. (That being said, even if you guys revert this commit I can still work on the modified code on a local branch, and re-push it after applying whatever regexp does the trick. But I'm afraid merging it with an up-to-date master branch afterwards, won't be a walk in the park.) Cheers, Valentin. ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: Line breaks in @file{} entries?
On Fri, Nov 26, 2010 at 11:37 AM, Valentin Villenave wrote: > I'm sure I can remove @/ and filter "long-ish" filenames with a regexp > if needed. As Graham said, we're at the "discussing policy" stage, so > I'd rather keep my commit and then bake a regexp that will apply said > policy consistenly throughout the files. Hi Trevor, Graham, everybody Here's what I'm thinking (I'll update the doc guidelines if you guys agree): @file{} entries should not contain a @/ escape sequence, unless these are long enough to justify a possible line break. Long entries are those who contain either more than one dash or more than one slash (not counting "../"). Examples: Write @file{scm/lily.scm} or @file{scm/backend-library.scm} but @file{scm/define@/-markup@/-commands.scm} or @file{input/@/regression/@/note-names.ly} [Optionally: @file{} entries in @seealso sections should not contain @/ escaping, no matter how long they are.] I've made a patch (against lilypond/translation) that does just that: http://dl.free.fr/qQQuXLyZB I'm trying to upload it on Rietveld, but I'm not sure it'll do: I'll let you know in a couple of hours :-) Cheers, Valentin. ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: Line breaks in @file{} entries?
Valentin Villenave wrote Friday, November 26, 2010 3:00 PM Here's what I'm thinking (I'll update the doc guidelines if you guys agree): @file{} entries should not contain a @/ escape sequence, unless these are long enough to justify a possible line break. Tick, as a policy statement. Long entries are those who contain either more than one dash or more that :) than one slash (not counting "../"). Examples: Write @file{scm/lily.scm} or @file{scm/backend-library.scm} but @file{scm/define@/-markup@/-commands.scm} or @file{input/@/regression/@/note-names.ly} Hhm. Not sure. I think I'd prefer "more than three dashes or slashes", if we are to do it that way, but really it depends more on the total length of the name rather than the number of dashes and slashes. I'd prefer "if the name is longer than 50 characters (say)". And if the name is too long then I'd prefer to place a single optional break near to the middle, so we don't get tiny fragments at the end or start of lines. Or as Graham suggests, use @example. [Optionally: @file{} entries in @seealso sections should not contain @/ escaping, no matter how long they are.] Tick Trevor ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: Line breaks in @file{} entries?
On 11/26/10 3:37 AM, "Valentin Villenave" wrote: > On Fri, Nov 26, 2010 at 8:44 AM, Trevor Daniels wrote: >> I'd prefer this patch to be reverted. That way the information about >> the long filenames that previously contained @/s is retained, making >> it easier to change these to @examples (if this is indeed desirable). > > Hmm, tricky. I get your point: in some sense, information has been > lost. How really relevant was that information, however? There were > some long filenames with @/ others without, and it wasn't even > consistent between translations of a same file. In many files, slashes > and dashes were "escaped" in the @seealso section, *but* not in the > main text where these are actually needed! > > Besides, as I said, this patch doesn't just add @/ everywhere, it also > adds quite a bunch of @file{} items (in many places where @code{} was > previously used, or even nothing at all -- for example, have a look at > the modifications in input.itely: > http://git.savannah.gnu.org/gitweb/?p=lilypond.git;a=commitdiff;h=1b832d794f14 > 44033f10465971e97d33f76fe310#patch42). With such a big patch, this is an example of a patch that should likely have been two patches: 1) Fix all the @file references (i.e. from @code, etc.) 2) Insert the line breaks where appropriate. Then we could have handled the two cases separately. This is something I continually have trouble with. I tend to make big patches, when I should be focusing on small patches. Not only is it easier to review, it's easier to adjust. Thanks, Carl ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: Line breaks in @file{} entries?
On 11/26/10 3:37 AM, "Valentin Villenave" wrote: > Besides, as I said, this patch doesn't just add @/ everywhere, it also > adds quite a bunch of @file{} items (in many places where @code{} was > previously used, or even nothing at all -- for example, have a look at > the modifications in input.itely: > http://git.savannah.gnu.org/gitweb/?p=lilypond.git;a=commitdiff;h=1b832d794f14 > 44033f10465971e97d33f76fe310#patch42). I looked at this patch, and the switches from @code to @file were buried in the insertion of all the @/. I think I agree with Trevor that the patch should be reverted (but I don't feel strongly enough about it to do it over your objection). Thanks, Carl ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: Line breaks in @file{} entries?
On Fri, Nov 26, 2010 at 5:28 PM, Carl Sorensen wrote: > With such a big patch, this is an example of a patch that should likely have > been two patches: > 1) Fix all the @file references (i.e. from @code, etc.) > 2) Insert the line breaks where appropriate. > Then we could have handled the two cases separately. Indeed. I realized that just afterwards :) On Fri, Nov 26, 2010 at 5:35 PM, Carl Sorensen wrote: > I think I agree with Trevor that the patch should be reverted (but I don't > feel strongly enough about it to do it over your objection). I understand it, and you would be completely right... if the existing @/ escaping had actually been consistent and meaningful in the first place (which it was really, really not). In this case, it would *certainly* be a pity to loose the information we had. If, however, we are to apply automatic substitution rules to make the syntax consistent (such as what I've been suggesting with my latest patch linked to in my former mail), then it doesn't really make a difference. A safer solution would be to remove all "@/" altogether for now. ---> Downside: we're still losing whatever information we might previously have had wrt escaped vs non-escaped @file entries (although, again, I sincerely doubt this information was more reliable and meaningful than whatever automatic rules we come up with in the future). ---> Upside: we don't lose whatever @file{} formatting I added, and this temporarily solves the line-breaks problem until we can have a more proper solution. Please have a look at the attached patch: http://dl.free.fr/pMyOkyICo (sorry about the inconvenience, but it's the only way for me to send larges patches. I did try and upload my patch on Rietveld, but git cl eventually failed with a BadStatusLine error. I'm guessing there was a server timeout at some point.) On Fri, Nov 26, 2010 at 4:47 PM, Trevor Daniels wrote: >> Long entries are those who contain either more than one dash or more > that :) >> >> than one slash (not counting "../"). Er, are you suggesting that @file{this/is/a/very/long/path/towards/myfile.scm} should be printed without a line break? > Hhm. Not sure. I think I'd prefer "more than three dashes or slashes", > if we are to do it that way, but really it depends more on the total length > of the name rather than the number of dashes and slashes. I'd prefer > "if the name is longer than 50 characters (say)". > And if the name is too long then I'd prefer to place a single optional break > near to the middle, so we don't get tiny fragments at the end or start of > lines. Both suggestions seem reasonable and easy enough to achieve. (50 chars are really long, though.) Cheers, Valentin. ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: Line breaks in @file{} entries?
On 11/26/10 10:51 AM, "Valentin Villenave" wrote: > > Please have a look at the attached patch: > http://dl.free.fr/pMyOkyICo > (sorry about the inconvenience, but it's the only way for me to send > larges patches. I did try and upload my patch on Rietveld, but git cl > eventually failed with a BadStatusLine error. I'm guessing there was a > server timeout at some point.) I like the new patch, I think. I believe that it would be preferable to do this instead of reverting the previous patch. > > On Fri, Nov 26, 2010 at 4:47 PM, Trevor Daniels wrote: >>> Long entries are those who contain either more than one dash or more >> that :) >>> >>> than one slash (not counting "../"). > > Er, are you suggesting that > @file{this/is/a/very/long/path/towards/myfile.scm} > should be printed without a line break? I am suggesting this. I would much prefer to keep file paths on one line as long as they fit. > >> Hhm. Not sure. I think I'd prefer "more than three dashes or slashes", >> if we are to do it that way, but really it depends more on the total length >> of the name rather than the number of dashes and slashes. I'd prefer >> "if the name is longer than 50 characters (say)". >> And if the name is too long then I'd prefer to place a single optional break >> near to the middle, so we don't get tiny fragments at the end or start of >> lines. > > Both suggestions seem reasonable and easy enough to achieve. > (50 chars are really long, though.) But a file name really *is* a single piece of information, so it should be kept on one line. If it's so long it won't fit on one line, then we should decide where to break it, rather than having it be done automatically at any slash. Thanks, Carl ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: Line breaks in @file{} entries?
Valentin Villenave wrote Friday, November 26, 2010 5:51 PM On Fri, Nov 26, 2010 at 4:47 PM, Trevor Daniels wrote: Long entries are those who contain either more than one dash or more that :) than one slash (not counting "../"). Er, are you suggesting that @file{this/is/a/very/long/path/towards/myfile.scm} should be printed without a line break? No I was just suggesting better English, but the spacing went awry - "that" should have been under "who" - "Long entries are those /that/ contain ...". (You once asked us to do that, IIRC :) Trevor ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: Line breaks in @file{} entries?
Carl Sorensen wrote Friday, November 26, 2010 6:43 PM On 11/26/10 10:51 AM, "Valentin Villenave" wrote: Please have a look at the attached patch: http://dl.free.fr/pMyOkyICo I like the new patch, I think. I believe that it would be preferable to do this instead of reverting the previous patch. OK; I agree. Patch looks good. Er, are you suggesting that @file{this/is/a/very/long/path/towards/myfile.scm} should be printed without a line break? I am suggesting this. I would much prefer to keep file paths on one line as long as they fit. Yes, /as long as they fit/, but fit into what? Hhm. Not sure. I think I'd prefer "more than three dashes or slashes", if we are to do it that way, but really it depends more on the total length of the name rather than the number of dashes and slashes. I'd prefer "if the name is longer than 50 characters (say)". And if the name is too long then I'd prefer to place a single optional break near to the middle, so we don't get tiny fragments at the end or start of lines. Both suggestions seem reasonable and easy enough to achieve. (50 chars are really long, though.) But a file name really *is* a single piece of information, so it should be kept on one line. If it's so long it won't fit on one line, then we should decide where to break it, rather than having it be done automatically at any slash. Ideally, yes. But who is going to look manually through all the docs? Better to do it automatically first, then fix up any that stand out as poor when we notice them. Otherwise we might have some names running over the right margin in 2.14. Don't forget we've now lost the ones that were done manually before - and some of them /were/ correct. Trevor ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: Line breaks in @file{} entries?
On Fri, Nov 26, 2010 at 10:41 PM, Trevor Daniels wrote: > OK; I agree. Patch looks good. Thanks! I've pushed this patch, and merged translation onto master (Francisco, I'll let you have a look in case I forgot something!). > Ideally, yes. But who is going to look manually through > all the docs? Er... Hello? :-) What do you think I've been doing for the past week or so? :) > Better to do it automatically first, then > fix up any that stand out as poor when we notice them. It's even easier; I can automatically grep @file{} entries that are longer than n characters, then manually decide what to do with each one individually. On Fri, Nov 26, 2010 at 10:21 PM, Trevor Daniels wrote: > No I was just suggesting better English, but the spacing > went awry - "that" should have been under "who" - "Long entries are > those /that/ contain ...". (You once asked us to do that, IIRC :) Oh, thanks! I do tend to get confused between these: "the people who", "the things that", "the things which" (does "which" even work with plural?). Thanks! Valentin. ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: Line breaks in @file{} entries?
On 11/26/10 2:41 PM, "Trevor Daniels" wrote: > Carl Sorensen wrote Friday, November 26, 2010 6:43 PM >> On 11/26/10 10:51 AM, "Valentin Villenave" >> wrote: > >>> Er, are you suggesting that >>> @file{this/is/a/very/long/path/towards/myfile.scm} >>> should be printed without a line break? > >> I am suggesting this. I would much prefer to keep file paths on >> one line as >> long as they fit. > > Yes, /as long as they fit/, but fit into what? I think the proposed 50 character limit is probably reasonable. > Hhm. Not sure. I think I'd prefer "more than three dashes or slashes", if we are to do it that way, but really it depends more on the total length of the name rather than the number of dashes and slashes. I'd prefer "if the name is longer than 50 characters (say)". And if the name is too long then I'd prefer to place a single optional break near to the middle, so we don't get tiny fragments at the end or start of lines. >>> >>> Both suggestions seem reasonable and easy enough to achieve. >>> (50 chars are really long, though.) > >> But a file name really *is* a single piece of information, so it >> should be >> kept on one line. If it's so long it won't fit on one line, then >> we should >> decide where to break it, rather than having it be done >> automatically at any >> slash. > > Ideally, yes. But who is going to look manually through > all the docs? Better to do it automatically first, then > fix up any that stand out as poor when we notice them. > Otherwise we might have some names running over the right > margin in 2.14. Don't forget we've now lost the ones > that were done manually before - and some of them /were/ > correct. I don't think we disagree here. It appeared to me that Valentin was thinking that 50 characters was too long. I am arguing that 50 characters is an appropriate maximum length. A typical optimum line length appears to be 55-75 characters, so 50 characters is most of a line. I'd totally agree with breaking file names that are too long. What automatic breaking algorithm would you propose for file names longer than 50 characters? The slash closest to the center? Thanks, Carl ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: Line breaks in @file{} entries?
On Fri, Nov 26, 2010 at 11:18 PM, Carl Sorensen wrote: > I don't think we disagree here. It appeared to me that Valentin was > thinking that 50 characters was too long. I am arguing that 50 characters > is an appropriate maximum length. A typical optimum line length appears to > be 55-75 characters, so 50 characters is most of a line. I'd totally agree > with breaking file names that are too long. What automatic breaking > algorithm would you propose for file names longer than 50 characters? The > slash closest to the center? Guys, I've fixed all @file refs that were more than 50-chars long (there were only a dozen or so, so this really was no big deal). http://git.savannah.gnu.org/gitweb/?p=lilypond.git;a=commitdiff;h=fff96cc1a95042ca4404adcc7f3d7076a83722cf Next step is to update the CG guidelines. I'll submit a patch this weekend. Thanks to both of you! Cheers, Valentin. ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: Line breaks in @file{} entries?
On 11/26/10 4:26 PM, "Valentin Villenave" wrote: > On Fri, Nov 26, 2010 at 11:18 PM, Carl Sorensen wrote: >> I don't think we disagree here. It appeared to me that Valentin was >> thinking that 50 characters was too long. I am arguing that 50 characters >> is an appropriate maximum length. A typical optimum line length appears to >> be 55-75 characters, so 50 characters is most of a line. I'd totally agree >> with breaking file names that are too long. What automatic breaking >> algorithm would you propose for file names longer than 50 characters? The >> slash closest to the center? > > Guys, > I've fixed all @file refs that were more than 50-chars long (there > were only a dozen or so, so this really was no big deal). > > http://git.savannah.gnu.org/gitweb/?p=lilypond.git;a=commitdiff;h=fff96cc1a950 > 42ca4404adcc7f3d7076a83722cf Most of these file references aren't actually more than 50 characters. They get over 50 when you include the @var{} inside the file, or in one case when the greedy regex gets a closing } at the end of the line. In my quick check, the only one that is really longer than 50 characters is the one from Learning under MacOS X. Thanks, Carl ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: Line breaks in @file{} entries?
Valentin Villenave wrote Friday, November 26, 2010 10:31 PM Thanks! I've pushed this patch, and merged translation onto master Great! Appreciated! On Fri, Nov 26, 2010 at 10:41 PM, Trevor Daniels wrote: Ideally, yes. But who is going to look manually through all the docs? Er... Hello? :-) What do you think I've been doing for the past week or so? :) Oh, I thought you were doing it with fancy regexps. No I was just suggesting better English, but the spacing went awry - "that" should have been under "who" - "Long entries are those /that/ contain ...". (You once asked us to do that, IIRC :) Oh, thanks! I do tend to get confused between these: "the people who", "the things that", "the things which" (does "which" even work with plural?). Yes, it's fine with plurals. The last two are both OK, although some maintain that "which" should only be used to introduce a parenthetical clause: "the things, which John brought, were ..." although "that" wouldn't be seriously wrong here either. But "who" is a no-no unless the subject is a real person or maybe an animal that is considered to be almost a person, like a pet. Trevor ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: Line breaks in @file{} entries?
Carl Sorensen wrote Saturday, November 27, 2010 12:03 AM On 11/26/10 4:26 PM, "Valentin Villenave" wrote: I've fixed all @file refs that were more than 50-chars long (there were only a dozen or so, so this really was no big deal). Most of these file references aren't actually more than 50 characters. They get over 50 when you include the @var{} inside the file, or in one case when the greedy regex gets a closing } at the end of the line. I don't think that matters. 50 was fairly arbitrary anyway. Adding the soft break manually as Valentin has done ensures bad breaks can't occur, even if the name is quite short. Trevor ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: Line breaks in @file{} entries?
On Sat, Nov 27, 2010 at 1:03 AM, Carl Sorensen wrote: > Most of these file references aren't actually more than 50 characters. They > get over 50 when you include the @var{} inside the file, or in one case when > the greedy regex gets a closing } at the end of the line. I know; like I said, 50 chars is *really* quite long :-) However, if we lower this threshold to 40 then we'll start getting such things as @file{ly/predefined-guitar-ninth-fretboards.ly} (I'm assuming we don't want that). There's also a matter of consistency: if we split the MacOSX command line, then it also makes sense to split the GNU/Linux one. (another example: if we were to split the predefined-guitar-ninth-fretboards, which we're not -- parenthetical clause, wink wink :) -- then we probably should split predefined-ukulele-fretboards as well, and so on.) I'm probably much of a control freak, but this @file{} syntax has been bugging me for quite some time, so I'm relieved that we're getting more consistency here :) Cheers, Valentin. ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: Line breaks in @file{} entries?
On 11/26/10 5:42 PM, "Valentin Villenave" wrote: > On Sat, Nov 27, 2010 at 1:03 AM, Carl Sorensen wrote: >> Most of these file references aren't actually more than 50 characters. They >> get over 50 when you include the @var{} inside the file, or in one case when >> the greedy regex gets a closing } at the end of the line. > > I know; like I said, 50 chars is *really* quite long :-) However, if > we lower this threshold to 40 then we'll start getting such things as > @file{ly/predefined-guitar-ninth-fretboards.ly} (I'm assuming we don't > want that). There's also a matter of consistency: if we split the > MacOSX command line, then it also makes sense to split the GNU/Linux > one. Well, I'm clearly in the minority here, so it's no problem for me. Thanks, Carl ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: Line breaks in @file{} entries?
On Fri, Nov 26, 2010 at 11:31:06PM +0100, Valentin Villenave wrote: > On Fri, Nov 26, 2010 at 10:41 PM, Trevor Daniels > wrote: > > OK; I agree. Patch looks good. > > Thanks! I've pushed this patch, and merged translation onto master What. You pushed a huge patch onto git, with only a few hours of review time. Notably, without any review or comments from Mark -- the developer who first questioned the original commit. - Graham ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: Line breaks in @file{} entries?
Graham Percival wrote Saturday, November 27, 2010 12:59 AM On Fri, Nov 26, 2010 at 11:31:06PM +0100, Valentin Villenave wrote: On Fri, Nov 26, 2010 at 10:41 PM, Trevor Daniels wrote: > OK; I agree. Patch looks good. Thanks! I've pushed this patch, and merged translation onto master What. You pushed a huge patch onto git, with only a few hours of review time. Notably, without any review or comments from Mark -- the developer who first questioned the original commit. I don't think that was unreasonable. This was correcting an equally big patch which we all agreed was wrong, and which was already in master. It was equivalent to reverting the bad patch, but without destroying the good bits within it. Both Carl and I had approved it. The reprehensible behaviour was pushing the first big patch without review, not the second. Trevor ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: Line breaks in @file{} entries?
On Sat, Nov 27, 2010 at 8:30 AM, Trevor Daniels wrote: > > I don't think that was unreasonable. This was correcting > an equally big patch which we all agreed was wrong, and > which was already in master. It was equivalent to reverting > the bad patch, but without destroying the good bits within > it. Both Carl and I had approved it. Once bitten, twice shy. I would have been happier if the patch had been up for review for at least 24 hours, to give developer in all time zones a chance to comment. I've asked Carl and Mark to delay pushing patches for that reason -- even when the patch had already gone through 5 revisions! If there is a hint of contention, then it seems to me that 24 hours is not a long time to wait. Cheers, - Graham ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: Line breaks in @file{} entries?
On Sat, Nov 27, 2010 at 10:32 AM, Graham Percival wrote: > Once bitten, twice shy. I would have been happier if the patch had > been up for review for at least 24 hours, to give developer in all > time zones a chance to comment. I've sent not one, but *three* patches for "review" successively. If by "review" you mean "Rietveld", then no, there's no way in hell I'll upload a patch that affects more than 100 files. That's why I didn't upload the very first patch in the first place. > I've asked Carl and Mark to delay pushing patches for that reason -- > even when the patch had already gone through 5 revisions! If there is > a hint of contention, then it seems to me that 24 hours is not a long > time to wait. As Trevor said, it was more about reverting things than anything else. Carl: I do get your point, and you're right that @file entries that contain a @var or something like that shouldn't necessarily be treated as "long" entries. Please don't think your objection was disregarded at all; I promise I'll have a thorough look once the new docs are online, and adjust things (I mean, submit patches :) if needed. Cheers, Valentin. ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: Line breaks in @file{} entries?
Le 26/11/2010 23:18, Carl Sorensen disait : On 11/26/10 2:41 PM, "Trevor Daniels" wrote: Carl Sorensen wrote Friday, November 26, 2010 6:43 PM On 11/26/10 10:51 AM, "Valentin Villenave" wrote: Er, are you suggesting that @file{this/is/a/very/long/path/towards/myfile.scm} should be printed without a line break? I am suggesting this. I would much prefer to keep file paths on one line as long as they fit. Yes, /as long as they fit/, but fit into what? I think the proposed 50 character limit is probably reasonable. Hhm. Not sure. I think I'd prefer "more than three dashes or slashes", if we are to do it that way, but really it depends more on the total length of the name rather than the number of dashes and slashes. I'd prefer "if the name is longer than 50 characters (say)". And if the name is too long then I'd prefer to place a single optional break near to the middle, so we don't get tiny fragments at the end or start of lines. Both suggestions seem reasonable and easy enough to achieve. (50 chars are really long, though.) But a file name really *is* a single piece of information, so it should be kept on one line. If it's so long it won't fit on one line, then we should decide where to break it, rather than having it be done automatically at any slash. Ideally, yes. But who is going to look manually through all the docs? Better to do it automatically first, then fix up any that stand out as poor when we notice them. Otherwise we might have some names running over the right margin in 2.14. Don't forget we've now lost the ones that were done manually before - and some of them /were/ correct. I don't think we disagree here. It appeared to me that Valentin was thinking that 50 characters was too long. I am arguing that 50 characters is an appropriate maximum length. A typical optimum line length appears to be 55-75 characters, so 50 characters is most of a line. I'd totally agree with breaking file names that are too long. What automatic breaking algorithm would you propose for file names longer than 50 characters? The slash closest to the center? Thanks, Just one comment: Don't forget that @file{how-do-you-feel-I-am-so-so} might not begin on the same column with every translated version of the documentation. I would therefore appreciate to have some consistency in the "splitting allowance", or to let it dealt by translators. Cheers, Jean-Charles ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel