From 06d175ab40b5a9d922595298cd43fe94e8fd98fa Mon Sep 17 00:00:00 2001 From: Graham Percival Date: Fri, 21 Sep 2007 16:22:02 -0700 Subject: [PATCH] More doc-writing hints. Also info for trivial/easy helpers. --- Documentation/user/README.txt | 239 ++++++++++++++++++++-------------- 1 file changed, 142 insertions(+), 97 deletions(-) diff --git a/Documentation/user/README.txt b/Documentation/user/README.txt index 7c28e2bc7e..d2480a0939 100644 --- a/Documentation/user/README.txt +++ b/Documentation/user/README.txt @@ -1,161 +1,206 @@ Info for Documentation ---------------------- -Current version of the manual: 2.11.28 -*** Please update this whenever you run convert-ly on the docs. - +%%%%% UPDATING DOCS convert-ly -e --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. + +Users are encouraged to read the complete Learning Manual from +start-to-finish. + -* Notation Reference is a (hopefully complete) description of +* 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. - -* Technical Details contains information about using -the program lilypond with other programs (lilypond-book, -operating systems, GUIs, convert-ly, etc). This section +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. -%%%%% -GENERAL GUIDELINES -* Use two spaces for indentation in lilypond examples. +* 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 (with @lsr{}); 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. - - . 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 for indentation in lilypond examples. - . Use two spaces after a period. +* Do not use tabs. They expand to nothing in DVI output. - . 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: +* 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. - The variable@tie{}@var{a} ... +* Use two spaces after 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 +* 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). + where `@example' starts the line (without leading spaces). - . Use the `quote' option in @lilypond commands if possible. +* Use the `quote' option in @lilypond commands if possible. - . Do not compress the input vertically; this is, do not use + Do not compress the input vertically; this is, do not use - Beginning of logical unit - @example - ... - @end example - continuation of logical unit + Beginning of logical unit + @example + ... + @end example + continuation of logical unit - but + but - Beginning of logical unit + Beginning of logical unit - @example - ... - @end example + @example + ... + @end example - @noindent - continuation of logical unit + @noindent + continuation of logical unit - This makes it easier to not forget `@noindent'. + This makes it easier to avoid forgetting the `@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. +* 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. -* Lines should be less than 80 characters long. +* Lines should be less than 72 characters long. (I personally + recommend writing with 66-char lines, but don't bother changing + this if you see long lines.) * 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. + 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. -%%%%% -HINTS FOR TECHNICAL WRITING STYLE + In most cases, you should use @code{} or @samp{} instead. + + +%%%%% READIBILITY + +* 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. + + -- 2.39.5