--- /dev/null
+@c -*- coding: us-ascii; mode: texinfo; -*-
+@node Compiling
+@chapter Compiling
+
+@menu
+* move AU 1 here::
+@end menu
+
+
+@node move AU 1 here
+@section move AU 1 here
+
+
+
\input texinfo @c -*- coding: utf-8; mode: texinfo; -*-
-@setfilename contrib-guide.info
-@settitle LilyPond Contributors' Guide
+@ignore
+ Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
+
+ When revising a translation, copy the HEAD committish of the
+ version that you are working on. See TRANSLATION for details.
+@end ignore
+@setfilename newweb.info
+@settitle GNU LilyPond New Website
+@documentencoding UTF-8
+@documentlanguage en
@include macros.itexi
-@documentencoding utf-8
-@documentlanguage en
+@afourpaper
-@finalout
+@c Keep this here, since it pertains to the direntry below.
+@ignore
+Distributions will want to install lilypond.info in postinstall, doing:
+
+ install-info --info-dir=/usr/share/info out[-www]/lilypond.info
+
+ * Prepend GNU for dir, must be unique.
+
+ * Do not list the `lilypond' node at toplevel, so that `info lilypond'
+ goes to Top.
+
+ * List all commands in direntry.
+@c * lilypond: (lilypond/lilypond)Running LilyPond. Invoking the
+@c LilyPond program.
+@end ignore
+
+
+@ifnottex
@node Top
-@top LilyPond Contributors' Guide
+@top GNU LilyPond --- New Website
+@chapheading The music typesetter
+@c HJJ: Info needs `@top', which is a synonym for `@unnumbered' in TeX.
+@end ifnottex
+
+
+@ifhtml
+@ifclear bigpage
+This document is also available as a
+@uref{source/Documentation/user/lilypond.pdf,PDF} and as
+@uref{source/Documentation/user/lilypond-big-page.html,one big page}.
+@end ifclear
+@ifset bigpage
+This document is also available as a
+@uref{source/Documentation/user/lilypond.pdf,PDF} and as a
+@uref{source/Documentation/user/lilypond/index.html,HTML indexed multiple pages}.
+@end ifset
+@end ifhtml
+
+
+@finalout
+
+@titlepage
+@title LilyPond
+@subtitle The music typesetter
+@titlefont{New Website}
+@author The LilyPond development team
+Copyright @copyright{} 1999--2008 by the authors
+
+@quotation
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.1
+or any later version published by the Free Software Foundation;
+with no Invariant Sections.
+A copy of the license is included in the section entitled ``GNU
+Free Documentation License''.
+@end quotation
+
+@vskip 20pt
+
+For LilyPond version
+@end titlepage
+
+@copying
+Copyright @copyright{} 1999--2008 by the authors
+
+@quotation
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.1
+or any later version published by the Free Software Foundation;
+with no Invariant Sections.
+A copy of the license is included in the section entitled ``GNU
+Free Documentation License''.
+@end quotation
+@end copying
+
+@ifnottex
+This file documents GNU LilyPond.
+
+Copyright 1999--2008 by the authors
+
+@quotation
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.1
+or any later version published by the Free Software Foundation;
+with no Invariant Sections.
+A copy of the license is included in the section entitled ``GNU
+Free Documentation License''.
+@end quotation
+@end ifnottex
+
+@ifnottex
+For more information about how this fits with the other
+
+@cindex web site
+@cindex URL
+
+More information can be found at
+@uref{http://@/www@/.lilypond@/.org/}. The website contains on-line copies
+of this and other documentation.
+
+@menu
+* Starting with git::
+* Compiling::
+* Documentation work::
+* Website work::
+* LSR work::
+* Issues::
+* Programming work::
+* Release work::
+@end menu
+@end ifnottex
+
+@contents
+
+@include git-starting.itexi
+@include compiling.itexi
+@include doc-work.itexi
+@include website-work.itexi
+@include lsr-work.itexi
+@include issues.itexi
+@include programming-work.itexi
+@include release-work.itexi
@bye
+
--- /dev/null
+@c -*- coding: us-ascii; mode: texinfo; -*-
+@node Documentation work
+@chapter Documentation work
+
+@menu
+* Introduction to documentation work::
+* Texinfo crash course::
+* Documentation policy::
+* Tips for writing docs::
+* Updating docs with convert-ly::
+* Translating the documentation::
+@end menu
+
+
+@node Introduction to documentation work
+@section Introduction to documentation work
+
+Our documentation tries to adhere to the @ref{Documentation
+policy} as strictly as possible. One policy in particular is
+often questioned by potential contributors: we do not repeat
+material in the Notation Reference, and instead provide links to
+the @qq{definitive} presentation of that information.
+
+Some people point out, with good reason, that this makes the
+documentation harder to read. If we repeated certain information
+in relevant places, readers would be less likely to miss that
+information.
+
+That reasoning is sound, but we have two counter-arguments.
+First, the Notation Reference -- one of @emph{five} manuals for
+users to read -- is already over 500 pages long. If we repeated
+material, we could easily exceed 1000 pages! Second, and much
+more importantly, LilyPond is an evolving project. New features
+are added, bugs are fixed, and bugs are discovered and documented.
+If features are discussed in multiple places, the documentation
+team must find every instance. Since the manual is so large, it
+is impossible for one person to have the location of every piece
+of information memorized, so any attempt to update the
+documentation will invariably omit a few places. This second
+concern is not at all theoretical; the documentation used to be
+plagued with inconsistent information.
+
+If the documentation were targeted for a specific version -- say,
+LilyPond 2.10.5 -- and we had unlimited resources to spend on
+documentation, then we could avoid this second problem. But since
+LilyPond evolves (and that is a very good thing!), and since we
+have quite limited resources, this policy remains in place.
+
+A few other policies (such as not permitting the use of tweaks in
+the main portion of NR 1+2) may also seem counter-intuitive, but
+they also stem from attempting to find the most effective use of
+limited documentation help.
+
+
+
+@node Texinfo crash course
+@section Texinfo crash course
+
+The language is called texinfo; you can see its manual here:
+@uref{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.
+
+@warning{Rule of thumb: follow the examples in the existing docs.
+You can learn most of what you need to know from this; if you want
+to do anything fancy, discuss it on @code{lilypond-devel} first.}
+
+
+@subsection 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 findw sections in texinfo.
+
+* sectioning commands (@@node and @@section) must not appear inside
+ an @@ignore. Separate those commands with a space, ie @@n ode.
+
+
+
+@subsection 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.
+
+
+@subsection 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.
+
+
+@subsection 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).
+
+
+
+@subsection 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.
+
+
+
+
+@node Documentation policy
+@section Documentation policy
+
+
+@subsection 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.
+
+
+@subsection 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).
+
+
+@subsection 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/.
+
+
+@subsection 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 <>)
+
+
+@subsection 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.
+
+
+@node Tips for writing docs
+@section Tips for writing docs
+
+In the NR, I highly 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.
+
+
+
+
+
+
+
+@node Updating docs with convert-ly
+@section Updating doc with convert-ly
+
+cd into Documentation and run
+
+@example
+find . -name '*.itely' | xargs convert-ly -e
+@end example
+
+@noindent
+(This also updates translated docs.)
+
+
+
+
+@node Translating the documentation
+@section Translating the documentation
+
+
--- /dev/null
+@c -*- coding: us-ascii; mode: texinfo; -*-
+@node Starting with git
+@chapter Starting with git
+
+@menu
+* Getting the source code::
+* Updating the source code::
+* Sharing your changes::
+* Other interesting Git commands::
+* Git on Windows::
+@end menu
+
+
+@node Getting the source code
+@section Getting the source code
+
+The source code is kept in a git respository.
+
+@warning{These instructions assume that you are using the
+command-line version of git 1.5 or higher.}
+
+
+@menu
+* Main source code::
+* Website source code::
+* Documentation translations source code::
+* Other branches::
+* Git user configuration::
+@end menu
+
+@node Main source code
+@subsection Main source code
+
+To get the main source code and documentation,
+
+FIXME: test this!!!
+
+@example
+mkdir lilypond; cd lilypond
+git init-db
+git remote add -f -t master -m master origin git://git.sv.gnu.org/lilypond.git/
+git checkout -b master origin/master
+@end example
+
+
+@node Website source code
+@subsection Website source code
+
+To get the website (including translations),
+
+@example
+mkdir lilyweb ; cd lilyweb
+git init-db
+git remote add -f -t web -m web origin git://git.sv.gnu.org/lilypond.git/
+git checkout -b web origin/web
+@end example
+
+
+@node Documentation translations source code
+@subsection Documentation translations source code
+
+To translate the documentation (@emph{not} the website),
+
+FIXME: change
+
+@example
+mkdir lilytranslate ; cd lilytranslate
+git init-db
+git remote add -f -t web -m web origin git://git.sv.gnu.org/lilypond.git/
+git checkout -b web origin/web
+@end example
+
+
+@menu
+* Other branches::
+* Git user configuration::
+@end menu
+
+@node Other branches
+@subsection Other branches
+
+Most contributors will never need to touch the other branches. If
+you wish to do so, you will need more familiarity with git.
+
+@itemize
+
+@item @code{gub}:
+This stores the Grand Unified Binary, our cross-platform building
+tool.
+
+@example
+FIXME: insert new gub addy
+@end example
+
+@item @code{dev/XYZ}:
+These branches are for individual developers. They store code
+which is not yet stable enough to be added to the @code{master}
+branch.
+
+@item @code{stable/XYZ}:
+The branches are kept for archival reasons.
+
+@end itemize
+
+
+@node Git user configuration
+@subsection Git user configuration
+
+To configure git to automatically use your name and email address
+for patches,
+
+@example
+git config --global user.name "MYNAME"
+git config --global user.email myemail@@example.net
+@end example
+
+
+@node Updating the source code
+@section Updating the source code
+
+@menu
+* Importance of updating::
+* Update command::
+* Resolving conflicts::
+* Technical notes::
+@end menu
+
+@node Importance of updating
+@subsection Importance of updating
+
+In a large project like LilyPond, contributors sometimes edit the
+same file at the same time. As long as everybody updates their
+version of the file with the most recent changes (@qq{pull}ing),
+there are generally no problems with this multiple-person editing.
+However, serious problems can arise if you do not pull before
+attempting commit.
+
+@node Update command
+@subsection Updating command
+
+Whenever you are asked to pull, it means you should update your
+local copy of the repository with the changes made by others on
+the remote @code{git.sv.gnu.org} repository:
+
+@example
+git pull origin
+@end example
+
+@node Resolving conflicts
+@subsection Resolving conflicts
+
+Occasionally an update may result in conflicts -- this happens
+when you and somebody else hae modified the same part of the same
+file and git cannot figure out how to merge the two versions
+together. When this happens, you must manually merge the two
+versions.
+
+@example
+TODO
+@end example
+
+
+@node Technical notes
+@subsection Technical notes
+
+Let's explain a bit of Git vocabulary. The @code{git pull
+origin} command is just a shortcut for this command:
+
+@example
+git pull git://git.sv.gnu.org/lilypond.git/ MY-BRANCH:origin/MY-BRANCH
+@end example
+
+A commit is a set of changes made to the sources; it also includes the
+committish of the parent commit, the name and e-mail of the author
+(the person who wrote the changes), the name and e-mail of the
+committer (the person who brings these changes into the git
+repository), and a commit message.
+
+A committish is the SHA1 checksum of a commit, a number made of 40
+hexadecimal digits, which acts as the internal unique identifier for
+this commit. To refer to a particular revision, don't use vague
+references like the (approximative) date, simply copy'n'paste the
+committish.
+
+A branch is a tree (in the mathematical or computer science sense) of
+commits, and the topmost commit of this branch is called a head.
+
+The "git fetch" command above has created a branch called origin/web
+in your local Git repository. As this branch is a copy of the remote
+branch web from git.sv.gnu.org LilyPond repository, it is
+called a `remote branch', and is meant to track the changes on the
+branch from git.sv.gnu.org: it will be updated every time you run 'git
+pull' or 'git fetch' with this branch reference as argument, e.g.
+by using .git/remotes/web remote file when running 'git fetch web'.
+
+The 'git checkout' command above has created a branch named 'web'. At
+the beginning, this branch is identical to 'origin/web', but it will
+differ as soon as you make changes, e.g. adding newly translated
+pages. Whenever you pull, you merge the changes from origin/web and
+your web branch since the last pulling. If you do not have push
+(i.e. "write") access on git.sv.gnu.org, your web branch will always
+differ from origin/web. In this case, remember that other people
+working like you on the remote web branch of
+git://git.sv.gnu.org/lilypond.git/ know nothing about your own web
+branch: this means that whenever you use a committish or make a patch,
+others expect you to take the lastest commit of origin/web branch as a
+reference.
+
+This README tries to explain most of Git commands needed for
+translating the web site. However, you are invited to read
+further documentation to make git more familiar to you; for
+instance, take a look at @uref{http://git.or.cz/gitwiki/},
+especially GitDocumentation and GitGlossary; a good alternative to
+reading the wiki is reading the first two chapters of Git User's
+Manual at
+@uref{http://www.kernel.org/pub/software/scm/git/docs/user-manual.html}
+
+
+
+
+@node Sharing your changes
+@section Sharing your changes
+
+
+@menu
+* Producing a patch::
+* Committing directly::
+@end menu
+
+@node Producing a patch
+@subsection Producing a patch
+
+Once you have finished editing your files, checked that your
+changes meet the @ref{Code style} and/or @ref{Documentation
+policy}, and checked that the entire thing compiles, you may
+
+@example
+git commit -a
+git-format-patch HEAD
+@end example
+
+Send an email to @email{lilypond-devel@@gnu.org} with the diff as
+an attachment.
+
+
+@node Committing directly
+@subsection Committing directly
+
+Most contributors do not have permission to commit directly. If
+you do, edit @file{.git/config} to contain
+
+@example
+FIXME?
+@end example
+
+You may then @code{git push}.
+
+
+@node Other interesting Git commands
+@section Other interesting Git commands
+
+The commands above don't only bring you the latest version of the
+sources, but also the full history of revisions (revisons, also
+called commits, are changes made to the sources), stored in the
+.git directory. You can browse this history with
+
+@example
+git log # only shows the logs (author, committish and commit message)
+git log -p # also shows diffs
+gitk # shows history graphically
+@end example
+
+
+
+
+@node Git on Windows
+@section Git on Windows
+
+
+
--- /dev/null
+@c -*- coding: us-ascii; mode: texinfo; -*-
+@node Issues
+@chapter Issues
+
+@menu
+* Introduction to issues::
+* Issue classification::
+* Adding issues to the tracker::
+@end menu
+
+
+@node Introduction to issues
+@section Introduction to issues
+
+First, @qq{issue} isn't just a politically-correct term for
+@qq{bug}. We use the same tracker for feature requests and code
+TODOs, so the term @qq{bug} wouldn't be accurate.
+
+Second, the classification of what counts as a bug vs. feature
+request, and the priorities assigned to bugs, are a matter of
+concern @strong{for developers only}. If you are curious about
+the classification, read on, but don't complain that your
+particular issue is higher priority or counts as a bug rather than
+a feature request.
+
+
+@node Issue classification
+@section Issue classification
+
+
+@node Adding issues to the tracker
+@section Adding issues to the tracker
+
+
+
+
+
+
--- /dev/null
+@c -*- coding: us-ascii; mode: texinfo; -*-
+@node LSR work
+@chapter LSR work
+
+@menu
+* Introduction to LSR::
+* Adding snippets::
+* Approving snippets::
+* LSR to git::
+@end menu
+
+
+@node Introduction to LSR
+@section Introduction to LSR
+
+
+@node Adding snippets
+@section Adding snippets
+
+
+@node Approving snippets
+@section Approving snippets
+
+
+@node LSR to git
+@section LSR to git
+
+
--- /dev/null
+@c -*- coding: us-ascii; mode: texinfo; -*-
+@ignore
+ Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
+
+ When revising a translation, copy the HEAD committish of the
+ version that you are working on. See TRANSLATION for details.
+@end ignore
+
+
+@c @include version.itexi
+
+
+@c Don't replace quotes with directed quotes.
+
+@set txicodequoteundirected
+@set txicodequotebacktick
+
+
+
+@c ***** Displaying text *****
+
+@c We need this since @q{\} doesn't work with makeinfo 4.11 --
+@c say @q{@bs{}} instead.
+
+@macro bs
+\\
+@end macro
+
+
+@c To get decent quotes in `foo' and ``foo''.
+
+@macro q{TEXT}
+@quoteleft{}\TEXT\@quoteright{}
+@end macro
+
+@macro qq{TEXT}
+@quotedblleft{}\TEXT\@quotedblright{}
+@end macro
+
+
+@ifhtml
+
+@macro warning{TEXT}
+@cartouche
+@b{Note:} \TEXT\
+@end cartouche
+@end macro
+
+@end ifhtml
+
+@ifnothtml
+
+@macro warning{TEXT}
+@quotation
+@quotation
+@cartouche
+@b{Note:} \TEXT\
+@end cartouche
+@end quotation
+@end quotation
+@end macro
+
+@end ifnothtml
+
+
+@ifnotinfo
+
+@macro notation{TEXT}
+@var{\TEXT\}
+@end macro
+
+@end ifnotinfo
+
+@ifinfo
+
+@macro notation{TEXT}
+\TEXT\
+@end macro
+
+@end ifinfo
+
+
+@macro smallspace
+@sp 1
+@end macro
+
+
+
+@c ***** Displaying images not generated by lilypond-book *****
+
+@c Current installation setup of Info docs requires that all images are
+@c expected to be found in the `lilypond/' subdirectory. `lilypond-book'
+@c already generates proper @image commands for images of music; these
+@c macro definitions do the same for other images.
+
+@ifnotinfo
+
+@macro sourceimage{FILENAME,WIDTH,HEIGHT,ALTTEXT}
+@image{\FILENAME\,\WIDTH\,\HEIGHT\,\ALTTEXT\}
+@end macro
+
+@end ifnotinfo
+
+@ifinfo
+
+@macro sourceimage{FILENAME,WIDTH,HEIGHT,ALTTEXT}
+@image{lilypond/\FILENAME\,\WIDTH\,\HEIGHT\,\ALTTEXT\}
+@end macro
+
+@end ifinfo
+
+
+
+@c ***** Headings in a doc subsection *****
+
+@c Don't insert an empty line after @predefined! Right now
+@c it doesn't matter, but a future implementation will probably
+@c add some code which needs this restriction.
+
+@macro predefined
+@noindent
+@subsubheading Predefined commands
+@end macro
+
+@c The next macro is a dummy currently since texinfo doesn't
+@c provide a real ragged-right environment yet.
+@c
+@c Due to a bug in texi2html (texi2html.pl CVS versions <= 1.245)
+@c the macro must not be empty.
+
+@macro endpredefined
+@c
+@end macro
+
+
+@macro snippets
+@noindent
+@subsubheading Selected Snippets
+@end macro
+
+
+@c Don't insert an empty line after @seealso! Otherwise we get
+@c unwanted extra vertical space in the PDF output.
+
+@macro seealso
+@noindent
+@subsubheading See also
+@indent
+@end macro
+
+
+@macro knownissues
+@noindent
+@subsubheading Known issues and warnings
+@end macro
+
+
+@macro lydoctitle {TEXT}
+@emph{\TEXT\}
+@end macro
+
+
+@c Don't remove the `@c' within the macro definition! See section 19.3,
+@c `Macro Details and Caveats', in the texinfo info file for explanation.
+
+@macro funindex {TEXT}
+@findex \TEXT\
+@kindex \TEXT\
+@c
+@end macro
+
+
+
+@c ***** Links and references *****
+
+@c Definitions for references:
+@c
+@c @rglos
+@c @rlearning
+@c @ruser
+@c @rprogram
+@c @rlsr
+@c @rinternals
+@c
+@c All these also have a @...named version which allows to specify the
+@c displayed text for the reference as second argument.
+@c
+@c ***** HTML + bigpage is a special case (other manual names); all other
+@c formats are treated similarly.
+
+
+@c *** not TeX ***
+
+@ifnottex
+
+@c ** bigpage **
+
+@ifset bigpage
+
+@macro rglos{TEXT}
+@vindex \TEXT\
+@ref{\TEXT\,,,music-glossary-big-page,Music Glossary}
+@end macro
+
+@macro rglosnamed{TEXT,DISPLAY}
+@vindex \TEXT\
+@ref{\TEXT\,,\DISPLAY\,music-glossary-big-page,Music Glossary}
+@end macro
+
+@macro rlearning{TEXT}
+@vindex \TEXT\
+@ref{\TEXT\,,,lilypond-learning-big-page,Learning Manual}
+@end macro
+
+@macro rlearningnamed{TEXT,DISPLAY}
+@vindex \TEXT\
+@ref{\TEXT\,,\DISPLAY\,lilypond-learning-big-page,Learning Manual}
+@end macro
+
+@macro ruser{TEXT}
+@vindex \TEXT\
+@ref{\TEXT\,,,lilypond-big-page,Notation Reference}
+@end macro
+
+@macro rusernamed{TEXT,DISPLAY}
+@vindex \TEXT\
+@ref{\TEXT\,,\DISPLAY\,lilypond-big-page,Notation Reference}
+@end macro
+
+@macro rprogram{TEXT}
+@vindex \TEXT\
+@ref{\TEXT\,,,lilypond-program-big-page,Application Usage}
+@end macro
+
+@macro rprogramnamed{TEXT,DISPLAY}
+@vindex \TEXT\
+@ref{\TEXT\,,\DISPLAY\,lilypond-program-big-page,Application Usage}
+@end macro
+
+@macro rlsr{TEXT}
+@ref{\TEXT\,,,lilypond-snippets-big-page,Snippets}
+@end macro
+
+@macro rlsrnamed{TEXT,DISPLAY}
+@ref{\TEXT\,,\DISPLAY\,lilypond-snippets-big-page,Snippets}
+@end macro
+
+@macro rinternals{TEXT}
+@vindex \TEXT\
+@ref{\TEXT\,,,lilypond-internals-big-page,Internals Reference}
+@end macro
+
+@macro rinternalsnamed{TEXT,DISPLAY}
+@vindex \TEXT\
+@ref{\TEXT\,,\DISPLAY\,lilypond-internals-big-page,Internals Reference}
+@end macro
+
+@end ifset
+
+
+@c ** not bigpage **
+
+@ifclear bigpage
+
+@macro rglos{TEXT}
+@vindex \TEXT\
+@ref{\TEXT\,,,music-glossary,Music Glossary}
+@end macro
+
+@macro rglosnamed{TEXT,DISPLAY}
+@vindex \TEXT\
+@ref{\TEXT\,,\DISPLAY\,music-glossary,Music Glossary}
+@end macro
+
+@macro rlearning{TEXT}
+@vindex \TEXT\
+@ref{\TEXT\,,,lilypond-learning,Learning Manual}
+@end macro
+
+@macro rlearningnamed{TEXT,DISPLAY}
+@vindex \TEXT\
+@ref{\TEXT\,,,lilypond-learning,Learning Manual}
+@end macro
+
+@macro ruser{TEXT}
+@vindex \TEXT\
+@ref{\TEXT\,,,lilypond,Notation Reference}
+@end macro
+
+@macro rusernamed{TEXT,DISPLAY}
+@vindex \TEXT\
+@ref{\TEXT\,,\DISPLAY\,lilypond,Notation Reference}
+@end macro
+
+@macro rprogram{TEXT}
+@vindex \TEXT\
+@ref{\TEXT\,,,lilypond-program,Application Usage}
+@end macro
+
+@macro rprogramnamed{TEXT,DISPLAY}
+@vindex \TEXT\
+@ref{\TEXT\,,\DISPLAY\,lilypond-program,Application Usage}
+@end macro
+
+@macro rlsr{TEXT}
+@ref{\TEXT\,,,lilypond-snippets,Snippets}
+@end macro
+
+@macro rlsrnamed{TEXT,DISPLAY}
+@ref{\TEXT\,,\DISPLAY\,lilypond-snippets,Snippets}
+@end macro
+
+@macro rinternals{TEXT}
+@vindex \TEXT\
+@ref{\TEXT\,,,lilypond-internals,Internals Reference}
+@end macro
+
+@macro rinternalsnamed{TEXT,DISPLAY}
+@vindex \TEXT\
+@ref{\TEXT\,,\DISPLAY\,lilypond-internals,Internals Reference}
+@end macro
+
+@end ifclear
+
+@end ifnottex
+
+
+@c *** TeX ***
+
+@iftex
+
+@macro rglos{TEXT}
+@vindex \TEXT\
+@ref{\TEXT\,,,music-glossary,Music Glossary}
+@end macro
+
+@macro rglosnamed{TEXT,DISPLAY}
+@vindex \TEXT\
+@ref{\TEXT\,,\DISPLAY\,music-glossary,Music Glossary}
+@end macro
+
+@macro rlearning{TEXT}
+@ref{\TEXT\,,,lilypond-learning,Learning Manual}
+@end macro
+
+@macro rlearningnamed{TEXT,DISPLAY}
+@ref{\TEXT\,,\DISPLAY\,lilypond-learning,Learning Manual}
+@end macro
+
+@macro ruser{TEXT}
+@ref{\TEXT\,,,lilypond,Notation Reference}
+@end macro
+
+@macro rusernamed{TEXT,DISPLAY}
+@ref{\TEXT\,,\DISPLAY\,lilypond,Notation Reference}
+@end macro
+
+@macro rprogram{TEXT}
+@ref{\TEXT\,,,lilypond-program,Application Usage}
+@end macro
+
+@macro rprogramnamed{TEXT,DISPLAY}
+@ref{\TEXT\,,\DISPLAY\,lilypond-program,Application Usage}
+@end macro
+
+@macro rlsr{TEXT}
+@ref{\TEXT\,,,lilypond-snippets,Snippets}
+@end macro
+
+@macro rlsrnamed{TEXT,DISPLAY}
+@ref{\TEXT\,,\DISPLAY\,lilypond-snippets,Snippets}
+@end macro
+
+@macro rinternals{TEXT}
+@vindex \TEXT\
+@ref{\TEXT\,,,lilypond-internals,Internals Reference}
+@end macro
+
+@macro rinternalsnamed{TEXT,DISPLAY}
+@vindex \TEXT\
+@ref{\TEXT\,,\DISPLAY\,lilypond-internals,Internals Reference}
+@end macro
+
+@end iftex
--- /dev/null
+@c -*- coding: us-ascii; mode: texinfo; -*-
+@node Programming work
+@chapter Programming work
+
+@menu
+* Introduction to programming::
+* Code style::
+@end menu
+
+
+@node Introduction to programming
+@section Introduction to programming
+
+blah blah
+
+
+@node Code style
+@section Code style
+@c email to wl@gnu.org when I get here.
+
+@menu
+@end menu
+
+@subsection Outputting errors
+
+As a general rule, you should always try to continue computations,
+even if there is some kind of error. When the program stops, it
+is often very hard for a user to pinpoint what part of the input
+causes an error. Finding the culprit is much easier if there is
+some viewable output.
+
+So functions and methods do not return errorcodes, they never
+crash, but report a programming_error and try to carry on.
+
+@subsection Languages
+
+C++ and Python are preferred. Python code should use PEP 8.
+
+@subsection Filenames
+
+Definitions of classes that are only accessed via pointers (*) or
+references (&) shall not be included as include files.
+
+@verbatim
+ filenames
+
+ ".hh" Include files
+ ".cc" Implementation files
+ ".icc" Inline definition files
+ ".tcc" non inline Template defs
+
+ in emacs:
+
+ (setq auto-mode-alist
+ (append '(("\\.make$" . makefile-mode)
+ ("\\.cc$" . c++-mode)
+ ("\\.icc$" . c++-mode)
+ ("\\.tcc$" . c++-mode)
+ ("\\.hh$" . c++-mode)
+ ("\\.pod$" . text-mode)
+ )
+ auto-mode-alist))
+@end verbatim
+
+The class Class_name is coded in @q{class-name.*}
+
+@subsection Indentation
+
+Standard GNU coding style is used. In emacs:
+
+@verbatim
+ (add-hook 'c++-mode-hook
+ '(lambda() (c-set-style "gnu")
+ ))
+@end verbatim
+
+If you like using font-lock, you can also add this to your
+@q{.emacs}:
+
+@verbatim
+ (setq font-lock-maximum-decoration t)
+ (setq c++-font-lock-keywords-3
+ (append
+ c++-font-lock-keywords-3
+ '(("\\b\\(a-zA-Z_?+_\\)\\b" 1 font-lock-variable-name-face) ("\\b\\(A-Z?+a-z_?+\\)\\b" 1 font-lock-type-face))
+ ))
+@end verbatim
+
+
+@subsection Classes and Types
+
+@verbatim
+ This_is_a_class
+@end verbatim
+
+
+@subsection Members
+
+Member variable names end with an underscore:
+
+@verbatim
+ Type Class::member_
+@end verbatim
+
+
+@subsection Macros
+
+Macro names should be written in uppercase completely.
+
+
+@subsection Broken code
+
+Do not write broken code. This includes hardwired dependencies,
+hardwired constants, slow algorithms and obvious limitations. If
+you can not avoid it, mark the place clearly, and add a comment
+explaining shortcomings of the code.
+
+We reject broken-in-advance on principle.
+
+@subsection Naming
+
+
+@subsection Messages
+
+Messages need to follow Localization.
+
+
+@subsection Localization
+
+This document provides some guidelines for programmers write user
+messages. To help translations, user messages must be
+uniformized. Follow these rules when coding for LilyPond.
+Hopefully, this can be replaced by general GNU guidelines in the
+future. Even better would be to have an English (en_BR, en_AM)
+helping programmers writing consistent messages for all GNU
+programs.
+
+Not-preferred messages are marked with `+'. By convention,
+ungrammatical examples are marked with `*'.
+
+@itemize
+
+@item
+Every message to the user should be localised (and thus be marked
+for localisation). This includes warning and error messages.
+
+@item
+Don't localise/gettextify:
+
+@itemize
+@item
+`programming_error ()'s
+
+@item
+`programming_warning ()'s
+
+@item
+debug strings
+
+@item
+output strings (PostScript, TeX, etc.)
+
+@end itemize
+
+@item
+Messages to be localised must be encapsulated in `_ (STRING)' or
+`_f (FORMAT, ...)'. Eg:
+
+@verbatim
+ warning (_ ("need music in a score"));
+ error (_f ("cannot open file: `%s'", file_name));
+@end verbatim
+
+In some rare cases you may need to call `gettext ()' by hand. This
+happens when you pre-define (a list of) string constants for later
+use. In that case, you'll probably also need to mark these string
+constants for translation, using `_i (STRING)'. The `_i' macro is
+a no-op, it only serves as a marker for `xgettext'.
+
+@verbatim
+ char const* messages[] = {
+ _i ("enable debugging output"),
+ _i ("ignore lilypond version"),
+ 0
+ };
+
+
+ void
+ foo (int i)
+ {
+ puts (gettext (messages i));
+ }
+@end verbatim
+
+See also `flower/getopt-long.cc' and `lily/main.cc'.
+
+@item
+Do not use leading or trailing whitespace in messages. If you need
+whitespace to be printed, prepend or append it to the translated
+message
+
+@verbatim
+ message (Calculating line breaks... + " ");
+@end verbatim
+
+@item
+Error or warning messages displayed with a file name and line
+number never start with a capital, eg,
+
+@verbatim
+ foo.ly: 12: not a duration: 3
+@end verbatim
+
+Messages containing a final verb, or a gerund (`-ing'-form) always
+start with a capital. Other (simpler) messages start with a
+lowercase letter
+
+@verbatim
+ Processing foo.ly...
+ `foo': not declared.
+ Not declaring: `foo'.
+@end verbatim
+
+@item
+Avoid abbreviations or short forms, use `cannot' and `do not'
+rather than `can't' or `don't'
+To avoid having a number of different messages for the same
+situation, we'll use quoting like this `"message: `%s'"' for all
+strings. Numbers are not quoted:
+
+@verbatim
+ _f ("cannot open file: `%s'", name_str)
+ _f ("cannot find character number: %d", i)
+@end verbatim
+
+@item
+Think about translation issues. In a lot of cases, it is better to
+translate a whole message. The english grammar mustn't be imposed
+on the translator. So, instead of
+
+@verbatim
+ stem at + moment.str () + does not fit in beam
+@end verbatim
+
+have
+
+@verbatim
+ _f ("stem at %s does not fit in beam", moment.str ())
+@end verbatim
+
+@item
+Split up multi-sentence messages, whenever possible. Instead of
+
+@verbatim
+ warning (_f ("out of tune! Can't find: `%s'",
+"Key_engraver"));
+ warning (_f ("cannot find font `%s', loading default",
+ font_name));
+@end verbatim
+
+rather say:
+
+@verbatim
+ warning (out of tune:;
+ warning (_f ("cannot find: `%s', "Key_engraver"));
+ warning (_f ("cannot find font: `%s', font_name));
+ warning (_f ("Loading default font"));
+@end verbatim
+
+@item
+If you must have multiple-sentence messages, use full punctuation.
+Use two spaces after end of sentence punctuation. No punctuation
+(esp. period) is used at the end of simple messages.
+
+@verbatim
+ _f ("Non-matching braces in text `%s', adding braces", text)
+ Debug output disabled. Compiled with NPRINT.
+ _f ("Huh? Not a Request: `%s'. Ignoring.", request)
+@end verbatim
+
+@item
+Do not modularise too much; a lot of words cannot be translated
+without context. It's probably safe to treat most occurences of
+words like stem, beam, crescendo as separately translatable words.
+
+@item
+When translating, it is preferable to put interesting information
+at the end of the message, rather than embedded in the middle.
+This especially applies to frequently used messages, even if this
+would mean sacrificing a bit of eloquency. This holds for original
+messages too, of course.
+
+@verbatim
+ en: cannot open: `foo.ly'
+ + nl: kan `foo.ly' niet openen (1)
+ kan niet openen: `foo.ly'* (2)
+ niet te openen: `foo.ly'* (3)
+@end verbatim
+
+
+The first nl message, although grammatically and stylistically
+correct, is not friendly for parsing by humans (even if they speak
+dutch). I guess we'd prefer something like (2) or (3).
+
+@item
+Do not run make po/po-update with GNU gettext < 0.10.35
+
+@end itemize
+
+
+
--- /dev/null
+@c -*- coding: us-ascii; mode: texinfo; -*-
+@node Release work
+@chapter Release work
+
+@menu
+* Development phases::
+* Minor release checklist::
+* Major release checklist::
+@end menu
+
+
+@node Development phases
+@section Development phases
+
+There are 2.5 states of development for LilyPond.
+
+@itemize
+
+@item @strong{Stable phase}:
+Starting from the release of a new major version @code{2.x.0}, the
+following patches @strong{MAY NOT} be merged with master:
+
+@itemize
+@item Any change to the input syntax. If a file compiled with a
+previous @code{2.x} version, then it must compile in the new
+version.
+
+@item New features with new syntax @emph{may be committed},
+although once committed that syntax cannot change during the
+remainder of the stable phase.
+
+@item Any change to the build dependencies (including programming
+libraries, documentation process programs, or python modules used
+in the buildscripts). If a contributor could compile a previous
+lilypond @code{2.x}, then he must be able to compile the new
+version.
+
+@end itemize
+
+@item @strong{Development phase}:
+Any commits are fine. Readers may be familiar with the term
+@qq{merge window} from following Linux kernel news.
+
+
+@item @strong{Release prep phase}:
+FIXME: I don't like that name.
+
+A new git branch @code{stable/2.x} is created, and a major release
+is made in two weeks.
+
+@itemize
+
+@item @code{stable/2.x branch}:
+Only translation updates and important bugfixes are allows.
+
+@item @code{master}:
+Normal @qq{stable phase} development occurs.
+
+@end itemize
+
+If we discover the need to change the syntax or build system, we
+will apply it and re-start the release prep phase.
+
+@end itemize
+
+This marks a radical change from previous practice in LilyPond.
+However, this setup is not intended to slow development -- as a
+rule of thumb, the next development phase will start within a
+month of somebody wanting to commit something which is not
+permitted during the stable phase.
+
+
+
+@node Minor release checklist
+@section Minor release checklist
+
+A @qq{minor release} means an update of @code{y} in @code{2.x.y}.
+
+email brief summary to info-lilypond
+
+
+
+@node Major release checklist
+@section Major release checklist
+
+A @qq{major release} means an update of @code{x} in @code{2.x.0}.
+
+Before release:
+
+* write release notes. note: stringent size requirements for
+ various websites, so be brief.
+
+* write preface section for manual.
+
+* submit pots for translation : send url of tarball to
+translation@@iro.umontreal.ca, mentioning lilypond-VERSION.pot
+
+* Check reg test
+
+* Check all 2ly scripts.
+
+* Run convert-ly on all files, bump parser minimum version.
+
+* Make FTP directories on lilypond.org
+
+* website:
+ - Make new table in download.html
+
+ - add to documentation list
+
+ - revise examples tour.html/howto.html
+
+ - add to front-page quick links
+
+ - change all links to the stable documentation
+
+ - doc auto redirects to v2.LATEST-STABLE
+
+News:
+
+ comp.music.research
+ comp.os.linux.announce
+
+ comp.text.tex
+ rec.music.compose
+
+Mail:
+
+ info-lilypond@@gnu.org
+
+linux-audio-announce@@lists.linuxaudio.org
+linux-audio-user@@lists.linuxaudio.org
+linux-audio-dev@@lists.linuxaudio.org
+
+ tex-music@@icking-music-archive.org
+
+ --- non-existant?
+ abcusers@@blackmill.net
+
+ rosegarden-user@@lists.sourceforge.net
+ info-gnu@@gnu.org
+ noteedit-user@@berlios.de
+
+ gmane.comp.audio.fomus.devel
+ gmane.linux.audio.users
+ gmane.linux.audio.announce
+ gmane.comp.audio.rosegarden.devel
+
+Web:
+
+ lilypond.org
+ freshmeat.net
+ linuxfr.com
+ http://www.apple.com/downloads
+ harmony-central.com (news@@harmony-central.com)
+ versiontracker.com [auto]
+ hitsquad.com [auto]
+ http://www.svgx.org
+
+
+
+
--- /dev/null
+@c -*- coding: us-ascii; mode: texinfo; -*-
+@node Website work
+@chapter Website work
+
+@menu
+* Introduction to website work::
+* Translating the website::
+@end menu
+
+
+@node Introduction to website work
+@section Introduction to website work
+
+
+
+
+@node Translating the website
+@section Translating the website
+
+
+
projects / lilypond.git / commitdiff