Re: GDP: summary and directions, 11 Sep
Trevor Bača wrote: That then leaves the question of what to do with the other stuff. What about this? * Spacing: recast as a separate manual called Page Layout * Input and output: move to Program Usage * Changing defaults: move to Program Reference * Interfaces for programmers: move to Program Reference Nu-huh, Program Reference is "where angels fear to tread", remember. :P That would then leave the following separate books: (5 books) I think that's getting too fragmented. ... My initial reaction was "no way; we want to make tweaking more friendly, not less". But I had forgotten about the Learning Manual -- that clearly shows the beginning of tweaks, and (of course) more work is planned. Hmmm... *IF* it were easy to move Changing and Interfaces into the program reference, I could almost buy that. That's a pretty big if, though. If we renamed the Program Usage book, we _might_ be able to fit Spacing and Input in there. I'm not wild about it, though. But I definitely don't agree with making a separate book for Page Layout. ... ok, what about everybody else? Think about it for a few minutes before responding: my initial reaction was "WTF is Trevor smoking", but I'm starting to think he wasn't crazy. Please remember the following: - HTML links between documents is cheap and easy. - introductions belong in the Learning manual. If you haven't skimmed through chapter 5, please do so. I'm planning on a least doubling the material in the LM, so users will have a good idea of how things work by the time they finish it. An extensive "how to read the other books" section will be included at the end of the LM. - we officially have no sympathy for users who haven't read the LM. :-) For the record, I'm still opposed to this idea, but it's now a "weak reject". I could be convinced otherwise. Cheers, - Graham ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: GDP: summary and directions, 11 Sep
On 9/11/07, Graham Percival <[EMAIL PROTECTED]> wrote: > If you're somewhat interested in GDP, but don't want to follow the > 50-email monster threads, simply read any email by me that starts a subject. > > Not because I think my opinion is the only one that matters :). Just > because I'll sum up the important points, and attempt to direct future > discussions, in emails like this. > > > ALMOST-CERTAIN (barring massive opposition, this will happen) > ** split the Learning Manual (chapters 2-5) into a separate manual, just > like Program Usage. Strongly agree. > cons: no shared index with Notation Reference. Benefits: no shared > index with Notation Reference. :)besides, chapters 2-5 have hardly > any index entries, anyway. > > I don't know what to do about chapter 1 (general intro, background). > The "about this manual" will obviously stay in some form or other. Omit > that section from the discussion for now. Opinions about the rest of > chapter 1 are desired, though. > > > ** combine multiple subsections into single subsections. Something like > an average of 3 subsections -> 1. Strongly agree. > Assuming there isn't significant opposition in the next 18 hours, I'll > take a stab at creating the new merged subsections. > > > ** Abandon basic/advanced/instrument/decorating/cakes division of > notation reference. See below as to how we do this, though. Strongly agree. More comments below. > NEEDS DISCUSSION > ** should the "combined index" include entires in the "command index" ? > We could easily separate the "concept" index from the "combined > index". Would that help or hurt? I vote for a single index. > ( assuming that we added many more index entries; don't bother > commenting that we don't have enough right now ) > > > ** combined subsections: print names of old subsections in the manual? > For example, suppose we make a "printing repeats" section that includes > Repeat types, Repeat syntax, Repeats and MIDI, and Manual repeat > commands. Do you want to only see "Printing repeats" in the table of > contents, or do you want to see > x.y Printing repeats > Repeat types > Repeat syntax > ... > (without any x.y.z numbers) I vote for the more verbose form of the TOC. > ** Abandon decorating/cakes method of dividing the notation reference. > > There's sufficient support for this, but I have some remaining concerns: > Pitch and Rhythm are more connected than Pitch and Spacing or Pitch and > Changing defaults. > > Now, we could indicate this purely by the proximity of chapters -- Pitch > is chapter 1, Spacing is chapter 27. > > Or, we could have a single chapter for all Notation. > 1. Notation > 1.1 Pitches > 1.2 Rhythms > ... > 2. Text (arguably as 1.25 inside Notation) > 3. Input and output > 4. Spacing > 5. Changing defaults > 6. Interfaces for programmers > > (exact order of the chapters to be determined) > > I'd rather have this kind of setup. Yes, chapter 1 will have 25 > sections (or whatever), but IMO something like "Repeats" just shouldn't > be at the same level as Changing defaults. Oooh. You know what's emerging as a really nice pattern? The 24 (or so) sections in "Notation" taken together with Text looks like it might make an almost perfect Notation Reference. So would it be insanely crazy to bind (metaphorically speaking) those 25 chapters together into a single manual, cut everything else out, and call that our Notation Reference? It sounds like it would be really beautiful. So: > Notation Reference > 1 Pitches > 2 Rhythms > > 25 Text That'd be very very cool imo. That then leaves the question of what to do with the other stuff. What about this? * Spacing: recast as a separate manual called Page Layout * Input and output: move to Program Usage * Changing defaults: move to Program Reference * Interfaces for programmers: move to Program Reference That would then leave the following separate books: * Learning Manual (4 or 5 chapters) * Notation Reference (25 chapters) * Page Layout (handful of chapters) * Program Usage (6 chapters) * Program Reference (15 chapters) Probably the radical idea here is elevating spacing to stauts of its own manual. But I think it makes sense -- seems to me that I'm either hunting notation-related grob settings xor figuring out how to move staves and systems apart, but not both at the same time. The coolest thing here is the possibility of a solid, 25-chapter NR. That's slick. -- Trevor Bača [EMAIL PROTECTED] ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: regression tests
Hi all, Han-Wen Nienhuys wrote: listing default values is easy This is actually pretty hard. Okay... EOT for me. If -- as Mats suggested -- we might (easily) print out the settable *properties* (without values) on a single page, that would be fantastic. Cheers, Kieren. ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
GDP: summary and directions, 11 Sep
If you're somewhat interested in GDP, but don't want to follow the 50-email monster threads, simply read any email by me that starts a subject. Not because I think my opinion is the only one that matters :). Just because I'll sum up the important points, and attempt to direct future discussions, in emails like this. ALMOST-CERTAIN (barring massive opposition, this will happen) ** split the Learning Manual (chapters 2-5) into a separate manual, just like Program Usage. cons: no shared index with Notation Reference. Benefits: no shared index with Notation Reference. :)besides, chapters 2-5 have hardly any index entries, anyway. I don't know what to do about chapter 1 (general intro, background). The "about this manual" will obviously stay in some form or other. Omit that section from the discussion for now. Opinions about the rest of chapter 1 are desired, though. ** combine multiple subsections into single subsections. Something like an average of 3 subsections -> 1. Assuming there isn't significant opposition in the next 18 hours, I'll take a stab at creating the new merged subsections. ** Abandon basic/advanced/instrument/decorating/cakes division of notation reference. See below as to how we do this, though. NEEDS DISCUSSION ** should the "combined index" include entires in the "command index" ? We could easily separate the "concept" index from the "combined index". Would that help or hurt? ( assuming that we added many more index entries; don't bother commenting that we don't have enough right now ) ** combined subsections: print names of old subsections in the manual? For example, suppose we make a "printing repeats" section that includes Repeat types, Repeat syntax, Repeats and MIDI, and Manual repeat commands. Do you want to only see "Printing repeats" in the table of contents, or do you want to see x.y Printing repeats Repeat types Repeat syntax ... (without any x.y.z numbers) ** Abandon decorating/cakes method of dividing the notation reference. There's sufficient support for this, but I have some remaining concerns: Pitch and Rhythm are more connected than Pitch and Spacing or Pitch and Changing defaults. Now, we could indicate this purely by the proximity of chapters -- Pitch is chapter 1, Spacing is chapter 27. Or, we could have a single chapter for all Notation. 1. Notation 1.1 Pitches 1.2 Rhythms ... 2. Text (arguably as 1.25 inside Notation) 3. Input and output 4. Spacing 5. Changing defaults 6. Interfaces for programmers (exact order of the chapters to be determined) I'd rather have this kind of setup. Yes, chapter 1 will have 25 sections (or whatever), but IMO something like "Repeats" just shouldn't be at the same level as Changing defaults. Cheers, - Graham ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: regression tests
2007/9/11, Rune Zedeler <[EMAIL PROTECTED]>:
> > Possibly... but an *automated* page -- containing a listing exactly as
> > Trevor outlined BUT WITH ONLY THE DEFAULT SETTING/VALUE -- would keep up
> > *precisely* with development, since it would be scripted into the main
> > compilation process.
>
> Yep listing default values is easy - I agree - this was not what I was
This is actually pretty hard. Lots of defaults are supplied as arguments in
robust_scm2xxx(grob->get_property("yyy"), DEFAULT)
and there is no mechanism that enforces a uniform default across the
c++ code base.
--
Han-Wen Nienhuys - [EMAIL PROTECTED] - http://www.xs4all.nl/~hanwen
___
lilypond-devel mailing list
lilypond-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: GDP: length/page-splitting of subsections
Le mardi 11 septembre 2007 à 23:15 +0200, Han-Wen Nienhuys a écrit : > 2007/9/10, Graham Percival <[EMAIL PROTECTED]>: > > Let me phrase this question differently: > > - if you currently use the all-in-one HTML page, how could we organize > > the non-all-in-one docs such that you use them? > > I haven't followed the discussion in detail, but isn't this something > that should be handled by makeinfo? It has a --split-size argument, > but that only works for info and plain text. If we could set size > limits to html files too, wouldn't that solve the problem? Of course! HTML files splitting is determined by @node commands, just like nodes splitting, so it's just a matter of adding/removing @nodes associated with (sub)*sections. Cheers, John ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: GDP: length/page-splitting of subsections
2007/9/10, Graham Percival <[EMAIL PROTECTED]>: > > At the very least, there are more (and more complex) things you can do > > with dynamics (in Lilypond), and so that section alone would be long > > enough to deserve its own HTML page. > > I'd certainly say so... but there's a large element of "the customer is > always right" here. > > The all-in-one HTML page is **5 megs**. I'm astounded that so many > people (ie more than 0) are choosing to download that monster _every > time_ they want to look something up in the docs. That's a terrible > waste of bandwidth, especially if you consider that the answer they're > looking for is probably 1k of text and 100k of example picture. To me, > that sounds like a terrible indictment of how badly organized the docs are. > > > Let me phrase this question differently: > - if you currently use the all-in-one HTML page, how could we organize > the non-all-in-one docs such that you use them? I haven't followed the discussion in detail, but isn't this something that should be handled by makeinfo? It has a --split-size argument, but that only works for info and plain text. If we could set size limits to html files too, wouldn't that solve the problem? -- Han-Wen Nienhuys - [EMAIL PROTECTED] - http://www.xs4all.nl/~hanwen ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: regression tests, not GDP
John Mandereau wrote: Le mardi 11 septembre 2007 à 13:15 -0700, Graham Percival a écrit : Please make a webpage that links to the regression checks and the comparisons. Link to it from... well, wherever you want. Probably either devel/ or devel/participating. devel/participating/ looks like the right place. We should also move there comparison links from documentation. Great! Advanced users will be able to find it, the programmers and bug people will have it bookmarked, and new users looking at the main doc page won't get confused. Everybody wins. Besides this, even if we removed the regtests link from the doc index, ... they were removed a month or two ago, you know :P ... the regtests are still present in the docball, so I second Jan's suggestion about creating a new page devel.html.in for developer resources, with a link from index.html.in. Sure, no complaints. Go ahead, whenever is convenient for you. I should also add that the website is outside the scope of GDP. I fully support the idea of a WIP (website improvement project), although to avoid having -user and -devel flagged as spammers, I respectfully suggest that WIP waits until GDP is done. :) Hmm... 6 months, GDP. 3 months, WIP. Then maybe a Program Reference Augmenting trY Extending Readability ? ;) Cheers, - Graham ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: regression tests, not GDP
Le mardi 11 septembre 2007 à 13:15 -0700, Graham Percival a écrit : > As Trevor said, I'm trying to keep discussions about GDP focused. So > I'd like to close off a few branches of discussion: > > 1) Who has a copy of web/master in git laying around? As a translator, I always do. > Please make a > webpage that links to the regression checks and the comparisons. Link > to it from... well, wherever you want. Probably either devel/ or > devel/participating. devel/participating/ looks like the right place. We should also move there comparison links from documentation. > Advanced users will be able to find it, the programmers and bug people > will have it bookmarked, and new users looking at the main doc page > won't get confused. Everybody wins. Besides this, even if we removed the regtests link from the doc index, the regtests are still present in the docball, so I second Jan's suggestion about creating a new page devel.html.in for developer resources, with a link from index.html.in. Graham, if you agree with these suggestions, I'll go ahead, not before Friday though. > If you _personally_ know how to modify the program reference (it's > constructed via scheme and/or python and/or C++ and/or prayers and/or > angel dust), and are willing to spend the time to make such changes, > please speak up. Otherwise, be aware that your discussions about the > Program Reference will be as fruitful as planning a manned mission to > Mars. Good idea, I plan to go to Mars (i.e. learning Scheme) asap, maybe next Summer :-P Cheers, John ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: GDP: flattening the manual to two layers?
Valentin Villenave wrote: I suggested avoiding subsubsections such as in current Vocal music. Graham is reluctant to make more chapters (still can't forget about his "four letters" answer in a private mail :) Ok, come on, it was hilarious! But we really need to explain this. John and Valentin were dithering about Vocal music: "should we leave it in instrument-specific, or make it a new chapter... but it's too short to be a chapter by itself... what to do, what to do...?" My response: "hmm, yeah... vocal music is tricky. If only we had a dedicated chapter for putting words on the page... especially if we had a new, dedicated chapter, that was much shorter than the other chapters... we could give that chapter a nice short name, like "word", or maybe something else with four letters..." Poor Valentin thought I was swearing at him*. I, of course, was referring to the new chapter "Text". * in English, most swearwords have four letters; the phrase "four-letter words" generally** refers to swearwords. ** one of my conductors make jokes about this: "no, no! You're playing loud, and `loud' is a four-letter word. Think `heroic' or `strong' instead! No four-letter words in this orchestra!" Cheers, - Graham ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
GDP: in a perfect world, nothing but RTFM
I should clarify one point: in only the past three years, I've seen a lot of lilypond's documentation become out of date. That makes me look for long-term solutions for the docs. I really think of this like software engineering: planning and designing a computer program may seem like a waste to beginning programmers, but experienced programmers know that it really is worth it to spend more than 50% of your time on design, instead of programming. * actual percentage completely made up. Don't quote some software engineering textbook at me. :P In a perfect world, the only discussions on -user would be this: 1) Q: how do I foo? 2) ??? 3) A: RTFM section x.y.z. 4) Profit. (Obviously step 3 would be phased nicer than RTFM.) The missing step 2 is that we work on the docs. This isn't quite practical -- we only upload the docs every one or two weeks, and we have a limited amount of time/effort/interest in maintaining the docs. But I honestly think that if everybody stopped answering questions on -user, after a year we would have *amazing* documentation. The first few months would suck, of course. LSR makes this ideal much more practical. Anybody can upload an example, and answer a question on -user with a link to that example. The doc team can then mark certain examples to be included in our "Snippets" section, and every so often we can move really great snippets into the actual manual. At the moment, there might be some useful snippets in the regtests that aren't in LSR. As I've said before, that's considered a bug. I honestly think that there are fewer than half a dozen such snippets -- I've looked through the regtests for good snippets, and Valentin has done the same. If you find any, please add them to LSR. (NB: regtests which can't be shown in LSR because they use new features are in input/new/. This should be resolved soon) That's why I'm so adamant that the regtests should not be on the main doc page. Short-term pain (for a small number of advanced users, who should know bloody well how to add stuff to LSR, anyway) for long-term gain (having a single place to look for short examples). Cheers, - Graham ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: regression tests
On 9/11/07, Mats Bengtsson <[EMAIL PROTECTED]> wrote: > Trevor Bača wrote: > > > > >Criterion 1: There's a *complete* enumeration of acceptable values for > >each property, and > > > >Criterion 2: There's a working, one-line example of each value for > >each property of each grob > > > > > > > I guess you haven't studied combinatorics. If so, you would > quickly realize that the resulting number of examples would > be so huge that it's is completely impossible, > especially if you want to cover all cases where different > settings interact with eachother. Also, as has already been > pointed out, many properties can take an arbitrary Scheme > function as the value. You misunderstand. 5 or 6 interfaces on average per grob on average, times between 2 and 8 user-settable properties per interface (excepting the grob interface, which 21) times between, say, 2 to 4 acceptable values per property gives around 6 * 8 * 4 or approximately 200 total settings per grob (leaving out the base settings in grob-interface). 200 is hardly a combinatorial quagmire. 200 is actually quite a nice number for some snarfing function to aggregate and put in a nice table, one per grob, with an example of the correct setting syntax for each, cut-and-pasteable. Anyway, the point that both you and Carl have made about some properties taking arbitrary Scheme functions is a much more interesting one. Are we talking about, for example, Stem #'direction? By default Stem #'direction = #ly:stem::calc-direction ... which is a very, very cool function that incorporates the correct musical knowledge about whether a stem should point up or down ... far more sophisticated than #up and #down (which are also permitted as acceptable values, of course). So, an observation: quite frequently very powerful things happen *when you assign a Scheme function* to some user-settable property (like assigning ly:stem::calc-direction to Stem #'direction). BUT my intuition -- and maybe this is wrong -- is that there are other really cool functions like ly:stem::calc-direction hiding out there that would be available to us as users ... if only they were documented in the grob reference. Is this intuition right? Are there cool Scheme functions hiding out there that aren't documented in the grob reference? If that is in fact the case, then it's exactly the wrong instinct to think "hm, well these properties can take arbitrary Scheme functions, so let's avoid documenting"; quite the opposite. Those are precisely the cases where documentation will help the most -- it's not hard to take a guess and assign #up or #down to any ole grob property ... but you *need* docs to help you come up with an incantation like #ly:stem::calc-direction. -- Trevor Bača [EMAIL PROTECTED] ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
regression tests, not GDP
As Trevor said, I'm trying to keep discussions about GDP focused. So I'd like to close off a few branches of discussion: 1) Who has a copy of web/master in git laying around? Please make a webpage that links to the regression checks and the comparisons. Link to it from... well, wherever you want. Probably either devel/ or devel/participating. Advanced users will be able to find it, the programmers and bug people will have it bookmarked, and new users looking at the main doc page won't get confused. Everybody wins. 2) the Program Reference is *entirely* outside the scope of GDP. You know the phrase "... where angels fear to tread"? That's how I feel about those docs. Can we think of a billion ways to improve them? Yes. Do I have a clue how to implement any of them? No (other than really simple things). Is it helpful to list pie-in-the-sky features that likely will never be implemented? ... I'd say generally no, but hey, if you enjoy doing that, I won't stop you. If you _personally_ know how to modify the program reference (it's constructed via scheme and/or python and/or C++ and/or prayers and/or angel dust), and are willing to spend the time to make such changes, please speak up. Otherwise, be aware that your discussions about the Program Reference will be as fruitful as planning a manned mission to Mars. Again, I'm sorry to be a wet blanket. I'm just doing this to save everybody's time and effort, since I honestly don't think this discussion will amount to anything. - Graham ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: regression tests
Hi Mats, This discussion is getting more and more confused. Sorry... that comes from (a) not really knowing the internal workings of Lilypond as well as I probably should; and, (b) putting my 2 cents in while simultaneously doing 42 other things... =\ - The list for each grob only includes the properties that are set by default. To see an exhaustive list of all available properties, you have to browse through all "interfaces". This is of course easy to change in the Program reference and we used to have the full list a long time ago, but I'm not sure if it's desirable. Perhaps the current HTML page per grob could include a link to another page that contains the full list of properties. IMO, that would be the perfect solution! Thanks for the clarification and suggestion. Kieren. ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
RE: regression tests
> -Original Message- > From: Kieren MacMillan [mailto:[EMAIL PROTECTED] > Sent: Tuesday, September 11, 2007 11:16 AM > To: Carl D. Sorensen > Cc: Graham Percival; lily-devel > Subject: Re: regression tests > > Hi Carl, > > > If I understand correctly, the program reference already > contains the > > complete list of user-settable properties for each grob. > > Not in a single page. This could conceivably be done, because each grob has its full interface defined (see grob-interfaces.scm), and it would be possible to collect the descriptions for each of the properties in the interface under the heading of a grob. I think it could be done in Scheme, just like the program reference already is created. > > > you can't say that the default value of property "foo" is "bar". > > It might > > be "bar" when applied to the "grackle" grob, and "baz" when > applied to > > the "frobozz" grob. > > But that's precisely my point! =\ > > Q. What is the default X-offset value of a LyricText grob? > A. Not easy to find! ;-) > > Because there is no (easy) way of finding these values, it > requires more trial-and-error on the part of the user. > > > Thus, there is only one internal documentation point for > "size", not > > one point for each grob that uses size. > > Yes, but these values are (i.e., must be) set for each grob > *somewhere* (in .ly or .scm or .cc files), right? > And if they're intentionally left "unset", what does that > really mean? That (e.g.) an Accidental doesn't have a > minimum-X-extent? The values are not ever really set. The way the default values get assigned is when routine needs a value of a property it calls chain-assoc-get with the name of the property and a default value. If the property is not found, the default is assigned. Speaking for the example that I know best, which is fret-diagrams, the various properties of the fret-diagram are called from at least six different Scheme functions (e.g. draw-dots, draw-strings, draw-frets, etc.). Although it would be relatively easy to search through the .scm files looking for calls to chain-assoc-get with the property size, it would be quite difficult to determine which grob each call references. That is, there is a call from fret-diagrams.scm for the fret-diagram size, but there are also calls from other .scm functions to set the sizes of other grobs. As the code is currently constructed, there's only a property name, not a grob name associated with the call. It's very difficult to say that something is impossible. After all, lots of the Lilypond team members have accomplished things that I would have said were impossible. But from what I know of the code, I don't think the infrastructure exists to make the page you want automatically. However, I think that the page you request is a _very_ desirable page to have. And I could conceive of changing the chain-assoc-get calls to include both a grob and a property, expressly for the purpose of allowing generation of such a page. There would still be some issues. For example, in fret-diagrams, there are two different default dot sizes. If the finger labels are on the strings or are non-existent, the default size is small. OTOH, if the labels are on the dots, the default size is larger. And one can only see the difference by reviewing the structure of the code that contains the chain-assoc-get call, not by examining the call itself. So I think it's pretty close to impossible generate the list of default values. I don't want to dismiss your idea. I'd like to see such a thing happen. I think it would even be OK to list two default values for dot-size in fret-diagrams. At least then I'd only have two choices to choose from, rather than an infinite set > > If feasible (i.e., scriptable, so it's automatically done at > make- docs time), we should offer users a single page (for > each grob) which includes ALL settable properties and their > default values (for that grob). For me, right now, with the current lilypond architecture, I think the page is infeasible. With a change in the chain-assoc-get interface to include a dummy argument that's just used for creating the documentation, I think it could be feasible. Carl ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: regression tests
Kieren MacMillan wrote: Hi Rune, I don't understand what you mean - we already list the default values today: http://lilypond.org/doc/v2.11/Documentation/user/lilypond-internals/ Clef Okay then... without looking anywhere except that page, tell me the default setting(s) for Clef #'space-alist. Copy and paste from that page gives \override Clef #'space-alist = #'((ambitus extra-space . 2.0) (staff-bar extra-space . 0.7) (key-cancellation minimum-space . 3.5) (key-signature minimum-space . 3.5) (time-signature minimum-space . 4.2) (first-note minimum-fixed-space . 5.0) (next-note extra-space . 0.5) (right-edge extra-space . 0.5)) What's the problem? In this specific case, there is no easier representation of that default setting that you can use. Perhaps, what you have in mind is the very nice trick you showed in http://lists.gnu.org/archive/html/lilypond-user/2007-07/msg00688.html which shows how to add a setting to this list. However, this has nothing to do with how the default value is displayed. Rather, it's you who very cleverly "misused" how nested properties are represented internally in LilyPond. /Mats ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: regression tests
This discussion is getting more and more confused. The current program reference does indeed list the default values of all properties that are set by default, for every separate grob. As far as I can see, the bottom line is the following issues: - These default values are printed as basic Scheme values, i.e. not using shorthands like #UP, #DOWN, ... - The list for each grob only includes the properties that are set by default. To see an exhaustive list of all available properties, you have to browse through all "interfaces". This is of course easy to change in the Program reference and we used to have the full list a long time ago, but I'm not sure if it's desirable. Perhaps the current HTML page per grob could include a link to another page that contains the full list of properties. /Mats Carl D. Sorensen wrote: -Original Message- From: Kieren MacMillan [mailto:[EMAIL PROTECTED] Sent: Tuesday, September 11, 2007 8:02 AM To: Graham Percival Cc: lily-devel Subject: Re: regression tests Is there any (automatic) way to generate a COMPLETE list of user- settable properties (and their defaults) for each grob? I mean, having TeXInfo actually drill down into all of the interfaces, etc.? If I understand correctly, the program reference already contains the complete list of user-settable properties for each grob. Under the current architecture, defaults will be difficult, if not impossible, because of the way properties are handled. Default property values are not passed to the routines; the absence of a property indicates that the routine should use the default value. Also, properties don't have a certain system-wide default value. Thus, you can't say that the default value of property "foo" is "bar". It might be "bar" when applied to the "grackle" grob, and "baz" when applied to the "frobozz" grob. The automatic documentation of properties is developed from a grob-independent list. Thus, there is only one internal documentation point for "size", not one point for each grob that uses size. Carl Sorensen ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel -- = Mats Bengtsson Signal Processing Signals, Sensors and Systems Royal Institute of Technology SE-100 44 STOCKHOLM Sweden Phone: (+46) 8 790 8463 Fax: (+46) 8 790 7260 Email: [EMAIL PROTECTED] WWW: http://www.s3.kth.se/~mabe = ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: regression test
Kieren MacMillan skrev: Oops... In that last email, I meant #'staff-position (from staff-symbol-referencer-interface). =\ Clefs don't have a default staff-position - staff-position depends on which clef you select. For G clef it is -2, for C clef it is 0, etc. I do not really see how we should reflect that in the docs. -Rune ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: regression tests
Trevor Bača wrote: Criterion 1: There's a *complete* enumeration of acceptable values for each property, and Criterion 2: There's a working, one-line example of each value for each property of each grob I guess you haven't studied combinatorics. If so, you would quickly realize that the resulting number of examples would be so huge that it's is completely impossible, especially if you want to cover all cases where different settings interact with eachother. Also, as has already been pointed out, many properties can take an arbitrary Scheme function as the value. /Mats ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: regression tests
Hi Rune, I don't understand what you mean - we already list the default values today: http://lilypond.org/doc/v2.11/Documentation/user/lilypond-internals/ Clef Okay then... without looking anywhere except that page, tell me the default setting(s) for Clef #'space-alist. we have to do "something" with the scheme representation in order to make it more feasible for the docs. Probably. Cheers, Kieren. ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: regression tests
Kieren MacMillan skrev: development of lilypond will run faster than any effort to try and keep up with such extended documentation of properties. Possibly... but an *automated* page -- containing a listing exactly as Trevor outlined BUT WITH ONLY THE DEFAULT SETTING/VALUE -- would keep up *precisely* with development, since it would be scripted into the main compilation process. Yep listing default values is easy - I agree - this was not what I was commenting. I was commenting the possibility of listing all POSSIBLE values. I don't understand what you mean - we already list the default values today: http://lilypond.org/doc/v2.11/Documentation/user/lilypond-internals/Clef Though, default values are expanded before they are listed. If some property is set to ,begin-of-line-invisible it will show in the docs as #(#t #f #f) - not as ,begin-of-line-invisible - which makes the whole thing fairly unusable. So we have to do "something" with the scheme representation in order to make it more feasible for the docs. -Rune ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: regression tests
Graham Percival writes: > And only about 10% regtests are useful *as documentation*. 60 easily > fits inside 220. If we missed a few, we can add them. > Most of the regtests are easily covered by the manual. Okay, maybe I underestimated the manual. I took a look at some interesting ones (feature-wise) and they were all covered in the manual. > What's the documentation value of tie-grace.ly ? It works exactly > like you'd expect it to work. This tells you two things: 1) lilypond has this feature, so *that* you can expect this feature to work. There are still quite a number of music notation constructs that just are not implemented yet. 2) the version of lilypond that this regtest refers to, is not broken. I agree that from a documentation pov, the two points above are rather weak, but they are still needed or at leaste valuable for a potential bug report/feature request. Consider for example beam-damp.ly. This is something that you do not want to have in the documentation, but you do want a power user to know about this. Especially if it breaks in a development version. > Power-users know how to read the program reference. They can see the > features there. > > Look, the regression tests are not _intended_ as documentation, and > they _should not_ be intended as documentation. They are regression > tests! Ok, these are very good points. I also agree that the new documentation page is better for new users. The regression test is ugly, but that should be fixed, because it's important for developers. And I would rather have lilypond developer friendly too. How about if I add a small link somewhere at the bottom that says `developers/power user info' to a new page that lists the regession tests and the comparisons (and ...?)? > I wish that more users searched the mailist archives, but they > don't. Useful tips sent to the mailist are essentially lost knowledge; > that's why I've really been pushing LSR. Yes. > Advertising goes in the Examples or in the new "inspirational > headword" examples that are planned in GDP. Ok. > Users report bugs without reading the *manual*. They're not going to > check the regtests. Yes, you're probably right. Thanks for the explanation! Greetings, Jan. -- Jan Nieuwenhuizen <[EMAIL PROTECTED]> | GNU LilyPond - The music typesetter http://www.xs4all.nl/~jantien | http://www.lilypond.org ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: regression tests
Hi Carl, If I understand correctly, the program reference already contains the complete list of user-settable properties for each grob. Not in a single page. you can't say that the default value of property "foo" is "bar". It might be "bar" when applied to the "grackle" grob, and "baz" when applied to the "frobozz" grob. But that's precisely my point! =\ Q. What is the default X-offset value of a LyricText grob? A. Not easy to find! ;-) Because there is no (easy) way of finding these values, it requires more trial-and-error on the part of the user. Thus, there is only one internal documentation point for "size", not one point for each grob that uses size. Yes, but these values are (i.e., must be) set for each grob *somewhere* (in .ly or .scm or .cc files), right? And if they're intentionally left "unset", what does that really mean? That (e.g.) an Accidental doesn't have a minimum-X-extent? If feasible (i.e., scriptable, so it's automatically done at make- docs time), we should offer users a single page (for each grob) which includes ALL settable properties and their default values (for that grob). Now, if it's not technically feasible, I'm happy to end this thread... I've just never been told that it's not feasible. =) Cheers, Kieren. ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: regression tests
Hi Rune, development of lilypond will run faster than any effort to try and keep up with such extended documentation of properties. Possibly... but an *automated* page -- containing a listing exactly as Trevor outlined BUT WITH ONLY THE DEFAULT SETTING/VALUE -- would keep up *precisely* with development, since it would be scripted into the main compilation process. Regards, Kieren. ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: regression tests
Trevor Bac(a skrev: Criterion 1: There's a *complete* enumeration of acceptable values for each property, and This will be very difficult make. And lots of properties takes infinitely many different arguments. For instance 'stencil can take any scheme function. I seriously think that development of lilypond will run faster than any effort to try and keep up with such extended documentation of properties. -Rune ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: regression tests
On 9/11/07, Valentin Villenave <[EMAIL PROTECTED]> wrote: > 2007/9/11, Reinhold Kainhofer <[EMAIL PROTECTED]>: > > > The program reference is (by definition) so closely tied to the internals of > > lilypond that you'll need a lot of experience with lilypond (to know about > > grobs, interfaces, events, etc.), that it's quite hard to turn things into > > real code. I mostly use trial-and-error then until I get the correct > > position > > to set one flag or so. > > With the regression test snippets you already have the correct code and can > > copy it. > > Don't blame me for quoting myself, but I just wanted to mention a line > from my previous mail (which has been lost in this thread), and Jan's > answer: > > > > > How about, for example, http://lilypond.org/web/devel/ > > > > > > That page could serve as a frontend to different versions, just like > > > > > > http://lilypond.org/web/documentation > > I do think, like Graham, that regtests do not belong in Documentation. > You want to cope with "actual code": I understand that, and nodoby > will prevent you from accessing the regtests. > > However, they are *not* Documentation. They do not contain verbose > explanations, they're not redacted, nor corrected, nor formatted, nor > organized, by any Documentation guy (excepted when the Documentation > guy happens to be the bug-tracking guy too :) > > The Reference is *pure* Documentation stuff, as it's intended for > people who'd wish to fully understand the complete LilyPond process. > When you want an easy, quick solution, without necessarily > understanding how, why, when, where etc. it works; here's the LSR. > > What you're looking for isn't in the LSR? Don't think "oh crap, the > LSR isn't any good, I'll never come back again"; just browse every > other non-Documentation sources (archives, regtests etc), and add it > to the LSR, so the next guy can be given a quick solution. > > That's why I fully agree with Graham having reduced the amount of > links on the http://lilypond.org/doc/v2.11/Documentation/ page > (actually I suggested the current layout). > > I do think there *has* to be a link to the regtests, but as said > before we need to find another place. It can be on web/devel, it can > be elsewhere. I just wanted to point out that it would make this > precise page more complete than it is now. > > > > I wish that more users searched the mailist archives, but they don't. > > > Useful tips sent to the mailist are essentially lost knowledge; > > > that's why I've really been pushing LSR. > > Excellent point. Avoiding lost knowledge; that's what we try to do. > > > A while ago, while I was working on some choir pieces, I collected some > > links > > and snippets that I frequently need. Most are from LSR, but e.g. the > > following don't seem to have made it to the LSR: > > ...Then how comes you haven't added these yourself yet? This is > precisely what Graham wants to avoid in the future, by removing the > link of the main Documentation page. > > OK, I've added the last three of your four snippets. > I let you add the first one, about dotted rests not fully merging; > IMHO it could be reported on Google tracker too, as I think the dots > should be merged in such a case... Hi everybody, Can I step in here for a moment, too? The tension about the regtests seems to come from these two things, both of which are equally true: 1. the regtests are ugly (and redacted, corrected, formatted ... exactly as Valentin points out), 2. BUT the regtests give examples of *settings* that are not (currently) available elsewhere. So you put these two observations together and you get exactly the tension you'd expect: the professional documenters and translators among us recoil at the fact that the regtests don't make professional-looking docs, while others among us mourn the loss of honest-to-goodness working examples of a large number of *settings*. So what to do? First, drop this particular thread during the GDP ;-) Scoping doc work is battling a hydra, and Graham's doing an admirable job of making sure that GDP has an actual chance of finishing. That said, when it comes time to scope such a project (next year or later), what I think is *really* needed -- and which addresses both #1 and #2 above -- is precisely what Kieren's pointing to: a greatly fleshed-out version of the programming reference. How fleshed-out? I think we can specify exactly, based on the following two criteria (and I'm thinking of the grob listing here when I write this, not necessarily the other parts of the program reference): Criterion 1: There's a *complete* enumeration of acceptable values for each property, and Criterion 2: There's a working, one-line example of each value for each property of each grob At the very very least you'd think that the grob listing would already have criterion #1, and, in fact, we see people on the list asking for just such lists of values on a fairly regular basis. As an example, this would cha
RE: regression tests
> -Original Message- > From: Kieren MacMillan [mailto:[EMAIL PROTECTED] > Sent: Tuesday, September 11, 2007 8:02 AM > To: Graham Percival > Cc: lily-devel > Subject: Re: regression tests > > > Is there any (automatic) way to generate a COMPLETE list of > user- settable properties (and their defaults) for each grob? > I mean, having TeXInfo actually drill down into all of the > interfaces, etc.? If I understand correctly, the program reference already contains the complete list of user-settable properties for each grob. Under the current architecture, defaults will be difficult, if not impossible, because of the way properties are handled. Default property values are not passed to the routines; the absence of a property indicates that the routine should use the default value. Also, properties don't have a certain system-wide default value. Thus, you can't say that the default value of property "foo" is "bar". It might be "bar" when applied to the "grackle" grob, and "baz" when applied to the "frobozz" grob. The automatic documentation of properties is developed from a grob-independent list. Thus, there is only one internal documentation point for "size", not one point for each grob that uses size. Carl Sorensen ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: regression tests
2007/9/11, Reinhold Kainhofer <[EMAIL PROTECTED]>: > The program reference is (by definition) so closely tied to the internals of > lilypond that you'll need a lot of experience with lilypond (to know about > grobs, interfaces, events, etc.), that it's quite hard to turn things into > real code. I mostly use trial-and-error then until I get the correct position > to set one flag or so. > With the regression test snippets you already have the correct code and can > copy it. Don't blame me for quoting myself, but I just wanted to mention a line from my previous mail (which has been lost in this thread), and Jan's answer: > > > How about, for example, http://lilypond.org/web/devel/ > > > > That page could serve as a frontend to different versions, just like > > > > http://lilypond.org/web/documentation I do think, like Graham, that regtests do not belong in Documentation. You want to cope with "actual code": I understand that, and nodoby will prevent you from accessing the regtests. However, they are *not* Documentation. They do not contain verbose explanations, they're not redacted, nor corrected, nor formatted, nor organized, by any Documentation guy (excepted when the Documentation guy happens to be the bug-tracking guy too :) The Reference is *pure* Documentation stuff, as it's intended for people who'd wish to fully understand the complete LilyPond process. When you want an easy, quick solution, without necessarily understanding how, why, when, where etc. it works; here's the LSR. What you're looking for isn't in the LSR? Don't think "oh crap, the LSR isn't any good, I'll never come back again"; just browse every other non-Documentation sources (archives, regtests etc), and add it to the LSR, so the next guy can be given a quick solution. That's why I fully agree with Graham having reduced the amount of links on the http://lilypond.org/doc/v2.11/Documentation/ page (actually I suggested the current layout). I do think there *has* to be a link to the regtests, but as said before we need to find another place. It can be on web/devel, it can be elsewhere. I just wanted to point out that it would make this precise page more complete than it is now. > > I wish that more users searched the mailist archives, but they don't. > > Useful tips sent to the mailist are essentially lost knowledge; > > that's why I've really been pushing LSR. Excellent point. Avoiding lost knowledge; that's what we try to do. > A while ago, while I was working on some choir pieces, I collected some links > and snippets that I frequently need. Most are from LSR, but e.g. the > following don't seem to have made it to the LSR: ...Then how comes you haven't added these yourself yet? This is precisely what Graham wants to avoid in the future, by removing the link of the main Documentation page. OK, I've added the last three of your four snippets. I let you add the first one, about dotted rests not fully merging; IMHO it could be reported on Google tracker too, as I think the dots should be merged in such a case... Regards, Valentin ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: GDP: rearrangement
Original-Nachricht > > > > Hello, > > > >> For instance I could imagine > >> a chapter "Ancient music", and one on educational subjects. At least I > >> don't see why Ancient is "instrument specific", so why not put it in 7 > >> from the current suggestion, right after educational and special > noteheads. > > > > Maybe "genre specific" instead of "instrument specific" is the correct > term here. Then, the "vocal music" can also stay in the chapter without > singers complaining that the the human voice is not an instrument (btw. > IMO the human voice _is_ an instrument, though a very special one). Sure it is, and this is important for Gregorian chant. But I can imagine thouthands of different instruments for which I would like to notate some mensural stuff. So this is just another style and nothing instrument specific. But I would be happy with genre specific... Greetings Till -- Pt! Schon vom neuen GMX MultiMessenger gehört? Der kanns mit allen: http://www.gmx.net/de/go/multimessenger ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: regression tests
Am Dienstag, 11. September 2007 schrieb Graham Percival: > Jan Nieuwenhuizen wrote: > > Ok. There it says > > > >if there is any regtests which is useful as documentation and there > >is no corresponding snippet in LSR > > > > Although I agree that would be nice, currently that statement is > > ridiculous. It is way too early for that? We have about 600 > > regression tests, and there are only about 220 lsr snippets. > > And only about 10% regtests are useful *as documentation*. 60 easily > fits inside 220. If we missed a few, we can add them. > > Most of the regtests are easily covered by the manual. Especially now > that we're adding new regtests whenever we fix a bug (which is quite > appropriate) Don't underestimate the value of actual code (where you can copy-paste from) compared to a documentation, where you need to turn the knowledge into actual code yourself. It's so much more convenient to take a working example of something even simply and follow the ideas there, tweaking the file until you find out what you are looking for. > Power-users know how to read the program reference. They can see the > features there. Actually, to me (and I regard myself a power user) the program reference is only a very last resort before completely giving up when I don't find any snippet in the regressions tests or the tips & tricks pages. The program reference is (by definition) so closely tied to the internals of lilypond that you'll need a lot of experience with lilypond (to know about grobs, interfaces, events, etc.), that it's quite hard to turn things into real code. I mostly use trial-and-error then until I get the correct position to set one flag or so. With the regression test snippets you already have the correct code and can copy it. > Look, the regression tests are not _intended_ as documentation, and they > _should not_ be intended as documentation. But they ARE useful documentation for power users. > I wish that more users searched the mailist archives, but they don't. > Useful tips sent to the mailist are essentially lost knowledge; That's mainly because of the noise on mailing lists (you'll need to read lots of messages until you hit the one -- if it exists -- that treats your problem), the fact that you don't have the output of lilypond code in postings readily visible, and the fact that messages get out of date with new versions, but are found by a search just as well. > that's why I've really been pushing LSR. I completely agree with you on that. A while ago, while I was working on some choir pieces, I collected some links and snippets that I frequently need. Most are from LSR, but e.g. the following don't seem to have made it to the LSR: - http://www.nabble.com/parenthesize-t2475322.html (parenthesize needs chord) - http://www.mail-archive.com/lilypond-user%40gnu.org/msg14115.html (\voiceOne and \voiceTwo set direction for dotted rests, so when combining rests, you'll need to override the dot direction manually. Otherwise you'll get a rest with two dots!) - http://lilypond.org/doc/v2.10/input/regression/collated-files#parenthesize.ly (parenthesized staccatos) - http://lilypond.org/doc/v2.10/input/regression/collated-files#span-bar.ly (showing bar lines also/only between staves) Cheers, Reinhold -- -- Reinhold Kainhofer, Vienna University of Technology, Austria email: [EMAIL PROTECTED], http://reinhold.kainhofer.com/ * Financial and Actuarial Mathematics, TU Wien, http://www.fam.tuwien.ac.at/ * K Desktop Environment, http://www.kde.org, KOrganizer maintainer * Chorvereinigung "Jung-Wien", http://www.jung-wien.at/ ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Using lilypond as a music layout library
Hi All, I was wondering whether it would be possible to extract lilypond's layout code and use it as a general library for performing music layout. That is to say a programmer would pass lilypond unformatted musical notation (as a data structure) and lilypond would perform layout and return the data structure now with positional information for all the components. The reason this would be desirable is that laying out music nicely is difficult and lilypond is well known for the quality of its output. Someone wanting to write a WYSIWYG GUI for note-editing (for example) could then re-use all the hard work that has gone in lilypond to do the layout of the music on the screen. Theoretically this should be possible. I would imagine that Lilypond's code is split into: - parsing and processing .ly files - laying out the musical notation - converting the notation with layout into output of some form (for example postscript). It would, in principal at least be possible to separate the part that performs layout from the rest of the code. However there are several practical concerns: - the modularity of lilypond's design. It could simply be that lilyponds components are too tightly integrated to make this separation possible. - incremental layout. For the purposes of producing a GUI it would have to be possible to perform incremental layout to some degree. At least to the point of only asking lilypond to recalculate layout the current bar/line/page. It is possible lilypond has been written assuming a 'one-shot' approach in which case making lilypond work incrementally would be almost impossible. - performance generally. An interactive editor would need to perform layout with relatively good performance. Incremental layout is perhaps the biggest component here but it could be that lilypond is simply too slow for this kind of task. One point is that even if the entire layout engine could not be extracted parts of the algorithm could still be useful. For example perhaps only having the code to do 'vertical' layout, i.e. deciding how notation on the beat-line should be arranged, even if the horizontal layout of the beat-line is undefined. So anyway I would be interested to know whether people think extracting the layout code is feasible or is broadly impossible/impractical. Thanks for your help :-) Tom ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: regression tests
Hi Graham, Power-users know how to read the program reference. I know this is slightly OT, but... Is there any (automatic) way to generate a COMPLETE list of user- settable properties (and their defaults) for each grob? I mean, having TeXInfo actually drill down into all of the interfaces, etc.? Sure, a power user CAN do it manually... but often it takes a WHOLE lot of clicking around the docs to get to the desired property, and the default value of that property for a given grob is not (usually) easily accessible. Best regards, Kieren. ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: regression tests
Graham Percival skrev: Look, the regression tests are not _intended_ as documentation, and they _should not_ be intended as documentation. They are regression tests! I agree. But they should still be easily readable. Having to search through the lsr for each and every regtest is hopeless. What are the ideas of how to make the accessible instead of via the manual? -Rune ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
regression tests
Jan Nieuwenhuizen wrote: Ok. There it says if there is any regtests which is useful as documentation and there is no corresponding snippet in LSR Although I agree that would be nice, currently that statement is ridiculous. It is way too early for that? We have about 600 regression tests, and there are only about 220 lsr snippets. And only about 10% regtests are useful *as documentation*. 60 easily fits inside 220. If we missed a few, we can add them. Most of the regtests are easily covered by the manual. Especially now that we're adding new regtests whenever we fix a bug (which is quite appropriate) What's the documentation value of tie-grace.ly ? It works exactly like you'd expect it to work. Or beam-cross-staff-script.ly ? I agree that newbies should not look at the regression test, but if you shut out power-users from the regression test, they'll miss about 400 features? We will have all sorts of questions: Can lily do this? Power-users know how to read the program reference. They can see the features there. Look, the regression tests are not _intended_ as documentation, and they _should not_ be intended as documentation. They are regression tests! Users should have three places to look for help: - manual - program reference (advanced users) - LSR - special-approved-lsr-snippets-in-our-docs (ok, that's 3.5 places) I wish that more users searched the mailist archives, but they don't. Useful tips sent to the mailist are essentially lost knowledge; that's why I've really been pushing LSR. It's also is an amazing advertisement for lily's features? Advertising goes in the Examples or in the new "inspirational headword" examples that are planned in GDP. How is a user supposed to report a bug or do a feature request without having access to the regression tests? Users report bugs without reading the *manual*. They're not going to check the regtests. Cheers, - Graham ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: GDP: rearrangement
On 9/11/07, Rune Zedeler <[EMAIL PROTECTED]> wrote: > Valentin Villenave skrev: > > > Why does "decorating" have a negative meaning to everyone but me? > > Your suggestions are fine too, though. > > The problems are > - even though the term makes sense, it is quite difficult to uniquely > determine whether a specific feature is "decorating" > - Separating decorating stuff from non-decorating stuff moves closely > related items away from each other. E.g. automatic accidentals are > non-decorating whereas cautional accidentals are decorating. Ties are > non-decorating whereas slurs are decorating. Moving these sections away > from each other will make the manual very difficult to use. Would it be bad for me to point to my previous thread (on flattening the manual)? The problem isn't whether "decorative" is perjorative or not; the problem is that grouping a bunch of (essential) notation stuff under the larger header of "decorating" *or anything else* doesn't actually buy us anything (and, in fact, separates related notation elements, as Rune points out). Promote each decorating section to the status of a free-standing chapter and the problem will disappear. We need not to freak out about a 20 or 30 chapter notaton reference; that's perfectly valid for a reference. -- Trevor Bača [EMAIL PROTECTED] ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: GDP: rearrangement
Valentin Villenave skrev: Why does "decorating" have a negative meaning to everyone but me? Your suggestions are fine too, though. The problems are - even though the term makes sense, it is quite difficult to uniquely determine whether a specific feature is "decorating" - Separating decorating stuff from non-decorating stuff moves closely related items away from each other. E.g. automatic accidentals are non-decorating whereas cautional accidentals are decorating. Ties are non-decorating whereas slurs are decorating. Moving these sections away from each other will make the manual very difficult to use. -Rune ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
GDP: flattening the manual to two layers?
Hey Graham, hey everyone, The GDP discussion has been extremely interesting and I think I've caught up on most of the threads. But I'm not certain so feel free to tell me if this topic has already come up. Question: has anyone suggested replacing the three-layer chapter / section / section structure with a two-layer chapter / section structure? The major sections are extremely useful and have, importantly, self-evident titles; but I've never felt that grouping the major sections into "basic", "decorating", "instrument-specific" etc really buys anything ... it's always going to be quite arbitrary as to what counts as "basic" versus "decorating" versus "text", IMO, so maybe best to just kill the false disctinctions. That would leave us with a 20 or 30 chapter manual, which makes perfect sense for something like a notation reference for an engraving system (again IMO). So like this: > o 6 Pitches >+ 6.1 Normal pitches >+ 6.2 Accidentals >+ 6.3 Cautionary accidentals >+ 6.4 Micro tones >+ 6.5 Note names in other languages >+ 6.6 Relative octaves >+ 6.7 Octave check >+ 6.8 Rests >+ 6..9 Skips > o 7 Affecting multiple pitches >+ 7.1 Clef >+ 7.2 Key signature >+ 7.3 Transpose >+ 7.4 Instrument transpositions >+ 7.5 Ottava brackets > o 8 Rhythms >+ 8.1 Durations >+ 8.2 Augmentation dots >+ 8.3 Tuplets >+ 8.4 Scaling durations >+ 8.5 Automatic note splitting >+ 8.6 Aligning to cadenzas > o 9 Meter >+ 9.1 Time signature >+ 9.2 Partial measures >+ 9.3 Unmetered music >+ 9.4 Polymetric notation (alternating) >+ 9.5 Polymetric notation (simultaneous) >+ 9.6 Time administration >+ 9.7 Proportional notation (introduction) >+ 9.8 Automatic beams >+ 9.9 Manual beams >+ 9.10 Feathered beams > o 10 Bars >+ 10.1 Bar check >+ 10.2 Barnumber check >+ 10.3 Multi measure rests >+ 10.4 Bar lines >+ 10.5 Bar numbers >+ 10.6 Rehearsal marks etc ... -- Trevor Bača [EMAIL PROTECTED] ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: GDP: rearrangement
2007/9/11, Till Rettig <[EMAIL PROTECTED]>: Hello, For instance I could imagine a chapter "Ancient music", and one on educational subjects. At least I don't see why Ancient is "instrument specific", so why not put it in 7 from the current suggestion, right after educational and special noteheads. Maybe "genre specific" instead of "instrument specific" is the correct term here. Then, the "vocal music" can also stay in the chapter without singers complaining that the the human voice is not an instrument (btw. IMO the human voice _is_ an instrument, though a very special one). But, of course, I am also happy if you think that ancient music deserves a chapter of its own. ;-) Greetings, Juergen ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: GDP: read the 2.11 docs
2007/9/11, Jan Nieuwenhuizen <[EMAIL PROTECTED]>: >if there is any regtests which is useful as documentation and there >is no corresponding snippet in LSR > > Although I agree that would be nice, currently that statement is > ridiculous. It is way too early for that? We have about 600 > regression tests, and there are only about 220 lsr snippets. I agree > that newbies should not look at the regression test, but if you shut > out power-users from the regression test, they'll miss about 400 > features? We will have all sorts of questions: Can lily do this? You have a good point. However this shouldn't prevent us from keeping adding the regtests to the LSR (IMO, every regtest can potentially be useful as documentation; however since they're very short and minimal, some have to be merged or developed). > > How about, for example, http://lilypond.org/web/devel/ > > That page could serve as a frontend to different versions, just like > > http://lilypond.org/web/documentation This would be very cool; I recently wished the "developers area" could be more developed... > The regression tests are (as the name implies) hard linked to a > specific lilypond version. They are built as part of the > documentation (or `make web') build, so there should still be an index > page in the documentation, besides Documentation/index.html.in, say > Documentation/devel.html.in? This is equally possible, and logical. Graham, what do you think? > It's also is an amazing advertisement for lily's features? How is > a user supposed to report a bug or do a feature request without > having access to the regression tests? I've recently been praising for feature pages too... About every open-source (or proprietary) software has a "Features" link on its home page. This could be a place for both nice, pedagogical, features pages, and a "Complete features list" link to the current regtests, couldn't it? Regards, Valentin ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: GDP: read the 2.11 docs
Valentin Villenave writes: > This issue have been discused with Graham and Trevor recently: > http://lists.gnu.org/archive/html/lilypond-devel/2007-08/msg00179.html Ok. There it says if there is any regtests which is useful as documentation and there is no corresponding snippet in LSR Although I agree that would be nice, currently that statement is ridiculous. It is way too early for that? We have about 600 regression tests, and there are only about 220 lsr snippets. I agree that newbies should not look at the regression test, but if you shut out power-users from the regression test, they'll miss about 400 features? We will have all sorts of questions: Can lily do this? > How about, for example, http://lilypond.org/web/devel/ That page could serve as a frontend to different versions, just like http://lilypond.org/web/documentation The regression tests are (as the name implies) hard linked to a specific lilypond version. They are built as part of the documentation (or `make web') build, so there should still be an index page in the documentation, besides Documentation/index.html.in, say Documentation/devel.html.in? It's also is an amazing advertisement for lily's features? How is a user supposed to report a bug or do a feature request without having access to the regression tests? Greetings, Jan. -- Jan Nieuwenhuizen <[EMAIL PROTECTED]> | GNU LilyPond - The music typesetter http://www.xs4all.nl/~jantien | http://www.lilypond.org ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: GDP: rearrangement
2007/9/11, Till Rettig <[EMAIL PROTECTED]>: Hello, > For instance I could imagine > a chapter "Ancient music", and one on educational subjects. At least I > don't see why Ancient is "instrument specific", so why not put it in 7 > from the current suggestion, right after educational and special noteheads. I'll let Graham do the talking on this one :) > I am also somewhat unpleasant with the current "string" section in the > instrument specific chapter: I would like to see here all those > \bowdown, \bowup, \flageolet, \thumb and so on that are in > "articulations" so far -- or at least a link to them. Well, that's > already about contents, not only rearranging. Yes, we should mention it (maybe in @seealso, or a @lsrtag link) > I like the "text"-section, that is a good idea. But going the same way > for other stuff as well... Name of chapter 7 should maybe be changed, > not everything is about "decoration", there are some really important > things. Would it be something like "polishing", "finishing" or the like? Why does "decorating" have a negative meaning to everyone but me? Your suggestions are fine too, though. Regards, Valentin ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: GDP: read the 2.11 docs
Hello Jan, 2007/9/11, Jan Nieuwenhuizen <[EMAIL PROTECTED]>: > > - regtests and tips are gone. > > Why is this? I can maybe understand that lsr replaces the tips, but > the regtest shows every feature that lilypond has. This issue have been discused with Graham and Trevor recently: http://lists.gnu.org/archive/html/lilypond-devel/2007-08/msg00179.html Most of the regtests have been, or will be, added to the LSR as well. We probably have to find some place to put a link, but it would probably be better on a developer-oriented rather than an user-oriented page. How about, for example, http://lilypond.org/web/devel/ ? We could add a section between "source code" and "participating", couldn't we? Regards, Valentin ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: GDP: length/page-splitting of subsections
Graham Percival wrote: There are two solutions for this: 1) Don't split HTML by into subsections; have one html page per section. 2) Merge many subsections. For example, 6.1 Pitches 6.1.1 Writing pitches(includes 6.1.1, 6.1.2, 6.1.3, 6.1.4, and 6.1.5 in the latest proposal) 6.1.2 Octaves/jumping pitches (includes 6.1.6, 6.1.7, and 7.1.8) 6.1.3 Rests(includes 6.1.9 and 6.10) the names obviously need work. My preference is for 2 -- I can't believe that users want to see articulations, dynamics, and trills on the same HTML page. But as I said, we should probably disregard my opinion on this issue. Yes, merging some selected subsections is probably the best solution. /Mats ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: GDP: rearrangement
Hello, from what so far has been discussed I catched somewhat the need is to group the issues more into "single topic" sections of subsections. For the discussion about the format of the html-docu: I would rather like to have whole subsections downloading than those tiny pages -- I also get lost on them and always have to go at least three steps up until I come again to the contents where I look for another promising section's name. So actually for me also a link to the toc would be sufficient, maybe also one to the index, to be on *every* page. I personally dislike the system that for going from a subsection to the next section demands climbing up one level -- I am probably too much used to reading real books where this kind of strange behaviour doesn't happen. But it might be a texinfo issue that we cannot incluence... About rearranging: I would suggest breaking up chapters (with only one number, like 6, 7, and so on) into smaller chapters in some cases, that is being more specific on the lowest level. For instance I could imagine a chapter "Ancient music", and one on educational subjects. At least I don't see why Ancient is "instrument specific", so why not put it in 7 from the current suggestion, right after educational and special noteheads. I didn't check the situation now but from the discussion about "aligning cadenzas" -- I would look for cadenzas either in grace notes (being something "additional") or at rhythmic issues. From there we could have a link to a general chapter about aligning... I am also somewhat unpleasant with the current "string" section in the instrument specific chapter: I would like to see here all those \bowdown, \bowup, \flageolet, \thumb and so on that are in "articulations" so far -- or at least a link to them. Well, that's already about contents, not only rearranging. I like the "text"-section, that is a good idea. But going the same way for other stuff as well... Name of chapter 7 should maybe be changed, not everything is about "decoration", there are some really important things. Would it be something like "polishing", "finishing" or the like? Sorry for writing so confused, I hope it is still understandable. It's mainly just some thoughts... Greetings Till * 6 Basic musical notation o 6.1 Pitches + 6.1.1 Normal pitches + 6.1.2 Accidentals + 6.1.3 Cautionary accidentals + 6.1.4 Micro tones + 6.1.5 Note names in other languages + 6.1.6 Relative octaves + 6.1.7 Octave check + 6.1.8 Rests + 6.1.9 Skips o 6.2 Affecting multiple pitches + 6.2.1 Clef + 6.2.2 Key signature + 6.2.3 Transpose + 6.2.4 Instrument transpositions + 6.2.5 Ottava brackets o 6.3 Rhythms + 6.3.1 Durations + 6.3.2 Augmentation dots + 6.3.3 Tuplets + 6.3.4 Scaling durations + 6.3.5 Automatic note splitting + 6.3.6 Aligning to cadenzas o 6.4 Meter + 6.4.1 Time signature + 6.4.2 Partial measures + 6.4.3 Unmetered music + 6.4.4 Polymetric notation (alternating) + 6.4.5 Polymetric notation (simultaneous) + 6.4.6 Time administration + 6.4.7 Proportional notation (introduction) + 6.4.8 Automatic beams + 6.4.9 Manual beams + 6.4.10 Feathered beams o 6.5 Bars + 6.5.1 Bar check + 6.5.2 Barnumber check + 6.5.3 Multi measure rests + 6.5.4 Bar lines + 6.5.5 Bar numbers + 6.5.6 Rehearsal marks o 6.6 Polyphony + 6.6.1 Chords + 6.6.2 Stems + 6.6.3 Basic polyphony + 6.6.4 Explicitly instantiating voices + 6.6.5 Collision resolution + 6.6.6 Clusters + 6.6.7 Automatic part combining + 6.6.8 Writing music in parallel * 7 Decorating musical notation o 7.1 Connecting notes + 7.1.1 Ties + 7.1.2 Slurs + 7.1.3 Phrasing slurs + 7.1.4 Laissez vibrer ties + 7.1.5 Grace notes + 7.1.6 Analysis brackets o 7.2 Expressive marks + 7.2.1 Articulations + 7.2.2 Dynamics (absolute) + 7.2.3 Dynamics (crescendi) + 7.2.4 Breath marks + 7.2.5 Trills + 7.2.6 Glissando + 7.2.7 Arpeggio + 7.2.8 Falls and doits o 7.3 Staff notation + 7.3.1 System start delimiters + 7.3.2 Staff symbol + 7.3.3 Hiding staves + 7.3.4 Metr
Re: GDP: structure of index
> > > Furthermore, I would like to see entries like > > > > > > \displayLilyMusic: Displaying LilyPond notation > > > \displayLilyMusic: Displaying music expressions > > > > > > rather being structured as follows: > > > > > > \displayLilyMusic: > > > Displaying LilyPond notation > > > Displaying music expressions If at all, it should be \displayLilyMusic: Displaying LilyPond notation, Displaying music expressions otherwise it sticks out far too promimently. > > I'm not certain if texinfo 4.8 can do that. Werner, do you know? No, sorry. > FWIW 4.9 was released on June 29, and the latest beta is 4.9.92, so > they might add it before 4.11... 4.11 has been released two days ago. Werner ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: GDP: read the 2.11 docs
Graham Percival writes: > To anybody involved in the GDP discussion, please take a few minutes > to look at the documentation for 2.11. > - regtests and tips are gone. Why is this? I can maybe understand that lsr replaces the tips, but the regtest shows every feature that lilypond has. If you don't want that in the documentation, where are we going to link those pages? Jan. -- Jan Nieuwenhuizen <[EMAIL PROTECTED]> | GNU LilyPond - The music typesetter http://www.xs4all.nl/~jantien | http://www.lilypond.org ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
