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

[Dmitry Gutov]

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.

Thanks.

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

Sure.