From 9ce3433c133f2546f784bf45e16346836e9a7878 Mon Sep 17 00:00:00 2001 From: Graham Percival Date: Sun, 3 Feb 2008 19:38:36 -0800 Subject: [PATCH] Misc small updates. --- Documentation/user/pitches.itely | 7 +- Documentation/user/policy.txt | 38 +++++---- Documentation/user/writing-sections.txt | 104 ++++++++++++++++++++++++ 3 files changed, 131 insertions(+), 18 deletions(-) create mode 100644 Documentation/user/writing-sections.txt diff --git a/Documentation/user/pitches.itely b/Documentation/user/pitches.itely index eed1e09646..8f8d5338c6 100644 --- a/Documentation/user/pitches.itely +++ b/Documentation/user/pitches.itely @@ -700,13 +700,14 @@ By adding @code{_8} or @code{^8} to the clef name, the clef is transposed one octave down or up, respectively, and @code{_15} and @code{^15} transposes by two octaves. The argument @var{clefname} must be enclosed in quotes when it contains underscores or digits. -For example, @cindex choral tenor clef @lilypond[verbatim,quote,ragged-right,fragment,relative=1] -\clef "treble_8" c1 -\clef "bass^15" c1 +\clef "treble_8" +c2 c +\clef "bass^15" +c2 c @end lilypond diff --git a/Documentation/user/policy.txt b/Documentation/user/policy.txt index 80bb6cc8b1..4813942499 100644 --- a/Documentation/user/policy.txt +++ b/Documentation/user/policy.txt @@ -31,21 +31,29 @@ start-to-finish. * Notation Reference: a (hopefully complete) description of LilyPond input notation. Some material from here may be - duplicated in the Learning Manual (for teaching). The material is - presented in an approximate order of increasing difficulty, but - the goal is _not_ to provide a step-by-step learning environment. - For example, all material under "Pitches" should remain in that - section, even though microtonal accidentals may seem more advanced - than info about clefs or time signatures -- "Pitches" should be a - one-stop reference about the pitch portion of notes. This section - is written in formal technical writing style. - -Users are not expected to read this manual from start to finish. -However, they should be familiar with the material in the Learning -Manual (particularly ``Fundamental Concepts''), so do not repeat -that material in each section of this book. Also, you should -assume that users know what the notation means; explaining musical -concepts happens in the Music Glossary. + duplicated in the Learning Manual (for teaching), but consider + the NR to be the "definitive" description of each notation + element, with the LM being an "extra". The goal is _not_ to + provide a step-by-step learning environment -- do not avoid + using notation that has not be introduced previously in the + NR (for example, use \break if appropriate). This section is + written in formal technical writing style. + +Avoid duplication. Although users are not expected to read this +manual from start to finish, they should be familiar with the +material in the Learning Manual (particularly ``Fundamental +Concepts''), so do not repeat that material in each section of +this book. Also watch out for common constructs, like ^ - _ for +directions -- those are explained in NR 3. In NR 1, you can +mention that "dynamics (or whatever) may be placed above or below +the staff, for details see @ref{Up and down}". + +Most tweaks should be added to LSR and not placed directly in the +.itely file. In some cases, tweaks may be placed in the main +text, but ask about this first. + +Finally, you should assume that users know what the notation +means; explaining musical concepts happens in the Music Glossary. * Application Usage: information about using the program lilypond diff --git a/Documentation/user/writing-sections.txt b/Documentation/user/writing-sections.txt new file mode 100644 index 0000000000..c43065819a --- /dev/null +++ b/Documentation/user/writing-sections.txt @@ -0,0 +1,104 @@ +CHECKLIST FOR DOC SECTION REWRITES + +You've volunteered (or are considering volunteering) to edit a +section of the NR. Congratulations! You'll learn a lot about +this part of lilypond. You'll also get thoroughly fed up with +documentation work, and especially with me... but as they say, +"you can't make an omelett without breaking a few eggs". Welcome +to egg-hood! + +REQUIRED READING + +- policy.txt +- writing-texinfo.txt +- this document :) +- NR 1.1 Pitches. Ideally, read it in your favorite output format + (either info, PDF, or HTML), *and* in source format + (pitches.itely). This is our "demonstration" chapter, so the + below points really just boil down to "make it like + pitches.itely". + + +WORKING + +I recommend working on one subsection at a time. For each +subsection, +- check the mundane formatting. Are the headings (@refcommands, + @seealso, etc) in the right order? +- check the links in the @seealso section -- links to music + glossary, internal references, and other NR sections are the + main concern. +- move LSR-worthy material into LSR. Add the snippet (or + just send it to Valentin for adding), delete the material from + the .itely file, and add a @lilypondfile command. + +- check the examples and descriptions. Do they still work? + *Do not* assume that the existing text is accurate/complete; + some of the manual is highly out of date. +- is the material in the @refbugs still accurate? +- can the examples be improved (made more explanatory), or is + there any missing info? (feel free to ask specific questions + on -user; a couple of people claimed to be interesting in being + "consultants" who would help with such questions) + +In general, I favor short text explanations with good examples -- +"an example is worth a thousand words". When I worked on the +docs, I spent about half my time just working on those tiny +lilypond examples. Making easily-understandable examples is much +harder than it looks. + + +TWEAKS + +In general, any \set or \override commands should go in the +"select snippets" section, which means that they should go in LSR +and not the .itely file. For some cases, the command obviously +belongs in the "main text" (ie not inside @refcommands or @seealso +or whatever) -- instrument names are a good example of this. + \set Staff.instrumentName = #"foo" +On the other side of this, + \override Score.Hairpin #'after-line-breaking = ##t +clearly belongs in LSR. + +I'm quite willing to discuss specific cases if you think that a +tweaks needs to be in the main text. But items that can go into +LSR are easier to maintain, so I'd like to move as much as +possible into there. + + +It would be "nice" if you spent a lot of time crafting nice tweaks +for users... but my recommendation is *not* to do this. There's a +lot of doc work to do without adding examples of tweaks. Tweak +examples are trivial to add later -- they could be made by normal +users, or by you after GDP is over. + +Basically, it's not something that needs to be done while I'm +around. Remember that I'm gone in August at the latest; there's a +*lot* of doc work that should be done before then. I strongly +recommend that you save all the tweaks until later. + + +FINAL + +- when you think you're finished, let me know. I'll spend a few + minutes and send you a list of mistakes to fix. + (there's a *lot* of details to cover; we'll probably spend a + week going back and forth like this. See earlier warning about + hating me by the time you're done with a doc section :) +- I'll ask people on -user to review the Snippet list at this + time; correcting things on the Snippet list is much easier than + getting comments on the integrated snippets. +- when we're both satisfied with the section, we'll invite + comments from -user. Judging from my experience with Pitches, + it will take between three and five weeks to keep on revising + the "final" version. + +I personally found it quite frustrating to still be fixing +problems in a doc section which I thought was "perfect" a whole +bloody *month* ago. Don't get me wrong; it's great that we get so +many comments from -user. :) But just be aware that when you +think you're finally done with a section, you're actually only +halfway there. + + + -- 2.39.5