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:
  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.


* Notation Reference: a (hopefully complete) description of
  LilyPond input notation.  Some material from here may be
  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.

Users are not expected to read this manual from start to finish.


* Music Glossary: information about the music notation itself.
  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
@predefined
@snippets
@seealso
@knownissues

* You _must_ include a @seealso.  The order of items inside the
  @seealso section is

    Music Glossary:
    @rglos{foo},
    @rglos{bar}.

    Learning Manual:
    @rlearning{baz},
    @rlearning{foozle}.

    Notation Reference:
    @ruser{faazle},
    @ruser{boo}.

    Application Usage:
    @rprogram{blah}.

    Installed Files:
    @file{path/to/dir/blahz}.

    Snippets: @rlsr{section}.

    Internals Reference:
    @rinternals{fazzle},
    @rinternals{booar}.

      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.

* @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,
  but other than that all material goes into third-level sections
  (ie 1.1.1 Writing Pitches).


%%%%% CHECKING CROSS-REFERENCES

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/.


%%%%% GENERAL WRITING

* 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.

  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
chord construct   NOT chord (when referring to <>)


%%%%% 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.



