X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2FREADME.txt;h=ae345e03d089d67c16ce0a3eb5c8025a119731f0;hb=024e51d1cb0e21d211baf91ad0774bc766dff687;hp=59552e6a4f5081a49412faa6cb1c58bef3a77209;hpb=d3e5224e52217369cff2870833292773e095f014;p=lilypond.git diff --git a/Documentation/user/README.txt b/Documentation/user/README.txt index 59552e6a4f..ae345e03d0 100644 --- a/Documentation/user/README.txt +++ b/Documentation/user/README.txt @@ -1,208 +1,21 @@ Info for Documentation ---------------------- +%%%%% GENERAL POLICY + +Formatting: writing-texinfo.txt +General policy: policy.txt + + %%%%% UPDATING DOCS convert-ly -e --from=... --to=... --no-version *.itely % to find the current version number, -grep "version \"" tutorial.itely +grep "version \"" fundamental.itely + +Please don't forget updating translated docs (in LANGS/user) too! % (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. - -* 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. - - -* 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. - - -%%%%% SECTION ORGANIZATION - -The order of headings inside documentation sections should be: - -main docs -@refcommands -@commonprop -@seealso -@refbugs - -(omit any headings which do not apply) - -Including at least one link to @lsrdir{} inside @seealso is -highly recommended. - - -%%%%% FORMATTING - -* Use two spaces for indentation in lilypond examples. - -* 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. - -* 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) - -* 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). - -* Use the `quote' option in @lilypond commands if possible. - - 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'. - -* 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 72 characters long. (I personally - recommend writing with 66-char lines, but don't bother modifying - existing material.) - -* 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 - -* 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 - 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. - - -