subject:"Re\: Line breaks in @file\{\} entries\?"

On Fri, Nov 26, 2010 at 8:44 AM, Trevor Daniels t.dani...@treda.co.uk 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
valen...@villenave.net 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 valen...@villenave.net wrote:

 On Fri, Nov 26, 2010 at 8:44 AM, Trevor Daniels t.dani...@treda.co.uk 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 valen...@villenave.net 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 c_soren...@byu.edu 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 c_soren...@byu.edu 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 t.dani...@treda.co.uk 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 valen...@villenave.net 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 t.dani...@treda.co.uk 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 
t.dani...@treda.co.uk 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 smile  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 
valen...@villenave.net 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 t.dani...@treda.co.uk 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 t.dani...@treda.co.uk wrote:
 No smile  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 t.dani...@treda.co.uk wrote:
 Carl Sorensen wrote Friday, November 26, 2010 6:43 PM
 On 11/26/10 10:51 AM, Valentin Villenave
 valen...@villenave.net 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 c_soren...@byu.edu 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 valen...@villenave.net wrote:

 On Fri, Nov 26, 2010 at 11:18 PM, Carl Sorensen c_soren...@byu.edu 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 
t.dani...@treda.co.uk 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 smile 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 valen...@villenave.net 
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 c_soren...@byu.edu 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?