Adds incipit section to NR

Incipit command added to property-init.ly.  Initial documentation created in the NR.  This will require further work to fix issue 3981.

[PhilEHolmes, 2014-06-29 13:51:33]

Please review.

[dak, 2014-06-29 14:44:59]

https://codereview.appspot.com/108270043/diff/1/Documentation/notation/ancien...
File Documentation/notation/ancient.itely (right):

https://codereview.appspot.com/108270043/diff/1/Documentation/notation/ancien...
Documentation/notation/ancient.itely:2663: incipit =
That's nothing belonging in the manual proper.  It is an ad-hoc recipe.  Those
belong in the snippets.

Incidentally, we have an \endincipit command in ly/property-init.ly.  It is not
(or no longer) documented, it is not (or no longer) used anywhere, and it
probably does not (or no longer) work.

Like so much of our old history, the corresponding commit message is absolutely
unrelated to the commit content:

commit 3e69ea97654a3992b7411b2979c20fdc18845e2c
Author: Han-Wen Nienhuys <hanwen@xs4all.nl>
Date:   Fri Apr 16 13:04:33 1999 +0200

    release: 1.1.40

appears to be where it has been introduced, and it has been moved around
afterwards a lot.

Doing git show 3e69ea97654a3992b7411b2979c20fdc18845e2c:input/test/incipit.ly
delivers
%{
 Test of how to make an ``incipit'' to indicate scordatora 
 tuning of a violin part, using the clefStyle property.
 The two first bars of Biber's Rosary sonata III.

   /Mats B
%}

\version "1.0.14";

incipit = \notes\relative c'{
  <b1 fis' b d>
}

violin = \notes\relative c''{
  \specialkey \keysignature f' fis'' g' gis'';
  \time 2/2;

  a4. b8 c4 fis |
  gis~ gis8 fis16^\trill ()e b8 c \type Staff<{\voiceone a d}{\voicetwo es,4}>|
}

BC  = \notes\relative c{
  \key D;
  \time 2/2;
  \clef "bass";

  b2. cis4 | 
  d e fis g |
}

\score{
  \notes{
    \type Staff=violin
    \property Staff.clefStyle = "transparent" 
      \incipit 
    < \type Staff=violin { 
      \bar ".|"; \endincipit
      \violin}
      \type Staff=cb { \property Staff.clefStyle = "transparent" 
      \bar ".|";  \endincipit 
      \BC}>
  }
  \paper{
    \translator{\StaffContext
      timeSignatureStyle = "C";
    }
  }
}  

So what we see here is a reasonably straightforward syntax and usage in version
1.0.14 of LilyPond (with a lot of nostalgia-inducing old syntax around it), and
apparently half the implementation (or more likely its non-functional corpse)
survived into the current source.

It may or may not have been as flexible as what you pasted here from a current
snippet.  But it was a confined and encapsulated solution in functionality and
call.  *That* is what belongs in the NR proper rather than in snippets.

I don't know when or how \incipit in that form died.  It is likely that it has
been dead and removed long enough that the name is free for the taking these
days without the need to adhere to the previous syntax.

But whether or not we'll try it with the original syntax: what belongs in the NR
is a proper, simple to use command that is available by default.

Incipits are common enough that we want to have them in the manual, sure, but as
a reasonably usable and maintained command rather than a wagonload of snippet
code.

The current proposal is much worse for the end user than what we head in version
1.0.14 or at least 1.1.40 (assuming that the version header has not been
properly updated).

That's embarrassing, to say the least.  At any rate, the snippet code does not
belong in NR proper.  Incipit functionality does, but not as a snippet.  This
needs to become a usable command out of the box again.

[email_philholmes.net, 2014-06-29 15:15:51]

----- Original Message ----- 
From: <dak@gnu.org>
To: <PhilEHolmes@googlemail.com>
Cc: <lilypond-devel@gnu.org>; <reply@codereview-hr.appspotmail.com>
Sent: Sunday, June 29, 2014 3:44 PM
Subject: Re: Adds incipit section to NR (issue 108270043 by 
PhilEHolmes@googlemail.com)


>
>
https://codereview.appspot.com/108270043/diff/1/Documentation/notation/ancien...
> File Documentation/notation/ancient.itely (right):
>
>
https://codereview.appspot.com/108270043/diff/1/Documentation/notation/ancien...
> Documentation/notation/ancient.itely:2663: incipit =
> That's nothing belonging in the manual proper.  It is an ad-hoc recipe.
> Those belong in the snippets.

> Incipits are common enough that we want to have them in the manual,
> sure, but as a reasonably usable and maintained command rather than a
> wagonload of snippet code.

> That's embarrassing, to say the least.  At any rate, the snippet code
> does not belong in NR proper.  Incipit functionality does, but not as a
> snippet.  This needs to become a usable command out of the box again.

Well, it seems to me you're not considering why the snippets in the LSR are 
there.  The CG says "A subset of these examples are automatically imported 
into the documentation, making it easy for users to contribute to the docs 
without learning Git and Texinfo." - so the snippets are designed to allow 
users who can't push doc changes to the repo a chance to add documentation 
to the manuals.  Nothing to do with the sort of code, simply an alternative 
route.

When I wanted a usable incipit, I went straight to the section of the NR 
headed "Incipits" because I've worked out this is a good way of getting 
usable code.  Unfortunately it said "TBC" which was as useful as a chocolate 
teapot.  I eventually found this code, which does what I want, in the 
snippets/new directory.

Therefore I have created documentation to show how to produce 
standard-looking incipits quickly and simply.  Had it been there when I 
wanted it, it would have saved me a lot of time.

Please feel free to correct errors in what I have contributed, but as a 
major user of the ancient music capabilities, I am convinced this section 
should be there.  If the code is taken into the code base I'd be happy to 
update this section of the NR.

--
Phil Holmes 

[dak, 2014-06-29 16:26:26]

On 2014/06/29 15:15:51, email_philholmes.net wrote: 
> From: <mailto:dak@gnu.org>
> To: <mailto:PhilEHolmes@googlemail.com>
> Cc: <mailto:lilypond-devel@gnu.org>;
<mailto:reply@codereview-hr.appspotmail.com>
> Sent: Sunday, June 29, 2014 3:44 PM
> Subject: Re: Adds incipit section to NR (issue 108270043 by 
> mailto:PhilEHolmes@googlemail.com)
> 
> > Incipits are common enough that we want to have them in the manual,
> > sure, but as a reasonably usable and maintained command rather than a
> > wagonload of snippet code.
> 
> > That's embarrassing, to say the least.  At any rate, the snippet code
> > does not belong in NR proper.  Incipit functionality does, but not as a
> > snippet.  This needs to become a usable command out of the box again.
> 
> Well, it seems to me you're not considering why the snippets in the LSR are 
> there.  The CG says "A subset of these examples are automatically imported 
> into the documentation, making it easy for users to contribute to the docs 
> without learning Git and Texinfo." - so the snippets are designed to allow 
> users who can't push doc changes to the repo a chance to add documentation 
> to the manuals.  Nothing to do with the sort of code, simply an alternative 
> route.

And we have a standard way to include snippets contributed in that manner, using
the @snippets command.  That's not what you are doing here.  You are doing a
copy&paste section into the NR files themselves.  That separates the ties
between the snippets maintained in the LSR and the code listed in the NR.  Where
we are talking about snippets documenting a basic feature that was lacking
documentation in the manual, that is a reasonable way forward.

But that's not what we are talking about here.  We are talking about a complex
(though somewhat straightforward) bout of code.  In the manual proper, it would
have sort of a reason to be in an "extending LilyPond" section.

But code defining a music function does not belong in any part of the basic
manual except those parts dealing with using music functions for extending
LilyPond.  The main body of the reference manual is not a "tricks & tips"
collection.  That's what the snippets are for, and we have a standard way to
include snippets in the manual.

> When I wanted a usable incipit, I went straight to the section of the NR 
> headed "Incipits" because I've worked out this is a good way of getting 
> usable code.  Unfortunately it said "TBC" which was as useful as a chocolate 
> teapot.  I eventually found this code, which does what I want, in the 
> snippets/new directory.

So if it does what you want in a basic manner, it belongs into LilyPond.  Once
it is in LilyPond, its use needs to be documented.  What you are documenting
here is not a feature of LilyPond, but a shortcoming.

One can actually use snippets for that, using @snippet.  But that's not what you
do.

> Therefore I have created documentation to show how to produce 
> standard-looking incipits quickly and simply.

No, you haven't.  You have created documentation that shows how to produce
standard-looking incipits with a lot of effort.  Basically consider the manual
to be printed as a book.  Whenever you need to type off oodles of opaque code
that does not match the level that the chapter is supposed to be explaining, you
are likely to get mistakes into them.

> Had it been there when I wanted it, it would have saved me a lot of time.

Then place it in the @snippets section of the respective chapter.  Or put it
there where you'd indeed want it, namely into LilyPond's code and then document
it as being there.

Anything that is in the manual outside of a @snippet section describes a feature
that is supported and will get upgraded when using convert-ly.  Humongous
bunches of mixed Scheme and LilyPond code in general don't carry any such
guarantee.

> Please feel free to correct errors in what I have contributed, but as a 
> major user of the ancient music capabilities, I am convinced this section 
> should be there.

This section should be documenting an existing facility.  The *feature* should
be there, and yes, it *should* be documented and supported.  A code dump of
unsupported code outside of the @snippets section of a chapter does not belong
there.

Perhaps it would make sense if you first rewrote the chapter under the pretense
that incipits are available with the most practical and useful interface you can
imagine.

And when everybody agrees "oh man, _that's_ just what we need", then we'll take
care that we make it available in that manner.

The current example, in spite of its use of a music function, still seems rather
opaque.  It may be that the example is not structured well, it may be that the
interface of the music function has not been chosen well.

So please try writing the documentation pretending that we have the best
imaginable interface to incipits you can imagine.  The code I quoted for use
with version 1.0.14 was quite straightforward.  It probably did not allow
switching in entirely different staff types.

So how should it look like?

\incipit MensuralStaff \with { xxx=yyy } { \time 3/2 ... } translating into a
set of \once\override for instrumentName and the related properties?  With \with
... being optional?

Would that fit the bill for creating straightforward input with incipits?  The
stuff where you don't need a copy&paste from the manual, and after having it
looked up three times or so, don't need to look at the manual either?

[email_philholmes.net, 2014-06-29 16:51:06]

----- Original Message ----- 
From: <dak@gnu.org>
To: <PhilEHolmes@googlemail.com>; <email@philholmes.net>
Cc: <lilypond-devel@gnu.org>; <reply@codereview-hr.appspotmail.com>
Sent: Sunday, June 29, 2014 5:26 PM
Subject: Re: Adds incipit section to NR (issue 108270043 by 
PhilEHolmes@googlemail.com)


