Re: [Emacs-diffs] widen-limits c331b66: Implement buffer-widen-limits functionality

[Eli Zaretskii]

> Date: Thu, 24 Mar 2016 07:41:50 -0700 (PDT)
> From: Drew Adams <address@hidden>
> Cc: address@hidden, address@hidden, address@hidden
> 
> > > And the text about indentation and the use of sub-mode for only a given
> > > chunk of text in a buffer is incomprehensible without some explanation.
> > > Normally, a major mode, no matter whether it is derived from some other
> > > major mode, has its effect on the entire buffer.
> > >
> > > It seems there is some non-negligible functionality/behavior/feature
> > > that has not been documented.  Not up to Emacs standards, it appears.
> > >
> > > It looks like someone perhaps implemented something and just tossed
> > > some minimal doc into the manual, in the form of doc-string-like text
> > > for a couple functions.  Insufficient.
> > 
> > "Compliments" such as these for something that caused me a
> > considerable effort to produce where no documentation by the code
> > developers existed in the first place is a very efficient method of
> > convincing me never to make such efforts again.  Not for this
> > community, anyway.  Thanks a lot!
> 
> Please consider it instead as a statement that "the code
> developers" for this feature (whatever it might be) should
> themselves have documented it.  Which is also what I think
> you suggest.
> 
> My plaint wrt what the user sees now (incomplete doc) is
> essentially the same as your plaint that the code developers
> did not provide adequate doc.  I don't at all complain about
> your effort to improve a complete lack by providing something
> helpful.

The documentation is complete.  I have just re-read it to be sure, and
I see no flaws there.  If you still think there are gaps, and if the
current text is unclear to you, that's a clear sign that the use cases
in which these features are supposed to be used are something you
never bumped into, and therefore you don't have a clear picture of the
issues.  Which is not a catastrophe, but it does mean that you are not
the best person to criticize this part of the documentation.

> As a user learning about this question for the first time, I
> searched the manuals for "sub-mode" and similar expressions
> to learn more, and came up empty-handed.  I reported that.

It is clear to anyone who understand the situations which need these
features.  Examples of such situations are part of the text in the
manual.  The fact is that this discussion thread references "sub-mode"
or "submode" several times, and people who used that terminology
evidently have to difficulty understanding what it is.