bug reports vs manuals [Re: shell completion documentation]

[Ilya N. Golubev]

> Bug reports and manuals are not comparable.

Only partially.  After all, they describe the related things, the
incorrect / correct behaviors of some tool.  And to state that the
behavior is incorrect, one has to have a definition of correct
behavior, which is normally supposed to be in documentation.  So bug
report normally relies on documentation.

> details; if they make the
> bug report hard to read, we just have to roll up our sleeves and read
> it anyway.

If something it hard to read, writing it is generally even harder.
And if something is hard to read even for maintainers, how can one
expect user to write that?

> there is no obligation to make the manual so hard to read,

Only in sense of no obligations for this program at all, as described
by C-h C-w.  Still one would normally expect documentation to answer
which behavior is correct and which is not.

> and it would be counterproductive to do so.

What is the alternative?  Not to document the correct behavior once
and forever, perhaps in some appendix, but instead to have users in
every discussion of software, bug reports or other, describe it again
and again.  Do you call this <productive>?


Anyway, for this particular issue, comint commands when
`inhibit-field-text-motion', have already described which behavior is
desired and why.