X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Fpolicy.txt;h=b4436a9085837cbb2c6a948fd9415b62165dcff0;hb=8902c91b10ba8afabeb4112e6681a99c028cce61;hp=98010e43a7dfbb7cd73fcc48b534796d6d226de4;hpb=881ad8de0492c010abc98e748c5c139486f1ae54;p=lilypond.git diff --git a/Documentation/user/policy.txt b/Documentation/user/policy.txt index 98010e43a7..b4436a9085 100644 --- a/Documentation/user/policy.txt +++ b/Documentation/user/policy.txt @@ -8,11 +8,22 @@ There are four parts to the documentation: the Learning Manual, the Notation Reference, the Program Reference, and the Music Glossary. -* 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. +* Learning Manual: + The LM is written in a tutorial style which introduces the most + important concepts, structure and syntax of the elements of a + LilyPond score in a carefully graded sequence of steps. + Explanations of all musical concepts used in the Manual can be + found in the Music Glossary, and readers are assumed to have no + prior knowledge of LilyPond. The objective is to take readers to + a level where the Notation Reference can be understood and + employed to both adapt the templates in the Appendix to their + needs and to begin to construct their own scores. Commonly used + tweaks are introduced and explained. Examples are provided + throughout which, while being focussed on the topic being + introduced, are long enough to seem real in order to retain the + readers' interest. Each example builds on the previous material, + and comments are used liberally. Every new aspect is thoroughly + explained before it is used. Users are encouraged to read the complete Learning Manual from start-to-finish. @@ -20,25 +31,34 @@ 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 "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. - -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. Also, you should assume that users -know what the notation means; explaining musical concepts happens -in the Music Glossary. - - -* Program Usage: information about using the program lilypond with - other programs (lilypond-book, operating systems, GUIs, + duplicated in the Learning Manual (for teaching), but consider + the NR to be the "definitive" description of each notation + element, with the LM being an "extra". The goal is _not_ to + provide a step-by-step learning environment -- do not avoid + using notation that has not be introduced previously in the + NR (for example, use \break if appropriate). This section is + written in formal technical writing style. + +Avoid duplication. Although users are not expected to read this +manual from start to finish, they should be familiar with the +material in the Learning Manual (particularly ``Fundamental +Concepts''), so do not repeat that material in each section of +this book. Also watch out for common constructs, like ^ - _ for +directions -- those are explained in NR 3. In NR 1, you can +write: +DYNAMICS may be manually placed above or below the +staff, see @ref{Controlling direction and placement}. + +Most tweaks should be added to LSR and not placed directly in the +.itely file. In some cases, tweaks may be placed in the main +text, but ask about this first. + +Finally, you should assume that users know what the notation +means; explaining musical concepts happens in the Music Glossary. + + +* Application 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. @@ -46,41 +66,70 @@ Users are not expected to read this manual from start to finish. * Music Glossary: information about the music notation itself. - Explainations and translations about notation terms go here. + Explanations and translations about notation terms go here. Users are not expected to read this manual from start to finish. +* Internals Reference: not really a documentation book, since it + is automagically generated from the source, but this is its + name. + %%%%% SECTION ORGANIZATION The order of headings inside documentation sections should be: main docs -@commonprop +@predefined +@snippets @seealso -@refbugs +@knownissues * You _must_ include a @seealso. The order of items inside the @seealso section is - Music glossary: @rglos{foo}, @rglos{bar}. + Music Glossary: + @rglos{foo}, + @rglos{bar}. + + Learning Manual: + @rlearning{baz}, + @rlearning{foozle}. + + Notation Reference: + @ruser{faazle}, + @ruser{boo}. - Learning Manual: @rlearning{baz}, @rlearning{foozle} + Application Usage: + @rprogram{blah}. - Notation Reference: @ruser{faazle}, @ruser{boo}. + Installed Files: + @file{path/to/dir/blahz}. - Snippets: @lsrdir{section}, @lsr{specific/example-name.ly} + Snippets: @rlsr{section}. - Program reference: @internalsref{fazzle}, @internalsref{booar}. + Internals Reference: + @rinternals{fazzle}, + @rinternals{booar}. - Installed files: @file{blahz}. + If there are multiple entries, separate them by commas + but do not include an `and'. + + Always end with a period. + + Place each link on a new line as above; this makes it much + easier to add or remove links. In the output, they + appear on a single line. ("Snippets" is REQUIRED; the others are optional) + Any new concepts or links which require an explanation should go + as a full sentence(s) in the main text. + * To create links, use @ref{} if the link is within the same manual. -* @commonprop and @refbugs are optional. +* @predefined is for commands in ly/*-init.ly FIXME? * Do not include any real info in second-level sections (ie 1.1 Pitches). A first-level section may have introductory material, @@ -88,172 +137,21 @@ main docs (ie 1.1.1 Writing Pitches). -%%%%% LILYPOND FORMATTING - -* Use two spaces for indentation in lilypond examples. (no tabs) - -* If possible, only write one bar per line. The notes on each - line should be an independent line. - Bad: - \override textscript #'padding = #3 c1^"hi" - Good: - \override textscript #'padding = #3 - c1^"hi" - -* 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 allowed. - -* Inspirational headwords are produced with - @lilypondfile[ragged-right,line-width=16\cm,staffsize=16,quote] - {pitches-headword.ly} - -* Avoid long stretches of input code. Noone is going to read them - in print. Instead refer to an example input file with @lsr{}. - -* If you want to work on an example outside of the manual (for - easier/faster processing), use this header: - -\paper { - #(define dump-extents #t) - indent = 0\mm - line-width = 160\mm - 2.0 * 0.4\in - ragged-right = ##t - force-assignment = #"" - line-width = #(- line-width (* mm 3.000000)) -} - -\layout { -} - - You may not change any of these values. If you are making an - example demonstrating special \paper{} values, contact the - Documentation Editor. - - -%%%%% TEXT FORMATTING - -* Lines should be less than 72 characters long. (I personally - recommend writing with 66-char lines, but don't bother modifying - existing material.) - -* 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. - -* Use two spaces after a period. - -* 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: +%%%%% CHECKING CROSS-REFERENCES - The variable@tie{}@var{a} ... +Cross-references between different manuals are heavily used in the +documentation, but they are not checked during compilation. However, +if you compile the documentation, a script called check_texi_refs can +help you with checking and fixing these cross-references; for +information on usage, cd into a source tree where documentation has +been built, cd into Documentation and look for check-xrefs and +fix-xrefs targets in 'make help' output. Note that you have to find +yourself the source files to fix cross-references in the generated +documentation such as the Internals Reference; e.g. you can grep +scm/ and lily/. -* 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). - -* 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 avoid forgetting the `@noindent'. Only - use @noindent if the material is discussing the same material; - new material should simply begin without anything special on the - line above it. - -* in @itemize use @item on a separate line like this: - @itemize - @item - Foo - - @item - Bar - - Do not use @itemize @bullet. - -* Specially-marked text: - - @code{}: actual lilypond code or property/context names. - @samp{}: ditto, for single-letter code. - - - ** Any `\' used inside the commands below must be ** - ** written as `\\'. Even if they are inside a @code{}. ** - ( this should only affect @warning{} ) - - @notation{}: refers to pieces of notation, such as - "@notation{crescendo} is often abbreviated as - @notation{cresc.}" This should also be used to refer to - specific lyrics ("the @notation{A - men} is centered...") - @q{}: used for `vague' terms in English (and other natural - languages). - @qq{}: only for actual quotes -- i.e. "he said" or "she - wrote". - @warning{}: produces a "Note: " box. Use for important - messages. - -* References must occur at the end of a sentence, for more - information see @ref{the texinfo manual}. Ideally this should - also be the final sentence of a paragraph, but this is not - required. Any link in a doc section must be duplicated in the - @seealso section at the bottom. - -* Introducing examples may be done with - . (ie finish the previous sentence/paragaph) - : (ie `in this example:') - , (ie `may add foo with the blah construct,') - - -%%%%% READABILITY - -* 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. - -* 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) +%%%%% GENERAL WRITING * Do not forget to create @cindex entries for new sections of text. Enter commands with @funindex, i.e. @@ -264,14 +162,26 @@ main docs Both index commands should go in front of the actual material. -* Abbrevs in caps, e.g., HTML, DVI, MIDI, etc. + @cindex entries should not be capitalized, ie + @cindex time signature + is preferred. (instead of `Time signature') Only use capital + letters for musical terms which demand them, like D.S. al Fine. -* Colon usage + For scheme functions, only include the final part, ie + @funindex modern-voice-cautionary + and NOT + @funindex #(set-accidental-style modern-voice-cautionary) - 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. +* Preferred terms: + - in general, use the American spellings. The internal + lilypond property names use this spelling. + - list of specific terms: +canceled +simultaenous NOT concurrent +measure: the unit of music +bar line: the symbol delimiting a measure NOT barline +note head NOT notehead +chord construct NOT chord (when referring to <>) %%%%% TECHNICAL WRITING STYLE @@ -297,9 +207,4 @@ main docs Say `invalid' instead. -FOR DOC EDITOR ONLY - -* sectioning commands (@node and @section) must not appear inside - an @ignore. Separate those commands with a space, ie @n ode. -