[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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

From: Mark Polesky
Subject: Re: [PATCH] Doc: LM: Reformat ly code.
Date: Sun, 2 May 2010 11:01:01 -0700 (PDT)

Graham Percival wrote:
>> If anyone is up to it, I'd like someone to look over the
>> patch to see if I've made anything worse.
> I started looking, and saw some questionable stuff.  I'll
> take a longer look later today, after I wake up and have
> coffee.

(the patch is at )

Before anyone gets too worked up about this patch, I think I
should explain my rationale for proposing these changes.

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.

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

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,
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
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.

So do I think that this specific case is hard to read?
  \new Staff { \clef treble c4 }

No.  But I *do* think that doing this instead is a "good
coding habit", that should be consistently employed:
  \new Staff {
    \clef "treble"

And do I care about examples of programming code being split
across pages in the PDF version?  Not reallly.  Perhaps it's
a small nuisance, but hardly a priority.  It happens all the
time in published programming books.  I think it would be
more appropriate to address that with some script to
minimize orphans/widows; I think that compromising the
formatting of the example code is the wrong approach.

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.

I hope this doesn't start a flame war...
- Mark

ps. Graham, I'll reply to certain things more specifically
    on the Rietveld page.


reply via email to

[Prev in Thread] Current Thread [Next in Thread]