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.