review new info on file layout

classic Classic list List threaded Threaded
21 messages Options
12
Reply | Threaded
Open this post in threaded view
|

review new info on file layout

Graham Percival-2
Hi guys,

I've written some more docs about file structure and writing lilypond  
files.  I've glossed over some issues in the interest of simplicity.  
Before I advertise this on -user, could a few people take a look at the  
docs?  As I said, I've glossed over some issues -- did I omit anything  
which you think is vital, or mislead people?

Sections 4.4, 4.5, 4.6:
http://lilypond.org/doc/v2.7/Documentation/user/lilypond/Putting-it- 
all-together.html

NB:  the version in 2.7.29 has some tabs instead of spaces; I've fixed  
this problem in CVS.

Thanks,
- Graham



_______________________________________________
lilypond-devel mailing list
[hidden email]
http://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Re: review new info on file layout

Cameron Horsburgh
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Graham Percival wrote:

> Hi guys,
>
> I've written some more docs about file structure and writing lilypond
> files.  I've glossed over some issues in the interest of simplicity.  
> Before I advertise this on -user, could a few people take a look at the
> docs?  As I said, I've glossed over some issues -- did I omit anything
> which you think is vital, or mislead people?
>
> Sections 4.4, 4.5, 4.6:
> http://lilypond.org/doc/v2.7/Documentation/user/lilypond/Putting-it-
> all-together.html
>
> NB:  the version in 2.7.29 has some tabs instead of spaces; I've fixed
> this problem in CVS.
>
> Thanks,
> - Graham
>
>
>
> _______________________________________________
> lilypond-devel mailing list
> [hidden email]
> http://lists.gnu.org/mailman/listinfo/lilypond-devel
>

At a first review, I'm quite impressed. It helps a lot, and it's
clarified my thinking on a few things.

You mention once or twice that users can use any names for variables
they like--I presume command names can't be used. This trivial case:

score = {a b c}
\score{\score}

fails for obvious reasons. If that is the case, perhaps a note should be
made, or a link to the section about using variables (2.18 Organizing
Larger Pieces--I wonder if the section on variables could be separated
out for easier reference?)

I also wonder if the instructions on commenting sections out could be
confusing for new users--it may be useful to add a note about commenting
single lines as well. (If you wanted to confuse things you could mention
that some editors will comment out regions too if needed.)

Overall it's a great addition to the manual. I'm a little put out
because I was starting to put together a few notes to do something
similar, but I'm sure I'll get over it!

Cameron
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.2 (GNU/Linux)
Comment: Using GnuPG with Thunderbird - http://enigmail.mozdev.org

iD8DBQFD3IcEvoajcVq9gkURAiptAKCGJ21L2RE4dlnsiznXqsM1E5bP4wCfX7/U
E8nUt2RzDuKJBLd9B3O2oE4=
=EHdI
-----END PGP SIGNATURE-----



_______________________________________________
lilypond-devel mailing list
[hidden email]
http://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Re: review new info on file layout

Han-Wen Nienhuys
In reply to this post by Graham Percival-2
Graham Percival wrote:

> Hi guys,
>
> I've written some more docs about file structure and writing lilypond  
> files.  I've glossed over some issues in the interest of simplicity.  
> Before I advertise this on -user, could a few people take a look at the  
> docs?  As I said, I've glossed over some issues -- did I omit anything  
> which you think is vital, or mislead people?
>
> Sections 4.4, 4.5, 4.6:
> http://lilypond.org/doc/v2.7/Documentation/user/lilypond/Putting-it- 
> all-together.html

couple of more points:

  -4.1 Suggestions for writing LilyPond files

if copying:

* enter one (manuscript) line at a time, and correct it directly. Use
showLastLength to speed up this process.

* define

   mBreak = { \break }

   and insert them where the manuscript breaks lines. This makes it
easier to  compare lily's output and the original.

The rest of it looks good, probably more verbose than I would write it,
but that's why I am the hacker, and you're the documentation editor :)



--
  Han-Wen Nienhuys - [hidden email] - http://www.xs4all.nl/~hanwen


