From: gpercival Date: Wed, 26 Apr 2006 12:09:38 +0000 (+0000) Subject: First round of doc reorg. X-Git-Tag: release/2.8.2~9^2~74 X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=2093ef5ce2553195b92c7a81d5413da6fa7cde65;p=lilypond.git First round of doc reorg. README.txt: moved info about style out of lilypond.tely. --- diff --git a/ChangeLog b/ChangeLog index 0c6ae97954..5cd7aba983 100644 --- a/ChangeLog +++ b/ChangeLog @@ -3,6 +3,11 @@ * Documentation/user/instrument-notation.itely: a few more fixes from Eduardo, thanks! + * Documentation/user/README.txt: new file; contains info on + style that used to be in lilypond.tely. + + * Documentation/user/ various: first round of doc reorg. + 2006-04-24 Graham Percival * Documentation/user/instrument-notation.itely: many alterations diff --git a/Documentation/user/README.txt b/Documentation/user/README.txt new file mode 100644 index 0000000000..ffe987da74 --- /dev/null +++ b/Documentation/user/README.txt @@ -0,0 +1,138 @@ +Info for Documentation +---------------------- + +Current version of the manual: 2.8.0 +*** Please update this whenever you run convert-ly on the docs. + +convert-ly --from=... --to=... --no-version *.itely + +%%%%% +Distributions will want to install lilypond.info in postinstall, doing: + + install-info --info-dir=/usr/share/info out/lilypond.info +%%%%% + * Prepend GNU for dir, must be unique. + + * Do not list the `lilypond' node at toplevel, so that `info lilypond' + goes to Top. + + * List all commands in direntry. + +@c * lilypond: (lilypond/lilypond)Running LilyPond. Invoking the +@c LilyPond program. + +%%%%% +HINTS FOR STYLE + +* Do not forget to create @cindex entries for new sections of text. + +* 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. 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. + +* Do not use abbreviations (don't, won't, etc.). If you do, use a + comma after it: + + blabla blabla, i.e., blabla blabla + +* Avoid fluff (``Notice that,'' ``as you can see,'' ``Currently,''). + +* The above three suggestions refer to the formal Notation Manual + (chapters 5 and up). In the Tutorial, Example templates, and + Putting it all together, you may write more colloquially + +* 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. + +* 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. + + 1. To introduce lists + 2. When beginning a quote: "So, he said,..." + 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 utf-8 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. + +%%%%% + + + diff --git a/Documentation/user/lilypond.tely b/Documentation/user/lilypond.tely index b6ce0497da..0e9cefd7a7 100644 --- a/Documentation/user/lilypond.tely +++ b/Documentation/user/lilypond.tely @@ -7,32 +7,6 @@ @dircategory GNU music project @direntry -@ignore -(I think) -Current version of the manual: 2.8.0 -****** Please update this whenever you run convert-ly on the docs. - -convert-ly --from=... --to=... --no-version *.itely - -%%%%% - -Distributions will want to install lilypond.info in postinstall, doing: - - install-info --info-dir=/usr/share/info out/lilypond.info - -%%%%% - - * Prepend GNU for dir, must be unique. - - * Do not list the `lilypond' node at toplevel, so that `info lilypond' - goes to Top. - - * List all commands in direntry. - -@c * lilypond: (lilypond/lilypond)Running LilyPond. Invoking the -@c LilyPond program. - -@end ignore * LilyPond: (lilypond/lilypond). The GNU music typesetter. * abc2ly: (lilypond/lilypond)Invoking abc2ly. Importing ABC. * convert-ly: (lilypond/lilypond)Invoking convert-ly. Older LilyPond versions. @@ -43,6 +17,7 @@ Distributions will want to install lilypond.info in postinstall, doing: @end direntry +@c don't remove this comment. @ignore @omfcreator Han-Wen Nienhuys, Jan Nieuwenhuizen and Graham Percival @omfdescription User manual of the LilyPond music engraving system @@ -51,121 +26,6 @@ Distributions will want to install lilypond.info in postinstall, doing: @omflanguage English @end ignore -@c don't remove this comment. - -@ignore - -HINTS FOR STYLE - -* Do not forget to create @cindex entries for new sections of text. - -* 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. 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. - -* Do not use abbreviations (don't, won't, etc.). If you do, use a - comma after it: - - blabla blabla, i.e., blabla blabla - -* Avoid fluff (``Notice that,'' ``as you can see,'' ``Currently,''). - -* The above three suggestions refer to the formal Notation Manual - (chapters 5 and up). In the Tutorial, Example templates, and - Putting it all together, you may write more colloquially - -* 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. - -* 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. - - 1. To introduce lists - 2. When beginning a quote: "So, he said,..." - 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 utf-8 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 This document is also available in @uref{source/Documentation/user/lilypond.pdf,PDF}. @@ -175,6 +35,7 @@ This document is also available in @uref{source/Documentation/user/lilypond.pdf, @documentlanguage en @documentencoding utf-8 +@c FIXME: Index has two alphabetically sorted lists @code vs plain? @syncodeindex fn cp @syncodeindex ky cp @syncodeindex pg cp @@ -202,21 +63,18 @@ Copyright @copyright{} 1999--2006 by the authors @vskip 20pt -@c Not yet debugged or reported. This crashes gs-8.01: -@c compiling gs-8.01 right now... -- jcn @lilypond[ragged-right] \score { - \context Lyrics { - \override Score.RehearsalMark #'self-alignment-X = #LEFT - \override Score.RehearsalMark #'font-size = #-2 - \mark #(ly:export (string-append - "(For LilyPond version " (lilypond-version) ")")) - s2 - } - \layout { - indent = 0.0\pt - ragged-right = ##t - } + \context Lyrics { + \override Score.RehearsalMark #'self-alignment-X = #LEFT + \override Score.RehearsalMark #'font-size = #-2 + \mark #(ly:export (string-append + "(For LilyPond version " (lilypond-version) ")")) + s2 + } + \layout { + indent = 0.0\pt + } } @end lilypond @@ -258,26 +116,37 @@ of this and other documentation. @include dedication.itely @menu +Learning manual / User manual / FIXME title + * Preface:: Preface. * Introduction:: What, Why, How. * Tutorial:: A tutorial introduction. -* Example templates:: Larger examples. * Working on LilyPond projects:: Demonstrates real-life LilyPond usage. -* Running LilyPond:: Operation. +* space1:: temporary filler chapter +* space2:: ditto. Hey, this is the unstable branch! :) + +Notation reference + * Basic notation:: Standard musical notation. * Instrument-specific notation:: Notation that is only used for some instruments. * Advanced notation:: Less frequently used notation. * Changing defaults:: Tuning output. * Global issues:: What LilyPond produces. - * Interfaces for programmers:: + +Technical details + +* Running LilyPond:: Operation. * LilyPond-book:: Integrating text and music. * Converting from other formats:: Converting to lilypond source format. + +Appendices + * Literature list:: * Scheme tutorial:: * Notation manual details:: -* Point and click:: +* Example templates:: Larger examples. * Cheat sheet:: * GNU Free Documentation License:: FDL. * LilyPond index:: @@ -291,27 +160,30 @@ of this and other documentation. @include preface.itely @include introduction.itely @include tutorial.itely -@include examples.itely @include putting.itely -@include invoking.itely +@node space1 +@chapter space1 +@node space2 +@chapter space2 + @include basic-notation.itely @include instrument-notation.itely @include advanced-notation.itely @include changing-defaults.itely @include global.itely - @include programming-interface.itely + +@include invoking.itely @include lilypond-book.itely @include converters.itely -@c FIXME: Index has two alphabetically sorted lists @code vs plain? @include literature.itely @include scheme-tutorial.itely @include notation-appendices.itely -@include point-and-click.itely +@include examples.itely @include cheatsheet.itely @include fdl.itexi