[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

bug#20637: incompatible, undocumented change to vc-working-revision

From: Dmitry Gutov
Subject: bug#20637: incompatible, undocumented change to vc-working-revision
Date: Sun, 17 Apr 2016 03:27:38 +0300
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:45.0) Gecko/20100101 Thunderbird/45.0

On 04/15/2016 04:23 PM, Michael Albinus wrote:

I'm not against this. But I would like to see the whole picture
first. Where else unregistered is used, and whether we run into
conflicts when using nil instead of unregistered.

Sure. I'm reasonably confident, but please take the time and do your own evaluation.

I disagree. The manual is the documentation for the users, to explain
in depth, give examples, et cetera. The docstrings and VC's internal
documentation have to stand on their own. It would be silly if the
difference between `vc-backend' and `vc-responsible-backend' were to
only be explained in the manual, but not in the docstrings.

Are we speaking about different manuals? I'm speaking about the ‘GNU
Emacs Lisp Reference Manual’, and not the ‘GNU Emacs Manual’ (the manual
dedicated to users).

I've split off a tangent to emacs-devel. Emacs Lisp Reference is a counter-example, but I think the last sentence in my paragraph above is still correct.

VC has been documented in the docstrings and the Commentary sections (especially the one at the begining of vc.el). The new important information should go there first.

If then you'd like to create a manual based on that information, to present it in more digestible form, sure, but let's not put anything essential into the manual only. We might avoid publishing that manual, though, until we're sure that VC is rock-solid to build third-party code on.

That would also be unfair to people such as myself who prefer to
consult the latter.

With your argument, we could nuke the Emacs Lisp manual. Shall we?

Does your argument allow nuking all docstrings and comments?

So, do you need anything from me in this area? E.g., feel free to give
a list of docstrings that seem insufficient to you, together with what
you feel they are missing.

I will start somehow, and show you for review.


I usually tease that kind of information out by reading the source
code. Is there anything in particular I could help add to your
understanding of the "global view"?

Even if I understand it, it won't help any other developer. Let's
document it.


reply via email to

[Prev in Thread] Current Thread [Next in Thread]