Re: [PATCH] Doc: LM: Reformat ly code.

[James Lowe]

Hello,

Trevor Daniels wrote:
> Mark Polesky wrote Tuesday, May 04, 2010 5:34 AM
> > Trevor Daniels wrote:
> > > Carl Sorensen wrote:
> > > > I think we should always use bar-checks when the piece
> > > > is more than one bar long.  That's a good habit to get
> > > > into; we ought to start it right from the first.
> > >
> > > I would agree with this.  In fact I put bar checks into
> > > quite a few of the examples in the LM originally, but they
> > > seem to have been removed.
> >
> > Perhaps the reason for removing the bar checks was that
> > they're not explained at all in the LM.  Do you think we
> > should mention bar checks (briefly) near the beginning of
> > the LM, without going into detail?  Then we'd be justified
> > using them in the examples.
>
> I don't think that was the reason, but you make a good point.

Actually, being the person who is responsible for removing many (not 
all) of the bar checks, that is one of the reasons.

Going through many of the ly examples, there would often be just a 
single line with a bar check at the end of it. The point of the lily 
examples was to show an example of the specific function that was being 
referred to in whatever place the manual the user was looking.

Adding 'irrelevant' (for the specific example being referred to) symbols 
just complicated the matter when they were at the end of a single line 
of music.

You will notice that when an example uses two measures on a single line 
we do keep the bar checks in - this is for clarity more than anything 
else. I did start putting every new measure on a new line (taking the CG 
literally) and it quickly became obvious that this would actually stop 
the example being easy to understand - which is the point of the Manuals.

Having a single bar check in the middle of the line but not at the end 
for a two-measure-per-line example looked very wrong so we left them in.

Having bar checks in (or any other function/symbol/markup) in an example 
just for the sake of it or just because the more experienced users know 
this is the best way is kind of beside the point (especially in the LM) 
unless it is relevant to the example.

Graham, Neil (I think) and I did discuss this at great length amongst 
other things, so it wasn't just an exercise in getting me to understand 
git to push patches as perhaps Graham implied (or perhaps I inferred), 
there was method to the 'madness'.

> Actually there is a convoluted path to bar checks from
> LM 1.3.1 Dealing with errors/General troubleshooting tips.
> The link there to Troubleshooting takes you to Usage 5.4
> and under Usage 1.4 Common errors there's a link to Bars
> in the NR which contains a section on bar checks.  This
> seems a pretty successful way of hiding the solution to
> probably the most common problem encountered by the new
> user.  IIRC I put this section on Common errors in the LM when I wrote it.
>
> A brief description of bar checks in 1.2.2 Working on input
> files would be good.  I think bar checks are at least as
> important as a \version statement, which is mentioned there.

If any one wants to make suggestions I'll be more than happy to 
implement them.

Regards

James

> Trevor
>
>
>
>
>
> _______________________________________________
> lilypond-devel mailing list
> address@hidden
> http://lists.gnu.org/mailman/listinfo/lilypond-devel