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

lilypond texinfo documents.

diff --git a/ChangeLog b/ChangeLog
index 92c4b9c1173746b63b3a6257469c35642733dc7f..586864230e5460282ede0a1cb878829c9afb57d3 100644 (file)
--- 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 24e457745680a806fb8d639f85d80b38fc4fe16e..5603e400aef4128fc98eab5bf99a09f35da9eea4 100644 (file)
--- 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 90296c0352c4d65da9e172f3b5bec75d8c054069..eb2fe604b259b325a1c4ee616f6294d43bca21a1 100644 (file)
--- 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.