[Pkg-emacsen-addons] Bug#905081: Bug#905081: improve documentation for buster

[David Bremner]

Nicholas D Steeves <nsteeves at gmail.com> writes:

> On Tue, Jul 31, 2018 at 03:43:13PM +0800, David Bremner wrote:
>> Nicholas D Steeves <nsteeves at gmail.com> writes:
>> 
>> >
>> > As why I feel "ok, this is a necessity now"?  Our recent changes to
>> > emacs-goodies-el are disruptive.  Hopefully most users will be
>> > satisfied, or will be apathetic, but I feel like dh-elpa documentation
>> > should be improved for Buster's release, both for the benefit of
>> > curious users and users who might think "argh, why?!"
>> >
>> > Source material thus far: tribal knowledge, an email or planetdebian
>> > (I think) post Sean wrote a long time ago.  Various other bits from
>> > conversations, bug reports, and emails.
>> >
>> > Let's codify it: Objective, Scope, Interactions, Pros, Cons,
>> > Relationship to MELPA, Culture of cargo culting snippets, MELPA
>> > culture, Emacswiki, Debian culture.
>> >
>> > Yeah, that's too much info, but I think that list is more or less
>> > comprehensive.  Feel free to suggest anything that ought to be added,
>> > cut, or published elsewhere.
>> >
>> 
>> Is there some reason this can't go in a wiki page?
>
> I guess it could, but dh-elpa's documentation is still in an
> early-middle phase of project state and it this point lintian is
> emitting a warning for packages that haven't yet been converted to use
> dh-elpa, so we really ought to improve its documentation at least to
> the point where it's a more mature late-middle phase of a project
> state.  eg: 1) see lintian warning  2) install dh-elpa  3) read the
> man page or README  4) Aha, that's why I should use it, this makes
> sense.  5) maintainers convert their package to dh-elpa.
>

I guess a seperate README-ish file is fine. I'd rather not add stuff to
to man pages that will just confuse people who are trying to use the
tool, rather that decide if they should use it.

> As for why not a wiki page?  Having maintained a large moinmoin page
> for a year or two I can unreservedly say that I'm not interested in
> long-term maintenance of another page.  Especially without an emacs
> mode to do edits...  I'm more motivated to maintain it in texinfo (in
> git) than moinmoin, and I don't even like texinfo.

OK, but I don't really want to do dh-elpa uploads to update this
document, whose contents are mostly independent of the software.

It sounds to me like what you are talking about might be more along the
lines of an emacs addons team policy. I'd suggest writing such a
document in rst / markdown / texinfo

d