State of the docs, April 2006

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

State of the docs, April 2006

Graham Percival-2
Hi all,

I'm getting burnt out from trying to do all the documentation.  In
addition, in a fit of insanity I agreed to be the new Bug Meister.  To
give me time to do the Bug stuff, we need more people working on the
docs.  I also have major doc changes that I've wanted to make for
almost a year now, but they keep on getting postponed due to more
urgent doc stuff.

I'll be making an appeal on -user soon for more help (I wanted this
email to get archived first).  Working on the docs requires no
technical knowledge, and in some ways a lack of lilypond experience is
a plus.  I'm not asking for diff files against CVS (although those are
nice); all I require are very clear emails.  See
http://lilypond.org/web/devel/participating/documentation-adding

Several people have been giving me help with the docs, and I'm very
grateful to them.  I'm just hoping that they, and others, will be able
to do even more.  :)    I have discussed a few of these items with some
of them.  I haven't forgotten about it, but it's up to you whether you
want to step forward publicly with your offer.


Here's a list of documentation tasks, in order of my desire for
somebody else to tackle it:

MAILIST DATA-MINER
Lilypond knowledge required: minor
Estimated time: 2-4 hours per week.

Somebody needs to monitor lilypond-user (and ideally -devel as well) to
find things that should be added to the docs.  It may be a particularly
informative email from Mats or Nicholas, or it could be the fourth
person asking for clarification of the same issue.  This is a good way
to learn about lilypond -- you'll quickly cover a wide range of the
docs, but only in little pieces.

Note:  I am *not* asking for somebody to send me these informative
emails.  I need somebody who will read those emails, read the
documentation, decide what to add/remove/replace in the documentation,
and send me the instructions about *exactly* what to
add/remove/replace.


UPDATING MANUAL WITH NEWS   -- taken by Cameron Horsburgh
Lilypond knowledge required: moderate
Estimated time: 10 hours (total, not per week)

Some info from the NEWS files has failed to make it into the manual.  
Somebody needs to check the old NEWS files for info that should be in
the manual, and then write docs for the items.  Other people are more
than welcome to help write those docs, of course.  :)
Cameron will be sending en email soon with more details.


INSTRUMENT-SPECIFIC NOTATION
Lilypond knowledge required: moderate knowledge in a specific area
Estimated time: variable

As far as I know, the "instrument-specific notation" chapter is ok as
it is.  However, if there are problems, I'm not going to fix them.  I
don't play those instruments, I don't write music for those
instruments, I don't know what music for those instruments should look
like, and in the near future I won't have the time and energy to find
out.

If you use any of the notation listed in this chapter -- including
lyrics, which I know is a big use of lilypond -- then please consider
"adopting" the appropriate section of this chapter.  If anything needs
to be clarified, or if new notation should be added, please write it
yourself.  If you use figured bass, or play guitar, or whatever, then
you know more about using lilypond for such things than I do.  I'm
still quite happy to do the technical step of translating specific
instructions from an email into the lilypond documentation, but I am a
poor choice for writing these docs.


CHEAT SHEET
Lilypond knowledge required: minor
Estimated time: 2 hours

We have a "cheat sheet" (appendix E, I think).  Currently I think it's
a bit useless; it doesn't have a lot of info in it.  It would be nice
if we had more info on it.


TIPS AND TRICKS
Lilypond knowledge required: moderate
Estimated time: 10 hours

