Doc-es: pre-merge update of texidoc committishes.

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

diff --git a/Documentation/user/writing-texinfo.txt b/Documentation/user/writing-texinfo.txt
index 901cf5caa3c5c225c19e5bb8e71d997ad62d9c50..8b55e9ab79fb4cc15983116f7016a644621004b8 100644 (file)
--- a/Documentation/user/writing-texinfo.txt
+++ b/Documentation/user/writing-texinfo.txt
@@ -53,21 +53,24 @@ 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]
 
-  Examples about page layout may alter the quote/ragged-right
-  options.  Omitting `verbatim' is not allowed except for special
-  circumstances.
+  If you want to use \layout{} or define variables, use
+    @lilypond[verbatim,quote]
+
+  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
@@ -126,6 +129,11 @@ commands.
 * 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:
@@ -222,9 +230,11 @@ commands.
   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").
+@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