[Top][All Lists]
[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
Re: doc enhancement for \headers, Mark Mathias, 2012/07/07