Documentation for stanza numbers /Sietse

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

Documentation for stanza numbers /Sietse

Sietse Brouwer-2
Dear developers,

One of my suggestions involves some shuffling around of parts, so I'll
first define into which parts I divide section 7.3.9.
Section 7.3.9 currently contains 4 topics:
(1) adding stanza numbers
    from "Stanza numbers can be added" to "start of first syllable."
(2) printing stanzas at the end
    from "Sometimes it is appropriate" to a snippet of Mary had a Little Lamb
(3) adding singer names
    from "Names of singers can" to a snippet where Ernie sings "je t'aime"
(4) printing stanzas at the end in side-to-side columns
    from "When a piece of music" to a snippet ending in "This is verse
five. It has two lines"

[A]
In the last line of topic one, "just before the start of first
syllable." is missing a "the". It should read "just before the start
of the first syllable."

[B]
I recommend swapping topic 2 and topic 3, since 3 and 4 are about
similar issues: about printing stanzas at the end, and about printing
stanzas at the end in columns next to each other.

[C] I also hereby submit a paragraph + code describing how to put a
dynamics marks in front of the stanza. I recommend putting it after
topic 1, as both deal with \set stanza.

I would have liked to explain why \set stanza must take place outside
\lyricmode: unfortunately, I don't know myself. All I know is that you
get the error message "Unexpected LYRIC_MARKUP". If you have an
explanation, I think it would be good to add it.

--start--
Stanzas differing in loudness are indicated by putting an appropriate
dynamics mark before each stanza. In Lilypond, everthing coming in
front of a stanza goes into the StanzaNumber object; dynamics marks
are no different. For technical reasons, you have to set the stanza
outside \lyricmode, like in the following example:

text = {
  \set stanza = \markup { \dynamic "ff" "1. " }
  \lyricmode {
    Big bang
  }
}

<<
  \new Voice = "tune" {
        \time 3/4
    g'4 c'2
  }
  \new Lyrics \lyricsto "tune" \text
>>
--end--

(For whoever makes the docs: this snippet compiles. Just precede it
with a \version and \layout { ragged-right = ##t }.)

[D] Finally, I would add a "Bugs" section after the "See also"
section, saying the following:

--start--
Bugs
When the stanza number becomes too wide, it just writes over whatever
is to its left.
--end--

So, the new "More about stanzas" section covers five topics, in the
following order:
(1) adding stanza numbers
(2) adding dynamics marks
(3) adding singer names
(4) printing stanzas at the end
(5) printing stanzas at the end in multiple columns

-------

Two more questions:
Firstly, do you think we should put the topics above into their own
subsections: 7.3.9.1 - 7.3.9.5?
Secondly: in my opinion, topic 5 (printing stanzas at the end in
multiple colums) is more of a template than it describes new
techniques. Perhaps it should be moved to the template appendix under
section D.4 "Vocal Ensembles". What do you all think?

Regards,

Sietse
Sietse Brouwer


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

Re: Documentation for stanza numbers /Sietse

Graham Percival-2
Sietse Brouwer wrote:
> [A]
> In the last line of topic one, "just before the start of first
> syllable." is missing a "the". It should read "just before the start
> of the first syllable."

Done.

> [B]
> I recommend swapping topic 2 and topic 3, since 3 and 4 are about
> similar issues: about printing stanzas at the end, and about printing
> stanzas at the end in columns next to each other.

Done.

> [C] I also hereby submit a paragraph + code describing how to put a
> dynamics marks in front of the stanza. I recommend putting it after
> topic 1, as both deal with \set stanza.

Done.

> I would have liked to explain why \set stanza must take place outside
> \lyricmode: unfortunately, I don't know myself. All I know is that you
> get the error message "Unexpected LYRIC_MARKUP". If you have an
> explanation, I think it would be good to add it.

I have no clue, sorry.  (see below)

> [D] Finally, I would add a "Bugs" section after the "See also"
> section, saying the following:
>
> --start--
> Bugs
> When the stanza number becomes too wide, it just writes over whatever
> is to its left.
> --end--

The "bugs" section is intended more for long-term design decisions.  In
this case, that collision is a small bug that will hopefully be fixed
within the next year or two.

Basically, if a bug is in the tracker, it doesn't go in the docs.  If a
bug in the tracker is too big to handle (i.e. long-term design issues),
then we remove it from the tracker and add it to the docs.


> Two more questions:
> Firstly, do you think we should put the topics above into their own
> subsections: 7.3.9.1 - 7.3.9.5?

Done.  I like splitting things into subsections.

> Secondly: in my opinion, topic 5 (printing stanzas at the end in
> multiple colums) is more of a template than it describes new
> techniques. Perhaps it should be moved to the template appendix under
> section D.4 "Vocal Ensembles". What do you all think?

Although I'm the doc editor, I never use vocal music.  One of the
reasons I structured the docs this way (chapters 6, 7, and 8) is that I
have no clue how stuff in chapter 7 works.  I play string instruments, I
write for string instruments, and that's it.  :)

When it comes to stuff in chapter 7, I really just take direction from
intelligent, interested users.  You qualify, so give me directions.  :)

I think the example in topic 5 should be changed a little before making
it a template, but it would probably only take you five minutes.

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: Documentation for stanza numbers /Sietse

Sietse Brouwer-2
Hullo,

Thanks, Graham, for making all those changes.

On 21/01/07, Graham Percival <[hidden email]> wrote:
> Basically, if a bug is in the tracker, it doesn't go in the docs.  If a
> bug in the tracker is too big to handle (i.e. long-term design issues),
> then we remove it from the tracker and add it to the docs.

Gotcha.

> > Secondly: in my opinion, topic 5 (printing stanzas at the end in
> > multiple colums) is more of a template than it describes new
> > techniques. Perhaps it should be moved to the template appendix under
> > section D.4 "Vocal Ensembles". What do you all think?
>
> I think the example in topic 5 should be changed a little before making
> it a template, but it would probably only take you five minutes.

I've had another look at it, and I agree: it needs to be expanded
until it's a ready-to-use template. You'll see the new version appear
on this list when I've made it. (If I don't forget.)

