First Frog Task

[Carl D. Sorensen]

Dear LilyPond Frogs,

Thanks for the great response!  We have eight new Frogs, who are willing to
work on making improvements to LilyPond.  I think that's great!

I've attached a file README-contrib.txt, which is an attempt at what one of
you described as "Frogging for Dummies".  It gives at least a brief
introduction to the key issues that I remember as obstacles when I got
started with LilyPond development.

Your first task is to fix up the documentation strings for the predefined
LilyPond functions defined in appendix B.14 of the Notation Reference.  Each
of these is a Scheme function found somewhere in the installed file tree.  I
won't tell you where it is, because trying to find things is an essential
skill for Frogs.  But if you have troubles finding things, be sure to drop
me an email, and I'll be happy to help you find them.  I'm trying to teach
you to fish (or maybe I should say "fly", as in the bug, not flapping
wings), rather than giving you a fish.  But I don't want you to get
frustrated, so please ask for help.

When you're done with this task, each function for which you are responsible
should have an internationalizable docstring.  By internationalizable, I
mean that it will look like (_i "This is the docstring."), rather than "This
is the docstring."  Because we are adding internationalizable docstrings,
you'll need to check even the functions that have docstrings.

There are 64 predefined functions identified in appendix B.14, and 8 of you
new Frogs.  So you'll each be responsible for 8 functions.  The assignments
are as follows:

Andrew H:  acciaccatura through applyMusic.
Andrew W:  applyOutput through bar.
Frederic (Sorry, I don't know how to type the accents):
       barNumberCheck through endSpanners
Hajo:  featherDurations through makeClusters
Ian:  musicMap through pageBreak
Josh:  pageTurn through quoteDuring
Kieren:  removeWithTag through storePredefinedDiagram
Marek:  tag through withMusicProperty

I'm sure that some of you will say "How can I document a function when I
don't know what it does?"  Good question.  My first answer is that you
search in the Notation Reference and the Learning Manual to see where the
function is used.  That should give you enough of an idea to add the
docstrings.  It will also give you examples that will allow you to test
the function to make sure it still works after you've made the changes.

As you're looking at the existing docstrings, you'll see that there's a wide
variation in the amount of information in them.  While we don't want to get
too long in the docstrings, if the docstring is so cryptic it doesn't make
any sense, you may want to embellish it a little bit.

Have fun with this assignment, and please get back to me with any questions
you have.  When you do, please reply to all of the Frogs, so we can all see
how one another is doing, and learn from each other.  But don't include the
lilypond-user in your reply; I just wanted to get one more announcement out
there.  And don't copy Graham, I just wanted to give him a copy of
README-contrib.

Thanks,

Carl

README-contrib.txt
Description: README-contrib.txt