_______________________________________________
lilypond-devel mailing list
[hidden email]
http://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Re: review new info on file layout

Cameron Horsburgh
In reply to this post by Cameron Horsburgh
Cameron Horsburgh wrote:

> Graham Percival wrote:
>
>>>Hi guys,
>>>
>>>I've written some more docs about file structure and writing lilypond
>>>files.  I've glossed over some issues in the interest of simplicity.  
>>>Before I advertise this on -user, could a few people take a look at the
>>>docs?  As I said, I've glossed over some issues -- did I omit anything
>>>which you think is vital, or mislead people?
>>>
>>>Sections 4.4, 4.5, 4.6:
>>>http://lilypond.org/doc/v2.7/Documentation/user/lilypond/Putting-it-
>>>all-together.html
>>>
 (snip)
>
> I also wonder if the instructions on commenting sections out could be
> confusing for new users--it may be useful to add a note about commenting
> single lines as well. (If you wanted to confuse things you could mention
> that some editors will comment out regions too if needed.)
(snip)
>
> Cameron

Oops, there is a note about single line comments. It follows a ( bracket
though and that confused me a bit until I carefully parsed the sentence.
Perhaps the sentence needs to read something like,

###########
The most powerful tools for this purpose are the single line comment
which uses the % sign and the block comment which uses the %{ ... %}
construct (see Section 2.12 for more information).
###########

Just a thought...

Cameron



_______________________________________________
lilypond-devel mailing list
[hidden email]
http://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Re: review new info on file layout

Graham Percival-2
In reply to this post by Cameron Horsburgh

On 29-Jan-06, at 1:12 AM, Cameron Horsburgh wrote:

> Overall it's a great addition to the manual.

Thanks!  I've added your suggestions.  I also added Han-Wen's
suggestions; I'll advertise it on -user when .30 comes out.

>  I'm a little put out
> because I was starting to put together a few notes to do something
> similar, but I'm sure I'll get over it!

Sorry.  Let me know if you're working on anything else; that way we can
avoid duplication of effort.

- Graham



_______________________________________________
lilypond-devel mailing list
[hidden email]
http://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Re: review new info on file layout

Don Blaheta
In reply to this post by Graham Percival-2
Quoth Graham Percival:
> I've written some more docs about file structure and writing lilypond  
> files.  I've glossed over some issues in the interest of simplicity.  
> Before I advertise this on -user, could a few people take a look at the  
> docs?  As I said, I've glossed over some issues -- did I omit anything  
> which you think is vital, or mislead people?

This looks really nice, and addresses much of the lack I found in
the manual before.  Thanks!  Some nits:

The parenthetical at the bottom of 4.4 is a little confusing.  Maybe:
  the value of melody (i.e. everything after the equals sign)
?

In 4.4 and 4.5, would it be better to say "A \score must contain exactly
one music expression (possibly complex)"?  Saying it must "begin with" a
music expression isn't saying quite enough.

(2.7 is also very nice---either it's new or I missed it before.)

The indents on the examples in 4.5 are really odd---very large and not
consistent.  (Oh... if this is the tab problem you mention, nevermind.)

Speaking of indents, you need to grep on "indent|ident"; you have a
tendency to confuse the two (I noticed an error one direction in 4.2 and
the other in 5.8).

The parenthetical at the top of 4.6 is a little confusing; maybe
  (line-based, with %, and block-based, with %{ ... %})
?  Also, in the same paragraph: "doens't"

--
-=-Don Blaheta-=-=-[hidden email]-=-=-=-<http://www.blahedo.org/>-=-
Cogito cogito ergo cogito sum---
"I think that I think, therefore I think that I am."
                        --Ambrose Bierce, "The Devil's Dictionary"


_______________________________________________
lilypond-devel mailing list
[hidden email]
http://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Re: review new info on file layout

Graham Percival-2

On 29-Jan-06, at 10:26 PM, Don Blaheta wrote:

> In 4.4 and 4.5, would it be better to say "A \score must contain
> exactly
> one music expression (possibly complex)"?  Saying it must "begin with"
> a
> music expression isn't saying quite enough.

The \score must _begin_ with the expression, and the whole point of
those docs is to make the point that a music expression can be complex
and long.  If that point isn't clearly made on its own, then I should
improve the rest of those docs, not that line.

> Speaking of indents, you need to grep on "indent|ident"; you have a
> tendency to confuse the two (I noticed an error one direction in 4.2
> and
> the other in 5.8).

Thanks.

> The parenthetical at the top of 4.6 is a little confusing; maybe
>   (line-based, with %, and block-based, with %{ ... %})

Already fixed.  I added other changes you mentioned.

Thanks,
- Graham



_______________________________________________
lilypond-devel mailing list
[hidden email]
http://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Re: review new info on file layout

Don Blaheta
Quoth Graham Percival:
> On 29-Jan-06, at 10:26 PM, Don Blaheta wrote:
> > In 4.4 and 4.5, would it be better to say "A \score must contain
> > exactly one music expression (possibly complex)"?  Saying it must
> > "begin with" a music expression isn't saying quite enough.
>
> The \score must _begin_ with the expression, and the whole point of
> those docs is to make the point that a music expression can be complex
> and long.  If that point isn't clearly made on its own, then I should
> improve the rest of those docs, not that line.

The complexity isn't in dispute; but if you say "must begin with a music
expression", it seems to imply that there can be more than one, but as I
understand it, there can only be exactly one.  That one expression can
contain others, of course, but there you go.  Maybe "...must begin with
*the* music expression"?  I dunno.  I guess it's not that big a deal.

--
-=-Don Blaheta-=-=-[hidden email]-=-=-=-<http://www.blahedo.org/>-=-
It is not what a teenager knows that bothers his parents, it is how
he found out.


_______________________________________________
lilypond-devel mailing list
[hidden email]
http://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Re: review new info on file layout

Erik Sandberg
In reply to this post by Graham Percival-2
On Monday 30 January 2006 23.53, Graham Percival wrote:
> On 29-Jan-06, at 10:26 PM, Don Blaheta wrote:
> > Speaking of indents, you need to grep on "indent|ident"; you have a
> > tendency to confuse the two (I noticed an error one direction in 4.2
> > and
> > the other in 5.8).
>
> Thanks.

BTW, is the meaning of the word 'indent' well-known among non-programmers? In
section 4.1 there's a suggestion "indent your braces" with no further
explanation. There's a risk that those who understand the sentence, are the
ones who already knew it's a good idea.


There's also a mistake in 4.5:
      \context Staff = singer {
        \context Voice = vocal { \melody }
        \lyricsto vocal \new Lyrics { \text }
      }
      \context PianoStaff = piano {
        \context Staff = upper { \upper }
        \context Staff = lower { \lower }
      }

- The outer braces should be << >> (using {} generates incorrect output)
- The following is a bit misleading:
      \context Staff = singer <<
        \context Voice = vocal { \melody }
        \lyricsto vocal \new Lyrics { \text }
      >>
The lyrics context is not part of the Staff context, and it might be created
after the PianoStaff (which typesets it below the PianoStaff).

The correct way would be:

      \context Staff = singer <<
        \context Voice = vocal { \melody }
      >>
      \new Lyrics \lyricsto vocal { \text }

(I think there's a minor pedagogical point in saying \new Lyrics before
\lyricsto, since the \new Lyrics really isn't a relevant argument of the
music function, and because all other contexts start with context names)

You could of course use \addlyrics instead.

--
Erik


_______________________________________________
lilypond-devel mailing list
[hidden email]
http://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Re: review new info on file layout

Cameron Horsburgh
In reply to this post by Don Blaheta
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Don Blaheta wrote:

> Quoth Graham Percival:
>
>>On 29-Jan-06, at 10:26 PM, Don Blaheta wrote:
>>
>>>In 4.4 and 4.5, would it be better to say "A \score must contain
>>>exactly one music expression (possibly complex)"?  Saying it must
>>>"begin with" a music expression isn't saying quite enough.
>>
>>The \score must _begin_ with the expression, and the whole point of
>>those docs is to make the point that a music expression can be complex
>>and long.  If that point isn't clearly made on its own, then I should
>>improve the rest of those docs, not that line.
>
>
> The complexity isn't in dispute; but if you say "must begin with a music
> expression", it seems to imply that there can be more than one, but as I
> understand it, there can only be exactly one.  That one expression can
> contain others, of course, but there you go.  Maybe "...must begin with
> *the* music expression"?  I dunno.  I guess it's not that big a deal.
>


How about something like:
***********************
A score block simply consists of a single music expression. That music
expression may be followed by midi, header, layout and/or paper blocks.

For example:

\score{
        ...music expression...
}

or perhaps

\score{
        ...music expression...
        \layout{...}
        \midi{...}
}
***********************
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.2 (GNU/Linux)
Comment: Using GnuPG with Thunderbird - http://enigmail.mozdev.org

iD8DBQFD3za9voajcVq9gkURAlSIAJ9Kfn1g1zNpUqtGELh8s+pAvptwEwCaAmsU
FT7VPIiN7ujFsNWVTWTD5iI=
=ZOEp
-----END PGP SIGNATURE-----



_______________________________________________
lilypond-devel mailing list
[hidden email]
http://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Re: review new info on file layout

Graham Percival-2
In reply to this post by Erik Sandberg

On 31-Jan-06, at 12:55 AM, Erik Sandberg wrote:

> BTW, is the meaning of the word 'indent' well-known among
> non-programmers? In

Excellent point!  I think I'll reformat the whole chapter 4 with this
distinction (programmers vs. non-programmers) in mind.

> - The outer braces should be << >> (using {} generates incorrect
> output)

Thanks, fixed.

> - The following is a bit misleading:
>       \context Staff = singer <<
>         \context Voice = vocal { \melody }
>         \lyricsto vocal \new Lyrics { \text }
>>>
> The lyrics context is not part of the Staff context,

Really?  That's a pity; it would help to keep things simple.  Anyway,
thanks!  I didn't know that.

> The correct way would be:
>
>       \context Staff = singer <<
>         \context Voice = vocal { \melody }
>>>
>       \new Lyrics \lyricsto vocal { \text }

Thanks, fixed in CVS.

> (I think there's a minor pedagogical point in saying \new Lyrics before
> \lyricsto, since the \new Lyrics really isn't a relevant argument of
> the
> music function, and because all other contexts start with context
> names)
>
> You could of course use \addlyrics instead.

I still haven't used lyrics -- what do you recommend?  We should
probably use the same thing here as we do in the Example templates...
what should those ones be?

Cheers,
- Graham



_______________________________________________
lilypond-devel mailing list
[hidden email]
http://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Re: review new info on file layout

Don Blaheta
Quoth Graham Percival:

> On 31-Jan-06, at 12:55 AM, Erik Sandberg wrote:
> > (I think there's a minor pedagogical point in saying \new Lyrics before
> > \lyricsto, since the \new Lyrics really isn't a relevant argument of
> > the music function, and because all other contexts start with
> > context names)
> >
> > You could of course use \addlyrics instead.
>
> I still haven't used lyrics -- what do you recommend?  We should
> probably use the same thing here as we do in the Example templates...
> what should those ones be?

I slightly prefer "\new Lyrics \lyricsto" to the reverse, but either one
is better than \addlyrics, by me; for whatever reason, I still find
\addlyrics oddly confusing, and using \lyricsto is (to me) much clearer
since I really know exactly what I'm associating with what.  As a
general rule, I think it's easier to learn named constructs before
anonymous ones.

On the "indent" issue, most people should at least be familiar with the
word wrt paragraphs or block quotations, so you should be able to
leverage that.

--
-=-Don Blaheta-=-=-[hidden email]-=-=-=-<http://www.blahedo.org/>-=-
Tell a man that there are 400 billion stars and he'll believe you.
Tell him a bench has wet paint and he has to touch it.


_______________________________________________
lilypond-devel mailing list
[hidden email]
http://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Re: review new info on file layout

Erik Sandberg
In reply to this post by Graham Percival-2
On Wednesday 01 February 2006 21.13, Graham Percival wrote:

> On 31-Jan-06, at 12:55 AM, Erik Sandberg wrote:
> > - The following is a bit misleading:
> >       \context Staff = singer <<
> >         \context Voice = vocal { \melody }
> >         \lyricsto vocal \new Lyrics { \text }
> >
> > The lyrics context is not part of the Staff context,
>
> Really?  That's a pity; it would help to keep things simple.  Anyway,
> thanks!  I didn't know that.



> > (I think there's a minor pedagogical point in saying \new Lyrics before
> > \lyricsto, since the \new Lyrics really isn't a relevant argument of
> > the
> > music function, and because all other contexts start with context
> > names)
> >
> > You could of course use \addlyrics instead.
>
> I still haven't used lyrics -- what do you recommend?  We should
> probably use the same thing here as we do in the Example templates...
> what should those ones be?

Well, \addlyrics only works in the most simple cases, so there's a point in
presenting \lyricsto instead.

BTW, the following template:
http://lilypond.org/doc/v2.7/Documentation/user/lilypond/Single-staff.html#Single-staff
does a \context Voice=one{} without explicitly creating the surrounding staff.
I'd recommend to add a \new Staff, like:
        <<
           \new Staff \context Voice = one {
              \autoBeamOff
              \melody
           }
           \lyricsto "one" \new Lyrics \text
        >>

Anyway that's what I usually do. It "feels" unsafe to use \context Voice alone
to create a new staff, it "feels" like that context could end up in an
already existing staff if more parts are added to the score in a similar way.
Consider the following, for example:
        <<
           \context Voice = one {
              \autoBeamOff
              \melody
           }
           \context Voice = two {
              \accomp
           }
           \lyricsto "one" \new Lyrics \text
        >>

I think lily does create separate staves for the voices in this case, but it's
not at all clear, and adding \new Staff statements explicitly makes the
semantics clearer.

--
Erik


_______________________________________________
lilypond-devel mailing list
[hidden email]
http://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Re: review new info on file layout

Mats Bengtsson-4
Quoting Erik Sandberg <[hidden email]>:
>> > (I think there's a minor pedagogical point in saying \new Lyrics before
>> > \lyricsto, since the \new Lyrics really isn't a relevant argument of
>> > the
>> > music function, and because all other contexts start with context
>> > names)

I would say the opposite, since in all other situations \new is used like
\new Lyrics {...} or \new Lyrics \with {...} {...}. If you insert
\lyricsto inbetween, people might get the the impression that
\lyricsto is part of the \new Lyrics construct. If you want to exaggerate
the pedagogics, I would even propose to say
\lyricsto mytune { \new Lyrics {...} }
to make it really clear what \lyricsto does (I hope it's legal syntax,
haven't checked).


> BTW, the following template:
> http://lilypond.org/doc/v2.7/Documentation/user/lilypond/Single-staff.html#Single-staff
> does a \context Voice=one{} without explicitly creating the
> surrounding staff.
> I'd recommend to add a \new Staff, like:
>        <<
>           \new Staff \context Voice = one {
>              \autoBeamOff
>              \melody
>           }
>           \lyricsto "one" \new Lyrics \text
>        >>
>
> Anyway that's what I usually do. It "feels" unsafe to use \context
> Voice alone
> to create a new staff, it "feels" like that context could end up in an
> already existing staff if more parts are added to the score in a similar way.
> Consider the following, for example:
>        <<
>           \context Voice = one {
>              \autoBeamOff
>              \melody
>           }
>           \context Voice = two {
>              \accomp
>           }
>           \lyricsto "one" \new Lyrics \text
>        >>
>
> I think lily does create separate staves for the voices in this case,
> but it's
> not at all clear, and adding \new Staff statements explicitly makes the
> semantics clearer.

We have lots of optional constructs in the syntax, { c } is actually a
short-cut for
\book{\score{\new Staff{\new Voice{ c }}}}
(maybe I missed something). I think this is one major source of confusion
but of course it's also convenient. My personal view is that we should
make at least some of these parts compulsory again (especially \score),
since it really only saves a significant portion of key-strokes when
you write an example file with one or two bars, but not really for any
real music.

    /Mats




_______________________________________________
lilypond-devel mailing list
[hidden email]
http://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Re: review new info on file layout

Erik Sandberg
On Friday 03 February 2006 21.12, Mats Bengtsson wrote:
> Quoting Erik Sandberg <[hidden email]>:
> I would say the opposite, since in all other situations \new is used like
> \new Lyrics {...} or \new Lyrics \with {...} {...}. If you insert
> \lyricsto inbetween, people might get the the impression that
> \lyricsto is part of the \new Lyrics construct. If you want to exaggerate
> the pedagogics, I would even propose to say
> \lyricsto mytune { \new Lyrics {...} }
> to make it really clear what \lyricsto does (I hope it's legal syntax,
> haven't checked).

Then I'd propose this instead:
\new Lyrics { \lyricsto mytune { ... } }
because it feels relevant to me to consequently create contexts as top-level
as possible. (hm.. the outer {} in my example are still confusing though,
since lyricsto never can be part of anything sequential)

> > I think lily does create separate staves for the voices in this case,
> > but it's
> > not at all clear, and adding \new Staff statements explicitly makes the
> > semantics clearer.
>
> We have lots of optional constructs in the syntax, { c } is actually a
> short-cut for
> \book{\score{\new Staff{\new Voice{ c }}}}
> (maybe I missed something).
yes, you can add a \new Score inbetween also, and empty layout and header
blocks.
> I think this is one major source of confusion
> but of course it's also convenient. My personal view is that we should
> make at least some of these parts compulsory again (especially \score),
> since it really only saves a significant portion of key-strokes when
> you write an example file with one or two bars, but not really for any
> real music.

I think the shorthand without score is highly relevant:
- Lots of music is just short snippets. See e.g. regression tests, LSR and bug
archive.
- Suppose that Wikipedia begins to use lily. They will probably support
constructs such as <music> {c d e f } </music> regardless of whether lily
forces \score. People who learn lily from wikipedia should be able to use the
syntax they learnt there directly.

--
Erik


_______________________________________________
lilypond-devel mailing list
[hidden email]
http://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Re: review new info on file layout

Mats Bengtsson-4
Quoting Erik Sandberg <[hidden email]>:

> On Friday 03 February 2006 21.12, Mats Bengtsson wrote:
>> Quoting Erik Sandberg <[hidden email]>:
>> I would say the opposite, since in all other situations \new is used like
>> \new Lyrics {...} or \new Lyrics \with {...} {...}. If you insert
>> \lyricsto inbetween, people might get the the impression that
>> \lyricsto is part of the \new Lyrics construct. If you want to exaggerate
>> the pedagogics, I would even propose to say
>> \lyricsto mytune { \new Lyrics {...} }
>> to make it really clear what \lyricsto does (I hope it's legal syntax,
>> haven't checked).
>
> Then I'd propose this instead:
> \new Lyrics { \lyricsto mytune { ... } }
> because it feels relevant to me to consequently create contexts as top-level
> as possible. (hm.. the outer {} in my example are still confusing though,
> since lyricsto never can be part of anything sequential)

The intuitive idea behind my proposal is that the second argument
of the \lyricsto construct is the Lyrics context, whereas with your
proposal it's only the lyrics expression. Of course, there might be
situations where you have several \lyricsto within the same Lyrics
context, so then your proposal makes more sense. However, in such
situations, I would normally use something like:
\lyricsto partI \context Lyrics = lyr {...}
\lyricsto partII \context Lyrics = lyr {...}
\lyricsto partIII \context Lyrics = lyr {...}

>> > I think lily does create separate staves for the voices in this case,
>> > but it's
>> > not at all clear, and adding \new Staff statements explicitly makes the
>> > semantics clearer.
>>
>> We have lots of optional constructs in the syntax, { c } is actually a
>> short-cut for
>> \book{\score{\new Staff{\new Voice{ c }}}}
>> (maybe I missed something).
> yes, you can add a \new Score inbetween also, and empty layout and header
> blocks.
>> I think this is one major source of confusion
>> but of course it's also convenient. My personal view is that we should
>> make at least some of these parts compulsory again (especially \score),
>> since it really only saves a significant portion of key-strokes when
>> you write an example file with one or two bars, but not really for any
>> real music.
>
> I think the shorthand without score is highly relevant:
> - Lots of music is just short snippets. See e.g. regression tests,
> LSR and bug archive.

That's only true for the small group of people like you and me who
spend more time answering mailing list questions and handling bug
reports than on typesetting any real music. It's clearly a suboptimization
to adapt the syntax too much to such unnormal use of the program.

> - Suppose that Wikipedia begins to use lily. They will probably support
> constructs such as <music> {c d e f } </music> regardless of whether lily
> forces \score. People who learn lily from wikipedia should be able to use the
> syntax they learnt there directly.

I agree that we shouldn't force people to remember lots of extra syntax
that the program itself can figure out. However, I've seen lots of
confusion on the mailing list because \score
is now optional.

   /Mats



_______________________________________________
lilypond-devel mailing list
[hidden email]
http://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Re: review new info on file layout

Graham Percival-2

On 4-Feb-06, at 1:59 AM, Mats Bengtsson wrote:

> Quoting Erik Sandberg <[hidden email]>:
>> Then I'd propose this instead:
>> \new Lyrics { \lyricsto mytune { ... } }
>> because it feels relevant to me to consequently create contexts as
>> top-level
>> as possible. (hm.. the outer {} in my example are still confusing
>> though,
>> since lyricsto never can be part of anything sequential)

I agree with Erik -- now the highest view of the music expression is
{
   \new Staff { vocal }
   \new Lyrics \lyricsto vocalstaff { \lyrics }
   \new PianoStaff
}

correct?  And I should change the vocal templates to match this?

> The intuitive idea behind my proposal is that the second argument
> of the \lyricsto construct is the Lyrics context, whereas with your
> proposal it's only the lyrics expression. Of course, there might be
> situations where you have several \lyricsto within the same Lyrics
> context, so then your proposal makes more sense. However, in such
> situations, I would normally use something like:
> \lyricsto partI \context Lyrics = lyr {...}
> \lyricsto partII \context Lyrics = lyr {...}
> \lyricsto partIII \context Lyrics = lyr {...}

Recall that this is an example for newbies (unless you two have moved
on to talking about general lily syntax by now :).  If somebody wants
to do complicated stuff, they can read chapter 7 of the manual, instead
of just chapters 3 and 4.  :)

>> I think the shorthand without score is highly relevant:
>> - Lots of music is just short snippets. See e.g. regression tests,
>> LSR and bug archive.
>
> That's only true for the small group of people like you and me who
> spend more time answering mailing list questions and handling bug
> reports than on typesetting any real music. It's clearly a
> suboptimization
> to adapt the syntax too much to such unnormal use of the program.

Yes, but it also applies to the manual.  We already explain that
examples from the manual need {} or even \relative c' { }   to compile.

> I agree that we shouldn't force people to remember lots of extra
> syntax that the program itself can figure out. However, I've seen lots
> of confusion on the mailing list because \score
> is now optional.

Hopefully this confusion will be lessened with the new chapter 4.  I
may revisit the tutorial with this in mind, too.

- Graham



_______________________________________________
lilypond-devel mailing list
[hidden email]
http://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Re: review new info on file layout

Erik Sandberg
On Tuesday 07 February 2006 05.47, Graham Percival wrote:

> On 4-Feb-06, at 1:59 AM, Mats Bengtsson wrote:
> > Quoting Erik Sandberg <[hidden email]>:
>
> I agree with Erik -- now the highest view of the music expression is
> {
>    \new Staff { vocal }
>    \new Lyrics \lyricsto vocalstaff { \lyrics }
>    \new PianoStaff
> }
>

And a different motivation: \lyricsto changes the lexical mode, and almost all
other lexical mode switching commands (\notemode, \lyricmode, etc.) need to
have the mode-switched parameter within {} or <<>>. (lyricsto is an exception
to this rule, but it might be good to keep that convention.)
    \new Lyrics \lyricsto vocalstaff { \lyrics }

> > The intuitive idea behind my proposal is that the second argument
> > of the \lyricsto construct is the Lyrics context, whereas with your
> > proposal it's only the lyrics expression. Of course, there might be
> > situations where you have several \lyricsto within the same Lyrics
> > context, so then your proposal makes more sense. However, in such
> > situations, I would normally use something like:
> > \lyricsto partI \context Lyrics = lyr {...}
> > \lyricsto partII \context Lyrics = lyr {...}
> > \lyricsto partIII \context Lyrics = lyr {...}
>
> Recall that this is an example for newbies (unless you two have moved
> on to talking about general lily syntax by now :).  If somebody wants
> to do complicated stuff, they can read chapter 7 of the manual, instead
> of just chapters 3 and 4.  :)

but it's IMHO good if the manual uses consistent conventions.

--
Erik


_______________________________________________
lilypond-devel mailing list
[hidden email]
http://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Re: review new info on file layout

Mats Bengtsson-4
In reply to this post by Graham Percival-2
Quoting Graham Percival <[hidden email]>:

>
> On 4-Feb-06, at 1:59 AM, Mats Bengtsson wrote:
>
>> Quoting Erik Sandberg <[hidden email]>:
>>> Then I'd propose this instead:
>>> \new Lyrics { \lyricsto mytune { ... } }
>>> because it feels relevant to me to consequently create contexts as
>>> top-level
>>> as possible. (hm.. the outer {} in my example are still confusing though,
>>> since lyricsto never can be part of anything sequential)
>
> I agree with Erik -- now the highest view of the music expression is
> {
>   \new Staff { vocal }
>   \new Lyrics \lyricsto vocalstaff { \lyrics }
>   \new PianoStaff
> }
>
> correct?  And I should change the vocal templates to match this?

Fine with me!
> ...

>>> I think the shorthand without score is highly relevant:
>>> - Lots of music is just short snippets. See e.g. regression tests,
>>> LSR and bug archive.
>>
>> That's only true for the small group of people like you and me who
>> spend more time answering mailing list questions and handling bug
>> reports than on typesetting any real music. It's clearly a suboptimization
>> to adapt the syntax too much to such unnormal use of the program.
>
> Yes, but it also applies to the manual.  We already explain that
> examples from the manual need {} or even \relative c' { }   to
> compile.

Exactly! One of the most common newbie complaints about the manual is
that the examples don't show all the details you need in a real score.


    /Mats



_______________________________________________
lilypond-devel mailing list
[hidden email]
http://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

RE: review new info on file layout

Carl Sorensen-3
In reply to this post by Graham Percival-2
 

Quoting Mats Bengtsson:

Quoting Erik Sandberg <[hidden email]>:

>> We have lots of optional constructs in the syntax, { c } is actually
>> a short-cut for \book{\score{\new Staff{\new Voice{ c }}}} (maybe I
>> missed something).
> yes, you can add a \new Score inbetween also, and empty layout and
> header blocks.
>> I think this is one major source of confusion but of course it's also

>> convenient. My personal view is that we should make at least some of
>> these parts compulsory again (especially \score), since it really
>> only saves a significant portion of key-strokes when you write an
>> example file with one or two bars, but not really for any real music.
>
> I think the shorthand without score is highly relevant:
> - Lots of music is just short snippets. See e.g. regression tests, LSR

> and bug archive.


I agree that we shouldn't force people to remember lots of extra syntax
that the program itself can figure out. However, I've seen lots of
confusion on the mailing list because \score is now optional.


This is Carl speaking:

I think that it's fine to have { c } as an easy-to-use syntax.  However,
somewhere in the documentation it ought to mention what { c } will
expand to, when the defaults are put in.

That simple explanation (including the empty layout and header blocks)
would greatly help me understand the content of a lilypond file.

Carl Sorensen


_______________________________________________
lilypond-devel mailing list
[hidden email]
http://lists.gnu.org/mailman/listinfo/lilypond-devel
12