From d6532ec38597f228ec5516f81bd5200043b2e5f9 Mon Sep 17 00:00:00 2001 From: Graham Percival Date: Wed, 10 Nov 2010 21:35:36 +0000 Subject: [PATCH] Doc: CG: add GLISS material. --- .../contributor/administration.itexi | 298 ++++++++++++++++++ 1 file changed, 298 insertions(+) diff --git a/Documentation/contributor/administration.itexi b/Documentation/contributor/administration.itexi index 69c7afeb33..547186e85c 100644 --- a/Documentation/contributor/administration.itexi +++ b/Documentation/contributor/administration.itexi @@ -483,6 +483,304 @@ Should we change the "structure" / "framework" for bounties? @node Grand LilyPond Input Syntax Standardization (GLISS) @section Grand LilyPond Input Syntax Standardization (GLISS) +@subheading Summary + +@itemize +@item +Start: sortly after 2.14 comes out, which is currently estimated +to happen in January 2011. + +@item +Length: 6-12 months. We're not going to rush this. + +@item +Goal: define an input which we commit to being +machine-updateable for the forseeable future. Any future patches +which change the syntax in a non-convert-ly-able format will be +rejected. (subject to the limitations, below) +Once this is finished, we will release lilypond 3.0. + +@end itemize + + +@subheading The Problem + +One of the biggest complaints people have with lilypond -- other +than silly thing like "there's no gui" -- is the changing syntax. +Now, inventing a language or standards is difficult. If you set +it in stone too soon, you risk being stuck with decisions which +may limit matters. If you keep on updating the syntax, +interaction with older data (and other programs!) becomes complex. + +@subheading Scope and Limitations + +@itemize +@item +tweaks will not be included. Anything with \override, \set, +\overrideProperty, \tweak, \revert, \unset... including even those +command names themselves... is still fair game for NOT_SMART +convert-ly updates. + +@item +other than that, everything is on the table. Is it a problem to +have the tagline inside \header? What should the default behavior +of \include be? When we abolish \times, do we move to \tuplet 3:2 +or \tuplet 2/3 or what (for typical triplets in 4/4 time)? + +@item +we need to get standards for command names. This will help users +remember them, and reduce the options for future names (and +potential renamings later on). \commandOn and \commandOff seem to +work well (should we *always* have an Off command?), but what +about the "command" part? Should it be \nounVerbOn, or +\verbNounOn ? Or \verbNotesWithExtraInformationOn ? + +@item +we need standards for the location of commands. Ligature +brackets, I'm looking at you. (non-postfix notation must die!) + +@item +this Grand Project doesn't affect whether we have a 2.16 or not. +The main problem will be deciding what to do (with a bit of +messiness anticipated for \tuplet); we should definitely release a +2.16 before merging _any_ of these changes. + +@item +we obviously can't /guarantee/ that we'll /never/ make any +non-convert-ly changes in the basic format. But we *can* +guarantee that such changes would force lilypond 4.0, and that we +would only do so for overwhelmingly good reasons. + +@end itemize + +@subheading Workflow + +@itemize +@item +We're going to have lots and lots of emails flying around. The +vast majority won't really fit into either -devel or -user, so +we'll use a list devoted to syntax issues. + +@item +Once we have a serious proposal that gained general acceptance +from the separate syntax mailing list, I'll bring it to -devel. +We're not going to make any changes without discussing it on +-devel, but if we're going to have huge threads about English +grammar and silly ideas, and I don't want to clutter up -devel. +Once whatever chaotic silliness on the syntax list is settled +down, I'll bring the ideas to -devel. + +@item +as with GDP, I'll moderate the discussion. Not as with mailist +moderation, but rather by introducing issues at specific times. +We don't want a free-for-all discussion of all parts of the syntax +at once; nothing will get resolved. + +@item +Whenever possible, we'll decide on policies at the highest level +of abstraction. For example, consider \numericTimeSignature, +\slurUp, \xNotesOn, \startTextSpan, and \verylongfermata. One of +them starts with the name of the notation first (slur). One has +an abbreviation (x instead of cross). One has the verb at the end +(On), another has it at the beginning (start). The adjective can +come at the beginning (numeric, x) or end (Up). Most are in +camelCase, but one isn't (verylongfermata). + +@item +Instead of arguing about each individual command, we'll decide on +abstract questions. Should each command begin the notation-noun, +or the verb? Should all commands be in camelCase, or should we +make everything other than articulations in camelCase but make +articulations all lower-case? Are abbreviations allowed? + +@item +Once we've answered such fundamental questions, most of the syntax +should fall into place pretty easily. There might be a few odd +questions left ("is it a span, or a spanner?"), but those can be +settled fairly quickly. + +@end itemize + +@subheading Implementation + +Nothing until the project is finished, then we declare the next +stable release (2.16.0 or 2.18.0 ?) to be the final 2.x version, +release it, then apply all the GLISS syntax changes and start +testing a beta for 3.0 a week or two later. + +@subheading Discussion + +Don't respond to any of the specifics yet. Yes, we all have our +pet irritations (like "what's up with \paper and \layout?!"). +There will be plenty of time to discuss them once GLISS starts. + +That said, we have a list of specific items that people really +wanted to have written down. See @ref{Specific GLISS issues}. + +@menu +* Specific GLISS issues:: +@end menu + + +@node Specific GLISS issues +@subsection Specific GLISS issues + +@itemize +@item +add regtests for every piece of syntax (not one-command-per-file, +but making a few files which, between them, use every single piece +of syntax.) This is a great test for convert-ly. + +@item +should GLISS cover suggested conventions? (indentation, +one-bar-per-line, etc -- the kind of stuff we list for the +lilypond formatting in the docs ?) + +@item +how much (if any) syntactic sugar should we add? i.e. +@example + \instrumentName #'foo +% instead of + \set Staff.instrumentName +@end example +? Carl: maybe yes, Neil: no. (for example, it fails for +pianostaff) + +@item +the values that are used as arguments to common used overrides. +Sometimes they are a symbol (e.g. #'around), sometimes a +predefined variable referring to a Scheme value or object (e.g. +#LEFT, #all-visible ). The main trouble is that for novice users +it is not clear when there should be an apostrophe and when not. + +@item +When do we need -\command and when is it just \command ? + + +@item +Command-line options to the lilypond binary. -dfoo counts as a +tweak; we won't be trying to pin those down. + +@item +@verbatim +\layout { + \context { \Score +% vs. +\layout { + \context { + \Score +@end verbatim + +@item +If would be pedagogically simpler to realize this difference if +the syntax was separate if you define a context from scratch (as +is the case with \RemoveEmptyStaffContext) or if it's defined by +adding onto an existing context. For example, a syntax like + +@verbatim +\context{ + % Copy the current settings of the Staff context: + \use Staff + % do whatever additional settings +} +%%% could be used to distinguish from +\context{ + % Take settings from a variable: + \Variable + % do whatever additional settings +} + +%%% and + +\context{ + % Start from scratch: + \type ... + \name ... + \consists ... + ... +} +@end verbatim + +@item +Capitalization of identifiers: \VoiceOne ? + +@item +@verbatim +%%% Allow +{ music expression } * 4 +%%% instead of +\repeat unfold 4 { music expression } +@end verbatim + +? patch here: +@uref{http://lists.gnu.org/archive/html/lilypond-devel/2010-04/msg00467.html} + +@item +Personally, I find it easier to understand when there's a repeated +8 in the half-bar position; it's much easier to see that you have +two groups of 4: + +@example +c8 c c c c8 c c c +%%% instead of one group of eight: +c8 c c c c c c c +@end example + +@item +trivially simple bar-lines: + +c1 | c1 | + +encourage, allow, or discourage, or disallow? + +@item +indentation of \\ inside a @{@} construct. + + +@item +barline checks at the end of line should be preceded by at least 2 +spaces? barline checks should line up if possible (i.e. if you +can use less than 4, 8, X empty spaces before a barline check to +make them line up?) + +@item +Why doesn't \transpose respect \relative mode? + + +@item +on \score vs. \new Score + +But in the light of a consistent syntax and semantic, I see no +reason (from the users POV) to disallow it. After all, the real +top-level context is a \book @{@}, isn't it, and I don't see a point +in disallowing a \new Score construct just like \new Staff. + +From a syntactical POV, I see the following pros for \new Score: +- You can write \with @{ ... @} for every other context but \Score, +which (for consistency) should also work with \new Score. +- When there's a \new Foo Bar, there's also a \context Foo Bar, + which makes the same as a parallel instantiation of all Bar's. +- [Quoting Rune from +@uref{http://www.mail-archive.com/lilypond-devel@@gnu.org/msg14713.html} + "I know that the \score-statement is a syntactical construct, +but I think it would be nice to hide this fact from the users. I +think we could make the use of score-block much more intuitive if +changing the syntax to \new \Score and adding an implicit +sequential-statement to the score." + + +@item +Discussion on +http://code.google.com/p/lilypond/issues/detail?id=1322 +about \new vs. \context. + + +@item +Let users add their own items to the parser? comment 11 on: +http://code.google.com/p/lilypond/issues/detail?id=1322 + + +@end itemize @node Unsorted policies -- 2.39.5