Another question: where (if at all) can I find the latest version of
the manual, i.e. one which incorporates the changes you just made?

Regards,

Sietse


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

Re: Documentation for stanza numbers /Sietse

Graham Percival-2
Sietse Brouwer wrote:
> Another question: where (if at all) can I find the latest version of
> the manual, i.e. one which incorporates the changes you just made?

When 2.11.13 comes out.  If you have the source code, you could build
the docs yourself; this doesn't require as much work as it does to
compile lilypond.  If you're on OSX or linux, you should be able to do
this fairly easily.  Ask me for details if you want.

If there are many people working on the docs and they can't compile the
docs themselves (say, they use windows and don't do any programming or
cygwin/unix stuff), then I sometimes make my latest doc builds available
to them.  The last time this happened was last June, though.

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: Documentation for stanza numbers /Sietse

Mats Bengtsson-4
In reply to this post by Graham Percival-2


Graham Percival wrote:
> Done.  I like splitting things into subsections.
As a reader of the on-line version, I must admit that I don't really
like the
large amount of subsections. I often find that I don't get the full
picture since
each subsection only covers a very specific aspect.
You can certainly follow the "Next: ..." links on each page, but we should
really try to hack the HTML producing scripts so we at least get the same
link also at the bottom of the page (which is where you are when you have
finished reading one subsection and want to continue on the next one).

   /Mats


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

Re: Documentation for stanza numbers /Sietse

Graham Percival-2
Mats Bengtsson wrote:
> You can certainly follow the "Next: ..." links on each page, but we should
> really try to hack the HTML producing scripts so we at least get the same
> link also at the bottom of the page (which is where you are when you have
> finished reading one subsection and want to continue on the next one).

Hmm, I hadn't realized how much my browsing habits influenced the docs
-- I almost always open pages in new tabs.  My first tab is the index,
then I open up three or four tabs, read them, close them, then open up
another couple of tabs.

I certainly agree about the texinfo placement of "next..."  I'll look
into it.

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: Documentation for stanza numbers /Sietse

John Mandereau
Le lundi 22 janvier 2007 à 00:45 -0800, Graham Percival a écrit :

> Mats Bengtsson wrote:
> > You can certainly follow the "Next: ..." links on each page, but we should
> > really try to hack the HTML producing scripts so we at least get the same
> > link also at the bottom of the page (which is where you are when you have
> > finished reading one subsection and want to continue on the next one).
>
> Hmm, I hadn't realized how much my browsing habits influenced the docs
> -- I almost always open pages in new tabs.  My first tab is the index,
> then I open up three or four tabs, read them, close them, then open up
> another couple of tabs.
>
> I certainly agree about the texinfo placement of "next..."  I'll look
> into it.

According to makeinfo docs, it has no option to put the navigation bar
at the end of each page, so we could hack it in add_html_footer.py.  As
I'm cleaning it up along with www_post and mirrortree, I offer to work
on this too.

Greetings
--
John Mandereau <[hidden email]>



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

Re: Documentation for stanza numbers /Sietse

Graham Percival-2
John Mandereau wrote:
> Le lundi 22 janvier 2007 à 00:45 -0800, Graham Percival a écrit :
>>
>> I certainly agree about the texinfo placement of "next..."  I'll look
>> into it.
>
> According to makeinfo docs, it has no option to put the navigation bar
> at the end of each page, so we could hack it in add_html_footer.py.  As
> I'm cleaning it up along with www_post and mirrortree, I offer to work
> on this too.

Please do, thanks.  My next step was to send an email to the texinfo
list asking for this to be added.

Actually, that might not be a bad idea to do in any case, but it would
be nice if I could present my request as "it would be nice if..."
instead of "please help!  we need this new feature!"

Cheers,
- Graham


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