> On 2014/06/29 15:15:51, email_philholmes.net wrote:
>> From: <mailto:dak@gnu.org>
>> To: <mailto:PhilEHolmes@googlemail.com>
>> Cc: <mailto:lilypond-devel@gnu.org>;
> <mailto:reply@codereview-hr.appspotmail.com>
>> Sent: Sunday, June 29, 2014 3:44 PM
>> Subject: Re: Adds incipit section to NR (issue 108270043 by
>> mailto:PhilEHolmes@googlemail.com)
>
>> > Incipits are common enough that we want to have them in the manual,
>> > sure, but as a reasonably usable and maintained command rather than
> a
>> > wagonload of snippet code.
>
>> > That's embarrassing, to say the least.  At any rate, the snippet
> code
>> > does not belong in NR proper.  Incipit functionality does, but not
> as a
>> > snippet.  This needs to become a usable command out of the box
> again.
>
>> Well, it seems to me you're not considering why the snippets in the
> LSR are
>> there.  The CG says "A subset of these examples are automatically
> imported
>> into the documentation, making it easy for users to contribute to the
> docs
>> without learning Git and Texinfo." - so the snippets are designed to
> allow
>> users who can't push doc changes to the repo a chance to add
> documentation
>> to the manuals.  Nothing to do with the sort of code, simply an
> alternative
>> route.
>
> And we have a standard way to include snippets contributed in that
> manner, using the @snippets command.  That's not what you are doing
> here.  You are doing a copy&paste section into the NR files themselves.
> That separates the ties between the snippets maintained in the LSR and
> the code listed in the NR.  Where we are talking about snippets
> documenting a basic feature that was lacking documentation in the
> manual, that is a reasonable way forward.


You seem to have missed the point.  Snippets are not judged by the lilypond 
code, but by the ability of the writer to include them into the 
documentation.  I did not need to do this as a snippet, so I didn't.

--
Phil Holmes 

[dak, 2014-06-29 17:48:49]

On 2014/06/29 16:51:06, email_philholmes.net wrote:
> ----- Original Message ----- 
> From: <mailto:dak@gnu.org>
> To: <mailto:PhilEHolmes@googlemail.com>; <mailto:email@philholmes.net>
> Cc: <mailto:lilypond-devel@gnu.org>;
<mailto:reply@codereview-hr.appspotmail.com>
> Sent: Sunday, June 29, 2014 5:26 PM
> Subject: Re: Adds incipit section to NR (issue 108270043 by 
> mailto:PhilEHolmes@googlemail.com)
> 
> 
> > On 2014/06/29 15:15:51, http://email_philholmes.net wrote:
> >> From: <mailto:dak@gnu.org>
> >> To: <mailto:PhilEHolmes@googlemail.com>
> >> Cc: <mailto:lilypond-devel@gnu.org>;
> > <mailto:reply@codereview-hr.appspotmail.com>
> >> Sent: Sunday, June 29, 2014 3:44 PM
> >> Subject: Re: Adds incipit section to NR (issue 108270043 by
> >> mailto:PhilEHolmes@googlemail.com)
> >
> >> > Incipits are common enough that we want to have them in the manual,
> >> > sure, but as a reasonably usable and maintained command rather than
> > a
> >> > wagonload of snippet code.
> >
> >> > That's embarrassing, to say the least.  At any rate, the snippet
> > code
> >> > does not belong in NR proper.  Incipit functionality does, but not
> > as a
> >> > snippet.  This needs to become a usable command out of the box
> > again.
> >
> >> Well, it seems to me you're not considering why the snippets in the
> > LSR are
> >> there.  The CG says "A subset of these examples are automatically
> > imported
> >> into the documentation, making it easy for users to contribute to the
> > docs
> >> without learning Git and Texinfo." - so the snippets are designed to
> > allow
> >> users who can't push doc changes to the repo a chance to add
> > documentation
> >> to the manuals.  Nothing to do with the sort of code, simply an
> > alternative
> >> route.
> >
> > And we have a standard way to include snippets contributed in that
> > manner, using the @snippets command.  That's not what you are doing
> > here.  You are doing a copy&paste section into the NR files themselves.
> > That separates the ties between the snippets maintained in the LSR and
> > the code listed in the NR.  Where we are talking about snippets
> > documenting a basic feature that was lacking documentation in the
> > manual, that is a reasonable way forward.
> 
> 
> You seem to have missed the point.  Snippets are not judged by the lilypond 
> code, but by the ability of the writer to include them into the 
> documentation.  I did not need to do this as a snippet, so I didn't.

Sigh.  <URL:http://lilypond.org/doc/v2.19/Documentation/contributor/books>:

"Notation Reference: a (hopefully complete) description of LilyPond input
notation."

Incipits are not currently a part of LilyPond input notation, and you appear
bent on this staying that way.  I don't understand why.

<URL:http://lilypond.org/doc/v2.19/Documentation/contributor/documentation-suggestions>

"Contributions that contain examples using overrides

Examples that use overrides, tweaks, customer Scheme functions etc. are (with
very few exceptions) not included in the main text of the manuals; as there
would be far too many, equally useful, candidates.

The correct way is to submit your example, with appropriate explanatory text and
tags, to the LilyPond Snippet Repository (LSR). Snippets that have the “docs”
tag can then be easily added as a selected snippet in the documentation. It will
also appear automatically in the Snippets lists. See Introduction to LSR."

I think that's rather clear.  I repeat: complex examples and workarounds belong
in the snippets and may be cited from there with the mechanisms we have
available for it.  Obviously, that's the proper way to integrate the current
incipit snippet if that is the goal.

Equally obviously, incipits are a frequent enough occurence that we want to
provide a regular mechanism instead of just a snippet and document it.  I'd add
Graham (as the one responsible for writing down the policies you cite in support
of copying the snippet into the manual) to the Cc list for an opinion here, but
then it would appear that only the owner of a review can do that.

While we ultimately need to come to a consensus ourselves, it might save time
_when_ a past consensus is dragged into the discussion to make sure to get it
right.  Consensus-finding is hard enough, so it makes sense to rereference an
old consensus in the assumption that the people having come to that consensus
spent more time and thought on it than we have so far.  But if we cannot come to
a consensus about what the consensus actually was judging from the documents
pinned down at the time, that will not help us now.

[Trevor Daniels, 2014-06-29 17:55:23]

On 2014/06/29 16:51:06, email_philholmes.net wrote:

> You seem to have missed the point.  Snippets are not judged by the lilypond 
> code, but by the ability of the writer to include them into the 
> documentation.  I did not need to do this as a snippet, so I didn't.

Not so.  Please read Section 5.5.1 of the CG.  It says there:

"Most tweaks should be added to LSR and not placed directly in the ‘.itely’
file. 
In some cases, tweaks may be placed in the main text, but ask about this first."

By tweaks it means tweaks or overrides of any sort.

Admittedly there are sections of the manual which were written before these
guidelines were approved which do not follow them, and the sections on Ancient
Music are such, but that's no reason for ignoring them now when entering new 
documentation.  What you have prepared is clearly better than "TBC", but the 
code parts should be added via the LSR using @lilypondfile[...] as is done in
the earlier sections of the NR.

Trevor

[mail_philholmes.net, 2014-06-29 20:41:32]

----- Original Message ----- 
From: <tdanielsmusic@googlemail.com>
To: <PhilEHolmes@googlemail.com>; <dak@gnu.org>; <email@philholmes.net>
Cc: <reply@codereview-hr.appspotmail.com>; <lilypond-devel@gnu.org>
Sent: Sunday, June 29, 2014 6:55 PM
Subject: Re: Adds incipit section to NR (issue 108270043 
byPhilEHolmes@googlemail.com)


> On 2014/06/29 16:51:06, email_philholmes.net wrote:
>
>> You seem to have missed the point.  Snippets are not judged by the
> lilypond
>> code, but by the ability of the writer to include them into the
>> documentation.  I did not need to do this as a snippet, so I didn't.
>
> Not so.  Please read Section 5.5.1 of the CG.  It says there:
>
> "Most tweaks should be added to LSR and not placed directly in the
> '.itely' file.
> In some cases, tweaks may be placed in the main text, but ask about this
> first."
>
> By tweaks it means tweaks or overrides of any sort.
>
> Admittedly there are sections of the manual which were written before
> these
> guidelines were approved which do not follow them, and the sections on
> Ancient
> Music are such, but that's no reason for ignoring them now when entering
> new
> documentation.  What you have prepared is clearly better than "TBC", but
> the
> code parts should be added via the LSR using @lilypondfile[...] as is
> done in
> the earlier sections of the NR.
>
> Trevor


I appreciate your comments, but I really don't see why it is better to add 
overrides in the LSR.  To the user, they both appear in the manual as equal 
relations.  Unless they are "Selected snippets" (and remember, I'm replacing 
a main part of the NR which had "TBC" with something that works, rather than 
adding anything new) there's no actual difference in the published version 
of the manual with text written directly into the manual as opposed to that 
included from the LSR, except that if it's added to the manual as I did it 
now, then it will appear without an LSR import, whereas adding it to the 
LSR, tagging it as docs, importing it, and then sorting out the other issues 
with the import (which I do have on my list to do) is a complete pain.

I think I'll just delete the section so no-one thinks we can make incipits.

--
Phil Holmes 

[PhilEHolmes, 2014-08-12 11:14:34]

Adds incipit command and provides initial documentation

[PhilEHolmes, 2014-08-12 11:17:03]

Please review.

[dak, 2014-08-12 11:46:12]

https://codereview.appspot.com/108270043/diff/20001/ly/property-init.ly
File ly/property-init.ly (right):

https://codereview.appspot.com/108270043/diff/20001/ly/property-init.ly#newco...
ly/property-init.ly:298: scale-factor = #1757/1000
Uh what?  Why are you overriding the scale-factor here?  This cannot possibly be
correct except possibly for a single staff size.

What are you trying to achieve?

[email_philholmes.net, 2014-08-12 11:54:38]

----- Original Message ----- 
From: <dak@gnu.org>
To: <PhilEHolmes@googlemail.com>; <tdanielsmusic@googlemail.com>
Cc: <lilypond-devel@gnu.org>; <reply@codereview-hr.appspotmail.com>
Sent: Tuesday, August 12, 2014 12:46 PM
Subject: Re: Adds incipit section to NR (issue 108270043 by 
PhilEHolmes@googlemail.com)


>
> https://codereview.appspot.com/108270043/diff/20001/ly/property-init.ly
> File ly/property-init.ly (right):
>
>
https://codereview.appspot.com/108270043/diff/20001/ly/property-init.ly#newco...
> ly/property-init.ly:298: scale-factor = #1757/1000
> Uh what?  Why are you overriding the scale-factor here?  This cannot
> possibly be correct except possibly for a single staff size.
>
> What are you trying to achieve?
>
> https://codereview.appspot.com/108270043/

When this was discussed earlier, we discovered that the dimensions within 
"\layout { $(ly:grob-layout grob)" are incorrectly scaled.  This is 
demonstrable by using the function I've provided with and without that 
scaling factor.  With the scaling factor, the incipits are the correct size.

See the exchange below: your comments with > and mine below that.  This from 
4 July.

===========================================

> I don't really have an idea where the scale of ly:grob-layout is
> actually coming from, but it would appear like the compensation for
> issue 677 will not work for both the standard \layout and the grob
> layout, the latter apparently already being scaled ?
>
> At any rate, if calculations with sizes are done, it would seem
> imperative to be talking about the same cm, so possibly the scaling in
> issue 677 does not happen at the right place.
>
> -- 
> David Kastrup


I checked how far out the scaling of the markup score was prior to 677: by
ruler I measured it as being a factor of 1.76. The command-line output
shows \cm as being 10 for the "normal" layout, and 5.69 for the \layout with
$(ly:grob-layout grob). The ratio between these is 1.757. So it seems
clear that the problem is related to 677, although I clearly have no idea
what's going on.

I can post this as a bug, but I'm guessing it would be tricky to fix. Would
you object to scaling the dimensions of the incipit (in the incipit code)
line-width and indent by the 1.76 factor, to work round the problem?

=================================================

--
Phil Holmes

[dak, 2014-08-12 12:09:14]

On 2014/08/12 11:54:38, email_philholmes.net wrote:

> I can post this as a bug, but I'm guessing it would be tricky to fix. Would
> you object to scaling the dimensions of the incipit (in the incipit code)
> line-width and indent by the 1.76 factor, to work round the problem?