Somebody should go through all the examples in "tips and tricks" and
make sure they all work (and fix them if they don't!).  This is
somewhat of a nostalgic proposal for me, as this was how I began doing
doc work for lilypond.  This is also a -fantastic- way of learning
about some of the wacky and really cool features of lilypond.


TEMPLATES
Lilypond knowledge required: moderate
Estimated time: 5 hours

Do all the templates in chapter 3 work?  I know that the "Jazz
ensemble" one is very old, and is generally icky.  If nobody updates
it, I think we should just delete it.  I don't know what the status is
on the other templates.  In addition, all the templates should follow
the same general style.


SCHEME / MUSIC EXPRESSIONS EXPLAINED
Lilypond knowledge required: lots
Estimated time: 5 hours?  10?

Many people have asked for clearer explanations of music expressions
and scheme.  Such documentation will not be coming from me within the
next two months, since I don't understand this stuff either.  If enough
people take over the daily doc stuff (such as mailist data-miner), and
once I finish my other tasks, I'll certainly tackle this one.  But only
after I finish other stuff.



INTERNAL ENGINE DOCS
Lilypond knowledge required: even more than lots.  Tons.  Oddles.  You
get the idea.
Estimated time: I have no clue

Some people have asked for documentation about "the working of the
engine (the interaction, passes etc. of scheme python, C, TeX, pdfwrite
...)".  I barely understand the question, let alone the answer.  I
_might_ be able to write documentation about this in two or three
years.  If you want it sooner, volunteer.


START-TO-FINISH EDITING
Lilypond knowledge required: moderate
Estimated time: depends on thoroughness

I'm not really looking for somebody to do this, but if you want to
offer, great!  This involves reading the whole manual and making minor
fixes as you go -- typos, grammatical mistakes, maybe re-writing a
paragraph or two, adding new links, etc.  I plan on doing this in about
a month, but it doesn't hurt to have more than one person looking for
such mistakes!



In case you're wondering what's left for me to do, here's my list (in
order of priority):
1)  Function as a human email-to-CVS gateway.  If anybody sends me
clear instructions for the docs, whether or not they've signed up for
one of these jobs, that has my very highest priority.
2)  Be the mailist data miner, if nobody else does.  :(
3)  Do any NEWS file updates if there are things left over that nobody
else takes.  :(
4)  Move chapter 3, probably into an appendix.  Increase visibility of
chapter 4; add info about style sheets, versioning control,
preprocessors, whatever.  I'll probably rename chapter 4 to "Working
with lilypond files".  This is always a fairly hot topic on
lilypond-user, but I haven't had time to write the material.  Hint: if
you'd like to see those docs, check out items 2 and 3, and make sure
that I don't have to work on them.  :)
5)  Work on integration with LSR.
6)  Revisit "global issues", specifically with regards to horizontal
and vertical spacing.  I know that some kind of awesome system-spacing
stuff was added in 2.7, but I don't know what it is, nor do I think we
have good docs for it.
7)  Revisit "chanding defaults"; I think that I could make it much
easier to understand.  Time, time, time...
8)  Start-to-finish editing.  As part of this, I'll be making a
separate "command index", which only contains entries for \commands in
the manual.
9)  Work on scheme/music expressions, if nobody else does.  :|   (I
won't be unhappy to do this, since I should learn this material anyway,
but it will only come after everything else on this list)

I've probably forgotten a few things, but as you can see, I still have
a lot of things to do even if volunteers step forward to do everything
I've asked for.


Please consider helping the LilyPond project by doing one or more
documentation tasks.  I'm quite willing to spend time helping you with
any difficulties you might have in doing these tasks.

- Graham Percival, LilyPond Documentation Editor



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

Re: State of the docs, April 2006

Father Geoffrey Horton
> INSTRUMENT-SPECIFIC NOTATION
> Lilypond knowledge required: moderate knowledge in a specific area
> Estimated time: variable

Since I've done a lot of worker on choral music already, I'd be happy
to work on that particular area.

Geoff


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

Re: State of the docs, April 2006

Nicolas Sceaux
In reply to this post by Graham Percival-2
Graham Percival <[hidden email]> writes:

> SCHEME / MUSIC EXPRESSIONS EXPLAINED
> Lilypond knowledge required: lots
> Estimated time: 5 hours?  10?
>
> Many people have asked for clearer explanations of music expressions
> and scheme.

I'm not as busy as Jan (just a day job, a house and a kid, no twins:),
but have very little spare time.

