Re: Adds incipit section to NR (issue 108270043 by address@hidden)

[dak]

On 2014/06/29 15:15:51, email_philholmes.net wrote:
> From: <mailto:address@hidden>
> To: <mailto:address@hidden>
> Cc: <mailto:address@hidden>;
<mailto:address@hidden>
> Sent: Sunday, June 29, 2014 3:44 PM
> Subject: Re: Adds incipit section to NR (issue 108270043 by
> mailto:address@hidden)

> > Incipits are common enough that we want to have them in the manual,
> > sure, but as a reasonably usable and maintained command rather than
a
> > wagonload of snippet code.

> > That's embarrassing, to say the least.  At any rate, the snippet
code
> > does not belong in NR proper.  Incipit functionality does, but not
as a
> > snippet.  This needs to become a usable command out of the box
again.

> Well, it seems to me you're not considering why the snippets in the
LSR are
> there.  The CG says "A subset of these examples are automatically
imported
> into the documentation, making it easy for users to contribute to the
docs
> without learning Git and Texinfo." - so the snippets are designed to
allow
> users who can't push doc changes to the repo a chance to add
documentation
> to the manuals.  Nothing to do with the sort of code, simply an
alternative
> route.

And we have a standard way to include snippets contributed in that
manner, using the @snippets command.  That's not what you are doing
here.  You are doing a copy&paste section into the NR files themselves.
That separates the ties between the snippets maintained in the LSR and
the code listed in the NR.  Where we are talking about snippets
documenting a basic feature that was lacking documentation in the
manual, that is a reasonable way forward.

But that's not what we are talking about here.  We are talking about a
complex (though somewhat straightforward) bout of code.  In the manual
proper, it would have sort of a reason to be in an "extending LilyPond"
section.

But code defining a music function does not belong in any part of the
basic manual except those parts dealing with using music functions for
extending LilyPond.  The main body of the reference manual is not a
"tricks & tips" collection.  That's what the snippets are for, and we
have a standard way to include snippets in the manual.

> When I wanted a usable incipit, I went straight to the section of the
NR
> headed "Incipits" because I've worked out this is a good way of
getting
> usable code.  Unfortunately it said "TBC" which was as useful as a
chocolate
> teapot.  I eventually found this code, which does what I want, in the
> snippets/new directory.

So if it does what you want in a basic manner, it belongs into LilyPond.
 Once it is in LilyPond, its use needs to be documented.  What you are
documenting here is not a feature of LilyPond, but a shortcoming.

One can actually use snippets for that, using @snippet.  But that's not
what you do.

> Therefore I have created documentation to show how to produce
> standard-looking incipits quickly and simply.

No, you haven't.  You have created documentation that shows how to
produce standard-looking incipits with a lot of effort.  Basically
consider the manual to be printed as a book.  Whenever you need to type
off oodles of opaque code that does not match the level that the chapter
is supposed to be explaining, you are likely to get mistakes into them.

> Had it been there when I wanted it, it would have saved me a lot of
time.

Then place it in the @snippets section of the respective chapter.  Or
put it there where you'd indeed want it, namely into LilyPond's code and
then document it as being there.

Anything that is in the manual outside of a @snippet section describes a
feature that is supported and will get upgraded when using convert-ly.
Humongous bunches of mixed Scheme and LilyPond code in general don't
carry any such guarantee.

> Please feel free to correct errors in what I have contributed, but as
a
> major user of the ancient music capabilities, I am convinced this
section
> should be there.

This section should be documenting an existing facility.  The *feature*
should be there, and yes, it *should* be documented and supported.  A
code dump of unsupported code outside of the @snippets section of a
chapter does not belong there.

Perhaps it would make sense if you first rewrote the chapter under the
pretense that incipits are available with the most practical and useful
interface you can imagine.

And when everybody agrees "oh man, _that's_ just what we need", then
we'll take care that we make it available in that manner.

The current example, in spite of its use of a music function, still
seems rather opaque.  It may be that the example is not structured well,
it may be that the interface of the music function has not been chosen
well.

So please try writing the documentation pretending that we have the best
imaginable interface to incipits you can imagine.  The code I quoted for
use with version 1.0.14 was quite straightforward.  It probably did not
allow switching in entirely different staff types.

So how should it look like?

\incipit MensuralStaff \with { xxx=yyy } { \time 3/2 ... } translating
into a set of \once\override for instrumentName and the related
properties?  With \with ... being optional?

Would that fit the bill for creating straightforward input with
incipits?  The stuff where you don't need a copy&paste from the manual,
and after having it looked up three times or so, don't need to look at
the manual either?

https://codereview.appspot.com/108270043/