Merge branch 'master' of git://git.sv.gnu.org/lilypond

[lilypond.git] / Documentation / user / writing-texinfo.txt

diff --git a/Documentation/user/writing-texinfo.txt b/Documentation/user/writing-texinfo.txt
index 3379fbf1fc0091dad3a8e24fb34df47a15ecbd77..4c988f754eb83724971cff8d21f78d3121d2771f 100644 (file)
--- a/Documentation/user/writing-texinfo.txt
+++ b/Documentation/user/writing-texinfo.txt
@@ -14,7 +14,7 @@ something, you can cut-and-paste that stuff into a new location.
 
 Most of the manual operates at the
        @node Foo
-       @unnumberedsubsubsec Foo
+       @subsubsection Foo
 level.  Sections are created with
        @node Foo
        @subsection Foo
@@ -29,8 +29,16 @@ commands.
 
 * Use two spaces for indentation in lilypond examples.  (no tabs)
 
+* All text strings should be prefaced with #.  LilyPond does not
+  strictly require this, but it is helpful to get users accustomed
+  to this scheme construct.  ie
+    \set Staff.instrumentName = #"cello"
+
+* Examples should end with a complete bar if possible.
+
 * If possible, only write one bar per line.  The notes on each
-  line should be an independent line.
+  line should be an independent line -- tweaks should occur on
+  their own line if possible.
   Bad:
     \override textscript #'padding = #3 c1^"hi"
   Good:
@@ -49,6 +57,10 @@ commands.
   @lilypondfile[quote,ragged-right,line-width=16\cm,staffsize=16]
   {pitches-headword.ly}
 
+* LSR snippets are linked with
+  @lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
+  {filename.ly}
+
 * Avoid long stretches of input code.  Noone is going to read them
   in print.  Please create a smaller example.  (the smaller
   example does not need to be minimal, however)
@@ -153,6 +165,8 @@ commands.
 %%%%% SYNTAX SURVEY
 
 @c - single line comments
+  "@c NOTE:" is a comment which should remain in the final
+  version.  (gp only command ;)
 @ignore ... @end ignore - multi-line comment
 
 @cindex - General index. Please add as many as you can.  Don't
@@ -194,10 +208,12 @@ commands.
   required.  Any link in a doc section must be duplicated in the
   @seealso section at the bottom.
 
-* Introducing examples may be done with
+* Introducing examples must be done with
      . (ie finish the previous sentence/paragaph)
      : (ie `in this example:')
      , (ie `may add foo with the blah construct,')
+  The old "sentence runs directly into the example" method is not
+  allowed any more.
 
 * Abbrevs in caps, e.g., HTML, DVI, MIDI, etc.
 
@@ -212,10 +228,3 @@ commands.
   this is, don't say `Ba@ss{}tuba' but `Baßtuba'.  This ensures that
   all such characters appear in all output formats.
 
-* Don't use a @ref{link to another section} in the middle of a
-  sentence.  It looks ok in HTML, moderately bad in PDF, and
-  utterly horrible in INFO.  Instead, reword the sentence so that
-  users are encouraged to see @ref{link to another section}.
-  (at the end of the sentence)
-
-