bug-lilypond
[Top][All Lists]
Advanced

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

Re: doc enhancement for \headers


From: David Kastrup
Subject: Re: doc enhancement for \headers
Date: Mon, 09 Jul 2012 01:09:50 +0200
User-agent: Gnus/5.13 (Gnus v5.13) Emacs/24.1.50 (gnu/linux)

Graham Percival <address@hidden> writes:

> On Thu, Jul 05, 2012 at 11:16:52AM -0700, -Eluze wrote:
>> 
>> Graham Percival-3 wrote:
>> >> there are 13 variables that can be defined in the \header block and which
>> >> will be used by the default header and footnote engraver:
>> > 
>> > The problem with such a list is that it's easy to forget to update it… 
>> 
>> certainly, but a documentation is only worthwhile if it shows the actual
>> state - I think LilyPond does a great effort to keep documentations
>> up-to-date and if there's a problem with it this should be attacked from
>> another starting point.
>
> It _is_ attacked from another starting point -- by explaining as
> much as possible with working examples.

If I have twenty relevant variables, I don't want to look for 200 lines
of prose for finding the right one to use, and not through 400 lines of
examples.  I am more interested in 20 one-liners.  And possibly a single
example where each field is set to its own name, so you can look at the
output and immediately see what goes where.  Non-textual fields are
somewhat more problematic.  Take a look at the second page in
<URL:ftp://ftp.fu-berlin.de/tex/CTAN/macros/latex/required/tools/layout.pdf>.
Yes, definitely more effort than writing twenty paragraphs of text.

> But what's one "language" that we all speak?  Regardless of our
> country, any programming mind-set, etc?  well, "lilypond", of
> course.

You can bore and confuse in every language including "LilyPond".

> It's really easy (for some people) to write whole gobs of text to
> explain stuff -- and it's easy (for some people) to skim through whole
> gobs of text without understanding anything.  But if there's an .ly
> example that shows exactly what to do, then it's easier for people to
> update that .ly if needed, and it's easier for a "lazy reader" (like
> me) to realize that the answer to their problem really is in the docs
> and they just need to slow down and understand the example.

I wish we had more people with the talent or will of creating
documentation one can take in midflight, without slowing down.  That's a
lot of work, and it starts with slowing down and understanding whatever
the creators of functionality put in the docs, and more likely than not,
finding out a few things that they failed to put there.  That's one very
important non-programmer opening that we have that could use a lot more
talent.

-- 
David Kastrup




reply via email to

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