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

[Graham Percival]

On Sun, May 2, 2010 at 7:01 PM, Mark Polesky <address@hidden> wrote:
> First, if you haven't looked at it yet, you should know that
> one direct result of the patch is the increase in length of
> many of the examples (vertically).  Graham has already
> expressed his dissatisfaction with this, since it increases
> the chances of individual examples being split across pages
> in the PDF version.

Not only in PDF, but other formats, of course... have you tried
reading the docs on a netbook screen?  Trust me, space is a premium on
some formats/circumstances.


> But the assumption, that I think things like this are too
> hard to read on one line, is incorrect:
>  \new Staff { \clef treble c4 }

Then why change it?  :)

> My rationale (and feel free to defend your opposition) is:
>
> 1) that we should have a basic "programming style" that most
>   (if not all) of us can agree on,

TOTALLY agreed.  I've been waiting impatiently for the right time to
start GLISS for over three years.

That time is not now.

> 2) that the programming style should make ly code easier to
>   * read   (eg. as on the mailing lists)
>   * modify (eg. being able to move stuff from one voice to
>                 another and back without needing to change
>                 some note's relative octave each time)
>   * debug  (eg. \lilycommands are harder to comment out if
>                 they're in the middle of a line of notes)
>   * update (ie. with convert-ly), and

Yes, other than some quibbles about your "modify" example.  However, I
would argue that in the context of a longer example focusing on
constructing a complicated piece of music,
 \new Staff { \clef treble c4 }
is easier to read than
 \new Staff {
    \clef treble
    c4
  }
because it allows you to see more of the piece's structure at once.


> 3) that the docs should use that style consistently, because
>   among other things, I think the docs should always
>   present the best example of good formatting.

Not necessarily.  Or rather -- I'd argue that "good formatting" will
be context-dependent.  If you're entire staff is:
 \new Staff { \clef treble c4 }
then I suggest that *this* is the "good formatting", not the expanded
version. OTOH, if you have a dozen notes, especially with complicated
rhythms, articulations, etc, then the "good formatting" would be the
expanded form.


But more than anything else, I don't think that this is the right time
to occupy people's attention with a debate about code formatting.


> I think it would be
> more appropriate to address that with some script to
> minimize orphans/widows;

Sadly, nobody wants to work on
http://code.google.com/p/lilypond/issues/detail?id=1019

> I think that compromising the
> formatting of the example code is the wrong approach.

I agree, but disagree that the compact form is "compromising the formatting".

> So should we wait for GLISS?  Honestly, I don't see why we'd
> need to.  I'm not proposing that we formalize everything all
> at once and right away, but there are some basics that we
> can probably agree on.

No, we can't agree on these basics.  :)

Code formatting is precisely the kind of thing that starts huge
bikeshed discussions, and occupies huge amounts of time.  Please,
please, wait until GLISS.

Cheers,
- Graham