X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Fwriting-texinfo.txt;h=8b55e9ab79fb4cc15983116f7016a644621004b8;hb=edf17353d89f4f6bd831466262402bb9151a26ca;hp=7913ed0ad76407f366f13ed43d7e14c82b462021;hpb=c6bd020ed6dfc2c197d195541be8ff60129ccbce;p=lilypond.git

diff --git a/Documentation/user/writing-texinfo.txt b/Documentation/user/writing-texinfo.txt
index 7913ed0ad7..8b55e9ab79 100644
--- a/Documentation/user/writing-texinfo.txt
+++ b/Documentation/user/writing-texinfo.txt
@@ -20,6 +20,9 @@ level.  Sections are created with
 	@subsection Foo
 commands.
 
+* Please leave two blank lines above a @node; this makes it easier
+  to find sections in texinfo.
+
 * sectioning commands (@node and @section) must not appear inside
   an @ignore.  Separate those commands with a space, ie @n ode.
 
@@ -34,6 +37,11 @@ commands.
   to this scheme construct.  ie
     \set Staff.instrumentName = #"cello"
 
+* All engravers should have double-quotes around them:
+    \consists "Spans_arpeggio_engraver"
+  Again, LilyPond does not strictly require this, but it is a
+  useful standard to follow.
+
 * Examples should end with a complete bar if possible.
 
 * If possible, only write one bar per line.  The notes on each
@@ -45,26 +53,44 @@ commands.
     \override textscript #'padding = #3
     c1^"hi"
 
-* LilyPond input should be produced via
-    @lilypond[verbatim,quote,ragged-right]
-  with `fragment' and `relative=2' optional.
+* Most LilyPond input should be produced with:
+    @lilypond[verbatim,quote,relative=2]
+  or
+    @lilypond[verbatim,quote,relative=1]
+
+  If you want to use \layout{} or define variables, use
+    @lilypond[verbatim,quote]
 
-  Examples about page layout may alter the quote/ragged-right
-  options.  Omitting `verbatim' is not allowed except for special
-  circumstances.
+  In rare cases, other options may be used (or omitted), but ask first.
 
 * Inspirational headwords are produced with
   @lilypondfile[quote,ragged-right,line-width=16\cm,staffsize=16]
   {pitches-headword.ly}
 
 * LSR snippets are linked with
-  @lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
+  @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
   {filename.ly}
+  excepted in Templates, where `doctitle' may be omitted.
 
 * 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)
 
+* Specify durations for at least the first note of every bar.
+
+* If possible, end with a complete bar.
+
+* Comments should go on their own line, and be placed before the
+  line(s) to which they refer.
+
+* Add extra spaces around { } marks; ie
+  not:          \chordmode {c e g}
+  but instead:  \chordmode { c e g }
+
+* If you only have one bar per line, omit bar checks.  If you
+  put more than one bar per line (not recommended), then include
+  bar checks.
+
 * If you want to work on an example outside of the manual (for
   easier/faster processing), use this header:
 
@@ -100,6 +126,14 @@ commands.
 
 * Use two spaces after a period.
 
+* In examples of syntax, use @var{musicexpr} for a music
+  expression.
+
+* Don't use @rinternals{} in the main text.  If you're tempted to
+  do so, you're probably getting too close to "talking through the
+  code".  If you really want to refer to a context, use @code{} in
+  the main text and @rinternals{} in the @seealso.
+
 * Variables or numbers which consist of a single character
   (probably followed by a punctuation mark) should be tied
   properly, either to the previous or the next word.  Example:
@@ -192,15 +226,15 @@ commands.
   Do not compress vertically like this.
 
 @code{} - typeset in a tt-font. Use for actual lilypond code or
-  property/context names.
+  property/context names.  If the name contains a space, wrap
+  the entire thing inside @w{@code{  }}.
 @notation{} - refers to pieces of notation, e.g.
   "@notation{cres.}".  Also use to specific lyrics ("the
-  @notation{A - men} is centered")
+  @notation{A - men} is centered").  Only use once per subsection
+  per term.
 @q{} - Single quotes. Used for `vague' terms.
-@qq{} - Double quotes.  Used for actual quotes ("he said").
-
-@warning{}: produces a "Note: " box.  Use for important
-      messages.
+@qq{} - Double quotes.  Used for actual quotes ("he said") or for
+  introducing special input modes.
 
 @tie{} - Variables or numbers which consist of a single character
   (probably followed by a punctuation mark) should be tied
@@ -208,8 +242,11 @@ commands.
     "The letter@tie{}@q{I} is skipped"
 
 @var - Use for variables.
-@warning{} - produces a "Note: " box.
-  Any `\' used inside this must be written as `\\'.
+@warning{} - produces a "Note: " box. Use for important messages.
+
+@bs - Generates a backslash inside @warning.
+    Any `\' used inside @warning (and @q or @qq) must be written as `@bs{}' 
+    (texinfo would also allow \\, but this breaks with PDF output).