Info for Documentation
----------------------
-%%%%% GENERAL POLICY
+See CG 3. Documentation work
-Formatting: writing-texinfo.txt
-General policy: policy.txt
-
-
-%%%%% UPDATING DOCS
-cd into Documentation and run
-
-find . -name '*.itely' | xargs convert-ly -e
-
-(This also updates translated docs.)
+++ /dev/null
-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
-@endpredefined
-@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.
-
- Don't insert an empty line between @seealso and the first entry!
- Otherwise there is excessive vertical space in the PDF output.
-
-* To create links, use @ref{} if the link is within the same
- manual.
-
-* @predefined ... @endpredefined 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.
-
- For scheme functions, only include the final part, ie
- @funindex modern-voice-cautionary
- and NOT
- @funindex #(set-accidental-style modern-voice-cautionary)
-
-* 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.
-
-
-
+++ /dev/null
-CHECKLIST FOR DOC SECTION REWRITES
-
-You've volunteered (or are considering volunteering) to edit a
-section of the NR. Congratulations! You'll learn a lot about
-this part of lilypond. You'll also get thoroughly fed up with
-documentation work, and especially with me... but as they say,
-"you can't make an omelett without breaking a few eggs". Welcome
-to egg-hood!
-
-REQUIRED READING
-
-- policy.txt
-- writing-texinfo.txt
-- this document :)
-- NR 1.1 Pitches. Ideally, read it in your favorite output format
- (either info, PDF, or HTML), *and* in source format
- (pitches.itely). This is our "demonstration" chapter, so the
- below points really just boil down to "make it like
- pitches.itely".
-
-
-WORKING
-
-I recommend working on one subsection at a time. For each
-subsection,
-- check the mundane formatting. Are the headings (@predefined,
- @seealso, etc) in the right order?
-- add any appropriate index entries.
-- check the links in the @seealso section -- links to music
- glossary, internal references, and other NR sections are the
- main concern. Check for potential additions.
-- move LSR-worthy material into LSR. Add the snippet (or
- just send it to Valentin for adding), delete the material from
- the .itely file, and add a @lilypondfile command.
-
-- check the examples and descriptions. Do they still work?
- *Do not* assume that the existing text is accurate/complete;
- some of the manual is highly out of date.
-- is the material in the @knownissues still accurate?
-- process anything on the TODO list on the GDP web site.
-- can the examples be improved (made more explanatory), or is
- there any missing info? (feel free to ask specific questions
- on -user; a couple of people claimed to be interesting in being
- "consultants" who would help with such questions)
-
-In general, I favor short text explanations with good examples --
-"an example is worth a thousand words". When I worked on the
-docs, I spent about half my time just working on those tiny
-lilypond examples. Making easily-understandable examples is much
-harder than it looks.
-
-
-TWEAKS
-
-In general, any \set or \override commands should go in the
-"select snippets" section, which means that they should go in LSR
-and not the .itely file. For some cases, the command obviously
-belongs in the "main text" (ie not inside @predefined or @seealso
-or whatever) -- instrument names are a good example of this.
- \set Staff.instrumentName = #"foo"
-On the other side of this,
- \override Score.Hairpin #'after-line-breaking = ##t
-clearly belongs in LSR.
-
-I'm quite willing to discuss specific cases if you think that a
-tweaks needs to be in the main text. But items that can go into
-LSR are easier to maintain, so I'd like to move as much as
-possible into there.
-
-
-It would be "nice" if you spent a lot of time crafting nice tweaks
-for users... but my recommendation is *not* to do this. There's a
-lot of doc work to do without adding examples of tweaks. Tweak
-examples are trivial to add later -- they could be made by normal
-users, or by you after GDP is over.
-
-Basically, it's not something that needs to be done while I'm
-around. Remember that I'm gone in August at the latest; there's a
-*lot* of doc work that should be done before then. I strongly
-recommend that you save all the tweaks until later.
-
-
-FINAL
-
-- when you think you're finished, let me know. I'll spend a few
- minutes and send you a list of mistakes to fix.
- (there's a *lot* of details to cover; we'll probably spend a
- week going back and forth like this. See earlier warning about
- hating me by the time you're done with a doc section :)
-- I'll ask people on -user to review the Snippet list at this
- time; correcting things on the Snippet list is much easier than
- getting comments on the integrated snippets.
-- when we're both satisfied with the section, we'll invite
- comments from -user. Judging from my experience with Pitches,
- it will take between three and five weeks to keep on revising
- the "final" version.
-
-I personally found it quite frustrating to still be fixing
-problems in a doc section which I thought was "perfect" a whole
-bloody *month* ago. Don't get me wrong; it's great that we get so
-many comments from -user. :) But just be aware that when you
-think you're finally done with a section, you're actually only
-halfway there.
-
-
-
+++ /dev/null
-DOCUMENTATION FORMATTING
-------------------------
-
-The language is called texinfo; you can see its manual here:
-http://www.gnu.org/software/texinfo/manual/texinfo/
-
-However, you don't need to read those docs. The most important
-thing to notice is that text is text. If you see a mistake in the
-text, you can fix it. If you want to change the order of
-something, you can cut-and-paste that stuff into a new location.
-
-
-%%%%% SECTIONING COMMANDS
-
-Most of the manual operates at the
- @node Foo
- @subsubsection Foo
-level. Sections are created with
- @node Foo
- @subsection Foo
-commands.
-
-* Please leave two blank lines above a @node; this makes it easier
- to find sections in texinfo.
-
-* sectioning commands (@node and @section) must not appear inside
- an @ignore. Separate those commands with a space, ie @n ode.
-
-
-
-%%%%% LILYPOND FORMATTING
-
-* Use two spaces for indentation in lilypond examples. (no tabs)
-
-* All text strings should be prefaced with #. LilyPond does not
- strictly require this, but it is helpful to get users accustomed
- to this scheme construct. ie
- \set Staff.instrumentName = #"cello"
-
-* All engravers should have double-quotes around them:
- \consists "Spans_arpeggio_engraver"
- Again, LilyPond does not strictly require this, but it is a
- useful standard to follow.
-
-* Examples should end with a complete bar if possible.
-
-* If possible, only write one bar per line. The notes on each
- line should be an independent line -- tweaks should occur on
- their own line if possible.
- Bad:
- \override textscript #'padding = #3 c1^"hi"
- Good:
- \override textscript #'padding = #3
- c1^"hi"
-
-* Most LilyPond input should be produced with:
- @lilypond[verbatim,quote,relative=2]
- or
- @lilypond[verbatim,quote,relative=1]
-
- If you want to use \layout{} or define variables, use
- @lilypond[verbatim,quote]
-
- In rare cases, other options may be used (or omitted), but ask first.
-
-* Inspirational headwords are produced with
- @lilypondfile[quote,ragged-right,line-width=16\cm,staffsize=16]
- {pitches-headword.ly}
-
-* LSR snippets are linked with
- @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
- {filename.ly}
- excepted in Templates, where `doctitle' may be omitted.
-
-* Avoid long stretches of input code. Noone is going to read them
- in print. Please create a smaller example. (the smaller
- example does not need to be minimal, however)
-
-* Specify durations for at least the first note of every bar.
-
-* If possible, end with a complete bar.
-
-* Comments should go on their own line, and be placed before the
- line(s) to which they refer.
-
-* Add extra spaces around { } marks; ie
- not: \chordmode {c e g}
- but instead: \chordmode { c e g }
-
-* If you only have one bar per line, omit bar checks. If you
- put more than one bar per line (not recommended), then include
- bar checks.
-
-* If you want to work on an example outside of the manual (for
- easier/faster processing), use this header:
-
-\paper {
- #(define dump-extents #t)
- indent = 0\mm
- line-width = 160\mm - 2.0 * 0.4\in
- ragged-right = ##t
- force-assignment = #""
- line-width = #(- line-width (* mm 3.000000))
-}
-
-\layout {
-}
-
- You may not change any of these values. If you are making an
- example demonstrating special \paper{} values, contact the
- Documentation Editor.
-
-
-%%%%% 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.
-
-* 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.
-
-* In examples of syntax, use @var{musicexpr} for a music
- expression.
-
-* Don't use @rinternals{} in the main text. If you're tempted to
- do so, you're probably getting too close to "talking through the
- code". If you really want to refer to a context, use @code{} in
- the main text and @rinternals{} in the @seealso.
-
-* 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'. 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.
-
-* To get LilyPond version, use @version{} (this does not work inside
- LilyPond snippets). If you write "@version{}" (enclosed with
- quotes), or generally if @version{} is not followed by a space,
- enclose it with
-
- @w{ ... }
-
- e.g.
-
- @w{"@version{}"}
-
- to prevent an ugly line break in PDF output.
-
-
-%%%%% SYNTAX SURVEY
-
-@c - single line comments
- "@c NOTE:" is a comment which should remain in the final
- version. (gp only command ;)
-@ignore ... @end ignore - multi-line comment
-
-@cindex - General index. Please add as many as you can. Don't
- capitalize the first word.
-@funindex - is for a \lilycommand.
-
-@example ... @end ignore - example text that should be set as a
- blockquote. Any {} must be escaped with @{ }@
-@itemize @item A @item B ... @end itemize - for bulleted lists.
- Do not compress vertically like this.
-
-@code{} - typeset in a tt-font. Use for actual lilypond code or
- property/context names. If the name contains a space, wrap
- the entire thing inside @w{@code{ }}.
-@notation{} - refers to pieces of notation, e.g.
- "@notation{cres.}". Also use to specific lyrics ("the
- @notation{A - men} is centered"). Only use once per subsection
- per term.
-@q{} - Single quotes. Used for `vague' terms.
-@qq{} - Double quotes. Used for actual quotes ("he said") or for
- introducing special input modes.
-
-@tie{} - 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 letter@tie{}@q{I} is skipped"
-
-@var - Use for variables.
-@warning{} - produces a "Note: " box. Use for important messages.
-
-@bs - Generates a backslash inside @warning.
- Any `\' used inside @warning (and @q or @qq) must be written as `@bs{}'
- (texinfo would also allow \\, but this breaks with PDF output).
-
-
-
-%%%%% OTHER TEXT CONCERNS
-
-* References must occur at the end of a sentence, for more
- information see @ref{the texinfo manual}. Ideally this should
- also be the final sentence of a paragraph, but this is not
- required. Any link in a doc section must be duplicated in the
- @seealso section at the bottom.
-
-* Introducing examples must be done with
- . (ie finish the previous sentence/paragaph)
- : (ie `in this example:')
- , (ie `may add foo with the blah construct,')
- The old "sentence runs directly into the example" method is not
- allowed any more.
-
-* 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.
-
-* 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.
-
projects / lilypond.git / commitdiff