Issue 4124056: Doc: NR rewrite of 3.2 Titles and Headers (Closed)
|
Created:
13 years, 2 months ago by pkx166h Modified:
12 years, 10 months ago Reviewers:
james.lowe, Graham Percival (old account), Trevor Daniels, Graham Percival, lemniskata.bernoulliego, Mark Polesky, t.daniels, Jean-Charles, carl.d.sorensen CC:
lilypond-devel_gnu.org Visibility:
Public. |
DescriptionDoc: NR rewrite of 3.2 Titles and Headers
This is an edited verion of Mark Polesky's patch
http://codereview.appspot.com/3667041/
No new information has been added from the original patch,
but the text has been edited so that it is more suitable to the Notation Reference Style.
Patch Set 1 #
Total comments: 20
Patch Set 2 : Second Draft #
Total comments: 25
Patch Set 3 : Third Draft of NR 3.2 Rewrite #Patch Set 4 : 4th Draft with new papersize incorp'd #
Total comments: 11
Patch Set 5 : Draft 5 without ly/ file and minor spacing edits #Patch Set 6 : 6th Draft #Patch Set 7 : 7th draft #
Total comments: 17
Patch Set 8 : Draft 8 #Patch Set 9 : Draft 9 #
Total comments: 2
MessagesTotal messages: 26
I've done a first pass at this. General comment: there's more "talking through the code" than I'd like. I'm willing to relax this a bit for Notation 3 instead of Notation 1+2, but I think it can be tightened up a bit with some work. Other than that, not bad at all! I think we're looking at 4-5 drafts, but definitely manageable in a week. Good job, Mark and James! http://codereview.appspot.com/4124056/diff/1/Documentation/notation/input.itely File Documentation/notation/input.itely (right): http://codereview.appspot.com/4124056/diff/1/Documentation/notation/input.ite... Documentation/notation/input.itely:526: @subsection Creating titles, headers, and footers I get nervous when the @subsection doesn't match the @node, but I can't think of a definitely alternative after a few seconds. The only serious alternative at the moment is "Creating titles and headers and footers". :( http://codereview.appspot.com/4124056/diff/1/Documentation/notation/input.ite... Documentation/notation/input.itely:548: @lilypond[quote,verbatim,noragged-right,staffsize=17,indent=13\mm] First - it's ok to be more "creative" with [options] when we're talking about spacing stuff. However, are you certain you need staffsize=17 and indent=13\mm ? If you experimented with a few values and decided this looked best, that's a perfectly acceptable answer! That said, could you standardize on indent=15\mm, instead of switching between 13 and 15 ? http://codereview.appspot.com/4124056/diff/1/Documentation/notation/input.ite... Documentation/notation/input.itely:555: \new Staff \relative g, { I think the doc policy officially calls for { between the Staff and \relative, but IMO this is ok syntax. (you might want to look at the CG, and prepare a patch saying "sometimes it's ok not to strictly add { everywhere, such as in NR 3, but always do it in the LM and NR 1+2) http://codereview.appspot.com/4124056/diff/1/Documentation/notation/input.ite... Documentation/notation/input.itely:584: @example Do you really need an @example ? I think this material could be worked into the following @lilypond. http://codereview.appspot.com/4124056/diff/1/Documentation/notation/input.ite... Documentation/notation/input.itely:592: #(set-default-paper-size "a5") I remember discussing this page-size thing before, but I confess that I can't remember the result of that discussion. Why does this example have a #(set-default-paper-size ? http://codereview.appspot.com/4124056/diff/1/Documentation/notation/input.ite... Documentation/notation/input.itely:597: indent = 0\mm are you putting indent in the [options], or in \paper ? If you have a particular rationale for switching between the two, that's ok, but it seems weird to me. http://codereview.appspot.com/4124056/diff/1/Documentation/notation/input.ite... Documentation/notation/input.itely:661: The default settings for @code{bookTitleMarkup}: I think the phrase "default settings" is a bit confusing. 99.9% of readers will never redefine bookTitleMarkup. I think we should discuss the redefinition later in this chapter/section, and drop the "default". http://codereview.appspot.com/4124056/diff/1/Documentation/notation/input.ite... Documentation/notation/input.itely:681: \header { Does this work? (a \header by itself, inside a @lilypond)? Cool! http://codereview.appspot.com/4124056/diff/1/Documentation/notation/input.ite... Documentation/notation/input.itely:752: The default tagline is a clickable link (to Hmm. Could this be a @lilypond instead? That way, if we alter the default tagline at all, it'll be updated automatically here. http://codereview.appspot.com/4124056/diff/1/Documentation/notation/input.ite... Documentation/notation/input.itely:759: The default tagline can be changed by adding a @code{tagline =} in the Holy "talking through the code", batman! Can we revise this?
Sign in to reply to this message.
Le 06/02/2011 04:21, percival.music.ca@gmail.com disait : > [...] > Documentation/notation/input.itely:526: @subsection Creating titles, > headers, and footers > I get nervous when the @subsection doesn't match the @node, but I can't > think of a definitely alternative after a few seconds. The only serious > alternative at the moment is "Creating titles and headers and footers". > :( > Then have a look at any node name and sectioning name, like @node Running lilypond @chapter Running @command{lilypond} It seems like a "@node xxx" is just what will be used in indexing and referencing, as the @sectioning will accept some "typesetting rules". I must admit that I do make some mistakes when cross-referencing, using the sectioning part instead of the noding. HTH, Jean-Charles
Sign in to reply to this message.
This comment of mine from Mark's patch still applies, even after these changes: > 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. IIRC Carl agreed with this, and suggested reworking it for the LM. Trevor
Sign in to reply to this message.
On 2011/02/06 17:48:56, Trevor Daniels wrote:
> This comment of mine from Mark's patch still applies, even after these
changes:
>
> > 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.
ok, I've compiled it myself. I still think that once we optimize away the
"talking through the code", it'll fit into Notation.
Title blocks explained: ouch. The music example is classy, but boy does it make
the input code confusing! Maybe it's just been too long (... 8 years now?)
since I wrote any music in lilypond.
(I recall Mats' suggestion that we use color highlighting in the docs... that
could really help here, but sadly nobody's been interested in adding it)
The second half of that portion needs to be rewritten, but that's what drafts
are for.
Default layout of book and score title blocks: just delete all the text, add a
\header{} to the final @example, and it's fine. Those itemized lists don't add
any clarity for either a newbie or experienced user.
Default layout of headers and footers: this one needs some trickery with
@lilypond[options] to get really small pages, but once that's been worked out,
just dump a \header and \relative { c1 \pageBreak c1 \pageBreak...} in there.
I still think it's doable in half a dozen drafts. Maybe 7 or 8.
Sign in to reply to this message.
<percival.music.ca@gmail.com> wrote Sunday, February 06, 2011 8:41 PM > On 2011/02/06 17:48:56, Trevor Daniels wrote: >> This comment of mine from Mark's patch still applies, even after >> these > changes: > >> > 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. > > ok, I've compiled it myself. I still think that once we optimize > away > the "talking through the code", it'll fit into Notation. I think the spacing controls are now so complex that they really do need a 'learning' approach to help users understand how to approach page layout. Mark's original patch was quite good for that, but belongs in the LM. Then the NR can contain purely reference material for users who simply want to look up a detail. I think we are in danger of falling between the two by paring this down. Trevor
Sign in to reply to this message.
Hello, ________________________________________ From: lilypond-devel-bounces+james.lowe=datacore.com@gnu.org [lilypond-devel-bounces+james.lowe=datacore.com@gnu.org] on behalf of Trevor Daniels [t.daniels@treda.co.uk] Sent: 07 February 2011 11:02 To: percival.music.ca@gmail.com; pkx166h@gmail.com Cc: reply@codereview.appspotmail.com; lilypond-devel@gnu.org Subject: Re: Doc: NR rewrite of 3.2 Titles and Headers (issue4124056) <percival.music.ca@gmail.com> wrote Sunday, February 06, 2011 8:41 PM > > On 2011/02/06 17:48:56, Trevor Daniels wrote: >> > This comment of mine from Mark's patch still applies, even after >> > these > > changes: >> >> >> 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. >> >> ok, I've compiled it myself. I still think that once we optimize >> away >> the "talking through the code", it'll fit into Notation. I think the spacing controls are now so complex that they really do need a 'learning' approach to help users understand how to approach page layout. Mark's original patch was quite good for that, but belongs in the LM. Then the NR can contain purely reference material for users who simply want to look up a detail. I think we are in danger of falling between the two by paring this down. --- It's not a problem for me to make two patches if that would help? I can pare this one down for NR, then work on an appropriate LM one afterwards. Can't guarantee them both by the end of the week if that is a problem. I'll have to move the information from one itely/itexi to another anyway and then I can easily grab an older 'patch' to base the LM one on. Where my skill falls down is if the new section names cannot be moved lock stock and barrel over to the LM and I have to end up making new nodes. Otherwise I can easily just cut/paste edited chunks into the existing LM texi/tely files. When a decision has been made (do we put this in LM only or both?) let me know so I don't waste any time by having to re-correct edits. I don't have an opinion either way, other than perhaps the NR could have more detail and better examples - even if we are (at the moment) talking through the code, but I do think that some of Mark's original patch was too complex for the LM 'as is' and would also need simplifying. So if you think we do need an LM patch and if you think what I have done as first draft of edits is a good starting point for the LM then let me know. James
Sign in to reply to this message.
On Mon, Feb 07, 2011 at 11:02:16AM -0000, Trevor Daniels wrote:
>
> I think the spacing controls are now so complex that
> they really do need a 'learning' approach to help
> users understand how to approach page layout.
I'm probably missing something because I don't know what the new
spacing controls are. But in the basic case, what's complicated
about
\header {
title = "title"
}
?
My understanding of this stuff is that you can have a \header in a
book or score, with various options to enable or disable
(re)printing fields carrying-over from book to score. I don't
think this needs a "learning" approach.
> I think we are in danger of falling between the two by paring
> this down.
I think we need to discuss specifics. Let's pick one portion (I'd
advise the very first @node, or possibly the first two @nodes) and
discuss exactly what we think should be changed in that.
(it may well be the case that the "simple" header stuff can be
pared down without harming anything, whereas whatever additional
complicated header stuff requires more text. That's fine --
certain @nodes like Setting automatic beaming behavior are more
chatty than other Notation @nodes.)
Cheers,
- Graham
Sign in to reply to this message.
On Mon, Feb 07, 2011 at 01:41:45PM +0000, James Lowe wrote: > Where my skill falls down is if the new section names cannot be > moved lock stock and barrel over to the LM and I have to end up > making new nodes. Otherwise I can easily just cut/paste edited > chunks into the existing LM texi/tely files. > > When a decision has been made (do we put this in LM only or > both?) let me know so I don't waste any time by having to > re-correct edits. Nothing goes in LM only. Let's work on making stuff for Notation. Then, once that's done, if people has a sad about any nice bits from the original patch that were removed, we can consider adding them to Learning. BTW, making new nodes is very simple; try reviewing Reinhold's three doc patches, because one of them adds a @node, and because you should be doing more patch reviewing anyway. Cheers, - Graham
Sign in to reply to this message.
Second draft been posted. I couldn't work out how to do one request so this has not been changed. Putting the tagline in an @lilypond without having the need for a whole page to print. http://codereview.appspot.com/4124056/diff/1/Documentation/notation/input.itely File Documentation/notation/input.itely (right): http://codereview.appspot.com/4124056/diff/1/Documentation/notation/input.ite... Documentation/notation/input.itely:526: @subsection Creating titles, headers, and footers On 2011/02/06 03:21:33, Graham Percival wrote: > I get nervous when the @subsection doesn't match the @node, but I can't think of > a definitely alternative after a few seconds. The only serious alternative at > the moment is "Creating titles and headers and footers". :( Done. http://codereview.appspot.com/4124056/diff/1/Documentation/notation/input.ite... Documentation/notation/input.itely:548: @lilypond[quote,verbatim,noragged-right,staffsize=17,indent=13\mm] On 2011/02/06 03:21:33, Graham Percival wrote: > First - it's ok to be more "creative" with [options] when we're talking about > spacing stuff. However, are you certain you need staffsize=17 and indent=13\mm > ? If you experimented with a few values and decided this looked best, that's a > perfectly acceptable answer! > > That said, could you standardize on indent=15\mm, instead of switching between > 13 and 15 ? I've done no experimenting - this was lifted from Mark's patch. I assumed he had. I'll standardize on 13mm indent for now. http://codereview.appspot.com/4124056/diff/1/Documentation/notation/input.ite... Documentation/notation/input.itely:555: \new Staff \relative g, { On 2011/02/06 03:21:33, Graham Percival wrote: > I think the doc policy officially calls for { between the Staff and \relative, > but IMO this is ok syntax. > (you might want to look at the CG, and prepare a patch saying "sometimes it's ok > not to strictly add { everywhere, such as in NR 3, but always do it in the LM > and NR 1+2) I'll revert to Doc Policy again if you think it looks worse I can put it back and make a CG addendum. It's better to be consistent throughout if we can though. http://codereview.appspot.com/4124056/diff/1/Documentation/notation/input.ite... Documentation/notation/input.itely:584: @example On 2011/02/06 03:21:33, Graham Percival wrote: > Do you really need an @example ? I think this material could be worked into the > following @lilypond. Done. http://codereview.appspot.com/4124056/diff/1/Documentation/notation/input.ite... Documentation/notation/input.itely:592: #(set-default-paper-size "a5") Again I don't know, this was done by Mark so I assumed he had a reason. I will take this out in the meantime. http://codereview.appspot.com/4124056/diff/1/Documentation/notation/input.ite... Documentation/notation/input.itely:597: indent = 0\mm Again, not me. I will remove these as I was unsure why they were here also. http://codereview.appspot.com/4124056/diff/1/Documentation/notation/input.ite... Documentation/notation/input.itely:661: The default settings for @code{bookTitleMarkup}: Done. and also removed 'Default' from all the @node and @numbered... http://codereview.appspot.com/4124056/diff/1/Documentation/notation/input.ite... Documentation/notation/input.itely:681: \header { Evidently. Although would it 'improve' things, do you think if we had a line of music underneath to give these context - just a thought. http://codereview.appspot.com/4124056/diff/1/Documentation/notation/input.ite... Documentation/notation/input.itely:752: The default tagline is a clickable link (to I'm not sure how to do this within an @lilypond without having a huge blank space of staff and the tagline at the bottom. http://codereview.appspot.com/4124056/diff/1/Documentation/notation/input.ite... Documentation/notation/input.itely:759: The default tagline can be changed by adding a @code{tagline =} in the On 2011/02/06 03:21:33, Graham Percival wrote: > Holy "talking through the code", batman! Can we revise this? Done.
Sign in to reply to this message.
Read Usage and play with lilypond-book a bit on your own.
1. I want you to create a Tiny .tely file and compile it to a pdf.
2. play with a few [options] to the @lilypond[]s in your Tiny file.
3. in particular, play with linewidth and textheight or pageheight or page sizes
or \paper { height = 5\mm } or something.
Spending an hour or two playing with these options and/or paper settings, and
checking them out in a TINY .tely file compiled to pdf, will be *extremely*
well-spent time. Such familiarity with the [options] wasn't necessary (or even
desirable) for 99% of our docs, but it'll be very useful for the Spacing
chapter.
I'm certain that we can have some settings which produce pages so small that
only 1-2 bars fit on them. Once we have that, it'll be trivially easy to
display tagline, instrument/copyright headers, break-before, etc.
http://codereview.appspot.com/4124056/diff/9001/Documentation/notation/input....
File Documentation/notation/input.itely (right):
http://codereview.appspot.com/4124056/diff/9001/Documentation/notation/input....
Documentation/notation/input.itely:541: outside of the first @code{\score} of a
book, and individual title
I'm not certain about the word "outside". Do you have a strong preference
against "above" ? I admit that this doesn't apply to things like tagline, but
the new docs seem to relegate that to a separate @node anyway.
http://codereview.appspot.com/4124056/diff/9001/Documentation/notation/input....
Documentation/notation/input.itely:586: @code{print-all-headers = ##t} inside a
@code{\paper} block.
Don't talk through the code.
http://codereview.appspot.com/4124056/diff/9001/Documentation/notation/input....
Documentation/notation/input.itely:589: blocks by adding @code{##f} to the Text
field.
Don't talk through the code.
http://codereview.appspot.com/4124056/diff/9001/Documentation/notation/input....
Documentation/notation/input.itely:590:
Replace the previous two paragraphs with this:
Text fields from the main title block of a book can be displayed in all
@code{\score} blocks, or manually suppressed:
http://codereview.appspot.com/4124056/diff/9001/Documentation/notation/input....
Documentation/notation/input.itely:599: tagline = ##f
If you want to clarify this, add a comment above this line.
% do not this text field:
http://codereview.appspot.com/4124056/diff/9001/Documentation/notation/input....
Documentation/notation/input.itely:641: @code{bookTitleMarkup} for the main
title block and
I'm confused -- below, you just write
\header {
dedication = "dedication"
...
}
So what the mao is this "bookTitleMarkup" about? Why should I know or care
about it?
This is a general note about the rewrite -- it's nicely laid out for people who
want to change these variables, but that's at most 5% of readers. Most people
just want to know how to spell "dedicated" or.. whoops, it's "dedication"... or
whether we call it "arranger" or "editor" or what.
I don't think it'd be hard to write docs that let people seeking easy answers
get them quickly, without making it harder for people wanting to do complicated
stuff.
http://codereview.appspot.com/4124056/diff/9001/Documentation/notation/input....
Documentation/notation/input.itely:650: These markup variables access text
fields from the @code{\header}
This is way less important than the general layout for stuff like title and
composer; move it to the bottom of this page (or even into another @node).
http://codereview.appspot.com/4124056/diff/9001/Documentation/notation/input....
Documentation/notation/input.itely:656: Settings for @code{bookTitleMarkup}:
If we keep the bookTitleMarkup string at all, how about moving this whole bit
(including @lilypond) into the first itemize in this @node ?
http://codereview.appspot.com/4124056/diff/9001/Documentation/notation/input....
Documentation/notation/input.itely:689: The default settings for
@code{scoreTitleMarkup} place the @code{piece}
If you're doing the @itemize thing for bookTitleMarkup, then do it here too.
http://codereview.appspot.com/4124056/diff/9001/Documentation/notation/input....
Documentation/notation/input.itely:691:
also, if you keep the first @itemize on this page, then consider moving this
into the second @item. Yes, we can have nested @itemize lists, and we can have
@lilypond inside those nested lists.
http://codereview.appspot.com/4124056/diff/9001/Documentation/notation/input....
Documentation/notation/input.itely:707: @end example
I'd rather have a @lilypond.
http://codereview.appspot.com/4124056/diff/9001/Documentation/notation/input....
Documentation/notation/input.itely:767: @node Custom headers footers and titles
I'm ignoring this subsection for now; let's focus on the first one.
Sign in to reply to this message.
Third draft done - sorry it took so long. http://codereview.appspot.com/4124056/diff/9001/Documentation/notation/input.... File Documentation/notation/input.itely (right): http://codereview.appspot.com/4124056/diff/9001/Documentation/notation/input.... Documentation/notation/input.itely:541: outside of the first @code{\score} of a book, and individual title On 2011/02/15 01:28:04, Graham Percival wrote: > I'm not certain about the word "outside". Do you have a strong preference > against "above" ? Not especially. Done. http://codereview.appspot.com/4124056/diff/9001/Documentation/notation/input.... Documentation/notation/input.itely:586: @code{print-all-headers = ##t} inside a @code{\paper} block. On 2011/02/15 01:28:04, Graham Percival wrote: > Don't talk through the code. Done. http://codereview.appspot.com/4124056/diff/9001/Documentation/notation/input.... Documentation/notation/input.itely:589: blocks by adding @code{##f} to the Text field. On 2011/02/15 01:28:04, Graham Percival wrote: > Don't talk through the code. Done. http://codereview.appspot.com/4124056/diff/9001/Documentation/notation/input.... Documentation/notation/input.itely:590: On 2011/02/15 01:28:04, Graham Percival wrote: > Replace the previous two paragraphs with this: > > Text fields from the main title block of a book can be displayed in all > @code{\score} blocks, or manually suppressed: Thanks...done. http://codereview.appspot.com/4124056/diff/9001/Documentation/notation/input.... Documentation/notation/input.itely:599: tagline = ##f On 2011/02/15 01:28:04, Graham Percival wrote: > If you want to clarify this, add a comment above this line. > % do not this text field: Good idea. Also did this for the next two scores in this example just for consistency. http://codereview.appspot.com/4124056/diff/9001/Documentation/notation/input.... Documentation/notation/input.itely:641: @code{bookTitleMarkup} for the main title block and I've taken a look at this - before I had just edited the existing paragraphs - and have I hope simplified this part of the section by removing the itemization and condensing it into a para and better comments in the @lilypond so that those 95% of users get what they want. See what you think with regard to the other comments and if we still need to move information to new nodes or not, it may give a different perspective. http://codereview.appspot.com/4124056/diff/9001/Documentation/notation/input.... Documentation/notation/input.itely:650: These markup variables access text fields from the @code{\header} See comment above. http://codereview.appspot.com/4124056/diff/9001/Documentation/notation/input.... Documentation/notation/input.itely:656: Settings for @code{bookTitleMarkup}: See comment above. http://codereview.appspot.com/4124056/diff/9001/Documentation/notation/input.... Documentation/notation/input.itely:689: The default settings for @code{scoreTitleMarkup} place the @code{piece} I personally don't normally like itemizing things, but see comments above as I have, I hope simplified this for readers. http://codereview.appspot.com/4124056/diff/9001/Documentation/notation/input.... Documentation/notation/input.itely:691: Again see comments above. I've incorporated this with the first @lilypond just so it is all in one example. http://codereview.appspot.com/4124056/diff/9001/Documentation/notation/input.... Documentation/notation/input.itely:707: @end example On 2011/02/15 01:28:04, Graham Percival wrote: > I'd rather have a @lilypond. I think until I can get a way to 1. Incorporate a small custom page in page.scm and 2. Somehow get @lilypond to allow a [pagesize=x,] option I am not sure how I can do this without massive white space for a 'real' page break. So for now I haven't done this. http://codereview.appspot.com/4124056/diff/9001/Documentation/notation/input.... Documentation/notation/input.itely:767: @node Custom headers footers and titles On 2011/02/15 01:28:04, Graham Percival wrote: > I'm ignoring this subsection for now; let's focus on the first one. No problem, but I am hoping that we can make this like the section above after my edits.
Sign in to reply to this message.
4th Draft posted. Still to do: Showing how 'breakbefore' works, as it was evident from recent mails that I need to go back and read the LM to see how to show this in an @lilypond. Also the last third of this patch still needs to be 'done' - we've left this until we get the first parts sorted. Just check the comments - I have done all of them (except breakbefore) but have also take the opportunity to make some more edits to make this section even less wordy. http://codereview.appspot.com/4124056/diff/9001/Documentation/notation/input.... File Documentation/notation/input.itely (right): http://codereview.appspot.com/4124056/diff/9001/Documentation/notation/input.... Documentation/notation/input.itely:707: @end example On 2011/02/15 01:28:04, Graham Percival wrote: > I'd rather have a @lilypond. Although I've now used the new papersize we have defined in the @lilypond option and the paper.scm file, until I better understand the breakbefore option (I need to go back evidently and re-read how it should be used properly), so have for now not done this.
Sign in to reply to this message.
Thanks again to everyone here for helping to finish what I started. I'll leave the style/content issues to the rest of you; the comments below are just nitpicks. - Mark http://codereview.appspot.com/4124056/diff/18001/Documentation/notation/input... File Documentation/notation/input.itely (right): http://codereview.appspot.com/4124056/diff/18001/Documentation/notation/input... Documentation/notation/input.itely:670: fields at opposite ends of the same line.To force titles to start on a Use 2 spaces between sentences. http://codereview.appspot.com/4124056/diff/18001/Documentation/notation/input... Documentation/notation/input.itely:689: the top and bottom of pages, separate from the main text of a book. They Use 2 spaces between sentences. http://codereview.appspot.com/4124056/diff/18001/Documentation/notation/input... Documentation/notation/input.itely:701: defined in @file{ly/titling-init.ly}. By default: Use 2 spaces between sentences.
Sign in to reply to this message.
http://codereview.appspot.com/4124056/diff/18001/Documentation/notation/input... File Documentation/notation/input.itely (right): http://codereview.appspot.com/4124056/diff/18001/Documentation/notation/input... Documentation/notation/input.itely:548: @lilypond[quote,verbatim,noragged-right,staffsize=17,indent=13\mm] I want a general rule for this stuff. Also, a comment at the top of the file. See Documentation/learning/common-notation.itely for an example of what I mean... our doc policy doesn't say that you can change the staffsize and indent. In this chapter, it may be necessary to change those -- but let's document that at the top of the file. Basically, I want you to list every @lilypond[options] that you think you should be allowed to use. At the moment, I'm imagining 3-5 sets of [options], but if you have a good reason to want more, that's fine. Let's make this a separate patch. Yes, I'd like to see a patch which only adds a comment to the top of this file. :) Remember, the smaller a patch, the less fuss it'll get, and the easier+faster it'll get pushed. http://codereview.appspot.com/4124056/diff/18001/ly/titling-init.ly File ly/titling-init.ly (right): http://codereview.appspot.com/4124056/diff/18001/ly/titling-init.ly#newcode1 ly/titling-init.ly:1: \version "2.12.0" you know, it occurs to me that we could have pushed the patch for this file ages ago. Want to do this now? Make a new patch, including only this file, and give it the commit message "Add clarifications to ly/titleing-init.ly", and then push.
Sign in to reply to this message.
5th Draft, nothing to really check (apart from Marks 3 spacing edits) but have removed the ly file now pushed in commit 524f726a5de0033e68525c65e58430de9b60b7ca So this is just some admin work so I know that the latest iteration of the patch is here. http://codereview.appspot.com/4124056/diff/18001/Documentation/notation/input... File Documentation/notation/input.itely (right): http://codereview.appspot.com/4124056/diff/18001/Documentation/notation/input... Documentation/notation/input.itely:548: @lilypond[quote,verbatim,noragged-right,staffsize=17,indent=13\mm] On 2011/04/10 04:11:43, Graham Percival wrote: > I want a general rule for this stuff. Also, a comment at the top of the file. Not Done Yet. I've just removed the ly file (pushed in an earlier commit as your suggestion) and made Mark's minor spacing adjustments. That way I know where I am on this patch and know that the latest iteration of all these changes are here. I'll work on the comment patch before making any more additions to this one. http://codereview.appspot.com/4124056/diff/18001/Documentation/notation/input... Documentation/notation/input.itely:670: fields at opposite ends of the same line.To force titles to start on a On 2011/04/09 21:34:27, Mark Polesky wrote: > Use 2 spaces between sentences. Done. http://codereview.appspot.com/4124056/diff/18001/Documentation/notation/input... Documentation/notation/input.itely:689: the top and bottom of pages, separate from the main text of a book. They On 2011/04/09 21:34:27, Mark Polesky wrote: > Use 2 spaces between sentences. Done. http://codereview.appspot.com/4124056/diff/18001/Documentation/notation/input... Documentation/notation/input.itely:701: defined in @file{ly/titling-init.ly}. By default: On 2011/04/09 21:34:27, Mark Polesky wrote: > Use 2 spaces between sentences. Done. http://codereview.appspot.com/4124056/diff/18001/ly/titling-init.ly File ly/titling-init.ly (right): http://codereview.appspot.com/4124056/diff/18001/ly/titling-init.ly#newcode1 ly/titling-init.ly:1: \version "2.12.0" On 2011/04/10 04:11:43, Graham Percival wrote: > you know, it occurs to me that we could have pushed the patch for this file ages > ago. > > Want to do this now? Make a new patch, including only this file, and give it > the commit message "Add clarifications to ly/titleing-init.ly", and then push. Done. As 524f726a5de0033e68525c65e58430de9b60b7ca
Sign in to reply to this message.
Just an updated. New Patch for @lilypond policy here http://codereview.appspot.com/4445070/ Once we have ratified this we can apply it to this one.
Sign in to reply to this message.
7th Draft up for review. Drafts 5 and 6 are not valid (one was just to keep the patch alive with lots of other recent changes and 6 was a mistake by me). Draft 4 was the last draft to have comments on so compare with 7 please. You can also see drafts 4 vs 3 to see what still has to be done - as this is such a large edit there is still a second part to do (the last quarter of this new text). http://codereview.appspot.com/4124056/diff/18001/Documentation/notation/input... File Documentation/notation/input.itely (right): http://codereview.appspot.com/4124056/diff/18001/Documentation/notation/input... Documentation/notation/input.itely:548: @lilypond[quote,verbatim,noragged-right,staffsize=17,indent=13\mm] Done as commits eb643ffa775d54ad342d82afe015c190c3bf8c2d and a0112838d85cb2187e3b27f24f68f8f51fb90fea
Sign in to reply to this message.
Looks mostly good to me. Carl http://codereview.appspot.com/4124056/diff/32001/Documentation/notation/input... File Documentation/notation/input.itely (right): http://codereview.appspot.com/4124056/diff/32001/Documentation/notation/input... Documentation/notation/input.itely:667: Text fields left unset in a @code{\header} block are replaced with This paragraph has three different ideas -- null markups, piece and opus, and forcing titles to start on a new page. They should probably be separated into three different paragraphs. http://codereview.appspot.com/4124056/diff/32001/Documentation/notation/input... Documentation/notation/input.itely:937: Need @seealso for the @ref in this node -- Title blocks explained, Default layout of book and score title blocks,. http://codereview.appspot.com/4124056/diff/32001/Documentation/notation/input... Documentation/notation/input.itely:987: @end lilypond Need @seealso here, with all of the @ref in this node (Default layout of book and title blocks).
Sign in to reply to this message.
comments about the first section. http://codereview.appspot.com/4124056/diff/32001/Documentation/notation/input... File Documentation/notation/input.itely (right): http://codereview.appspot.com/4124056/diff/32001/Documentation/notation/input... Documentation/notation/input.itely:674: @example We just spent a month working on a8landscape, precisely to avoid having an @example like this. Change to @lilypond. http://codereview.appspot.com/4124056/diff/32001/Documentation/notation/input... Documentation/notation/input.itely:719: clickable link (@url{http://www.lilypond.org}). Don't talk about it. Having the example already shows you the default tagline. http://codereview.appspot.com/4124056/diff/32001/Documentation/notation/input... Documentation/notation/input.itely:730: c4 d e f IIRC this produces two lines (I haven't compiled it). If so, do we need two lines? Why not just have one bar? Also, do we need a title? This is an example for a tagline, right? http://codereview.appspot.com/4124056/diff/32001/Documentation/notation/input... Documentation/notation/input.itely:748: c4 d e f This is good, but previous comments apply as well. Lose the title and one bar. http://codereview.appspot.com/4124056/diff/32001/Documentation/notation/input... Documentation/notation/input.itely:755: To remove the @code{tagline} set the value to to @code{##f}. this is fine; no need to another @lilypond here.
Sign in to reply to this message.
Draft 8 http://codereview.appspot.com/4124056/diff/32001/Documentation/notation/input... File Documentation/notation/input.itely (right): http://codereview.appspot.com/4124056/diff/32001/Documentation/notation/input... Documentation/notation/input.itely:667: Text fields left unset in a @code{\header} block are replaced with On 2011/05/04 17:08:39, Carl wrote: > This paragraph has three different ideas -- null markups, piece and opus, and > forcing titles to start on a new page. > > They should probably be separated into three different paragraphs. Actually I have split it into two and removed the middle part as the example above states this already in the comment within the verbatim @lilypond example. http://codereview.appspot.com/4124056/diff/32001/Documentation/notation/input... Documentation/notation/input.itely:674: @example On 2011/05/04 23:32:36, Graham Percival wrote: > We just spent a month working on a8landscape, precisely to avoid having an > @example like this. Change to @lilypond. Yes we did, you'll also remember that you sent out an email to dev asking for help as I struggled to get this working and it seemed to me that there are some very specific places where it will and won't work. http://article.gmane.org/gmane.comp.gnu.lilypond.general/63567/ :( http://codereview.appspot.com/4124056/diff/32001/Documentation/notation/input... Documentation/notation/input.itely:719: clickable link (@url{http://www.lilypond.org}). On 2011/05/04 23:32:36, Graham Percival wrote: > Don't talk about it. Having the example already shows you the default tagline. Done. http://codereview.appspot.com/4124056/diff/32001/Documentation/notation/input... Documentation/notation/input.itely:730: c4 d e f On 2011/05/04 23:32:36, Graham Percival wrote: > IIRC this produces two lines (I haven't compiled it). If so, do we need two > lines? Why not just have one bar? No reason. > > Also, do we need a title? This is an example for a tagline, right? Yes but it does show it all in context - i.e. a 'whole page' from top to bottom. It's odd that you'd have a tagline and no title for a finished score (in my opinion), but again I have no strong feelings about removing the titles. Done http://codereview.appspot.com/4124056/diff/32001/Documentation/notation/input... Documentation/notation/input.itely:748: c4 d e f On 2011/05/04 23:32:36, Graham Percival wrote: > This is good, but previous comments apply as well. Lose the title and one bar. Done. http://codereview.appspot.com/4124056/diff/32001/Documentation/notation/input... Documentation/notation/input.itely:755: To remove the @code{tagline} set the value to to @code{##f}. On 2011/05/04 23:32:36, Graham Percival wrote: > this is fine; no need to another @lilypond here. Done. http://codereview.appspot.com/4124056/diff/32001/Documentation/notation/input... Documentation/notation/input.itely:937: On 2011/05/04 17:08:39, Carl wrote: > Need @seealso for the @ref in this node -- Title blocks explained, Default > layout of book and score title blocks,. This section is not being done until the above node is complete - see previous comment by Graham http://codereview.appspot.com/4124056/diff/32001/Documentation/notation/input... Documentation/notation/input.itely:987: @end lilypond On 2011/05/04 17:08:39, Carl wrote: > Need @seealso here, with all of the @ref in this node (Default layout of book > and title blocks). This section is not being done until the above node is complete - see previous comment by Graham
Sign in to reply to this message.
http://codereview.appspot.com/4124056/diff/32001/Documentation/notation/input... File Documentation/notation/input.itely (right): http://codereview.appspot.com/4124056/diff/32001/Documentation/notation/input... Documentation/notation/input.itely:674: @example On 2011/05/05 11:05:22, J_lowe wrote: > Yes we did, you'll also remember that you sent out an email to dev asking for > help as I struggled to get this working No, it's worse than that -- I sent an email to the *user* list. Almost every user knows the answer. Certainly anybody who asks about scheme or page layout knows the answer. > and it seemed to me that there are some > very specific places where it will and won't work. It's not any more or less specific than any other type of layout command. > :( Yes, definitely. I'll poke people again.
Sign in to reply to this message.
On 2011/05/05 23:06:25, Graham Percival wrote: > http://codereview.appspot.com/4124056/diff/32001/Documentation/notation/input... > File Documentation/notation/input.itely (right): > > http://codereview.appspot.com/4124056/diff/32001/Documentation/notation/input... > Documentation/notation/input.itely:674: @example > On 2011/05/05 11:05:22, J_lowe wrote: > > Yes we did, you'll also remember that you sent out an email to dev asking for > > help as I struggled to get this working > > No, it's worse than that -- I sent an email to the *user* list. Almost every > user knows the answer. Certainly anybody who asks about scheme or page layout > knows the answer. > > > and it seemed to me that there are some > > very specific places where it will and won't work. > > It's not any more or less specific than any other type of layout command. > > > :( > > Yes, definitely. > > I'll poke people again. Thanks, with that and my going back and re-reading the replies I have come up with an example and a para before the example, which I think might be a bit convoluted :) comments welcome. Nearly there I think?
Sign in to reply to this message.
LGTM 2011/5/19 <pkx166h@gmail.com> > On 2011/05/05 23:06:25, Graham Percival wrote: > > > http://codereview.appspot.com/4124056/diff/32001/Documentation/notation/input... > >> File Documentation/notation/input.itely (right): >> > > > > http://codereview.appspot.com/4124056/diff/32001/Documentation/notation/input... > >> Documentation/notation/input.itely:674: @example >> On 2011/05/05 11:05:22, J_lowe wrote: >> > Yes we did, you'll also remember that you sent out an email to dev >> > asking for > >> > help as I struggled to get this working >> > > No, it's worse than that -- I sent an email to the *user* list. >> > Almost every > >> user knows the answer. Certainly anybody who asks about scheme or >> > page layout > >> knows the answer. >> > > > and it seemed to me that there are some >> > very specific places where it will and won't work. >> > > It's not any more or less specific than any other type of layout >> > command. > > > :( >> > > Yes, definitely. >> > > I'll poke people again. >> > > Thanks, with that and my going back and re-reading the replies I have > come up with an example and a para before the example, which I think > might be a bit convoluted :) comments welcome. > > Nearly there I think? > > http://codereview.appspot.com/4124056/ > > _______________________________________________ > lilypond-devel mailing list > lilypond-devel@gnu.org > https://lists.gnu.org/mailman/listinfo/lilypond-devel >
Sign in to reply to this message.
It's not perfect (I didn't comment on a few things), but it's now unquestionably better than the existing material. Please push. :) http://codereview.appspot.com/4124056/diff/40001/Documentation/notation/input... File Documentation/notation/input.itely (right): http://codereview.appspot.com/4124056/diff/40001/Documentation/notation/input... Documentation/notation/input.itely:548: @warning{Remember when adding a @bs{}@code{header} block inside a The first block inside a \score must be the music expression; the \header block cannot be first. http://codereview.appspot.com/4124056/diff/40001/Documentation/notation/input... Documentation/notation/input.itely:674: The default settings for @code{scoreTitleMarkup} place the @code{piece} delete this sentence; it's covered in the image.
Sign in to reply to this message.
Pushed as 9bc65fa2efa4711ce96c648db6d703ae190f944c Graham, if you want to add your 'new' comments now here, I can pick these up and run with a new issue number for these changes. I still need to look at the 'second half' as you mentioned that in a comment in one of the earlier drafts, that 'for now lets concentrate on the first part'. Thanks to everyone for the help (inc Mark P).
Sign in to reply to this message.
On 2011/05/04 17:08:39, Carl wrote: > Looks mostly good to me. > > Carl > > http://codereview.appspot.com/4124056/diff/32001/Documentation/notation/input... > File Documentation/notation/input.itely (right): > > http://codereview.appspot.com/4124056/diff/32001/Documentation/notation/input... > Documentation/notation/input.itely:667: Text fields left unset in a > @code{\header} block are replaced with > This paragraph has three different ideas -- null markups, piece and opus, and > forcing titles to start on a new page. > > They should probably be separated into three different paragraphs. > > http://codereview.appspot.com/4124056/diff/32001/Documentation/notation/input... > Documentation/notation/input.itely:937: > Need @seealso for the @ref in this node -- Title blocks explained, Default > layout of book and score title blocks,. > > http://codereview.appspot.com/4124056/diff/32001/Documentation/notation/input... > Documentation/notation/input.itely:987: @end lilypond > Need @seealso here, with all of the @ref in this node (Default layout of book > and title blocks). Carl, I have done this now (and the one above). We only really focused on the 'first half' of the text that Mark did (and also hammer out all the @lilypond settings too). I am going to close this issue - I left it open only because I remembered you wanted some additions that were not going to be in the main patch, and open a new one with these and other changes. I also wanted to make some more 'edits' to this text once the major changes were done to keep some layout and style consistency.
Sign in to reply to this message.
|
