[Top][All Lists]

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

Re: doc enhancement for \headers

From: Graham Percival
Subject: Re: doc enhancement for \headers
Date: Mon, 9 Jul 2012 23:32:10 +0100
User-agent: Mutt/1.5.21 (2010-09-15)

On Mon, Jul 09, 2012 at 01:09:50AM +0200, David Kastrup wrote:
> Graham Percival <address@hidden> writes:
> > On Thu, Jul 05, 2012 at 11:16:52AM -0700, -Eluze wrote:
> > 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.

... I'm not certain what you mean by this.  Are you agreeing or
disagreeing with my claim that working examples are easy to
maintain and easy to read?

IMO the second page in that link is an example of great
documentation.  You can clearly see the variables, how the effect
the page creation [1], etc.  Granted, by asking for a full working
example, I'm suggesting that we have a bit of "boilerplate" code
in there as well, so it wouldn't be _quite_ as clear as the latex
example.  But anybody looking up such details in Notation
shouldn't be confused by the order of \score{} and \paper{}, and
IMO the ease of maintaining a full working example in the docs
makes that trade-off well worth it.

[1] http://xkcd.com/326/

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

Sure.  But we're all fluent in "ly", and there's now pretty good
understanding of the term "Tiny examples", so I expect that it's
much easier to create high-quality "ly" explanations than
high-quality "english" explanations.

- Graham

reply via email to

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