Merge branch 'widen-less' into emacs-26

1 files changed, 10 insertions, 46 deletions

diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
index 1e19f75d682..0ec1998da40 100644
--- a/doc/lispref/text.texi
+++ b/doc/lispref/text.texi
@@ -2396,57 +2396,31 @@ text at point (@pxref{Completion in Buffers}).
 syntax belongs to a different major mode.  Examples include
 @dfn{literate programming} source files that combine documentation and
 snippets of source code, Yacc/Bison programs that include snippets of
-plain C code, etc.  To correctly indent the embedded chunks, the major
+Python or JS code, etc.  To correctly indent the embedded chunks, the primary
 mode needs to delegate the indentation to another mode's indentation
-engine (e.g., call @code{c-indent-defun} for C code or
+engine (e.g., call @code{js-indent-line} for JS code or
 @code{python-indent-line} for Python), while providing it with some
-context to guide the indentation.  The following facilities support
-such multi-mode indentation.
+context to guide the indentation.  Major modes, for their part, should
+avoid calling @code{widen} in their indentation code and obey
+@code{prog-first-column}.
 
 @defvar prog-indentation-context
 This variable, when non-@code{nil}, holds the indentation context for
 the sub-mode's indentation engine provided by the superior major mode.
-The value should be a list of the form @code{(@var{first-column}
-@w{(@var{start} . @var{end})} @code{prev-chunk})}.  The members of the
-list have the following meaning:
+The value should be a list of the form @code{(@var{first-column} . @var{rest}}.
+The members of the list have the following meaning:
 
 @table @var
 @item first-column
 The column to be used for top-level constructs.  This replaces the
 default value of the top-level column used by the sub-mode, usually
 zero.
-@item start
-@itemx end
-The region of the code chunk to be indented by the sub-mode.  The
-value of @var{end} can be @code{nil}, which stands for the value of
-@code{point-max}.
-@item prev-chunk
-If this is non-@code{nil}, it should provide the sub-mode's
-indentation engine with a virtual context of the code chunk.  Valid
-values include:
-
-@itemize @minus
-@item
-A string whose contents is the text the sub-mode's indentation engine
-should consider to precede the code chunk.  The sub-mode's indentation
-engine can add text properties to that string, to be reused in
-repeated calls with the same string, thus using it as a cache.  An
-example where this is useful is code chunks that need to be indented
-as function bodies, but lack the function's preamble---the string
-could then include that missing preamble.
-@item
-A function.  It is expected to be called with the start position of
-the current chunk, and should return a cons cell
-@w{@code{(@var{prev-start} . @var{prev-end})}} that specifies the
-region of the previous code chunk, or @code{nil} if there is no previous
-chunk.  This is useful in literate-programming sources, where code is
-split into chunks, and correct indentation needs to access previous
-chunks.
-@end itemize
+@item rest
+This value is currently unused.
 @end table
 @end defvar
 
-The following convenience functions should be used by major mode's
+The following convenience function should be used by major mode's
 indentation engine in support of invocations as sub-modes of another
 major mode.
 
@@ -2457,16 +2431,6 @@ function's value is the column number to use for top-level constructs.
 When no superior mode is in effect, this function returns zero.
 @end defun
 
-@defun prog-widen
-Call this function instead of @code{widen} to remove any restrictions
-imposed by the mode's indentation engine and restore the restrictions
-recorded in @code{prog-indentation-context}.  This prevents the
-indentation engine of a sub-mode from inadvertently operating on text
-outside of the chunk it was supposed to indent, and preserves the
-restriction imposed by the superior mode.  When no superior mode is in
-effect, this function just calls @code{widen}.
-@end defun
-
 
 @node Region Indent
 @subsection Indenting an Entire Region