[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [PATCH] Doc: LM: Reformat ly code.
From: |
Graham Percival |
Subject: |
Re: [PATCH] Doc: LM: Reformat ly code. |
Date: |
Wed, 5 May 2010 18:55:46 +0100 |
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
- [PATCH] Doc: LM: Reformat ly code., Mark Polesky, 2010/05/02
- Re: [PATCH] Doc: LM: Reformat ly code., Trevor Daniels, 2010/05/02
- Re: [PATCH] Doc: LM: Reformat ly code., Graham Percival, 2010/05/02
- Re: [PATCH] Doc: LM: Reformat ly code., Carl Sorensen, 2010/05/02
- Re: [PATCH] Doc: LM: Reformat ly code., Trevor Daniels, 2010/05/02
- Re: [PATCH] Doc: LM: Reformat ly code., Graham Percival, 2010/05/02
- Re: [PATCH] Doc: LM: Reformat ly code., Mark Polesky, 2010/05/04
- Re: [PATCH] Doc: LM: Reformat ly code., Trevor Daniels, 2010/05/04
- Re: [PATCH] Doc: LM: Reformat ly code., James Lowe, 2010/05/04
- Re: [PATCH] Doc: LM: Reformat ly code., Trevor Daniels, 2010/05/04
- Re: [PATCH] Doc: LM: Reformat ly code., Mark Polesky, 2010/05/04
- Re: [PATCH] Doc: LM: Reformat ly code., Trevor Daniels, 2010/05/04
- Re: [PATCH] Doc: LM: Reformat ly code., James Lowe, 2010/05/05
- Re: [PATCH] Doc: LM: Reformat ly code., James Lowe, 2010/05/05
- Re: [PATCH] Doc: LM: Reformat ly code., Carl Sorensen, 2010/05/04