Misc small updates.

diff --git a/Documentation/user/pitches.itely b/Documentation/user/pitches.itely
index eed1e096461c5fd2fc6941432574d5e485ae97be..8f8d5338c61326dedd97d0ac272bd3fb270f2b11 100644 (file)
--- 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 80bb6cc8b1096a9783961ddeff49b177233884f1..481394249972e99f936dffd7f963e70e4017a89f 100644 (file)
--- 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 (file)
index 0000000..c430658
--- /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.
+
+
+