I can work on that with someone that have better writing skills than
myself, that is I can explain the methodology to follow to inspect music
expressions, build new ones, define music functions.  (I've writen some
time ago an article on that topic:
<http://nicolas.sceaux.free.fr/prelude/prelude.html>)

nicolas


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

Re: State of the docs, April 2006

Juergen Reuter
In reply to this post by Graham Percival-2
On Tue, 11 Apr 2006, Graham Percival wrote:

> ...
> TEMPLATES
> Lilypond knowledge required: moderate
> Estimated time: 5 hours
>
> Do all the templates in chapter 3 work?  I know that the "Jazz ensemble" one
> is very old, and is generally icky.  If nobody updates it, I think we should
> just delete it.  I don't know what the status is on the other templates.  In
> addition, all the templates should follow the same general style.
>
Attached is a diff that makes the template working again, with a minimal
set of changes.  Still, the general style of the template is rather
peculiar, such that the comments immediately before the template still
hold.  I do not know if this patch is of any value for user reading the
manual, but at least it fixes the appearance of the example.

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

diff.txt (2K) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Docu Sect. 3.5.2

Juergen Reuter

The introduction for the Gregorian transcription template currently says:

"This example demonstrates how to do modern transcriptions of Gregorian
music. Gregorian music has no measure, no stems; it uses only half and
quarter notes, and two types of barlines, a short one indicating a rest,
and a second one indicating a breath mark."

The template has been recently updated, such that the text is now somewhat
outdated.  I would like to propose a slightly modified text, maybe
something like:

"This example demonstrates how to do modern transcription of Gregorian
music. Gregorian music has no measure, no stems; it uses only half and
quarter noteheads, and special marks, indicating rests of different
length."

Greetings,
Juergen


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

Docu Sect. 7.7.10.2

Juergen Reuter
Hi,

considering the recent misreading of lily's Gregorian chant capabilities
that could be seen on this list, I would like to propose a minor update
with clarifications to Sect. 7.7.10.2.  See attachment.

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

diff.txt (2K) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: State of the docs, April 2006

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

> Graham Percival <[hidden email]> writes:
>
>> SCHEME / MUSIC EXPRESSIONS EXPLAINED
>> Lilypond knowledge required: lots
>> Estimated time: 5 hours?  10?
>>
>> Many people have asked for clearer explanations of music expressions
>> and scheme.
>
> I'm not as busy as Jan (just a day job, a house and a kid, no twins:),
> but have very little spare time.
>
> I can work on that with someone that have better writing skills than
> myself, that is I can explain the methodology to follow to inspect music
> expressions, build new ones, define music functions.  (I've writen some
> time ago an article on that topic:
> <http://nicolas.sceaux.free.fr/prelude/prelude.html>)
>
> nicolas
>
>
> _______________________________________________
> lilypond-devel mailing list
> [hidden email]
> http://lists.gnu.org/mailman/listinfo/lilypond-devel
>
>
If you're willing to write the docs, I'm more than happy to review and
edit for language issues, if that would help.

Cameron


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

Re: Docu Sect. 3.5.2

Graham Percival-2
In reply to this post by Juergen Reuter

On 12-Apr-06, at 3:21 PM, Juergen Reuter wrote:
> The template has been recently updated, such that the text is now
> somewhat outdated.  I would like to propose a slightly modified text,
> maybe something like:
>
> "This example demonstrates how to do modern transcription of Gregorian
> music. Gregorian music has no measure, no stems; it uses only half and
> quarter noteheads, and special marks, indicating rests of different
> length."

Thanks, applied.
- Graham



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

Re: Docu Sect. 7.7.10.2

Graham Percival-2
In reply to this post by Juergen Reuter

On 12-Apr-06, at 4:47 PM, Juergen Reuter wrote:

> considering the recent misreading of lily's Gregorian chant
> capabilities that could be seen on this list, I would like to propose
> a minor update with clarifications to Sect. 7.7.10.2.  See attachment.

Thanks, applied.
- Graham



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

Re: State of the docs, April 2006

Graham Percival-2
In reply to this post by Juergen Reuter

On 12-Apr-06, at 3:00 PM, Juergen Reuter wrote:

> Attached is a diff that makes the template working again, with a
> minimal set of changes.  Still, the general style of the template is
> rather peculiar, such that the comments immediately before the
> template still hold.  I do not know if this patch is of any value for
> user reading the manual, but at least it fixes the appearance of the
> example.

Thanks, applied.
- Graham



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

Re: State of the docs, April 2006

Graham Percival-2
In reply to this post by Nicolas Sceaux

On 12-Apr-06, at 12:45 PM, Nicolas Sceaux wrote:

> I can work on that with someone that have better writing skills than
> myself, that is I can explain the methodology to follow to inspect
> music
> expressions, build new ones, define music functions.  (I've writen some
> time ago an article on that topic:
> <http://nicolas.sceaux.free.fr/prelude/prelude.html>)

Thanks for the offer -- I still have half a dozen saved emails of your
on this subject.  :)

I don't mind writing the scheme stuff; the only problem is that I need
to finish other things first.  I'll just continue to ignore complaints
about the scheme docs for the next month or two.

Cheers,
- Graham



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