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

[dak]

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


> > On 2014/06/29 15:15:51, http://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.


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