Issue 3667041: Rewrite NR 3.2 Titles and headers. (Closed)
|
Created:
13 years, 4 months ago by Mark Polesky Modified:
10 years, 8 months ago CC:
lilypond-devel_gnu.org Visibility:
Public. |
DescriptionRewrite NR 3.2 Titles and headers.
Patch Set 1 #Patch Set 2 : More changes. #Patch Set 3 : More changes. #Patch Set 4 : More changes. #Patch Set 5 : First draft. #
Total comments: 35
MessagesTotal messages: 7
Hey guys. Here's a complete rewrite of NR 3.2 Titles and headers. Please comment. You can disregard the first couple of patch sets, and go straight to the "First Draft" one. Thanks. - Mark
Sign in to reply to this message.
Hope these aren't too nit-picky. http://codereview.appspot.com/3667041/diff/13001/Documentation/notation/input... File Documentation/notation/input.itely (right): http://codereview.appspot.com/3667041/diff/13001/Documentation/notation/input... Documentation/notation/input.itely:527: Could we have some appropriate @cindex here? and possibly some @funindex? I think this would be really useful http://codereview.appspot.com/3667041/diff/13001/Documentation/notation/input... Documentation/notation/input.itely:547: @code{\score} blocks). It is typically placed near the top of the Can't you just say simply that ...text fields for the main title block should be placed outside of and before a \score block. (what is 'toplevel scope'?). http://codereview.appspot.com/3667041/diff/13001/Documentation/notation/input... Documentation/notation/input.itely:558: block. On the other hand, the @code{piece} text fields belong to 'However' instead of 'On the other hand' (too idiomatic). http://codereview.appspot.com/3667041/diff/13001/Documentation/notation/input... Documentation/notation/input.itely:570: \clef bass \key g \major new line for \key g \major http://codereview.appspot.com/3667041/diff/13001/Documentation/notation/input... Documentation/notation/input.itely:581: \clef bass \key g \major new line for \key g \major http://codereview.appspot.com/3667041/diff/13001/Documentation/notation/input... Documentation/notation/input.itely:593: can be displayed in individual score title blocks by adding the does 'score' in this sentence need @code{\score}? http://codereview.appspot.com/3667041/diff/13001/Documentation/notation/input... Documentation/notation/input.itely:601: @code{\header} blocks, so some fields may need to manually some fields may need to *be* manually... http://codereview.appspot.com/3667041/diff/13001/Documentation/notation/input... Documentation/notation/input.itely:603: @code{##f}). I think the brackets here are unnecessary and would prefer to see 'print-all-headers = ##f' in full. http://codereview.appspot.com/3667041/diff/13001/Documentation/notation/input... Documentation/notation/input.itely:611: @lilypond[quote,verbatim,noragged-right,staffsize=17] Some of these aren't standard @lilypond variables and we do ask that any changes in Doc to these are 'discussed' :) http://codereview.appspot.com/3667041/diff/13001/Documentation/notation/input... Documentation/notation/input.itely:657: Need @seealso for @ref{Custom layout for title blocks} http://codereview.appspot.com/3667041/diff/13001/Documentation/notation/input... Documentation/notation/input.itely:743: Need @seealso for @file{ly/titling-init.ly} @ref{Custom layout for title blocks} http://codereview.appspot.com/3667041/diff/13001/Documentation/notation/input... Documentation/notation/input.itely:772: right (if odd), starting on the second page. Starting on the second page, even page numbers are placed on the left and odd on the right. http://codereview.appspot.com/3667041/diff/13001/Documentation/notation/input... Documentation/notation/input.itely:808: Need @seealso @file{ly/titling-init.ly} http://codereview.appspot.com/3667041/diff/13001/Documentation/notation/input... Documentation/notation/input.itely:829: @lilypond[quote,verbatim,noragged-right,indent=15\mm,staffsize=17] Ditto above for @lilypond variables - not standard http://codereview.appspot.com/3667041/diff/13001/Documentation/notation/input... Documentation/notation/input.itely:875: @lilypond[quote,verbatim,noragged-right,indent=15\mm,staffsize=17] Ditto above regarding non Standard @lilypond variables. http://codereview.appspot.com/3667041/diff/13001/Documentation/notation/input... Documentation/notation/input.itely:889: @lilypond[quote,verbatim,noragged-right,staffsize=17] Ditto above regarding non Standard @lilypond variables. http://codereview.appspot.com/3667041/diff/13001/Documentation/notation/input... Documentation/notation/input.itely:931: @lilypond[quote,verbatim,noragged-right,staffsize=17] Ditto above regarding non Standard @lilypond variables. http://codereview.appspot.com/3667041/diff/13001/Documentation/notation/input... Documentation/notation/input.itely:1062: We need @seealso here Notation Reference @ref{Title blocks explained} @ref{Default layout of book and score title blocks} One for Internals too {ly/titling-init.ly} http://codereview.appspot.com/3667041/diff/13001/Documentation/notation/input... Documentation/notation/input.itely:1071: as for title blocks (see is it 'basically the same' or just 'the same' if you see what I mean? http://codereview.appspot.com/3667041/diff/13001/Documentation/notation/input... Documentation/notation/input.itely:1114: @end lilypond Another @seealso needed @ref{Custom layout for title blocks} @ref{Default layout of headers and footers}
Sign in to reply to this message.
Just a few comments after eye-balling the patch. I'll need to download and compile to comment more fully. http://codereview.appspot.com/3667041/diff/13001/Documentation/notation/input... File Documentation/notation/input.itely (right): http://codereview.appspot.com/3667041/diff/13001/Documentation/notation/input... Documentation/notation/input.itely:601: @code{\header} blocks, so some fields may need to manually to be http://codereview.appspot.com/3667041/diff/13001/Documentation/notation/input... Documentation/notation/input.itely:915: As discussed in a previous section, text fields normally reserved Remove "As discussed in a previous section" http://codereview.appspot.com/3667041/diff/13001/Documentation/notation/input... Documentation/notation/input.itely:969: @code{\header} block inside the @code{\score}: I had to read this twice to understand it. Might be clearer to say "a new text field called @code{voices} is defined in @code{scoreTitleMarkup}, and printed in the score with the value set in the ..."
Sign in to reply to this message.
A short note about bookpart titles. http://codereview.appspot.com/3667041/diff/13001/Documentation/notation/input... File Documentation/notation/input.itely (right): http://codereview.appspot.com/3667041/diff/13001/Documentation/notation/input... Documentation/notation/input.itely:538: @c TODO: figure out how \bookpart titles work On the first page of a bookpart is inserted a bookTitleMarkup, which depends on the \header variables accessible from that bookpart. That means that if a top level \header block sets, say, the title property, then this book title will be printed at the beginning of each bookpart, which is probably not desirable. So I'd advice, in a book containing several bookpart, to set the \header block containing the title, etc, properties in a dedicated bookpart (the first one). Alternatively, the bookTitleMarkup \paper variable might be set to #f at top-level, and overridden in the first bookpart so that the title is printed on the first page.
Sign in to reply to this message.
I've looked at the compiled version now. It's nicely written, but my concern is that this is no longer written in 'reference' style. To me, parts of it seem more suited to the LM. The idea of the NR is that people already well-familiar with LilyPond can quickly find a keyword or syntax they have forgotten, without having to wade through introductory material. That process was easier with the old layout. I'll not object to this change, but we ought to do it only after explicit agreement from others that this style of writing is acceptable in the NR. http://codereview.appspot.com/3667041/diff/13001/Documentation/notation/input... File Documentation/notation/input.itely (right): http://codereview.appspot.com/3667041/diff/13001/Documentation/notation/input... Documentation/notation/input.itely:525: @node Creating titles headers and footers This breaks a ref in learning/common-notation.itely http://codereview.appspot.com/3667041/diff/13001/Documentation/notation/input... Documentation/notation/input.itely:789: @code{copyright} if there is only one page). ... @code{copyright} notice if there ...
Sign in to reply to this message.
Greetings Mark, I actually kinda like this writing style, it's more explanatory and detailed that other NR material but if it can help make things more clear then I think we should accept it. The downside is that it "talks through the code" quite a lot, perhaps you could remove all variable names from the main text and use more comments in @lilypond fragments instead? Anyway, LmostlyGTM. http://codereview.appspot.com/3667041/diff/13001/Documentation/notation/input... File Documentation/notation/input.itely (right): http://codereview.appspot.com/3667041/diff/13001/Documentation/notation/input... Documentation/notation/input.itely:621: title = "DAS WOHLTEMPERIRTE CLAVIER" Should be Wohltemperierte http://codereview.appspot.com/3667041/diff/13001/Documentation/notation/input... Documentation/notation/input.itely:634: title = "PRAELUDIUM I" How about PRÆLUDIUM ? http://codereview.appspot.com/3667041/diff/13001/ly/titling-init.ly File ly/titling-init.ly (right): http://codereview.appspot.com/3667041/diff/13001/ly/titling-init.ly#newcode146 ly/titling-init.ly:146: %% oddHeaderMarkup if it were not defined here These comments are a welcome addition IMO.
Sign in to reply to this message.
Mark, This is really useful stuff. Thanks! However, I agree with Trevor about the LM vs NR style of writing. The NR needs to be terse and show, rather than tell, the story. In an effort to be clear, we often try to both tell and show. I spent a lot of time when I first started writing NR sections doing both. Graham relentlessly focused on getting me to remove text, using the aphorism "A document is complete, not when nothing more can be added, but when nothing more can be removed." I fought against that at first, but ultimately came to agree with this policy. This is the reason that the hard part of writing NR documentation is coming up with effective snippets. They need to be short and self-evident, while demonstrating the appropriate principle. I think that much of your explanation here is written in LM style. And I'd be happy to have a chapter/section in the LM that explained these items. However, in the NR, I think that we need to have much less writing to accommodate your excellent examples. Thanks, Carl http://codereview.appspot.com/3667041/diff/13001/Documentation/notation/input... File Documentation/notation/input.itely (right): http://codereview.appspot.com/3667041/diff/13001/Documentation/notation/input... Documentation/notation/input.itely:683: The default settings for @code{bookTitleMarkup}: You don't need to itemize the settings; the example shows them. http://codereview.appspot.com/3667041/diff/13001/Documentation/notation/input... Documentation/notation/input.itely:721: The default settings for @code{scoreTitleMarkup} place the Again, no explanation necessary. Just show. http://codereview.appspot.com/3667041/diff/13001/Documentation/notation/input... Documentation/notation/input.itely:766: The default settings for headers are such that: An example would be better than an itemized list, if it's doable. http://codereview.appspot.com/3667041/diff/13001/Documentation/notation/input... Documentation/notation/input.itely:971: @lilypond[quote,verbatim,noragged-right,staffsize=17] Would this be better as a selected snippet? http://codereview.appspot.com/3667041/diff/13001/Documentation/notation/input... Documentation/notation/input.itely:1005: The following example integrates several of the above techniques I think this is definitely better as a selected snippet. http://codereview.appspot.com/3667041/diff/13001/ly/titling-init.ly File ly/titling-init.ly (right): http://codereview.appspot.com/3667041/diff/13001/ly/titling-init.ly#newcode146 ly/titling-init.ly:146: %% oddHeaderMarkup if it were not defined here Me too.
Sign in to reply to this message.
|
