Menu
▾
▴
#989 ensure that no information about 2.12.3 features is only in the regtests
Originally created by: *anonymous
Originally created by: percival.music.ca@gmail.com
Some information can only be found in regtests... even worse, it's only
present in the *comment* of a regtest. It's therefore only visible to
people with the source code.
A few things come to mind immediately -- the gonville.ly font-switching
instructions, internalational font packages listed in utf-8.ly -- but it
would be good to thoroughly examine the whole lot.
And by "it would be good", I mean "I will not release 2.14 until it's done".
Originally posted by: v.villenave
I'm taking ownership of this one. Not that I won't welcome any help in handling it;
any (preferably experienced) LilyPonder can contact me if they want to help, I'd be
happy to accompany them!
Owner: v.villenave
Originally posted by: percival.music.ca@gmail.com
Great! A few more tidbits:
- you don't need to write the docs yourself; just keep track of regtest filenames
with info we should add.
- if the regtests is about an obscure property, you don't need to flag that for
doc-inclusion; the IR already includes them.
Originally posted by: v.villenave
I have begun an extensive review of the regtests, my current progression may be seen
on http://wiki.lilynet.net/index.php/Regtests
We need someone (actually, a few people) to address the undocumented stuff (or lacks
in user-oriented documentation) listed on this Wiki page.
About 40% of these items should be addressed in the NR, 50% should be added as LSR
snippets (you can either create an LSR account or send me your snippets), and the
other 10% are missing documentation in the source code itself (i.e. docstrings etc.)
-- these I can take care of on my own, or ask devs to help me.
Originally posted by: pkx1...@hotmail.com
I can help with the NR stuff. I have looked at the Wiki but don't really understand
what it is that needs documenting. Sorry to be slow.
if you can give me an example perhaps of an existing one and a missing one so I can
see what is needed, i can start work on the NR stuff.
Originally posted by: percival.music.ca@gmail.com
Unfortunately, most of the regtests that Valentin picked out don't have anything to
do with the NR, so it's not your concern. The first one that looks like one for you is:
------
bend-after.ly
-> \bendAfter supports non-integer arguments,
this is undocumented AFAICS. Snippet?
I'd mention it in the docs.
---------
Here's how you'd solve it:
1. find \bendAfter in the docs.
2. add a non-integer argument (i.e. 2.5) to the example. (I mean, add another bar
with a \bendAfter 2.5 and maybe another \bendAfter -2.5).
3. check that the example looks decent, shows what it's meant to show, etc. Maybe
2.5 is a bad number -- should it be higher or lower? (I'm totally guessing here)
4. consider adding the sentence "The number of staff spaces can be a non-integer
number", although if it's clear from the example (which it should be), then don't add
such a sentence.
5. send me a patch. Follow our guidelines for that. :)
In general, if somebody says "snippet" or "LSR" after one of the regtests, skip over
it immediately because it's not your concern.
chord-skips.ly looks like the next contender for the NR. Find the place where we
discuss chords, find a good place to discuss articulations inside the chord, and
modify an example (or add a whole new example) accordingly. (in this case, you
probably want to add one 1-2 sentence paragraph, followed by a new @lilypond).
Originally posted by: v.villenave
Thanks for posting this howto, Graham. I've been ill for a few days and it's not
getting any better, but I'll go on with the regtest-review as soon as I'm able to.
(PS - you forgot beam-quarter.ly, Carl said it should go into the NR.)
Originally posted by: pkx1...@hotmail.com
Graham, here is a patch to show the non-integer example for \bendAfter in the NR i
haven't touched any snippets though - they still show only integer examples.
James
Originally posted by: percival.music.ca@gmail.com
Comment 7: committed.
Originally posted by: pnorcks@gmail.com
(No comment was entered for this change.)
Status: Started
Originally posted by: percival.music.ca@gmail.com
postfix \cresc should be documented elsewhere than the regtests.
Originally posted by: kie...@alumni.rice.edu
Can I help with this issue?
Originally posted by: percival.music.ca@gmail.com
The biggest problem right now is the lack of somebody organizing this effort. See
http://lists.gnu.org/archive/html/lilypond-devel/2010-06/msg00072.html
for a tips.
I know that many people who offered to help don't know exactly what goes in LSR vs. D/s/n/ vs. the main docs... but if nobody does anything, that won't change. We really need somebody to take overall responsibility for this effort, find (one of) the places that work is blocked, and then discuss with me how to fix the block if it's not obvious.
Originally posted by: percival.music.ca@gmail.com
PS the easiest way to figure out what's "blocking work" would just be to go to the top of the list and find the first regtest that isn't completely finished. Figure out what that one needs, then either do it or ask for help with it. Once that's finished, move on to the next one.
I think that a steady "10 minutes per day" will be the best approach here -- that gives time for experienced developers to make suggestions or point out mistakes, before you've spent a lot of effort doing something the wrong way.
Originally posted by: pkx1...@hotmail.com
Just an update as I have been doing most of the work here.
According to:
http://wiki.lilynet.net/index.php/Regtests
I have left to do/verify:
dynamics-text-spanner-postfix.ly
flags-in-scheme.ly
flags-straight-stockhausen-boulez.ly
dynamics-context-textspan.ly
dynamics-custom-text-spanner-postfix.ly
dynamics-hairpin-length.ly
dynamics-text-spanner-postfix.ly
I'd also like someone to review the entries (in the wiki) for
markup-eyeglasses.ly - this is already documented
lyric-hyphen.ly - half the ly file is not shown in the reg tests and I am not sure what to do here.
font-postscript.ly - this i believe is already documented
Thanks
James
Originally posted by: hanw...@gmail.com
graham,
not wanting to rain on anyone's parade, but why are you holding back the release for this? Have these things been removed from the 2.12 documentation ?
Originally posted by: percival.music.ca@gmail.com
A lot of these things were never added to the 2.12 docs (or 2.10, or 2.8...). But with the old doc system, the regtests were considered to be part of the documentation.
The new website + doc layout deliberately does *not* link to the regtests in the "manuals" section, so all the neat little features that were never added to the (user) documentation would become impossible for users to find. Basically, 989 is part of the doc rearrangement, and is definitely required under our traditional "a stable release should not be worse than the previous one".
Owner: ---
Originally posted by: percival.music.ca@gmail.com
As Han-Wen pointed out, we shouldn't be holding back a release for any undocumented 2.13-only features. I've therefore made a separate issue 1217 for taking care of that.
This issue is now about features present in 2.12.3 only -- we will not have a stable release until any relevant information in the 2.12.3 regtests is in the documentation.
(I know that some people might feel strongly that "undocumented new features" is a reason to delay a release... frankly, I feel the same way, and after 2.14.0 is out, I'm going to propose that this become an official release-blocking condition. However, it doesn't match our traditional release-blocking condition, and I don't feel justified in changing the rules at this stage in the release.)
Summary: ensure that no information about 2.12.3 features is only in the regtests
Originally posted by: pkx1...@hotmail.com
I think this is now done.
of the 6 remaining snippets, 4 were committed yesterday and the last 2 have been put in the LSR by Phil.
Originally posted by: percival.music.ca@gmail.com
LSR seems to be down; we won't have the latest 2 snippets until it's back up and we can download from the database.
I agree that this issue seems done, though. :)
Originally posted by: percival.music.ca@gmail.com
LSR is now up; have those two snippets been added? I can't recall seeing them in a LSR update. If they've been added, are they Approved and tagged with "docs" ?
Originally posted by: PhilEHol...@googlemail.com
The one that remained that needs to be done has just been uploaded to the LSR. The other that remained outstanding didn't need documenting, IMHO, and I've shifted it to the "Queries" page of the Wiki. Once the patch that had the dynamics documentation goes through, I think this is complete.
Originally posted by: percival.music.ca@gmail.com
I just did a LSR update, but didn't see them. Were they tagged with "docs" and approved?
Originally posted by: bealings...@googlemail.com
http://lsr.dsi.unimi.it/LSR/Item?id=706
As stated a few times, it's not "them, it's "it".
Originally posted by: percival.music.ca@gmail.com
Sorry for the pronoun misuse.
Apparently a snippet only makes it into our docs if it's tagged with "docs" and at least one other tag. I've added "scheme" and "symbols and glyphs" to that snippet, so it should be available tomorrow, and we can finally close this issue.
Originally posted by: n.putt...@gmail.com
> I've added "scheme" and "symbols and glyphs" to that snippet
These aren't used in the docs. I've changed them to `rhythms' and `tweaks-and-overrides'.
I don't think we should close this issue until somebody's taken a thorough look through the regtests to see if anything's been missed.