From: Werner Lemberg <wl@gnu.org>
Date: Fri, 5 Nov 2004 11:47:19 +0000 (+0000)
Subject: * Documentation/user/lilypond.tely: Add more guidelines for writing
X-Git-Tag: release/2.4.2~3^2~11
X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=09ec70062dd63c5700c1ef318d448c69d9927e65;p=lilypond.git

* Documentation/user/lilypond.tely: Add more guidelines for writing
lilypond texinfo documents.
---

diff --git a/ChangeLog b/ChangeLog
index 92c4b9c117..586864230e 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,4 +1,9 @@
-2004-11-05  Heikki Junes <hjunes@cc.hut.fi>
+2004-11-05  Werner Lemberg  <wl@gnu.org>
+
+	* Documentation/user/lilypond.tely: Add more guidelines for writing
+	lilypond texinfo documents.
+
+2004-11-05  Heikki Junes  <hjunes@cc.hut.fi>
 
 	* Documentation/index.html.in: remove <hr>.
 
diff --git a/Documentation/user/lilypond.tely b/Documentation/user/lilypond.tely
index 24e4577456..5603e400ae 100644
--- a/Documentation/user/lilypond.tely
+++ b/Documentation/user/lilypond.tely
@@ -45,28 +45,36 @@ HINTS FOR STYLE
 
 * Do not forget to create @cindex entries for new sections of text.
 
-* Try not to use punctuation between introductocing sentence and
-display material (verbatim, music, example code).
+* Try not to use punctuation between an introductory sentence and
+  display material (music, example code).
 
 * Do not refer to LilyPond in the text.  The reader knows what the
-manual is about.
+  manual is about.  If you do, capitalization is LilyPond.
 
-* If you do, capitalization is LilyPond.
+* If you explicitly refer to `lilypond', the program (or any other
+  command to be executed), say `@command{lilypond}'.
 
 * Do not explicitly refer to the reader/user.  There is no one else
-besides the reader and the writer.
+  besides the reader and the writer.
 
-* Do not use abbreviations (don't, won't, etc.).
+* Do not use abbreviations (don't, won't, etc.).  If you do, use a
+  comma after it:
 
-* Avoid fluff (``Notice that,'' ``as you can see,'' ``Currently,'') 
+    blabla blabla, i.e., blabla blabla
+
+* Avoid fluff (``Notice that,'' ``as you can see,'' ``Currently,'').
+
+* The use of the word `illegal' is inappropriate in most cases.  Say
+  `invalid' instead.
 
 * Avoid long stretches of input code.  Noone is going to read them in
-print.  Instead refer to an example input file (@inputfileref), these
-are clickable in HTML.
+  print.  Instead refer to an example input file (@inputfileref), these
+  are clickable in HTML.
 
 * Abbrevs in caps, e.g., HTML, DVI, MIDI, etc.
 
 * Colon usage
+
   0. Do not use a colon to introduce examples, sentences just continue
 
       in the display material.
@@ -76,6 +84,69 @@ are clickable in HTML.
      This usage is rarer.  Americans often just use a comma.
   3. When adding a defining example at the end of a sentence.
 
+* To produce good looking texinfo output (for both TTY and DVI) some
+  additional formatting rules should be followed.
+
+  . Do not use tabs.  They expand to nothing in DVI output.
+
+  . Do not use spaces at the beginning of a line (except in @example
+    or @verbatim environments), and do not use more than a single space
+    between words.  `makeinfo' copies the input lines verbatim without
+    removing those spaces.
+
+  . 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:
+
+      The variable@tie{}@var{a} ...
+
+  . To get consistent indentation in the DVI output it is better to avoid
+    the @verbatim environment.  Use the @example environment instead if
+    possible, but without extraneous indentation.  For example, this
+
+      @example
+        foo {
+          bar
+        }
+      @end example
+
+    should be replaced with
+
+      @example
+      foo {
+        bar
+      }
+      @end example
+
+    where `@example' starts the line (without leading spaces).
+
+  . Use the `quote' option in @lilypond commands if possible.
+
+  . Do not compress the input vertically; this is, do not use
+
+      Beginning of logical unit
+      @example
+      ...
+      @end example
+      continuation of logical unit
+
+    but
+
+      Beginning of logical unit
+
+      @example
+      ...
+      @end example
+
+      @noindent
+      continuation of logical unit
+
+    This makes it easier to not forget `@noindent'.
+
+  . Non-ASCII characters which are in latin-1 should be directly used;
+    this is, don't say `Ba@ss{}tuba' but `Baßtuba'.  This ensures that
+    all such characters appear in all output formats.
+
 @end ignore
 
 @ifhtml
diff --git a/Documentation/user/music-glossary.tely b/Documentation/user/music-glossary.tely
index 90296c0352..eb2fe604b2 100644
--- a/Documentation/user/music-glossary.tely
+++ b/Documentation/user/music-glossary.tely
@@ -459,7 +459,7 @@ S: handskrift,
 FI: käsinkirjoitettu nuotti.
 
 1.@tie{}A manuscript in the composer's own hand.
-2.@tie{} Music prepared for photoreproduction by freehand drawing,
+2.@tie{}Music prepared for photoreproduction by freehand drawing,
 with the aid of a straightedge ruler and T-square only,
 which attempts to emulate engraving.
 This required more skill than did engraving.