Re: GDP: rearrange manual
Rune Zedeler wrote: Well, in its current state I find the each subsection has its own page version of the manual unusable, and therefore always uses the one big page manual. I suggest that we gives each section its own page containing section and all subsections. Ofcourse each section should still contain a table of links, but the links should stay on the same page (just as the one big page documentation does now). What makes the each subsection has its own page unusable? Is it the lack of a good index? That's certainly something I plan on improving in GDP. Given that all subsections for the same section live on the same webpage I agree with graham that further splitting would be a good idea. One possibility is to have larger subsections, but use @subheading to visually divide the page. In the table of contents, we would see a single Dynamics subsection, but the HTML page itself would be Dynamics Dynamics (absolute) \ff \mp blah blah Dynamics (crescendi) \cr \! blah blah Dynamics (positioning) \override blah blah This will satisfy my desire to have short, logically-bundles pieces of information. When a newbie is browsing the docs, he'll easily see the Dynamics (positioning) section, so if he cares about that info he can read it. Cheers, - Graham ___ lilypond-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user
Re: GDP: rearrange manual
Trevor Bača wrote: ~ subsection 8.4.3 Proportional notation can be removed completely in favor of subsection 11.6.5 Proportional notation I'd rather not remove subsections yet; we'll do that when we GDPify that particular chapter. ~ subsections 8.4.4 Clusters and 8.4.5 Special noteheads can become the very last subsections of section 6.1 Pitches General note: I'd like to have between 5 and 9 subsections inside each section. Besides, IMO clusters are polyphony. :) ~ subsection 8.4.8 Selecting notation font size; how did this ever wind up here? I don't understand the intent of this section; it talks only about notehead font size (not about font sizes in general), so if we keep it (which seems unnecessary, actually) then it should go to section 6.1 Pitches It doesn't belong in pitches, but I really don't know what to do with it. The whole 7.6 Special use (in the new arrangement) is kind-of giving up; I'd really like to move those sections elsewhere, or get a better title, or something. (I make the preceding recommendation on contemporary notation based on the fact that we've come a *TREMENDOUSLY* far way with contemporary notation in the last major releases and I think that the most professional way to reflect this fact is to un-ghetto-ize the contemporary stuff and just include it -- elegantly and cleanly -- in the other major sections of the manual.) Yes, absolutely. Already done. :) Cheers, - Graham ___ lilypond-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user
Re: GDP: rearrange manual
Eyolf Østrem wrote: I would also say -- although this may exceed the limits of what kind of suggestions were allowed -- that one thing that is missing is a comprehensive survey of the syntax of Lilypond. Like Appendix E Cheat sheet ? It's quite limited at the moment, but is that what you're talking about? Expanding the Cheat sheet has been discussed from time to time; it comes down to resources. At the moment, I think it's more important to clean up the notation reference. If we have time/energy left afterwards, we could tackle this... or if anybody wants to volunteer specifically to do this, that would be great; I could help you get started. Cheers, - Graham ___ lilypond-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user
Re: GDP: rearrange manual
Just a question... (by the way, is it really relevant to cross post this entire discussion to -devel?) I'm finishing translating the current chapter #9 (changing-defaults) and here's what I see: 9.3.2 Suppose we want to move the fingering indication in the fragment below: === but it actually doesn't tell how to do it; you have to keep reading... 9.3.3 The HTML page that we found in the previous section === now we're beginning to understand what we've seen previously. *but* we still don't have the bloody answer :) 9.3.4 Recall that we wanted to change the position of the... === And *now* we have the answer... It's fun, interesting, thrilling, very well thought. great pedagogy; but it implies that the subsections are absolutely not independant from each other. Therefore, I would second Rune's proposal for gathering subsections on a single page. Or we'd have to rewrite this whole section (and that would be a pity). Graham, what do you think? Valentin ___ lilypond-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user
Re: GDP: rearrange manual
Valentin Villenave wrote: Just a question... (by the way, is it really relevant to cross post this entire discussion to -devel?) We're talking about some major lilypond development work here. Documentation is still development. A better question is is it really relevant to cross post this entire discussion to -user? In this case, I think it's worth it. I'm finishing translating the current chapter #9 (changing-defaults) and here's what I see: It's fun, interesting, thrilling, very well thought. great pedagogy; but it implies that the subsections are absolutely not independant from each other. Therefore, I would second Rune's proposal for gathering subsections on a single page. Or we'd have to rewrite this whole section (and that would be a pity). Graham, what do you think? Valentin Err.. we're talking about Changing defaults, a chapter which hasn't been significantly changed in the past three years, and which you've _already_ complained as being a pile of garbage... and using this as an argument for changing the way the rest of the manual is displayed? :) I disagree; I think the short loading time for pages is important. Now, I'm not opposed to merging existing subsections... and I was already planning on completely rewriting Changing defaults as part of GDP. Cheers, - Graham ___ lilypond-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user
Re: GDP: rearrange manual
Yes, I guess my main point was the on-line manual, where the splitting into separate HTML pages is a problem in some cases, like Valentin just illustrated. As far as I understand, it's the texinfo - HTML conversion that imposes the constraint that each subsection ends up in a separate HTML. It would really be a pity to be forced to use a specific kind of document structure just because these tools are not so flexible. Being able to quickly scroll through a section in the on-line documentation is clearly very valuable when you're looking for an answer to a specific problem but don't know exactly what subsection to look into, or to get an overview of a more complicated solution as in the example Valentin brought up. /Mats Valentin Villenave wrote: Just a question... (by the way, is it really relevant to cross post this entire discussion to -devel?) I'm finishing translating the current chapter #9 (changing-defaults) and here's what I see: 9.3.2 Suppose we want to move the fingering indication in the fragment below: === but it actually doesn't tell how to do it; you have to keep reading... 9.3.3 The HTML page that we found in the previous section === now we're beginning to understand what we've seen previously. *but* we still don't have the bloody answer :) 9.3.4 Recall that we wanted to change the position of the... === And *now* we have the answer... It's fun, interesting, thrilling, very well thought. great pedagogy; but it implies that the subsections are absolutely not independant from each other. Therefore, I would second Rune's proposal for gathering subsections on a single page. Or we'd have to rewrite this whole section (and that would be a pity). Graham, what do you think? Valentin ___ lilypond-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user -- = 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-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user
Re: GDP: rearrange manual
On 10.09.2007 (05:28), Graham Percival wrote:
Eyolf Østrem wrote:
I would also say -- although this may exceed the limits of what kind
of suggestions were allowed -- that one thing that is missing is a
comprehensive survey of the syntax of Lilypond.
Like Appendix E Cheat sheet ? It's quite limited at the moment, but is
that what you're talking about?
Something like that, but also containing a summary of what is in ch. 9
Changing defaults and 10. File structure. Anyone who uses LP is to
some extent a programmer, and one doesn't have to stray very far from
the simplest pieces before it becomes necessary to look into those
chapters. But although the information is probably there, there is a
gap between the simple basics and the syntactically quite complicated
stuff in scheme: it takes a while to get one's head around Why should
this word be in CamelCase? Why are there no braces here? etc.
In an earlier mail, I mentioned one such case:
9.1.5 Changing context default settings
\layout {
...
\context {
\Staff
...
}
}
Here \Staff takes the existing definition for context Staff from the
identifier \Staff.
Why is this an identifier, which usually (it seems) are lower-case? Why isn't
what follows it enclosed in {}? And, again, do the three Staffs in the
explaining sentence refer to three different (types of) objects? Is the first
\Staff a different item than the context Staff, which just happens to have
the same name? Is this \Staff the identifier \Staff which is mentioned
later in the sentence, or is it yet another thing with the same name?
I'm confused... Mostly because of the {}-less syntax, but also by the
same-same-but-different names.
Expanding the Cheat sheet has been discussed from time to time; it comes
down to resources. At the moment, I think it's more important to clean up
the notation reference. If we have time/energy left afterwards, we could
tackle this... or if anybody wants to volunteer specifically to do this,
that would be great; I could help you get started.
I fully understand the resources thing, and I greatly appreciate your
work on this.
Eyolf
--
Seek for the Sword that was broken:
In Imladris it dwells;
There shall be counsels taken
Stronger than Morgul-spells.
There shall be shown a token
That Doom is near at hand,
For Isildur's Bane shall waken,
And the Halfling forth shall stand.
-- J. R. R. Tolkien
___
lilypond-user mailing list
lilypond-user@gnu.org
http://lists.gnu.org/mailman/listinfo/lilypond-user
Re: GDP: rearrange manual
2007/9/10, Graham Percival [EMAIL PROTECTED]: Err.. we're talking about Changing defaults, a chapter which hasn't been significantly changed in the past three years, and which you've _already_ complained as being a pile of garbage... and using this as an argument for changing the way the rest of the manual is displayed? :) I guess garbage can be fun though :) This whole chapter has to be rewritten indeed. But in this case, I just wanted to emphasize the positive (pedagogical) aspects of a linear documentation. Maybe such tricks are more convenient in LM than NR anyway. I disagree; I think the short loading time for pages is important. Oh yes. Good point. Like Rune, I'm always using the big-page manual; but that's because I have a DSL connection, and Firefox makes searching very easy... Valentin ___ lilypond-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user
Re: GDP: rearrange manual
Am Montag, 10. September 2007 schrieb Graham Percival: Rune Zedeler wrote: Well, in its current state I find the each subsection has its own page version of the manual unusable, and therefore always uses the one big page manual. I suggest that we gives each section its own page containing section and all subsections. Ofcourse each section should still contain a table of links, but the links should stay on the same page (just as the one big page documentation does now). What makes the each subsection has its own page unusable? Is it the lack of a good index? Often I know what I need, but I don't know how to name it exactly, so an index with some selected keywords is not so helpful. In these cases, I tend to go to a page that treats that subject, and do a full text search (or with the short subsections in the lilypond documentation click through all subsections of that sections, manually scanning the section for what I'm looking for). If lilypond's documentation has larger sections (one for each larger topic), doing a text search is possible and I don't have to read (i.e. quickly scan each page visually for what I'm looking for). The other reason is that it's easier to remember where to find somethings. Currently, whenever I look for that nice lilypond example of all articulations, I go to the contents, search for articulation, and then from that page, I know I have to take the Articulations link to the page I'm actually looking for. Having everything related on one page removes the need to click through many pages, and additionally makes it possible to print out only the wanted section. One possibility is to have larger subsections, but use @subheading to visually divide the page. Yes, I would prefer that. In the table of contents, we would see a single Dynamics subsection, but the HTML page itself would be 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-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user
Re: GDP: rearrange manual
Le lundi 10 septembre 2007 à 14:46 +0200, Mats Bengtsson a écrit : Yes, I guess my main point was the on-line manual, where the splitting into separate HTML pages is a problem in some cases, like Valentin just illustrated. As far as I understand, it's the texinfo - HTML conversion that imposes the constraint that each subsection ends up in a separate HTML. It would really be a pity to be forced to use a specific kind of document structure just because these tools are not so flexible. But Texinfo does not force us to have one HTML page per subsection! HTML splitted pages are generated just like Info nodes, with the @node command. E.g. if you want to get a whole section in one single page, you just need to remove @node commands for all its subsections. Cheers, John ___ lilypond-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user
Re: GDP: rearrange manual
Le lundi 10 septembre 2007 à 15:31 +0200, Reinhold Kainhofer a écrit : Am Montag, 10. September 2007 schrieb Graham Percival: Rune Zedeler wrote: Well, in its current state I find the each subsection has its own page version of the manual unusable, and therefore always uses the one big page manual. I suggest that we gives each section its own page containing section and all subsections. Ofcourse each section should still contain a table of links, but the links should stay on the same page (just as the one big page documentation does now). We could use @anchor to get links (@ref's in Info) on the same page, but I'm not sure *Menu items can redirect to an @anchor. Often I know what I need, but I don't know how to name it exactly, so an index with some selected keywords is not so helpful. In these cases, I tend to go to a page that treats that subject, and do a full text search (or with the short subsections in the lilypond documentation click through all subsections of that sections, manually scanning the section for what I'm looking for). If lilypond's documentation has larger sections (one for each larger topic), doing a text search is possible and I don't have to read (i.e. quickly scan each page visually for what I'm looking for). The other reason is that it's easier to remember where to find somethings. Currently, whenever I look for that nice lilypond example of all articulations, I go to the contents, search for articulation, and then from that page, I know I have to take the Articulations link to the page I'm actually looking for. Having everything related on one page removes the need to click through many pages, and additionally makes it possible to print out only the wanted section. The PDF manual is certainly much more suitable for printing, and easy full text searching is one purpose of the big page HTML manual. We will decide about having larger HTML pages (and thus larger Info nodes) in a further step of the Grand Documentation Project. Now we only decide about naming new chapters and sections, moving sections between chapters and subsections between sections. Cheers, John ___ lilypond-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user
Re: GDP: rearrange manual
John Mandereau wrote: We could use @anchor to get links (@ref's in Info) on the same page, but I'm not sure *Menu items can redirect to an @anchor. @menu items direct to @section items. This is no problem. We will decide about having larger HTML pages (and thus larger Info nodes) in a further step of the Grand Documentation Project. Now we only decide about naming new chapters and sections, moving sections between chapters and subsections between sections. Sorry, I disagree. If we decide to merge an average of 4 subsections into a single subsection, that will drastically change the way the chapter/sections look. If we were just talking about one or two specific subsections, I'd agree with you, but a general change like this should be settled now. For example, if we combine subsections, then it makes sence for 6.1 and 6.2 to be a single section. Cheers, - Graham ___ lilypond-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user
GDP: rearrange manual
Despite me being fairly happy with out table of contents, I think we could still improve the arrangement of subsections. Here's my proposal. LIMITED DISCUSSION To keep discussion focused and as un-confused as possible, this is a discussion *only* about the arrangement of subsections. Other parts of GDP will be discussed later. This means: - propose new/changed chapter/sections - propose renamings of chapter/sections - *do not* discuss new subsections or renamings of subsections. That will come later. GENERAL IDEAS - the manual will be split even more into Learning Manual / Notation Reference. This is the notation reference, so we assume that users have read the LM. They know about music expressions, \override, etc. The LM will be increased to accomodate for this, but that's a separate discussion. * 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 Metronome marks + 7.3.5 Instrument names + 7.3.6 Quoting other voices + 7.3.7 Formatting cue notes o 7.4 Repeats + 7.4.1 Repeat types + 7.4.2 Repeat syntax + 7.4.3 Repeats and MIDI + 7.4.4 Manual repeat commands + 7.4.5 Tremolo repeats + 7.4.6 Tremolo subdivisions + 7.4.7 Measure repeats o 7.5 Educational use + 7.5.1 Balloon help + 7.5.2 Fingering instructions + 7.5.3 Blank music sheet + 7.5.4 Grid lines + 7.5.5 Shape note heads + 7.5.6 Easy Notation note heads o 7.6 Special use + 7.6.1 Special noteheads + 7.6.2 Improvisation + 7.6.3 Selecting notation font size + 7.6.4 Hidden notes + 7.6.5 Coloring objects + 7.6.6 Parentheses * 8 Instrument-specific notation o 8.1 Piano music + 8.1.1 Pedals + 8.1.2 Automatic staff changes + 8.1.3 Manual staff switches + 8.1.4 Staff switch lines + 8.1.5 Cross staff stems o 8.2 Chord names + 8.2.1 Introducing chord names + 8.2.2 Chords mode + 8.2.3 Printing chord names
Re: GDP: rearrange manual
Graham Percival skrev: LIMITED DISCUSSION To keep discussion focused and as un-confused as possible, this is a discussion *only* about the arrangement of subsections. Other parts of GDP will be discussed later. This means: - propose new/changed chapter/sections - propose renamings of chapter/sections - *do not* discuss new subsections or renamings of subsections. That will come later. Sorry I do not understand what you mean. How can we discuss arrangement of subsections without discussing new subsections or renaming of subsections? Btw: Chapters are the ones with one number, sections are the ones with two numbers and subsections are the ones with tre numbers, right? -Rune ___ lilypond-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user
Re: GDP: rearrange manual
Rune Zedeler wrote: Graham Percival skrev: LIMITED DISCUSSION To keep discussion focused and as un-confused as possible, this is a discussion *only* about the arrangement of subsections. Other parts of GDP will be discussed later. This means: - propose new/changed chapter/sections - propose renamings of chapter/sections - *do not* discuss new subsections or renamings of subsections. That will come later. Sorry I do not understand what you mean. How can we discuss arrangement of subsections without discussing new subsections or renaming of subsections? Like this: 6.1.8 rests and 6.1.9 should not be part of 6.1 pitches, because they're not real notes. Move them to 6.3 rhythms instead or 9.3 Vocal music is too large. Split it up into: 9.3 Adding lyrics 9.3.1 Setting simple songs 9.3.2 Entering lyrics. ... and 9.4 Multiple stanzas and aligning lyrics 9.4.1 foo 9.4.2 bar ... Also, 9.3.8 Ambitus should be moved into chapter 7 In other words, treat the subsections as atoms (indivisible parts) and form them into new structures. The reasons: - I don't want new proposed subsections right now, since writing new docs takes a lot more work than rearranging docs. We'll tackle this step in about a week, once I know how much help we have - I don't want renamed subsections yet, so that it's easy for everybody to compare the new arrangement with the current one. When we start renaming subsections, it gets much more complicated. Btw: Chapters are the ones with one number, sections are the ones with two numbers and subsections are the ones with tre numbers, right? Yes, sorry. I should have explained that. Cheers, - Graham ___ lilypond-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user
Re: GDP: rearrange manual
Just one general comment for the moment: I'd rather propose longer than shorter subsections. I think that there already is too much fragmentation at some places for the moment, which means that you never get the chance to see the full picture as a reader. We shouldn't expect a user to keep reading several consecutive subsections, especially not in a reference manual, where you expect to get an answer to your question by just looking at a single subsection (=web page in the on-line manual). /Mats Quoting Graham Percival [EMAIL PROTECTED]: Rune Zedeler wrote: Graham Percival skrev: LIMITED DISCUSSION To keep discussion focused and as un-confused as possible, this is a discussion *only* about the arrangement of subsections. Other parts of GDP will be discussed later. This means: - propose new/changed chapter/sections - propose renamings of chapter/sections - *do not* discuss new subsections or renamings of subsections. That will come later. Sorry I do not understand what you mean. How can we discuss arrangement of subsections without discussing new subsections or renaming of subsections? Like this: 6.1.8 rests and 6.1.9 should not be part of 6.1 pitches, because they're not real notes. Move them to 6.3 rhythms instead or 9.3 Vocal music is too large. Split it up into: 9.3 Adding lyrics 9.3.1 Setting simple songs 9.3.2 Entering lyrics. ... and 9.4 Multiple stanzas and aligning lyrics 9.4.1 foo 9.4.2 bar ... Also, 9.3.8 Ambitus should be moved into chapter 7 In other words, treat the subsections as atoms (indivisible parts) and form them into new structures. The reasons: - I don't want new proposed subsections right now, since writing new docs takes a lot more work than rearranging docs. We'll tackle this step in about a week, once I know how much help we have - I don't want renamed subsections yet, so that it's easy for everybody to compare the new arrangement with the current one. When we start renaming subsections, it gets much more complicated. Btw: Chapters are the ones with one number, sections are the ones with two numbers and subsections are the ones with tre numbers, right? Yes, sorry. I should have explained that. Cheers, - Graham ___ lilypond-devel mailing list [EMAIL PROTECTED] http://lists.gnu.org/mailman/listinfo/lilypond-devel ___ lilypond-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user
Re: GDP: rearrange manual
Mats Bengtsson wrote: Just one general comment for the moment: I'd rather propose longer than shorter subsections. I think that there already is too much fragmentation at some places for the moment, which means that you never get the chance to see the full picture as a reader. Interesting suggestion; I was obviously thinking opposite to this -- for example, consider splitting Dynamics into (absolute) and (crescendi). My motivation is that some people clearly hadn't read the whole doc subsection, and that having shorter subsections would make people more likely to read the whole thing. Any other comments about this? I'm not convinced either way, but this is something we should definitely decide before getting into more details about a rearrangement. Cheers, - Graham ___ lilypond-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user
Re: GDP: rearrange manual
Citat Graham Percival [EMAIL PROTECTED]: Just one general comment for the moment: I'd rather propose longer than shorter subsections. I think that there already is too much fragmentation at some places for the moment, which means that you never get the chance to see the full picture as a reader. Well, in its current state I find the each subsection has its own page version of the manual unusable, and therefore always uses the one big page manual. I suggest that we gives each section its own page containing section and all subsections. Ofcourse each section should still contain a table of links, but the links should stay on the same page (just as the one big page documentation does now). Given that all subsections for the same section live on the same webpage I agree with graham that further splitting would be a good idea. -Rune ___ lilypond-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user
Re: GDP: rearrange manual
On 9/9/07, Graham Percival [EMAIL PROTECTED] wrote: Mats Bengtsson wrote: Just one general comment for the moment: I'd rather propose longer than shorter subsections. I think that there already is too much fragmentation at some places for the moment, which means that you never get the chance to see the full picture as a reader. Interesting suggestion; I was obviously thinking opposite to this -- for example, consider splitting Dynamics into (absolute) and (crescendi). My motivation is that some people clearly hadn't read the whole doc subsection, and that having shorter subsections would make people more likely to read the whole thing. Any other comments about this? I'm not convinced either way, but this is something we should definitely decide before getting into more details about a rearrangement. I can't see a strong argument towards either smaller subsections or larger subsections. Maybe this means that size of the subsections is probably just fine in most cases and that arguments for combining (or splitting) subsections can be handled on a case-by-cases basis as the rest of the chunking takes place? As a first pass, I took a look at chapter 8 Advanced notation, because I've never been very comfortable with the distinction between basic, advanced and contemporary notation in the current structure. So the first suggestions here give a way to remove 8 Advanced notation completely (keeping the content of course!) by redistributing the content to possibly smarter places; I've left 6 Basic notation alone for the moment (though I think a similar pattern of promoting many of the sections of chapter 6 to the status of free-standing chapters will probably make very good sense as we move to a true notation manual): Specifically: - promote section 8.1 Text to the status of a free-standing chapter - combine sections 8.2 Preparing parts and 8.3 Orchestral music and promote the combined content to the status of a free-standing chapter, perhaps called Scores and parts or Working in full score - remove section 8.4 Contemporary music altogether because the contents of Contemporary music fit perfectly in the following other parts of the manual: ~ subsections 8.4.1 Polymetric notation and 8.4.2 Time administration can both go live with the other subsections on rhythm under section 6.2 Rhythms ~ subsection 8.4.3 Proportional notation can be removed completely in favor of subsection 11.6.5 Proportional notation ~ subsections 8.4.4 Clusters and 8.4.5 Special noteheads can become the very last subsections of section 6.1 Pitches ~ subsection 8.4.6 Feathered beams belongs with other rhythmic devices under section 6.2 Rhythms ~ subsection 8.4.7 Improvisation doesn't belong in the manual, imo; seems like a good candidate for LSR ~ subsection 8.4.8 Selecting notation font size; how did this ever wind up here? I don't understand the intent of this section; it talks only about notehead font size (not about font sizes in general), so if we keep it (which seems unnecessary, actually) then it should go to section 6.1 Pitches (I make the preceding recommendation on contemporary notation based on the fact that we've come a *TREMENDOUSLY* far way with contemporary notation in the last major releases and I think that the most professional way to reflect this fact is to un-ghetto-ize the contemporary stuff and just include it -- elegantly and cleanly -- in the other major sections of the manual.) Lastly, to complete the removal / redistribution of chapter 8 ... - promote section 8.5 Educational use to the status of a free-standing chapter (just like Text and Scores and parts, above), perhaps near the very end of the table of contents More suggestions like this or no? -- Trevor Bača [EMAIL PROTECTED] ___ lilypond-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user
Re: GDP: rearrange manual
Trevor Bac(a skrev: As a first pass, I took a look at chapter 8 Advanced notation, because I've never been very comfortable with the distinction between basic, advanced and contemporary notation in the current structure. It seems like your comments are meant to the online 2.11 documentation, and not to the list that Gragam posted in the first message of this thread. Lots of the things you wrote are sort of already there. -Rune ___ lilypond-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user
Re: GDP: rearrange manual
On 09.09.2007 (16:32), Graham Percival wrote:
Well, don't I feel like a complete newbie. :/Does anybody know how to
make Thunderbird treat text like pure bloody text, and not change the
displayed text when it sends an email out? thanks in advance. :(
One of the reasons why I prefer mutt over any other mail handler...
perfect example of the difference between user-friendliness and
*user-friendliness*.
Anyway, I second the suggestions that ...
On 09.09.2007 (18:06), Trevor Bača made:
Specifically:
- promote section 8.1 Text to the status of a free-standing chapter
Definitely. It also belongs together with ...
~ subsection 8.4.8 Selecting notation font size;
... which is relevant, in my experience at least, when you want to
change the size of the whole score and have also made changes to the
pango font tree -- much more so than for changing the size of
individual notes in contemporary notation (then again, I don't write
contemporary scores).
So perhaps a unified section on Fonts and sizes?
I would also say -- although this may exceed the limits of what kind
of suggestions were allowed -- that one thing that is missing is a
comprehensive survey of the syntax of Lilypond. Now, it's all there,
I'm sure, but there is a huge gap between the First Steps section,
giving the beginner just enough information at the time to avoid
overflow, and the Interfaces for Programmers section, which is
intimidating, not only because it's complex, but also because of the
language: one is likely to think: Hey, I'm not a programmer, I hardly
know what 'interface' means -- this section is not for me, which is
wrong, because that chapter contains information that anyone is likely
to need some day if one writes things more advanced than single melody
lines.
In the gap between these two extremes -- which means the rest of the
manual -- I'm sure everything one needs to know can be found, but I'd
welcome a separate section Lilypond syntax, which would briefly but
exactly list and explain the syntax, from the file structure (which
also belongs here) down to typographical requirements (escapes, space
around { } , naming conventions for various types of objects
(Music expressions, GROBs and Contexts with CamelCase, Music classes, music
properties, Grob interfaces, and backend properties use scheme-type,
Engravers: Caps_and_underscores, and Context properties use
lowercaseAndCamelCase).
This would be very helpful, I think.
Eyolf
--
Aliquid melius quam pessimum optimum non est.
___
lilypond-user mailing list
lilypond-user@gnu.org
http://lists.gnu.org/mailman/listinfo/lilypond-user
