X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2FREADME.txt;h=0c70368a90beea7e140c994f046fb0bba7641031;hb=cd4dd66b3c24a96415a065852c300ebb47e76013;hp=ba2f98793ac3cb7068cdb767c7d8dd2d505cc4d8;hpb=4be843d96b1e76fda2755118f6f804d6397c5f79;p=lilypond.git diff --git a/Documentation/user/README.txt b/Documentation/user/README.txt index ba2f98793a..0c70368a90 100644 --- a/Documentation/user/README.txt +++ b/Documentation/user/README.txt @@ -1,155 +1,212 @@ Info for Documentation ---------------------- -Current version of the manual: 2.9.13 -*** Please update this whenever you run convert-ly on the docs. +%%%%% UPDATING DOCS +convert-ly -e --from=... --to=... --no-version *.itely -convert-ly --from=... --to=... --no-version *.itely - -%%%%% -DOC ORGANIZATION +% to find the current version number, +grep "version \"" tutorial.itely + +% (nobody ever remembers to update this file, so I've stopped +% trying to record it here) + + +%%%%% BOOKS There are three parts to the documentation: the Learning Manual, the Notation Reference, and the Technical Details. -* Long, wordy, chatty explanations go in the Learning Manual. -This is aimed at users learning something for the first -time -- not necessarily just learning lilypond notation, but -also things like learning how to deal with projects, tweaking, -preparing parts for orchestras, etc. Less formal language -may be used here. +* Learning Manual: long, chatty, friendly explanations go here. +This is aimed at users learning something for the first time -- +not necessarily just learning lilypond notation, but also things +like learning how to deal with projects, tweaking, preparing parts +for orchestras, etc. Less formal language may be used here. -* Notation Reference is a (hopefully complete) description of +Users are encouraged to read the complete Learning Manual from +start-to-finish. + + +* Notation Reference: a (hopefully complete) description of LilyPond input notation. Some material from here may be -duplicated in the Learning Manual (for teaching). The -material is presented in an approximate order of increasing -difficulty, but the goal is _not_ to provide a step-by-step -learning environment. For example, all material under -"Notes" should remain in that section, even though microtonal -accidentals may seem more advanced than info about clefs or -time signatures -- "Notes" should be a one-stop reference -about, well, notes. This section is written in formal -technical writing style. +duplicated in the Learning Manual (for teaching). The material is +presented in an approximate order of increasing difficulty, but +the goal is _not_ to provide a step-by-step learning environment. +For example, all material under "Pitches" should remain in that +section, even though microtonal accidentals may seem more advanced +than info about clefs or time signatures -- "Pitches" should be a +one-stop reference about the pitch portion of notes. This section +is written in formal technical writing style. -* Technical Details contains information about using -the program lilypond with other programs (lilypond-book, -operating systems, GUIs, convert-ly, etc). This section -is writtin in formal technical writing style. +Users are not expected to read this manual from start to finish. +However, they should be familiar with the material in the Learning +Manual (particularly ``Fundamental Concepts''), so do not repeat +that material in this book. -%%%%% -GENERAL GUIDELINES +* Program Usage: information about using the program lilypond with +other programs (lilypond-book, operating systems, GUIs, +convert-ly, etc). This section is written in formal technical +writing style. -* Do not forget to create @cindex entries for new sections of text. - Enter commands with @funindex, i.e. - @funindex \relative - do not bother with the @code{} (they are added automatically). These - items are added to both the command index and the unified index. +Users are not expected to read this manual from start to finish. -* 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. +%%%%% SECTION ORGANIZATION -* Abbrevs in caps, e.g., HTML, DVI, MIDI, etc. +The order of headings inside documentation sections should be: -* Colon usage +main docs +@refcommands +@commonprop +@seealso +@refbugs - 0. Do not use a colon to introduce examples, sentences just continue +(omit any headings which do not apply) - in the display material. +Including at least one link to @lsrdir{} inside @seealso is +highly recommended. - 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. +%%%%% FORMATTING - . Do not use tabs. They expand to nothing in DVI output. +* Use two spaces for indentation in lilypond examples. - . 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. +* Do not use tabs. They expand to nothing in DVI output. - . Use two spaces after a priod. +* 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: +* Use two spaces after a period. - The variable@tie{}@var{a} ... +* Don't use a @ref{link to another section} in the middle of a + sentence. It looks ok in HTML, moderately bad in PDF, and + utterly horrible in INFO. Instead, reword the sentence so that + users are encouraged to see @ref{link to another section}. + (at the end of the sentence) - . 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 +* 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: - @example - foo { - bar - } - @end example + The variable@tie{}@var{a} ... - should be replaced with +* 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 + @example foo { bar } - @end example + @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 - where `@example' starts the line (without leading spaces). + Beginning of logical unit + @example + ... + @end example + continuation of logical unit - . Use the `quote' option in @lilypond commands if possible. + but - . Do not compress the input vertically; this is, do not use + Beginning of logical unit - Beginning of logical unit - @example - ... - @end example - continuation of logical unit + @example + ... + @end example - but + @noindent + continuation of logical unit - Beginning of logical unit + This makes it easier to avoid forgetting the `@noindent'. - @example - ... - @end example +* 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. - @noindent - continuation of logical unit +* Lines should be less than 72 characters long. (I personally + recommend writing with 66-char lines, but don't bother modifying + existing material.) - This makes it easier to not forget `@noindent'. +* Use @q instead of `...' and @qq instead of ``...''. The latter macro + should be used with care since we use `...' as the default quoting + throughout the manual, except for things related to direct speech. - . 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. + Warning: @q{} and @qq{} *MUST NOT* come at the end or beginning + of a line (unless it begins the paragraph). If these macros + @qq{appear like this}, then they will being a new paragraph. -* Lines should be less than 80 characters long. + In most cases, you should use @code{} or @samp{} instead. -%%%%% -HINTS FOR TECHNICAL WRITING STYLE +%%%%% READABILITY + +* LilyPond input should be produce via + @lilypond[verbatim,quote,ragged-right] + with `fragment' and `relative=2' optional. + + Examples about page layout may alter the quote/ragged-right + options. Omitting `verbatim' is not recommended (other than the + ``inspirational headword'' examples) + +* Do not forget to create @cindex entries for new sections of text. + Enter commands with @funindex, i.e. + @cindex pitches, writing in different octaves + @funindex \relative + do not bother with the @code{} (they are added automatically). These + items are added to both the command index and the unified index. + +* Avoid long stretches of input code. Noone is going to read them in + print. Instead refer to an example input file (with @lsr{}); these + are clickable in HTML. + +* Abbrevs in caps, e.g., HTML, DVI, MIDI, etc. + +* Colon usage + + 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. + + +%%%%% HINTS FOR TECHNICAL WRITING STYLE * 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 +* 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 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,''). +* Avoid fluff (``Notice that,'' ``as you can see,'' + ``Currently,''). + +* The use of the word `illegal' is inappropriate in most cases. + Say `invalid' instead. + +