From: Graham Percival Date: Sun, 7 Oct 2007 23:03:45 +0000 (-0700) Subject: Update policy. X-Git-Tag: release/2.11.35-1~46^2~63 X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=f46ef55979a0f3eabb877f7405376d5ee9192331;p=lilypond.git Update policy. --- diff --git a/Documentation/user/README.txt b/Documentation/user/README.txt index 0f787e9301..80c9f92c16 100644 --- a/Documentation/user/README.txt +++ b/Documentation/user/README.txt @@ -1,226 +1,9 @@ Info for Documentation ---------------------- -%%%%% BOOKS +%%%%% GENERAL POLICY -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. - -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 "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, - convert-ly, etc). This section is written in formal technical - writing style. - -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. - -Users are not expected to read this manual from start to finish. - - -%%%%% SECTION ORGANIZATION - -The order of headings inside documentation sections should be: - -main docs -@commonprop -@seealso -@refbugs - -* You must include a @seealso with at least one link to @lsrdir{}. - -* @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.) - -* 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: - - 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). - -* 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'. - -* in @itemize use @item on a separate line like this: - @itemize - @item - Foo - - @item - Bar - - Do not use @itemize @bullet. - -* 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. - - In most cases, you should use @code{} or @samp{} instead. - - -%%%%% 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) - -* 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. - -* 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. - - -%%%%% 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 - 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 use of the word `illegal' is inappropriate in most cases. - Say `invalid' instead. +See policy.txt %%%%% UPDATING DOCS @@ -233,4 +16,3 @@ grep "version \"" tutorial.itely % trying to record it here) - diff --git a/Documentation/user/policy.txt b/Documentation/user/policy.txt new file mode 100644 index 0000000000..d923d8a003 --- /dev/null +++ b/Documentation/user/policy.txt @@ -0,0 +1,238 @@ +DOCUMENTATION POLICY +-------------------- + + +%%%%% BOOKS + +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. + +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 "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, + convert-ly, etc). This section is written in formal technical + writing style. + +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. + +Users are not expected to read this manual from start to finish. + + +%%%%% SECTION ORGANIZATION + +The order of headings inside documentation sections should be: + +main docs +@commonprop +@seealso +@refbugs + +* You must include a @seealso with at least one link to @lsrdir{}. + 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.) + +* 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: + + 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). + +* 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'. + +* in @itemize use @item on a separate line like this: + @itemize + @item + Foo + + @item + Bar + + Do not use @itemize @bullet. + +* 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. + + In most cases, you should use @code{} or @samp{} instead. + + +%%%%% 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) + +* 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. + +* 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. + + +%%%%% 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 + 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 use of the word `illegal' is inappropriate in most cases. + Say `invalid' instead. + + +