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 11f49990c59221dfe1f27ad9d172ddcdac421d15..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:
@@ -153,6 +161,19 @@ 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
 
@@ -200,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.
 
@@ -218,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)
-
-