Yes, I would object to scaling the dimensions of the incipit line-width and
indent by the 1.76 factor since that is just an ad-hoc approximation for a
single case.

Is there a reason you don't scale by the ratio of output-scale between
grob-layout and layout?

[mail_philholmes.net, 2014-08-12 12:16:12]

----- Original Message ----- 
From: <dak@gnu.org>
To: <PhilEHolmes@googlemail.com>; <tdanielsmusic@googlemail.com>; 
<email@philholmes.net>
Cc: <reply@codereview-hr.appspotmail.com>; <lilypond-devel@gnu.org>
Sent: Tuesday, August 12, 2014 1:09 PM
Subject: Re: Adds incipit section to NR (issue 108270043 
byPhilEHolmes@googlemail.com)


> On 2014/08/12 11:54:38, email_philholmes.net wrote:
>
>> I can post this as a bug, but I'm guessing it would be tricky to fix.
> Would
>> you object to scaling the dimensions of the incipit (in the incipit
> code)
>> line-width and indent by the 1.76 factor, to work round the problem?
>
> Yes, I would object to scaling the dimensions of the incipit line-width
> and indent by the 1.76 factor since that is just an ad-hoc approximation
> for a single case.

Shame you didn't when I first asked.

> Is there a reason you don't scale by the ratio of output-scale between
> grob-layout and layout?
>
> https://codereview.appspot.com/108270043/


Tell me how and I'll do it.

--
Phil Holmes 

[dak, 2014-08-12 12:56:31]

On 2014/08/12 12:16:12, mail_philholmes.net wrote:
> ----- Original Message ----- 
> From: <mailto:dak@gnu.org>
> To: <mailto:PhilEHolmes@googlemail.com>;
<mailto:tdanielsmusic@googlemail.com>; 
> <mailto:email@philholmes.net>
> Cc: <mailto:reply@codereview-hr.appspotmail.com>;
<mailto:lilypond-devel@gnu.org>
> Sent: Tuesday, August 12, 2014 1:09 PM
> Subject: Re: Adds incipit section to NR (issue 108270043 
> mailto:byPhilEHolmes@googlemail.com)
> 
> 
> > On 2014/08/12 11:54:38, http://email_philholmes.net wrote:
> >
> >> I can post this as a bug, but I'm guessing it would be tricky to fix.
> > Would
> >> you object to scaling the dimensions of the incipit (in the incipit
> > code)
> >> line-width and indent by the 1.76 factor, to work round the problem?
> >
> > Yes, I would object to scaling the dimensions of the incipit line-width
> > and indent by the 1.76 factor since that is just an ad-hoc approximation
> > for a single case.
> 
> Shame you didn't when I first asked.
> 
> > Is there a reason you don't scale by the ratio of output-scale between
> > grob-layout and layout?
> >
> > https://codereview.appspot.com/108270043/
> 
> 
> Tell me how and I'll do it.

I think the problem you are trying to work around will likely go away when you
give "incipit-width" the same treatment as "short-indent" everywhere it occurs
in scm/paper.scm.

It's sort of irritating that this is not equally easy to do for a user-level
extension.  Even then, one could check the setting of "mm" and scale by that. 
But when implementing this as a "native" feature, we are probably better off
using the native mechanisms.

[dak, 2014-08-12 13:01:13]

On 2014/08/12 12:16:12, mail_philholmes.net wrote:
> ----- Original Message ----- 
> From: <mailto:dak@gnu.org>

> >
> > Yes, I would object to scaling the dimensions of the incipit line-width
> > and indent by the 1.76 factor since that is just an ad-hoc approximation
> > for a single case.
> 
> Shame you didn't when I first asked.

Patch 1 did not contain such an ad-hoc factor, patch 2 has been up for less than
two hours.

I have no idea what I am supposed to be at blame for here.

[mail_philholmes.net, 2014-08-12 13:58:44]

----- Original Message ----- 
From: <dak@gnu.org>
To: <PhilEHolmes@googlemail.com>; <tdanielsmusic@googlemail.com>; 
<email@philholmes.net>; <mail@philholmes.net>
Cc: <lilypond-devel@gnu.org>; <reply@codereview-hr.appspotmail.com>
Sent: Tuesday, August 12, 2014 1:56 PM
Subject: Re: Adds incipit section to NR (issue 108270043 by 
PhilEHolmes@googlemail.com)


> On 2014/08/12 12:16:12, mail_philholmes.net wrote:
>> ----- Original Message -----
>> From: <mailto:dak@gnu.org>
>> To: <mailto:PhilEHolmes@googlemail.com>;
> <mailto:tdanielsmusic@googlemail.com>;
>> <mailto:email@philholmes.net>
>> Cc: <mailto:reply@codereview-hr.appspotmail.com>;
> <mailto:lilypond-devel@gnu.org>
>> Sent: Tuesday, August 12, 2014 1:09 PM
>> Subject: Re: Adds incipit section to NR (issue 108270043
>> mailto:byPhilEHolmes@googlemail.com)
>
>
>> > On 2014/08/12 11:54:38, http://email_philholmes.net wrote:
>> >
>> >> I can post this as a bug, but I'm guessing it would be tricky to
> fix.
>> > Would
>> >> you object to scaling the dimensions of the incipit (in the incipit
>> > code)
>> >> line-width and indent by the 1.76 factor, to work round the
> problem?
>> >
>> > Yes, I would object to scaling the dimensions of the incipit
> line-width
>> > and indent by the 1.76 factor since that is just an ad-hoc
> approximation
>> > for a single case.
>
>> Shame you didn't when I first asked.
>
>> > Is there a reason you don't scale by the ratio of output-scale
> between
>> > grob-layout and layout?
>> >
>> > https://codereview.appspot.com/108270043/
>
>
>> Tell me how and I'll do it.
>
> I think the problem you are trying to work around will likely go away
> when you give "incipit-width" the same treatment as "short-indent"
> everywhere it occurs in scm/paper.scm.
>
> It's sort of irritating that this is not equally easy to do for a
> user-level extension.  Even then, one could check the setting of "mm"
> and scale by that.  But when implementing this as a "native" feature, we
> are probably better off using the native mechanisms.
>
> https://codereview.appspot.com/108270043/


The problem is the other way round.  incipit-width is not scaled within the 
layout block, and so produces correct results for width.  indent and 
short-indent are scaled, and so produce widths that are too small for the 
desired output.  Attached is a sample file that illustrates the problem.  In 
it is a potential solution: using

scale-factor = #( / 1.0 (module-ref (current-module) 'mm) )

That would seem to be a satisfactory way of avoiding problems should the way 
scaling is done change in future?

--
Phil Holmes 

[dak, 2014-08-12 14:17:45]

On 2014/08/12 13:58:44, mail_philholmes.net wrote:
 
> The problem is the other way round.  incipit-width is not scaled within the 
> layout block, and so produces correct results for width.

I am not convinced that the results are "correct" when they are not scaled the
same as every other measure including "\mm".  Have you tried my proposal?

> indent and 
> short-indent are scaled, and so produce widths that are too small for the 
> desired output.  Attached is a sample file that illustrates the problem.

No attachment here.

> In 
> it is a potential solution: using
> 
> scale-factor = #( / 1.0 (module-ref (current-module) 'mm) )
> 
> That would seem to be a satisfactory way of avoiding problems should the way 
> scaling is done change in future?

I am skeptical.  The main problem I see is that when inheriting a grob-layout as
the start of a \layout block, then 3 will not be the same as 3\mm.  We probably
need a way to get at the unscaled layout, then scale afterwards.  I would not
want to _calculate_ the unscaled layout since that buys us a buildup of
numerical errors.

[PhilEHolmes, 2014-08-16 13:10:54]

Updates following scaling changes

[PhilEHolmes, 2014-08-16 13:12:56]

Please review further updates to this patch

[dak, 2014-08-16 13:53:35]

On 2014/08/16 13:12:56, PhilEHolmes wrote:
> Please review further updates to this patch

Ok, this version does not offer any "Huh?" experiences apart from the
primitive-eval which has sort of an easy to understand cause and no really
convincing workaround.  Have you checked that something useful happens when
incipit-width is undefined?  Half of the time I stare at that false-if-exception
I am not really sure it will trigger at the right moment.

[email_philholmes.net, 2014-08-16 13:59:25]

----- Original Message ----- 
From: <dak@gnu.org>
To: <PhilEHolmes@googlemail.com>; <tdanielsmusic@googlemail.com>
Cc: <lilypond-devel@gnu.org>; <reply@codereview-hr.appspotmail.com>
Sent: Saturday, August 16, 2014 2:53 PM
Subject: Re: Adds incipit section to NR (issue 108270043 by 
PhilEHolmes@googlemail.com)


> On 2014/08/16 13:12:56, PhilEHolmes wrote:
>> Please review further updates to this patch
>
> Ok, this version does not offer any "Huh?" experiences apart from the
> primitive-eval which has sort of an easy to understand cause and no
> really convincing workaround.  Have you checked that something useful
> happens when incipit-width is undefined?  Half of the time I stare at
> that false-if-exception I am not really sure it will trigger at the
> right moment.
>
> https://codereview.appspot.com/108270043/

Yes, I have.  As hoped for, it the incipit staff is half the width of the 
indent.

--
Phil Holmes 

[Trevor Daniels, 2014-08-16 20:38:46]

Minor typo, otherwise LGTM

Trevor

https://codereview.appspot.com/108270043/diff/40001/Documentation/notation/an...
File Documentation/notation/ancient.itely (right):

https://codereview.appspot.com/108270043/diff/40001/Documentation/notation/an...
Documentation/notation/ancient.itely:2651: an indication of how the initial
rests and note of the original version
notes

[email_philholmes.net, 2014-08-17 09:56:32]

----- Original Message ----- 
From: <tdanielsmusic@googlemail.com>
To: <PhilEHolmes@googlemail.com>; <dak@gnu.org>; <email@philholmes.net>
Cc: <lilypond-devel@gnu.org>; <reply@codereview-hr.appspotmail.com>
Sent: Saturday, August 16, 2014 9:38 PM
Subject: Re: Adds incipit section to NR (issue 108270043 by 
PhilEHolmes@googlemail.com)


> Minor typo, otherwise LGTM
>
> Trevor
>
>
>
>
https://codereview.appspot.com/108270043/diff/40001/Documentation/notation/an...
> File Documentation/notation/ancient.itely (right):
>
>
https://codereview.appspot.com/108270043/diff/40001/Documentation/notation/an...
> Documentation/notation/ancient.itely:2651: an indication of how the
> initial rests and note of the original version
> notes
>
> https://codereview.appspot.com/108270043/
>

No - it should be "note".  A standard incipit has all the rests leading to 
the first note, but just the first note alone.

--
Phil Holmes 

[dak, 2014-08-17 12:28:06]

On 2014/08/17 09:56:32, email_philholmes.net wrote:
> ----- Original Message ----- 
> From: <mailto:tdanielsmusic@googlemail.com>
> To: <mailto:PhilEHolmes@googlemail.com>; <mailto:dak@gnu.org>;
<mailto:email@philholmes.net>
> Cc: <mailto:lilypond-devel@gnu.org>;
<mailto:reply@codereview-hr.appspotmail.com>
> Sent: Saturday, August 16, 2014 9:38 PM
> Subject: Re: Adds incipit section to NR (issue 108270043 by 
> mailto:PhilEHolmes@googlemail.com)
> 
> 
> > Minor typo, otherwise LGTM
> >
> > Trevor
> >
> >
> >
> >
>
https://codereview.appspot.com/108270043/diff/40001/Documentation/notation/an...
> > File Documentation/notation/ancient.itely (right):
> >
> >
>
https://codereview.appspot.com/108270043/diff/40001/Documentation/notation/an...
> > Documentation/notation/ancient.itely:2651: an indication of how the
> > initial rests and note of the original version
> > notes
> >
> > https://codereview.appspot.com/108270043/
> >
> 
> No - it should be "note".  A standard incipit has all the rests leading to 
> the first note, but just the first note alone.

