On 2014/06/29 16:51:06, email_philholmes.net wrote:
----- Original Message ----- From: <mailto:d...@gnu.org> To: <mailto:philehol...@googlemail.com>; <mailto:em...@philholmes.net> Cc: <mailto:lilypond-devel@gnu.org>;
<mailto:re...@codereview-hr.appspotmail.com>
Sent: Sunday, June 29, 2014 5:26 PM Subject: Re: Adds incipit section to NR (issue 108270043 by mailto:philehol...@googlemail.com)
> On 2014/06/29 15:15:51, http://email_philholmes.net wrote: >> From: <mailto:d...@gnu.org> >> To: <mailto:philehol...@googlemail.com> >> Cc: <mailto:lilypond-devel@gnu.org>; > <mailto:re...@codereview-hr.appspotmail.com> >> Sent: Sunday, June 29, 2014 3:44 PM >> Subject: Re: Adds incipit section to NR (issue 108270043 by >> mailto:philehol...@googlemail.com) > >> > 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.
You seem to have missed the point. Snippets are not judged by the
lilypond
code, but by the ability of the writer to include them into the documentation. I did not need to do this as a snippet, so I didn't.
Sigh. <URL:http://lilypond.org/doc/v2.19/Documentation/contributor/books>: "Notation Reference: a (hopefully complete) description of LilyPond input notation." Incipits are not currently a part of LilyPond input notation, and you appear bent on this staying that way. I don't understand why. <URL:http://lilypond.org/doc/v2.19/Documentation/contributor/documentation-suggestions> "Contributions that contain examples using overrides Examples that use overrides, tweaks, customer Scheme functions etc. are (with very few exceptions) not included in the main text of the manuals; as there would be far too many, equally useful, candidates. The correct way is to submit your example, with appropriate explanatory text and tags, to the LilyPond Snippet Repository (LSR). Snippets that have the "docs" tag can then be easily added as a selected snippet in the documentation. It will also appear automatically in the Snippets lists. See Introduction to LSR." I think that's rather clear. I repeat: complex examples and workarounds belong in the snippets and may be cited from there with the mechanisms we have available for it. Obviously, that's the proper way to integrate the current incipit snippet if that is the goal. Equally obviously, incipits are a frequent enough occurence that we want to provide a regular mechanism instead of just a snippet and document it. I'd add Graham (as the one responsible for writing down the policies you cite in support of copying the snippet into the manual) to the Cc list for an opinion here, but then it would appear that only the owner of a review can do that. While we ultimately need to come to a consensus ourselves, it might save time _when_ a past consensus is dragged into the discussion to make sure to get it right. Consensus-finding is hard enough, so it makes sense to rereference an old consensus in the assumption that the people having come to that consensus spent more time and thought on it than we have so far. But if we cannot come to a consensus about what the consensus actually was judging from the documents pinned down at the time, that will not help us now. https://codereview.appspot.com/108270043/ _______________________________________________ lilypond-devel mailing list lilypond-devel@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-devel
