From 09ec70062dd63c5700c1ef318d448c69d9927e65 Mon Sep 17 00:00:00 2001 From: Werner Lemberg Date: Fri, 5 Nov 2004 11:47:19 +0000 Subject: [PATCH] * Documentation/user/lilypond.tely: Add more guidelines for writing lilypond texinfo documents. --- ChangeLog | 7 +- Documentation/user/lilypond.tely | 89 +++++++++++++++++++++++--- Documentation/user/music-glossary.tely | 2 +- 3 files changed, 87 insertions(+), 11 deletions(-) diff --git a/ChangeLog b/ChangeLog index 92c4b9c117..586864230e 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,4 +1,9 @@ -2004-11-05 Heikki Junes +2004-11-05 Werner Lemberg + + * Documentation/user/lilypond.tely: Add more guidelines for writing + lilypond texinfo documents. + +2004-11-05 Heikki Junes * Documentation/index.html.in: remove
. 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. -- 2.39.5