From: Graham Percival Date: Sat, 10 Jan 2009 08:52:47 +0000 (+0800) Subject: Move contributor's guide from web-gop. X-Git-Tag: release/2.12.2-1~38 X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=e62f6375698ae97625a288d95ad88b858c17aebb;p=lilypond.git Move contributor's guide from web-gop. --- diff --git a/Documentation/devel/compiling.itexi b/Documentation/devel/compiling.itexi new file mode 100644 index 0000000000..a39e0d85de --- /dev/null +++ b/Documentation/devel/compiling.itexi @@ -0,0 +1,14 @@ +@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 + + + diff --git a/Documentation/devel/contrib-guide.texi b/Documentation/devel/contrib-guide.texi index 6e8ec88788..3cf1b16d66 100644 --- a/Documentation/devel/contrib-guide.texi +++ b/Documentation/devel/contrib-guide.texi @@ -1,16 +1,143 @@ \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 + diff --git a/Documentation/devel/doc-work.itexi b/Documentation/devel/doc-work.itexi new file mode 100644 index 0000000000..c3d264f124 --- /dev/null +++ b/Documentation/devel/doc-work.itexi @@ -0,0 +1,666 @@ +@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 + + diff --git a/Documentation/devel/git-starting.itexi b/Documentation/devel/git-starting.itexi new file mode 100644 index 0000000000..a009470671 --- /dev/null +++ b/Documentation/devel/git-starting.itexi @@ -0,0 +1,280 @@ +@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 + + + diff --git a/Documentation/devel/issues.itexi b/Documentation/devel/issues.itexi new file mode 100644 index 0000000000..f7b5260aa9 --- /dev/null +++ b/Documentation/devel/issues.itexi @@ -0,0 +1,38 @@ +@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 + + + + + + diff --git a/Documentation/devel/lsr-work.itexi b/Documentation/devel/lsr-work.itexi new file mode 100644 index 0000000000..9b239ee34a --- /dev/null +++ b/Documentation/devel/lsr-work.itexi @@ -0,0 +1,28 @@ +@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 + + diff --git a/Documentation/devel/macros.itexi b/Documentation/devel/macros.itexi new file mode 100644 index 0000000000..103c077743 --- /dev/null +++ b/Documentation/devel/macros.itexi @@ -0,0 +1,384 @@ +@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 diff --git a/Documentation/devel/programming-work.itexi b/Documentation/devel/programming-work.itexi new file mode 100644 index 0000000000..24741412fa --- /dev/null +++ b/Documentation/devel/programming-work.itexi @@ -0,0 +1,311 @@ +@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 + + + diff --git a/Documentation/devel/release-work.itexi b/Documentation/devel/release-work.itexi new file mode 100644 index 0000000000..4ce6945818 --- /dev/null +++ b/Documentation/devel/release-work.itexi @@ -0,0 +1,162 @@ +@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 + + + + diff --git a/Documentation/devel/website-work.itexi b/Documentation/devel/website-work.itexi new file mode 100644 index 0000000000..c452cb2c38 --- /dev/null +++ b/Documentation/devel/website-work.itexi @@ -0,0 +1,21 @@ +@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 + + +