Beg to differ.  See for example
<URL:https://en.wikipedia.org/wiki/Mensural_notation#mediaviewer/File:Josquin_Domine_ne_in_furore.svg>.
 It's usually the first bar or half bar, but enough that every voice has at
least one actual note.

[mail_philholmes.net, 2014-08-17 12:50:16]

----- Original Message ----- 
From: <dak@gnu.org>
To: <PhilEHolmes@googlemail.com>; <tdanielsmusic@googlemail.com>; 
<email@philholmes.net>
Cc: <reply@codereview-hr.appspotmail.com>; <lilypond-devel@gnu.org>
Sent: Sunday, August 17, 2014 1:28 PM
Subject: Re: Adds incipit section to NR (issue 108270043 
byPhilEHolmes@googlemail.com)


> On 2014/08/17 09:56:32, email_philholmes.net wrote:
>> ----- Original Message -----
>> From: <mailto:tdanielsmusic@googlemail.com>
>> To: <mailto:PhilEHolmes@googlemail.com>; <mailto:dak@gnu.org>;
> <mailto:email@philholmes.net>
>> Cc: <mailto:lilypond-devel@gnu.org>;
> <mailto:reply@codereview-hr.appspotmail.com>
>> Sent: Saturday, August 16, 2014 9:38 PM
>> Subject: Re: Adds incipit section to NR (issue 108270043 by
>> mailto:PhilEHolmes@googlemail.com)
>
>
>> > Minor typo, otherwise LGTM
>> >
>> > Trevor
>> >
>> >
>> >
>> >
>
>
https://codereview.appspot.com/108270043/diff/40001/Documentation/notation/an...
>> > File Documentation/notation/ancient.itely (right):
>> >
>> >
>
>
https://codereview.appspot.com/108270043/diff/40001/Documentation/notation/an...
>> > Documentation/notation/ancient.itely:2651: an indication of how the
>> > initial rests and note of the original version
>> > notes
>> >
>> > https://codereview.appspot.com/108270043/
>> >
>
>> No - it should be "note".  A standard incipit has all the rests
> leading to
>> the first note, but just the first note alone.
>
> Beg to differ.  See for example
>
<URL:https://en.wikipedia.org/wiki/Mensural_notation#mediaviewer/File:Josquin_Domine_ne_in_furore.svg>.
>  It's usually the first bar or half bar, but enough that every voice has
> at least one actual note.
>
> https://codereview.appspot.com/108270043/

TBH I've sung from a lot of music with incipits and have never seen more 
than one note: finding a sole example on Wikipedia from an author who does 
not appear to have a username isn't categorical!

However, Grove says "A 'melodic incipit' or 'musical incipit' is the opening 
fragment of music" and Oxford Music Online has "The preliminary staff in 
modern editions of early music, giving the original clefs and time and key 
signatures, the opening note or notes in their original notation, and 
occasionally the range of the part", so probably a sound update would be to 
replace "note" with "note or notes".  I'll do this before pushing: it's not 
worth an updated patch.

--
Phil Holmes 

[benko.pal, 2014-08-17 15:30:26]

>>> > Documentation/notation/ancient.itely:2651: an indication of how the
>>> > initial rests and note of the original version
>>> > notes
>>> >
>>> > https://codereview.appspot.com/108270043/
>>> >
>>
>>
>>> No - it should be "note".  A standard incipit has all the rests
>>> leading to the first note, but just the first note alone.
>>
>> Beg to differ.  See for example
>>
>>
<URL:https://en.wikipedia.org/wiki/Mensural_notation#mediaviewer/File:Josquin_Domine_ne_in_furore.svg>.
>>  It's usually the first bar or half bar, but enough that every voice has
>> at least one actual note.
>>
>> https://codereview.appspot.com/108270043/
>
>
> TBH I've sung from a lot of music with incipits and have never seen more
> than one note: finding a sole example on Wikipedia from an author who does
> not appear to have a username isn't categorical!

FWIW I've also sung a lot of music with incipits and I didn't gather that
one single note would be standard; I've even seen full movements as incipit.
if the sung music starts with a ligature, it's even impossible to have
just one note as incipit.  to me "note or notes" is just pleonasm for "notes".

p

[mail_philholmes.net, 2014-08-17 16:02:01]

----- Original Message ----- 
From: "Benkő Pál" <benko.pal@gmail.com>
To: "Phil Holmes" <mail@philholmes.net>
Cc: "Phil Holmes" <PhilEHolmes@googlemail.com>; "David Kastrup" 
<dak@gnu.org>; "Trevor Daniels" <tdanielsmusic@googlemail.com>; 
<lilypond-devel@gnu.org>; <reply@codereview-hr.appspotmail.com>
Sent: Sunday, August 17, 2014 4:30 PM
Subject: Re: Adds incipit section to NR (issue 108270043 
byPhilEHolmes@googlemail.com)


>>>> > Documentation/notation/ancient.itely:2651: an indication of how the
>>>> > initial rests and note of the original version
>>>> > notes
>>>> >
>>>> > https://codereview.appspot.com/108270043/
>>>> >
>>>
>>>
>>>> No - it should be "note".  A standard incipit has all the rests
>>>> leading to the first note, but just the first note alone.
>>>
>>> Beg to differ.  See for example
>>>
>>>
<URL:https://en.wikipedia.org/wiki/Mensural_notation#mediaviewer/File:Josquin_Domine_ne_in_furore.svg>.
>>>  It's usually the first bar or half bar, but enough that every voice has
>>> at least one actual note.
>>>
>>> https://codereview.appspot.com/108270043/
>>
>>
>> TBH I've sung from a lot of music with incipits and have never seen more
>> than one note: finding a sole example on Wikipedia from an author who 
>> does
>> not appear to have a username isn't categorical!
>
> FWIW I've also sung a lot of music with incipits and I didn't gather that
> one single note would be standard; I've even seen full movements as 
> incipit.
> if the sung music starts with a ligature, it's even impossible to have
> just one note as incipit.  to me "note or notes" is just pleonasm for 
> "notes".


Well, blame the Oxford Music dictionary.

--
Phil Holmes 

[Trevor Daniels, 2014-08-17 18:16:22]

> TBH I've sung from a lot of music with incipits and have never seen more 
> than one note: finding a sole example on Wikipedia from an author who does 
> not appear to have a username isn't categorical!
> 
> However, Grove says "A 'melodic incipit' or 'musical incipit' is the opening 
> fragment of music" and Oxford Music Online has "The preliminary staff in 
> modern editions of early music, giving the original clefs and time and key 
> signatures, the opening note or notes in their original notation, and 
> occasionally the range of the part", so probably a sound update would be to 
> replace "note" with "note or notes".  I'll do this before pushing: it's not 
> worth an updated patch.

It depends on the publisher, or maybe the editor.  For example,
"European Sacred Music" edited by Rutter and published by Oxford 
seems to consistently show just the first note of each part, omitting 
all prior rests, whereas the publisher Mapa Mundi always shows all 
rests and several notes, usually corresponding to at least one full 
bar, often more, of the following modern transcription.

Trevor

[dak, 2014-08-19 17:11:42]

https://codereview.appspot.com/108270043/diff/40001/ly/property-init.ly
File ly/property-init.ly (right):

https://codereview.appspot.com/108270043/diff/40001/ly/property-init.ly#newco...
ly/property-init.ly:293: \once \override Staff.InstrumentName.self-alignment-X =
#RIGHT
I don't think we should prescribe Staff.InstrumentName.self-alignment-X here. 
That is a user preference.  While it would be nice to glean that information
from the outer Staff.InstrumentName.self-alignment-X, that's likely tricky to do
while at the same time overriding the Staff.InstrumentName settings.

