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

[Phil Holmes]

----- Original Message ----- 
From: <address@hidden>
To: <address@hidden>
Cc: <address@hidden>; <address@hidden>
Sent: Sunday, June 29, 2014 3:44 PM
Subject: Re: Adds incipit section to NR (issue 108270043 by 
address@hidden)


> https://codereview.appspot.com/108270043/diff/1/Documentation/notation/ancient.itely
> File Documentation/notation/ancient.itely (right):
>
> https://codereview.appspot.com/108270043/diff/1/Documentation/notation/ancient.itely#newcode2663
> Documentation/notation/ancient.itely:2663: incipit =
> That's nothing belonging in the manual proper.  It is an ad-hoc recipe.
> Those belong in the snippets.

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

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.

Therefore I have created documentation to show how to produce 
standard-looking incipits quickly and simply.  Had it been there when I 
wanted it, it would have saved me a lot of time.

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.  If the code is taken into the code base I'd be happy to 
update this section of the NR.

--
Phil Holmes