Merge branch 'original' into HEAD

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

diff --git a/Documentation/user/writing-texinfo.txt b/Documentation/user/writing-texinfo.txt
index 3379fbf1fc0091dad3a8e24fb34df47a15ecbd77..7913ed0ad76407f366f13ed43d7e14c82b462021 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)
@@ -149,10 +161,25 @@ commands.
 
   Do not use @itemize @bullet.
 
+* To get LilyPond version, use @version{} (this does not work inside
+  LilyPond snippets).  If you write "@version{}" (enclosed with
+  quotes), or generally if @version{} is not followed by a space,
+  enclose it with
+
+  @w{ ... }
+
+  e.g.
+
+  @w{"@version{}"}
+
+  to prevent an ugly line break in PDF output.
+
 
 %%%%% 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 +221,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 +241,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)
-
-