So I'd rather suggest the syntax
\incipit \with { \override InstrumentName.self-alignment-X = #RIGHT } {...}
if you want such an override.  That could be achieved by putting an
optional incipit-mods argument of type (ly:context-mod? (ly:make-context-mod))
before the incipit-music argument and then using \new MensuralStaff \with {
instrumentName = #instrument-name \with #incipit-mods }
(not sure about the last \with) instead of just \new MensuralStaff.

https://codereview.appspot.com/108270043/diff/40001/ly/property-init.ly#newco...
ly/property-init.ly:303: ragged-last = ##f
wouldn't we also want system-count = 1 here?

[email_philholmes.net, 2014-08-19 20:22:01]

----- Original Message ----- 
From: <dak@gnu.org>
To: <PhilEHolmes@googlemail.com>; <tdanielsmusic@googlemail.com>; 
<email@philholmes.net>; <mail@philholmes.net>; <benko.pal@gmail.com>
Cc: <lilypond-devel@gnu.org>; <reply@codereview-hr.appspotmail.com>
Sent: Tuesday, August 19, 2014 6:11 PM
Subject: Re: Adds incipit section to NR (issue 108270043 by 
PhilEHolmes@googlemail.com)


>
> https://codereview.appspot.com/108270043/diff/40001/ly/property-init.ly
> File ly/property-init.ly (right):
>
>
https://codereview.appspot.com/108270043/diff/40001/ly/property-init.ly#newco...
> ly/property-init.ly:293: \once \override
> Staff.InstrumentName.self-alignment-X = #RIGHT
> I don't think we should prescribe Staff.InstrumentName.self-alignment-X
> here.  That is a user preference.  While it would be nice to glean that
> information from the outer Staff.InstrumentName.self-alignment-X, that's
> likely tricky to do while at the same time overriding the
> Staff.InstrumentName settings.
>
> So I'd rather suggest the syntax
> \incipit \with { \override InstrumentName.self-alignment-X = #RIGHT }
> {...}

Don't agree at all.  I'd accept it if you proposed an alternative that left 
aligned the instrument name as a possible option, but as it is, I believe 
right alignment is the correct option here.  It should require an override 
to change that.  Don't accept this change should delay pushing this patch.

> if you want such an override.  That could be achieved by putting an
> optional incipit-mods argument of type (ly:context-mod?
> (ly:make-context-mod)) before the incipit-music argument and then using
> \new MensuralStaff \with { instrumentName = #instrument-name \with
> #incipit-mods }
> (not sure about the last \with) instead of just \new MensuralStaff.
>
>
https://codereview.appspot.com/108270043/diff/40001/ly/property-init.ly#newco...
> ly/property-init.ly:303: ragged-last = ##f
> wouldn't we also want system-count = 1 here?
>
> https://codereview.appspot.com/108270043/

Possibly. I'd be happy to add that prior to push.

--
Phil Holmes 

[dak, 2014-08-19 20:55:43]

On 2014/08/19 20:22:01, email_philholmes.net wrote:
> ----- Original Message ----- 
> From: <mailto:dak@gnu.org>
> To: <mailto:PhilEHolmes@googlemail.com>;
<mailto:tdanielsmusic@googlemail.com>; 
> <mailto:email@philholmes.net>; <mailto:mail@philholmes.net>;
<mailto:benko.pal@gmail.com>
> Cc: <mailto:lilypond-devel@gnu.org>;
<mailto:reply@codereview-hr.appspotmail.com>
> Sent: Tuesday, August 19, 2014 6:11 PM
> Subject: Re: Adds incipit section to NR (issue 108270043 by 
> mailto:PhilEHolmes@googlemail.com)
> 
> 
> >
> > https://codereview.appspot.com/108270043/diff/40001/ly/property-init.ly
> > File ly/property-init.ly (right):
> >
> >
>
https://codereview.appspot.com/108270043/diff/40001/ly/property-init.ly#newco...
> > ly/property-init.ly:293: \once \override
> > Staff.InstrumentName.self-alignment-X = #RIGHT
> > I don't think we should prescribe Staff.InstrumentName.self-alignment-X
> > here.  That is a user preference.  While it would be nice to glean that
> > information from the outer Staff.InstrumentName.self-alignment-X, that's
> > likely tricky to do while at the same time overriding the
> > Staff.InstrumentName settings.
> >
> > So I'd rather suggest the syntax
> > \incipit \with { \override InstrumentName.self-alignment-X = #RIGHT }
> > {...}
> 
> Don't agree at all.  I'd accept it if you proposed an alternative that left 
> aligned the instrument name as a possible option,

The optional context mod obviously allows choosing any default that can be
explicitly overridden by the user.

> but as it is, I believe 
> right alignment is the correct option here.

Why would the correct default alignment for an instrument name before an incipit
be explicitly different from the correct default alignment for an instrument
name before an incipit-less staff?

> Don't accept this change should delay pushing this patch.

So what is the reasoning behind changing the default instrument placement before
an incipit?

[email_philholmes.net, 2014-08-20 08:07:34]

----- Original Message ----- 
From: <dak@gnu.org>
To: <PhilEHolmes@googlemail.com>; <tdanielsmusic@googlemail.com>; 
<email@philholmes.net>; <mail@philholmes.net>; <benko.pal@gmail.com>
Cc: <lilypond-devel@gnu.org>; <reply@codereview-hr.appspotmail.com>
Sent: Tuesday, August 19, 2014 9:55 PM
Subject: Re: Adds incipit section to NR (issue 108270043 by 
PhilEHolmes@googlemail.com)
>
https://codereview.appspot.com/108270043/diff/40001/ly/property-init.ly#newco...
>> > ly/property-init.ly:293: \once \override
>> > Staff.InstrumentName.self-alignment-X = #RIGHT
>> > I don't think we should prescribe
> Staff.InstrumentName.self-alignment-X
>> > here.  That is a user preference.  While it would be nice to glean
> that
>> > information from the outer Staff.InstrumentName.self-alignment-X,
> that's
>> > likely tricky to do while at the same time overriding the
>> > Staff.InstrumentName settings.
>> >
>> > So I'd rather suggest the syntax
>> > \incipit \with { \override InstrumentName.self-alignment-X = #RIGHT
> }
>> > {...}
>
>> Don't agree at all.  I'd accept it if you proposed an alternative that
> left
>> aligned the instrument name as a possible option,
>
> The optional context mod obviously allows choosing any default that can
> be explicitly overridden by the user.
>
>> but as it is, I believe
>> right alignment is the correct option here.
>
> Why would the correct default alignment for an instrument name before an
> incipit be explicitly different from the correct default alignment for
> an instrument name before an incipit-less staff?
>
>> Don't accept this change should delay pushing this patch.
>
> So what is the reasoning behind changing the default instrument
> placement before an incipit?
>
> https://codereview.appspot.com/108270043/

Because, after a considerable amount of experimentation to find the optimum 
design, I concluded that using a right-aligned instrument name and incipit 
provided the best-looking output with the least adjustment required by the 
user.  I have not done the same amount of experimentation and evaluation 
with the default instrument name: partly because that still suffers badly 
from the effects of Issue 766.

I do feel that this patch is suffering from a rather nit-picking approach. 
It is undoubtedly an enormous improvement over the current availability and 
documentation for incipits, which currently says "Incipits.  TBC".  It 
could, no doubt, be improved by other contributors adding options and 
features.  But I believe it is, in its current state, good _enough_ to go.

--
Phil Holmes 

[email_philholmes.net, 2014-08-20 08:17:01]

----- Original Message ----- 
From: "Phil Holmes" <email@philholmes.net>
To: <PhilEHolmes@googlemail.com>; <dak@gnu.org>; 
<tdanielsmusic@googlemail.com>; <benko.pal@gmail.com>; 
<lilypond-devel@gnu.org>; <reply@codereview-hr.appspotmail.com>
Cc: <lilypond-devel@gnu.org>; <reply@codereview-hr.appspotmail.com>
Sent: Tuesday, August 19, 2014 9:21 PM
Subject: Re: Adds incipit section to NR (issue 108270043 by 
PhilEHolmes@googlemail.com)


> ----- Original Message ----- 
> From: <dak@gnu.org>
> To: <PhilEHolmes@googlemail.com>; <tdanielsmusic@googlemail.com>; 
> <email@philholmes.net>; <mail@philholmes.net>; <benko.pal@gmail.com>
> Cc: <lilypond-devel@gnu.org>; <reply@codereview-hr.appspotmail.com>
> Sent: Tuesday, August 19, 2014 6:11 PM
> Subject: Re: Adds incipit section to NR (issue 108270043 by 
> PhilEHolmes@googlemail.com)
>
>
>>
>> https://codereview.appspot.com/108270043/diff/40001/ly/property-init.ly
>> File ly/property-init.ly (right):
>>
>>
https://codereview.appspot.com/108270043/diff/40001/ly/property-init.ly#newco...
>> ly/property-init.ly:293: \once \override
>> Staff.InstrumentName.self-alignment-X = #RIGHT
>> I don't think we should prescribe Staff.InstrumentName.self-alignment-X
>> here.  That is a user preference.  While it would be nice to glean that
>> information from the outer Staff.InstrumentName.self-alignment-X, that's
>> likely tricky to do while at the same time overriding the
>> Staff.InstrumentName settings.
>>
>> So I'd rather suggest the syntax
>> \incipit \with { \override InstrumentName.self-alignment-X = #RIGHT }
>> {...}
>
> Don't agree at all.  I'd accept it if you proposed an alternative that 
> left aligned the instrument name as a possible option, but as it is, I 
> believe right alignment is the correct option here.  It should require an 
> override to change that.  Don't accept this change should delay pushing 
> this patch.
>
>> if you want such an override.  That could be achieved by putting an
>> optional incipit-mods argument of type (ly:context-mod?
>> (ly:make-context-mod)) before the incipit-music argument and then using
>> \new MensuralStaff \with { instrumentName = #instrument-name \with
>> #incipit-mods }
>> (not sure about the last \with) instead of just \new MensuralStaff.
>>
>>
https://codereview.appspot.com/108270043/diff/40001/ly/property-init.ly#newco...
>> ly/property-init.ly:303: ragged-last = ##f
>> wouldn't we also want system-count = 1 here?
>>
>> https://codereview.appspot.com/108270043/
>
> Possibly. I'd be happy to add that prior to push.
>
> --
> Phil Holmes


Actually, I've just checked.  System-count has no effect: the incipit is 
always a single line.

--
Phil Holmes 

[dak, 2014-08-20 20:40:34]

On 2014/08/20 08:17:01, email_philholmes.net wrote:
> >> ly/property-init.ly:303: ragged-last = ##f
> >> wouldn't we also want system-count = 1 here?
> >>
> >> https://codereview.appspot.com/108270043/
> >
> > Possibly. I'd be happy to add that prior to push.
> >
> > --
> > Phil Holmes
> 
> 
> Actually, I've just checked.  System-count has no effect: the incipit is 
> always a single line.

Take the following example:

\layout {
  indent = 3\cm
}

\new Staff \with {
  instrumentName = "Tenor"
}
{
  \incipit \relative c' { \time 6/1 \partial 1*2 e1 d \bar "|" c d e d c e }
  \relative c' { \time 6/8 \partial 4 e8( d) c( d e d c e) | d2. }
}

Without the system-count restriction, its reaction to the small indent is quite
out of line.

This example shows some more problems: Outcommenting the assignment to indent
leads to a strange error message.  Outcommenting the assignment to
instrumentName lets the incipit disappear completely.

Now taking your last reply into account

> Don't agree at all.  I'd accept it if you proposed an alternative that 
> left aligned the instrument name as a possible option, but as it is, I 
> believe right alignment is the correct option here.  It should require an 
> override to change that.  Don't accept this change should delay pushing 
> this patch.

I think that our basic disagreement here has more or less grown over the history
of this patch which makes it somewhat sad that nobody else chimed in.

I think it boils down to a mismatch between your original intent reflected in
the patch title "Adds incipit section to NR" and the course I am trying to take
it.  To me it looks like you want a section in the NR (rather than some snippet)
that produces an incipit like the one you can see in your scores.  And it would
appear that everything which happened in between is a distraction and an
annoyance to you since it does not actually change the image that appears while
causing additional work.

However, we are changing from what was "just a snippet" into functionality built
into LilyPond.  In a snippet, hardwiring some instrument alignment for the
outcome desired for a particular graphic is quite fine: the user who wants a
different alignment can just change the snippet code.  But when we are creating
built-in functionality for LilyPond, we don't want decisions hardwired into code
that is no longer user-maintained.  We also don't want surprising changes of
defaults.  The last proposals of mine were for
a) changing the normal instrumentName placement to the default placement without
incipit
b) giving the \incipit command the facility to conveniently override such
defaults with a context modification
The intended graphic end result after all this effort would indeed be exactly
the same result you already have, but with the alignment choices differing from
the default explicitly specified by the code.

Now obviously one can commit and document one interface now and fix stuff up
afterwards.  But then that kind of documentation patchwork is done by different
authors and checked in and translated at different times.

I would prefer to get stuff as correct and complete at the first go as we can
manage.  Of course, once you throw up your hands in disgust, the work we can
hope to get achieved from one author in one go is over.  And naturally, there is
not much of a point to exhaust your enthusiasm for LilyPond over a single issue.
 I'd still be glad if we could get the code and documentation at least to a
state where we don't need to touch the translatable part in the NR (example use
and description) any more for a large variation of different applications, even
if it will fall to my lot to do further work on the \incipit definition in
property-init.ly itself in order to have it work in more situations.

[mail_philholmes.net, 2014-08-21 10:21:18]

----- Original Message ----- 
From: <dak@gnu.org>
To: <PhilEHolmes@googlemail.com>; <tdanielsmusic@googlemail.com>; 
<email@philholmes.net>; <mail@philholmes.net>; <benko.pal@gmail.com>
Cc: <lilypond-devel@gnu.org>; <reply@codereview-hr.appspotmail.com>
Sent: Wednesday, August 20, 2014 9:40 PM
Subject: Re: Adds incipit section to NR (issue 108270043 by 
PhilEHolmes@googlemail.com)


> On 2014/08/20 08:17:01, email_philholmes.net wrote:
>> >> ly/property-init.ly:303: ragged-last = ##f
>> >> wouldn't we also want system-count = 1 here?
>> >>
>> >> https://codereview.appspot.com/108270043/
>> >
>> > Possibly. I'd be happy to add that prior to push.
>> >
>> > --
>> > Phil Holmes
>
>
>> Actually, I've just checked.  System-count has no effect: the incipit
> is
>> always a single line.
>
> Take the following example:
>
> \layout {
>   indent = 3\cm
> }
>
> \new Staff \with {
>   instrumentName = "Tenor"
> }
> {
>   \incipit \relative c' { \time 6/1 \partial 1*2 e1 d \bar "|" c d e d c
> e }
>   \relative c' { \time 6/8 \partial 4 e8( d) c( d e d c e) | d2. }
> }
>
> Without the system-count restriction, its reaction to the small indent
> is quite out of line.

I'd concluded something similar yesterday - but it was difficult to check 
since I was on the motorbike at the time!

The difference between our two pices of music used to check the effect is 
that you included a bar line, allowing Lily somewhere to break the line: I 
hadn't.  In practice, whether the system-count = #1 is there or not makes no 
difference to whether acceptable output is produced.  Because of 
http://code.google.com/p/lilypond/issues/detail?id=766 both look poor.  I've 
attached examples of both: I believe it's worth adding the line and will do 
so, but it's rather like "putting lipstick on a pig".

> This example shows some more problems: Outcommenting the assignment to
> indent leads to a strange error message.  Outcommenting the assignment
> to instrumentName lets the incipit disappear completely.

Not convinced the error message is strange: "error: unknown escaped string: 
`\indent'  line-width = \indent".  So clearly it is complaining that where 
we assign the value of line-width to the variable \indent, that variable 
doesn't exist.  It seems we have three options.

a) Document the needs to set indent explicitly
b) Re-use the rather ugly '(or (false-if-exception (- indent incipit-width)) 
(* 0.5 indent))) syntax to set indent to a default for incipits
c) If \indent does not exist, use the default value of indent set in 
paper-defaults.  I'd assume this will need the same code as b)

c) would seem best, if I can get it working?

As to the incipit disappearing: I assume that this happens because we're 
over-riding the code that sets instrument name, but since we never tell Lily 
that there is an instrument name, she never calls that code.  This can be 
fixed by using instrumentName = "".  It's a bit ugly, but unless there is a 
better answer, then this should be documented.

> Now taking your last reply into account
>
>> Don't agree at all.  I'd accept it if you proposed an alternative that
>
>> left aligned the instrument name as a possible option, but as it is, I
>
>> believe right alignment is the correct option here.  It should require
> an
>> override to change that.  Don't accept this change should delay
> pushing
>> this patch.
>
> I think that our basic disagreement here has more or less grown over the
> history of this patch which makes it somewhat sad that nobody else
> chimed in.

I'll pick up on the right/left alignment issue first.  I believe I concluded 
right-aligned to be the correct answer because we are effectively reusing 
the \indent value to set the width of the incipit, including instrument 
name.  Now, if someone wishes to have the first line actually indented, this 
makes it impossible.  See the 3rd image attached as an example.

See?  The instrument name ("Altus") is stuck to the left margin and it's 
impossible to adjust its position.  Right align it, however, and the first 
line can be indented to the value desired (with a little experimentation). 
The fourth image shows this.  This is surely far better?

> I think it boils down to a mismatch between your original intent
> reflected in the patch title "Adds incipit section to NR" and the course
> I am trying to take it.  To me it looks like you want a section in the
> NR (rather than some snippet) that produces an incipit like the one you
> can see in your scores.  And it would appear that everything which
> happened in between is a distraction and an annoyance to you since it
> does not actually change the image that appears while causing additional
> work.

Not at all.  I wanted a section in the NR that shows how to do incipits. 
Period.  No-one else had picked this up and so we have the shitty state that 
currently exists.  A section that just says "TBC".  What help is that?

I did not try to recreate the incipits I see in my current scores: almost 
all of those use modern notation, which seems wrong to me - they probably do 
it because of the inability to use mensural.  What I actually did was take 
the code for incipits that already existed 
(http://lsr.di.unimi.it/LSR/Snippet?id=582 and regression/incipt.ly), remove 
some code that seemed over-complex to me, fix the layout issues and go with 
that.  I personally find the result pleasing and do now use it, but there 
has never been any attempt on my part to slavishly recreate incipits "like 
the one you can see in your scores".

As to my occasional irritation.  I am driven solely by my desire to improve 
Lilypond, and particularly currently the documentation for ancient music.  I 
believe that this can be an incremental process: if what I have proposed is 
better than the status quo ante, then I believe it should be pushed and then 
subsequently improved where not perfect.  This is the basis of Agile 
development: make incremental improvements, let everyone (not just 
developers who understand the output from a review cycle) see the result, 
and improve further.  I took on board wholeheartedly the need to create an 
incipit command and implemented one.  That was over a week ago.  If 
constructive comments had been made then, I could have pushed this and 
started work on the "Ancient and modern from one source" section, which also 
says TBC and is thus similarly useless.  However, that will require 
incipits, and so I can't start.  Similarly, if my patch were in the code 
base, you could have shown code for review that would have improved it, as 
opposed to simply disagreeing with what I had proposed.

> However, we are changing from what was "just a snippet" into
> functionality built into LilyPond.  In a snippet, hardwiring some
> instrument alignment for the outcome desired for a particular graphic is
> quite fine: the user who wants a different alignment can just change the
> snippet code.  But when we are creating built-in functionality for
> LilyPond, we don't want decisions hardwired into code that is no longer
> user-maintained.  We also don't want surprising changes of defaults.
> The last proposals of mine were for
> a) changing the normal instrumentName placement to the default placement
> without incipit

See my comment above.  I explained why I did this, but it apparently remains 
wrong simply because it's not the default.

> b) giving the \incipit command the facility to conveniently override
> such defaults with a context modification
> The intended graphic end result after all this effort would indeed be
> exactly the same result you already have, but with the alignment choices
> differing from the default explicitly specified by the code.

There's nothing wrong in changing a poor default to a good one, and then 
allowing the user to restore the poor one.

> Now obviously one can commit and document one interface now and fix
> stuff up afterwards.  But then that kind of documentation patchwork is
> done by different authors and checked in and translated at different
> times.
>
> I would prefer to get stuff as correct and complete at the first go as
> we can manage.  Of course, once you throw up your hands in disgust, the
> work we can hope to get achieved from one author in one go is over.  And
> naturally, there is not much of a point to exhaust your enthusiasm for
> LilyPond over a single issue.  I'd still be glad if we could get the
> code and documentation at least to a state where we don't need to touch
> the translatable part in the NR (example use and description) any more
> for a large variation of different applications, even if it will fall to
> my lot to do further work on the \incipit definition in property-init.ly
> itself in order to have it work in more situations.
>
>
> https://codereview.appspot.com/108270043/

As I explained above, I believe in a kind of "push and show" approach. I am 
severely discouraged by continual "this is wrong, no it's not" bickering.  I 
(as you may note today) can recover my enthusiasm despite this, but I find 
it wearing, as I know others do.  I believe we need to work from a 
standpoint that we accept the view of the creator of the patch unless there 
is _proof_ that what is being proposed is wrong in terms of code quality or 
other damage to the code base.  The two you cited above (missing indent, 
missing incipit) are examples of proof that there is something wrong and I 
will work to get rid of them.  "I think the instrument name should be on the 
left" is not.

All the best,

--
Phil Holmes 

[email_philholmes.net, 2014-08-21 10:45:25]

Sorry - the images were not helpful.  It looks like my mailer adds the image 
when it's sent, not when it's attached.  Here they are again.

--
Phil Holmes 

[dak, 2014-08-21 11:31:53]

On 2014/08/21 10:21:18, mail_philholmes.net wrote:

> There's nothing wrong in changing a poor default to a good one, and then 
> allowing the user to restore the poor one.

But you are not "changing a poor default to a good one".  You are
overriding locally, as the default of a single command, what you
perceive as a poor overall default.  If the default is poor, changing
it is reasonably.  Scattering different defaults everywhere where
someone adds code isn't.

Please note that if the incipit command changes some _entirely_
_unrelated_ default, then the description of the incipit would need to
include "as one side effect, the alignment of the instrument name is
changed from its default of #CENTER to #RIGHT because #CENTER looks
ugly anyway."  Not in relation to incipits, but anyway.

> > I would prefer to get stuff as correct and complete at the first go as
> > we can manage.  Of course, once you throw up your hands in disgust, the
> > work we can hope to get achieved from one author in one go is over.  And
> > naturally, there is not much of a point to exhaust your enthusiasm for
> > LilyPond over a single issue.  I'd still be glad if we could get the
> > code and documentation at least to a state where we don't need to touch
> > the translatable part in the NR (example use and description) any more
> > for a large variation of different applications, even if it will fall to
> > my lot to do further work on the \incipit definition in property-init.ly
> > itself in order to have it work in more situations.
> >
> >
> > https://codereview.appspot.com/108270043/
> 
> As I explained above, I believe in a kind of "push and show"
> approach.

It's not just "push and show".  It is "push and show and document and
translate, and if subsequently any defaults are changed, write and
maintain respective convert-ly rules".

I spend easily 75% of my time on analyzing and fixing "push and show"
work that went wrong and that people now _expect_ to be available.
Just right now I had to completely reimplement nested overrides,
something that was implemented on a "push and show" basis because the
assumptions underlying the original implementation were simply broken
and nobody could be bothered getting or proving the details workable
before dumping some half-working code into LilyPond.

At the current point of time, we have diverging Midi features that
cannot work at the same time.

In this case, you override some defaults in a fixed manner because you
don't like the defaults of LilyPond and the code did not provide a
convenient way to override the defaults.

So I propose a way allowing it to override the respective defaults in
a convenient manner that would warrant getting put in there and
_utilized_ and documented in order to get the result you consider
better and show the users how they can arrive there themselves, and
you basically go at me with a knife.

It's not like I ask you to toil for hours.  I spelled out all the
details of code explicitly, and I can naturally also provide a patch
which is not more than a few lines.  What I cannot do is rewrite the
documentation section as if it were written by you, and that is what
this issue is actually about.

> I am severely discouraged by continual "this is wrong, no it's not"
> bickering.  I (as you may note today) can recover my enthusiasm
> despite this, but I find it wearing, as I know others do.  I believe
> we need to work from a standpoint that we accept the view of the
> creator of the patch unless there is _proof_ that what is being
> proposed is wrong in terms of code quality or other damage to the
> code base.  The two you cited above (missing indent, missing
> incipit) are examples of proof that there is something wrong

They are examples of problems in the incipit code.  _Those_ actually
are no showstoppers since fixing them does not create additional
documentation or translation or convert-ly or other followup work.
All of those should be fixable.  The one with the non-appearing
incipit will likely require a code change (I suspect that a code
shortcut has to be removed somewhere) to avoid documenting an
implementation quirk.  At any rate, _those_ problems do not affect the
_design_ of the code and the design of the user interface and its
documentation.  In contrast, diverging defaults and the inability to
predict and/or override them _do_ affect the user interface and its
documentation.

> and I will work to get rid of them.  "I think the instrument name
> should be on the left" is not.

The current default is #CENTER, by the way.

You put quote marks around that sentence as if I uttered it.  I never
did.  And I never claimed that I think the instrument name should be
on the left.  What I stated is that since the start of an incipit is
not in any graphically relevant manner different from the start of a
regular staff, there is no reason to tamper with the default
instrument alignment as part of the incipit code, whatever the default
may happen to be.

"But it looks ugly to me" is a perfectly valid reason for providing a
documented and easily accessible way of overriding it, like we do for
the default InstrumentName grob too.  It may also provide part of a
reason of eventually changing our overall default instrument name
aligment.

And once issue 766 is tackled in some manner, we better make sure that
our implementation of \incipit eventually cooperates with that
solution.  Defining how that cooperation is supposed to look becomes
harder when \incipit chooses to implement independent behavior.

[email_philholmes.net, 2014-08-21 12:03:12]

----- Original Message ----- 
From: <dak@gnu.org>
To: <PhilEHolmes@googlemail.com>; <tdanielsmusic@googlemail.com>; 
<email@philholmes.net>; <mail@philholmes.net>; <benko.pal@gmail.com>
Cc: <lilypond-devel@gnu.org>; <reply@codereview-hr.appspotmail.com>
Sent: Thursday, August 21, 2014 12:31 PM
Subject: Re: Adds incipit section to NR (issue 108270043 by 
PhilEHolmes@googlemail.com)


> On 2014/08/21 10:21:18, mail_philholmes.net wrote:
>
>> There's nothing wrong in changing a poor default to a good one, and
> then
>> allowing the user to restore the poor one.
>
> But you are not "changing a poor default to a good one".  You are
> overriding locally, as the default of a single command, what you
> perceive as a poor overall default.  If the default is poor, changing
> it is reasonably.  Scattering different defaults everywhere where
> someone adds code isn't.
>
> Please note that if the incipit command changes some _entirely_
> _unrelated_ default, then the description of the incipit would need to
> include "as one side effect, the alignment of the instrument name is
> changed from its default of #CENTER to #RIGHT because #CENTER looks
> ugly anyway."  Not in relation to incipits, but anyway.


I'm failing to understand something here.  I'm assuming the line at issue is 
this:

\once \override Staff.InstrumentName.self-alignment-X = #RIGHT

which is the line that sets the instrument alignment of the incipit 
instrument itself.  My assumption is that, since is is using \once, then it 
is not changing another entirely unrelated default.  Please could you 
explain how/why/whether this is incorrect, and how/whether it could be 
fixed.  I really don't like having to specify \incipit \with { \override 
InstrumentName.self-alignment-X = #RIGHT } because I do believe that this 
should be default behaviour in this situation.


--
Phil Holmes 

[dak, 2014-08-21 12:35:07]

"Phil Holmes" <email@philholmes.net> writes:

> ----- Original Message ----- 
> From: <dak@gnu.org>
> To: <PhilEHolmes@googlemail.com>; <tdanielsmusic@googlemail.com>;
>
>> On 2014/08/21 10:21:18, mail_philholmes.net wrote:
>>
>>> There's nothing wrong in changing a poor default to a good one, and
>>> then allowing the user to restore the poor one.
>>
>> But you are not "changing a poor default to a good one".  You are
>> overriding locally, as the default of a single command, what you
>> perceive as a poor overall default.  If the default is poor, changing
>> it is reasonably.  Scattering different defaults everywhere where
>> someone adds code isn't.
>>
>> Please note that if the incipit command changes some _entirely_
>> _unrelated_ default, then the description of the incipit would need to
>> include "as one side effect, the alignment of the instrument name is
>> changed from its default of #CENTER to #RIGHT because #CENTER looks
>> ugly anyway."  Not in relation to incipits, but anyway.
>
>
> I'm failing to understand something here.  I'm assuming the line at
> issue is this:
>
> \once \override Staff.InstrumentName.self-alignment-X = #RIGHT
>
> which is the line that sets the instrument alignment of the incipit
> instrument itself.

There are two of those lines.  The first places the incipit immediately
to the left of the normal staff.  That one is not an issue since it is
both sensible as well as unique to incipits.

The second places the normal instrument name immediately to the left of
the incipit.

> My assumption is that, since is is using \once, then it is not
> changing another entirely unrelated default.

Doesn't matter whether it is is \once or not since the value is only
consulted a single time anyway when the first and only system of the
incipit markup is created.

> Please could you explain how/why/whether this is incorrect, and
> how/whether it could be fixed.  I really don't like having to specify
> \incipit \with { \override InstrumentName.self-alignment-X = #RIGHT }
> because I do believe that this should be default behaviour in this
> situation.

In my opinion, the optimal situation would be if
InstrumentName.self-alignment-X would just be taken from the enclosing
Staff.  In that manner, one would put any overrides for the Staff
InstrumentName exactly where one would put them without incipit.
I don't see a good way to do that, however.  Thus the \with proposal.

At any rate: why do you believe that an instrument should be formatted
differently before an incipit than before a regular score?

-- 
David Kastrup

[Jean-Charles, 2014-08-21 12:55:37]

On 2014/06/29 13:51:33, PhilEHolmes wrote:
> Please review.

Sorry to step in like that.  I'm not able to comment on the code, but have just
one question, since I don't use incipits: does it happen that the original score
reproduced in an incipit happens to be on a four lines staff? How would it then
be verticaly positionned relatively to the "modern" staff?

[mail_philholmes.net, 2014-08-21 12:59:04]

----- Original Message ----- 
From: "David Kastrup" <dak@gnu.org>
To: "Phil Holmes" <email@philholmes.net>
Cc: <reply@codereview-hr.appspotmail.com>; <PhilEHolmes@googlemail.com>; 
<tdanielsmusic@googlemail.com>; <lilypond-devel@gnu.org>
Sent: Thursday, August 21, 2014 1:26 PM
Subject: Re: Adds incipit section to NR (issue 108270043 
byPhilEHolmes@googlemail.com)

> At any rate: why do you believe that an instrument should be formatted
> differently before an incipit than before a regular score?

I explained this in some detail in my email timed 11:20-ish BST.  It's 
because of the way \indent is used both for the incipit width and the 
indent.

--
Phil Holmes 

[dak, 2014-08-21 13:02:57]

On 2014/08/21 12:55:37, Jean-Charles wrote:
> On 2014/06/29 13:51:33, PhilEHolmes wrote:
> > Please review.
> 
> Sorry to step in like that.  I'm not able to comment on the code, but have
just
> one question, since I don't use incipits: does it happen that the original
score
> reproduced in an incipit happens to be on a four lines staff? How would it
then
> be verticaly positionned relatively to the "modern" staff?

There is one incipit per Staff and in line with it.  The horizontal positioning
is more of an issue: in the approach taken here, each incipit is typeset
independently and stretched to the same length.  Arguably that's not a good fit
for anything but first-note-or-syllable incipits.  However, at the current point
of time I don't see a convincing approach to get both horizontal alignment and a
good integration of incipits with the rest.  Since the main function of the
incipit is to illustrate the original key and clef, first-note-or-syllable
incipits are about the most important variants anyway.  If we figure out
something better for inherently polyphonic incipits, it will likely need to get
an entirely different interface.

So there is little point in worrying about it in the course of this issue.

[email_philholmes.net, 2014-08-21 13:14:05]

----- Original Message ----- 
From: <lilyfan@orange.fr>
To: <PhilEHolmes@googlemail.com>; <dak@gnu.org>; 
<tdanielsmusic@googlemail.com>; <email@philholmes.net>; 
<mail@philholmes.net>; <benko.pal@gmail.com>
Cc: <lilypond-devel@gnu.org>; <reply@codereview-hr.appspotmail.com>
Sent: Thursday, August 21, 2014 1:55 PM
Subject: Re: Adds incipit section to NR (issue 108270043 by 
PhilEHolmes@googlemail.com)


> On 2014/06/29 13:51:33, PhilEHolmes wrote:
>> Please review.
>
> Sorry to step in like that.  I'm not able to comment on the code, but
> have just one question, since I don't use incipits: does it happen that
> the original score reproduced in an incipit happens to be on a four
> lines staff? How would it then be verticaly positionned relatively to
> the "modern" staff?
>
> https://codereview.appspot.com/108270043/

Using the alignments proposed in my patch: like the attached.

--
Phil Holmes 

[dak, 2014-08-21 13:43:45]

"Phil Holmes" <mail@philholmes.net> writes:

> ----- Original Message ----- 
> From: "David Kastrup" <dak@gnu.org>
> To: "Phil Holmes" <email@philholmes.net>
> Cc: <reply@codereview-hr.appspotmail.com>;
> <PhilEHolmes@googlemail.com>; <tdanielsmusic@googlemail.com>;
> <lilypond-devel@gnu.org>
> Sent: Thursday, August 21, 2014 1:26 PM
> Subject: Re: Adds incipit section to NR (issue 108270043
> byPhilEHolmes@googlemail.com)
>
>> At any rate: why do you believe that an instrument should be formatted
>> differently before an incipit than before a regular score?
>
> I explained this in some detail in my email timed 11:20-ish BST.  It's
> because of the way \indent is used both for the incipit width and the
> indent.

It isn't really.

After using that "reference" for digging up the relevant quote, taking
only about a quarter of an hour, I arrive at

    I'll pick up on the right/left alignment issue first.  I believe I
    concluded right-aligned to be the correct answer because we are
    effectively reusing the \indent value to set the width of the
    incipit, including instrument name.  Now, if someone wishes to have
    the first line actually indented, this makes it impossible.  See the
    3rd image attached as an example.

    See?  The instrument name ("Altus") is stuck to the left margin and
    it's impossible to adjust its position.  Right align it, however,
    and the first line can be indented to the value desired (with a
    little experimentation). The fourth image shows this.  This is
    surely far better?


At the current state of the debate I have a hard time viewing this as
anything but a straw man.  The default, as I have written several times
already, is _not_ left alignment.  It is #CENTER.  Indeed, if you set
the instrument name alignment to the NON-standard #LEFT, the instrument
name, as long as \indent (or, in the case of the incipit,
\indent-\incipit-width) provides enough space, will not budge from the
left edge.  No question about that.  But that's not the issue at all.

Because InstrumentName.self-alignment-X declares where to place the
instrument name in the free space provided by \indent.  The default in
every score is to _center_ the instrument name in the available space.

Here is how that looks
<URL:http://lilypond.org/doc/v2.18/Documentation/snippets/pitches#pitches-orchestra-choir-and-piano-template>.

Only when there is insufficient indent to place the instrument name is
it put right before the staff, _right_-aligned.

The default _never_ works out to be aligned at the left edge, yet you
continue to argue against the completely irrelevant case of
left-alignment when wanting to have the default overriden in the
presence of incipits.

I don't get it.  There is _nothing_ in the presence of incipits that
would make _any_ difference in regard to how the instrument name is
placed to the left of staff or incipit.

Unless incipit-width is too small to accommodate the incipit in the
first place, the amount of space available for the instrument name is
\indent-\incipit-width.  Even in that case, I don't see that the natural
or best placement of the instrument name in the remaining space would be
at the right of the remaining space.

-- 
David Kastrup

[mail_philholmes.net, 2014-08-21 14:18:27]

----- Original Message ----- 
From: "David Kastrup" <dak@gnu.org>
To: "Phil Holmes" <mail@philholmes.net>
Cc: <tdanielsmusic@googlemail.com>; <PhilEHolmes@googlemail.com>; 
<reply@codereview-hr.appspotmail.com>; <lilypond-devel@gnu.org>
Sent: Thursday, August 21, 2014 2:43 PM
Subject: Re: Adds incipit section to NR (issue 108270043 
byPhilEHolmes@googlemail.com)


> "Phil Holmes" <mail@philholmes.net> writes:
>
>> ----- Original Message ----- 
>> From: "David Kastrup" <dak@gnu.org>
>> To: "Phil Holmes" <email@philholmes.net>
>> Cc: <reply@codereview-hr.appspotmail.com>;
>> <PhilEHolmes@googlemail.com>; <tdanielsmusic@googlemail.com>;
>> <lilypond-devel@gnu.org>
>> Sent: Thursday, August 21, 2014 1:26 PM
>> Subject: Re: Adds incipit section to NR (issue 108270043
>> byPhilEHolmes@googlemail.com)
>>
>>> At any rate: why do you believe that an instrument should be formatted
>>> differently before an incipit than before a regular score?
>>
>> I explained this in some detail in my email timed 11:20-ish BST.  It's
>> because of the way \indent is used both for the incipit width and the
>> indent.
>
> It isn't really.
>
> After using that "reference" for digging up the relevant quote, taking
> only about a quarter of an hour, I arrive at
>
>    I'll pick up on the right/left alignment issue first.  I believe I
>    concluded right-aligned to be the correct answer because we are
>    effectively reusing the \indent value to set the width of the
>    incipit, including instrument name.  Now, if someone wishes to have
>    the first line actually indented, this makes it impossible.  See the
>    3rd image attached as an example.
>
>    See?  The instrument name ("Altus") is stuck to the left margin and
>    it's impossible to adjust its position.  Right align it, however,
>    and the first line can be indented to the value desired (with a
>    little experimentation). The fourth image shows this.  This is
>    surely far better?
>
>
> At the current state of the debate I have a hard time viewing this as
> anything but a straw man.  The default, as I have written several times
> already, is _not_ left alignment.  It is #CENTER.  Indeed, if you set
> the instrument name alignment to the NON-standard #LEFT, the instrument
> name, as long as \indent (or, in the case of the incipit,
> \indent-\incipit-width) provides enough space, will not budge from the
> left edge.  No question about that.  But that's not the issue at all.

That was my mistake, for which I apologise.  I don't believe you'd pointed 
this out prior to my earlier mail.

> Unless incipit-width is too small to accommodate the incipit in the
> first place, the amount of space available for the instrument name is
> \indent-\incipit-width.  Even in that case, I don't see that the natural
> or best placement of the instrument name in the remaining space would be
> at the right of the remaining space.
>
> -- 
> David Kastrup

And this is the nub of the discussion.  There's nothing actually _wrong_ 
with my patch: it's just you don't like how it looks.  I very much do.  This 
time I've attached a centre-aligned and a right-aligned example, and much 
prefer the latter.  And if you say right-aligned is wrong, you should also 
write to Elaine Gould to correct her.

This takes me back to my previous mail.  I'm very happy to attempt to 
correct incorrect code, etc.  However, I don't think it's good to have this 
continuing debate simply about what looks better.  You have one opinion, I 
have another, and it's my patch.

--
Phil Holmes 

[dak, 2014-08-21 14:38:33]

"Phil Holmes" <mail@philholmes.net> writes:

>> Unless incipit-width is too small to accommodate the incipit in the
>> first place, the amount of space available for the instrument name is
>> \indent-\incipit-width.  Even in that case, I don't see that the natural
>> or best placement of the instrument name in the remaining space would be
>> at the right of the remaining space.
>>
>> -- 
>> David Kastrup
>
> And this is the nub of the discussion.  There's nothing actually
> _wrong_ with my patch: it's just you don't like how it looks.

Again, I have a hard time viewing this as anything than a strawman by
now since I have repeated my argument more than half a dozen times
already.  Yet you _insist_ on misrepresenting it.

The question is not what looks better.  The problem is that there is
_no_ reason to _gratuitiously_ introduce a _different_ default for a
command like incipit when there is _no_ _reason_ _whatsoever_ that the
introduction of an incipit should _change_ the best default.

I have asked pretty much _every_ _single_ mail: what do you think makes
the situation _with_ an incipit _different_ from the situation without
an incipit with regard to formatting of the instrument name?

I would protest _just_ the same if you overrode the default with
#CENTER.  We _don't_ want to maintain a separate default _with_ and
_without_ incipits.

If you consider right alignment correct, it will be correct without
incipits as well.  And there is nothing wrong with proposing to change
our current default.  But there _is_ something wrong with scattering
different defaults all over the code base.

> I very much do.  This time I've attached a centre-aligned and a
> right-aligned example, and much prefer the latter.  And if you say
> right-aligned is wrong, you should also write to Elaine Gould to
> correct her.

Does Elaine Gould state _different_ defaults for the alignment of
instrument names before an incipit and before a regular staff?

Or is this yet another straw man?

> This takes me back to my previous mail.  I'm very happy to attempt to
> correct incorrect code, etc.  However, I don't think it's good to have
> this continuing debate simply about what looks better.

Strawman.  We are not debating what looks better.  My objection has
_always_ been one that we don't want to have two different standards in
our code base without a reason.

Please point out a single mail of mine where I have made this an issue
about "what looks better".  Whether or not this unabated
misrepresentation is intentional, it is definitely quite annoying.

> You have one opinion, I have another, and it's my patch.

Your patch is supposed to include documentation.  If the \incipit patch
changes the default instrument alignment, the documentation is
incomplete without pointing out that change.

The rationale of this difference cannot be expected to be obvious to
other documentation writers or users, so please describe it in your
documentation of the usage of the \incipit music function.

-- 
David Kastrup

[email_philholmes.net, 2014-08-21 14:40:33]

Let's see if anyone else has an opinion.

--
Phil Holmes

[dak, 2014-08-21 14:56:55]

"Phil Holmes" <email@philholmes.net> writes:

> Let's see if anyone else has an opinion.

About what?  You want to argue about what instrument name alignment
looks nicest.  But that's besides the point.

The issue I am talking about is that there is nothing inherent in
incipits that makes aligning instrument names differently in the
presence of incipits sensible.

If you want a different default alignment of instrument names, by all
means propose a respective issue and support it with quotes from Gould.
I am not opposed to that, and on forming a common decision about the
default based on literature and visual comparisons.

But it's an issue separate from incipits.  You have not volunteered
_any_ argument that would make the situation different regarding
incipits, so there is no point in overriding the default.  Not even with
#CENTER which is _currently_ the default instrument name alignment but
which we may elect to change at some point of time.

-- 
David Kastrup

[t.daniels_treda.co.uk, 2014-08-21 15:03:21]

Phil, you wrote Thursday, August 21, 2014 3:18 PM
 
> And this is the nub of the discussion.  There's nothing actually _wrong_ 
> with my patch: it's just you don't like how it looks.  I very much do.  This 
> time I've attached a centre-aligned and a right-aligned example, and much 
> prefer the latter.  And if you say right-aligned is wrong, you should also 
> write to Elaine Gould to correct her.

The only mention of incipits that I can find in Elaine Gould's book is on
page  433.  She says nothing there about alignment of instrument names, but
the image of the incipit has them left-aligned, above the staff showing the
ancient
music.  On page 509 she shows two alternatives for instrument labels in
general: traditional-style in which the labels are centered and
alternative-style 
in which the labels are right-aligned.  The accompanying text says, "Instrument
labels may be centered in the margin space - this is the most traditional
layout.  Alternatively they may be justified right or even justified left." 

Have I missed something?

Trevor

[mail_philholmes.net, 2014-08-21 15:08:09]

----- Original Message ----- 
From: "David Kastrup" <dak@gnu.org>
To: "Phil Holmes" <email@philholmes.net>
Cc: <lilypond-devel@gnu.org>; <reply@codereview-hr.appspotmail.com>; 
<PhilEHolmes@googlemail.com>; <tdanielsmusic@googlemail.com>
Sent: Thursday, August 21, 2014 3:56 PM
Subject: Re: Adds incipit section to NR (issue 
108270043byPhilEHolmes@googlemail.com)


"Phil Holmes" <email@philholmes.net> writes:

> > Let's see if anyone else has an opinion.

> About what?

About whether it's sufficiently a problem to prevent any further updates to 
the ancient music documentation, which is what it's doing.  Please stop 
further debate, let others comment.  If no-one does, then no-one else shares 
your concern.  If they do, I'll happily accept consensus.

--
Phil Holmes 

[dak, 2014-08-21 15:24:35]

"Phil Holmes" <mail@philholmes.net> writes:

> ----- Original Message ----- 
> From: "David Kastrup" <dak@gnu.org>
> To: "Phil Holmes" <email@philholmes.net>
> Cc: <lilypond-devel@gnu.org>; <reply@codereview-hr.appspotmail.com>;
> <PhilEHolmes@googlemail.com>; <tdanielsmusic@googlemail.com>
> Sent: Thursday, August 21, 2014 3:56 PM
> Subject: Re: Adds incipit section to NR (issue
> 108270043byPhilEHolmes@googlemail.com)
>
>
> "Phil Holmes" <email@philholmes.net> writes:
>
>> > Let's see if anyone else has an opinion.
>
>> About what?
>
> About whether it's

What is "it"?

> sufficiently a problem to prevent any further updates to the ancient
> music documentation, which is what it's doing.

What is "it" here?

> Please stop further debate, let others comment.

On what?

> If no-one does, then no-one else shares your concern.

I would have written "or yours", but since you do not even bother giving
a reason why instrument names should be aligned differently in the
presence of incipits, it is not even clear what your concern is.  Maybe
it's "reviews are a hassle".  I can agree with that.

-- 
David Kastrup

[Trevor Daniels, 2014-08-21 17:50:15]

Let's see if I understand the issue here.

Because the incipit is generated as a separate score hidden inside a music
function it is not possible to use the usual override mechanism to change any
values set inside the music function, including the value of
InstrumentName.self-aligment-X.  The default value of self-aligment-X is CENTER,
but it is set to RIGHT within the music function because it is thought this
makes the incipit look better.  Since the user cannot change it, it is important
that the value chosen is optimum.

The problem I see arises when the user has a standard for the position of
InstrumentName which is different from whatever is set in the incipit music
function.  A publisher will want to maintain his house style whatever that is,
and will want incipits to follow that.  So in my view it is essential that a
means to change the position of InstrumentName for incipits is highly desirable.
 David has suggested one way of achieving this, albeit by a rather inelegant
approach.  I think the means of achieving this needs to be explored further.

Trevor

[dak, 2014-08-21 18:02:57]

On 2014/08/21 17:50:15, Trevor Daniels wrote:
> Let's see if I understand the issue here.
> 
> Because the incipit is generated as a separate score hidden inside a music
> function it is not possible to use the usual override mechanism to change any
> values set inside the music function, including the value of
> InstrumentName.self-aligment-X.  The default value of self-aligment-X is
CENTER,
> but it is set to RIGHT within the music function because it is thought this
> makes the incipit look better.  Since the user cannot change it, it is
important
> that the value chosen is optimum.
> 
> The problem I see arises when the user has a standard for the position of
> InstrumentName which is different from whatever is set in the incipit music
> function.  A publisher will want to maintain his house style whatever that is,
> and will want incipits to follow that.  So in my view it is essential that a
> means to change the position of InstrumentName for incipits is highly
desirable.
>  David has suggested one way of achieving this, albeit by a rather inelegant
> approach.  I think the means of achieving this needs to be explored further.
> 
> Trevor

As long as the \incipit does not contain any grace notes, it should likely work
to change the alignment via
\incipit { \override Staff.InstrumentName.self-alignment-X = #... }
In contrast to the \with solution, one would need to explicitly specify Staff or
MensuralStaff.  As opposed to having the InstrumentName.self-alignment-X taken
from the Staff _containing_ the \incipit (I proposed some mechanisms to do that
on the developer list), either way of overriding the InstrumentName alignment
from one of \incipit's arguments would require documentation.

I definitely would prefer the solution siphoning off the alignment from the
outer Staff since the incipit being a score environment of its own is an
implementation detail, and the less the user needs to think about its internals,
the better.

[PhilEHolmes, 2014-09-30 15:10:43]

Changes as discussed

[PhilEHolmes, 2014-09-30 15:15:31]

I hope this is close to what is required...

[dak, 2014-09-30 16:27:03]

Other than that LGTM.  Sorry for holding this up for so long.

https://codereview.appspot.com/108270043/diff/60001/Documentation/notation/an...
File Documentation/notation/ancient.itely (right):

https://codereview.appspot.com/108270043/diff/60001/Documentation/notation/an...
Documentation/notation/ancient.itely:2680: Note that instrumentName must be set
in the music for the incipit to be
@knownissue perhaps?

[Trevor Daniels, 2014-10-01 13:14:31]

LGTM

Trevor