X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Fpolicy.txt;h=80bb6cc8b1096a9783961ddeff49b177233884f1;hb=d1280a8d31c7d6e1ebc8cff7621b87039201d0b2;hp=57acddda6bae062b5537893a76a93be07fc489a3;hpb=f9699ef192963358d63ebfa9a26f9862e0a1a563;p=lilypond.git diff --git a/Documentation/user/policy.txt b/Documentation/user/policy.txt index 57acddda6b..80bb6cc8b1 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. @@ -32,13 +43,13 @@ start-to-finish. 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. +that material in each section of 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, +* 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. @@ -50,12 +61,17 @@ Users are not expected to read this manual from start to finish. 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 +@refcommands @commonprop @seealso @refbugs @@ -63,149 +79,38 @@ main docs * You _must_ include a @seealso. The order of items inside the @seealso section is - Music glossary: @rgloss{foo}, @rgloss{bar}. - - User manual: @ref{baz}, @ref{foozle}. - - Snippets: @lsrdir{section}. - - Program reference: @internalsref{fazzle}, @internalsref{booar}. - - ("Snippets" is REQUIRED; the others are optional) - -* @commonprop and @refbugs are optional. - - -%%%%% 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{}. - - -%%%%% 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.) + Music Glossary: @rglos{foo}, @rglos{bar}. -* Do not use tabs. They expand to nothing in DVI output. + Learning Manual: @rlearning{baz}, @rlearning{foozle} -* 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. + Notation Reference: @ruser{faazle}, @ruser{boo}. -* Use two spaces after a period. + Application Usage: @rprogram{blah}. -* 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: + Installed Files: @file{path/to/dir/blahz}. - The variable@tie{}@var{a} ... + Snippets: @lsrdir{section}, @lsr{specific/example-name.ly}. + (if there is only one entry, omit a final period. If there + are multiple entries, separate them by commas, do not + include an `and', and end with a period.) -* 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 + Internals Reference: @internalsref{fazzle}, @internalsref{booar}. - @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. - @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". + ("Snippets" is REQUIRED; the others are optional) -* @warning{} produces a "Note: " box. Use for important messages. + 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. -%%%%% READABILITY +* Do not include any real info in second-level sections (ie 1.1 + Pitches). A first-level section may have introductory material, + but other than that all material goes into third-level sections + (ie 1.1.1 Writing Pitches). -* 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. @@ -214,14 +119,22 @@ main docs do not bother with the @code{} (they are added automatically). These items are added to both the command index and the unified index. -* 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. + Both index commands should go in front of the actual material. + + @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. + +* 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 %%%%% TECHNICAL WRITING STYLE