Swap the role of `replace-region-contents` and `replace-buffer-contents`,
so `replace-region-contents` is the main function, implemented in C,
and `replace-buffer-contents` is a mere wrapper (marked as obsolete).
Also remove the need to rely on narrowing and on describing the
new text as a function.
Finally, allow MAX-SECS==0 to require a cheap replacement, and
add an INHERIT argument.

* src/editfns.c: Include `coding.h`.
(Freplace_region_contents): Rename from `Freplace_buffer_contents`.
Change calling convention to that of `replace-region-contents`.
Add more options for the SOURCE argument.  Add INHERIT argument.
Skip the costly algorithm if MAX-SECS is 0.
* src/insdel.c (replace_range): Allow NEW to be a buffer.

* lisp/subr.el (replace-buffer-contents): New implementation.
* lisp/emacs-lisp/subr-x.el (replace-region-contents): Delete.

* doc/lispref/text.texi (Replacing): Document new API for
`replace-region-contents`.  Remove documentation of
`replace-buffer-contents`.

* test/src/editfns-tests.el (replace-buffer-contents-1)
(replace-buffer-contents-2, replace-buffer-contents-bug31837):
Use `replace-region-contents`.
(editfns--replace-region): Delete.
(editfns-tests--replace-region): Use `replace-region-contents`.
Adds tests for new types of SOURCE args.

894b0e3a2fe ; Adapt comment in tramp.el
cc87717fa07 Add keyword placeholder to tramp.el
7d0d61d8549 Rewrite ERT manual introduction
b2f124f2a88 ; cperl-mode.el: Don't misinterpret exec_fcn as keyword exec
59d1aac49df Document return values of the various read-* functions

* lisp/textmodes/string-edit.el (read-string-from-buffer):
* lisp/simple.el (read-from-kill-ring, read-shell-command)
(read-signal-name):
* lisp/replace.el (read-regexp-case-fold-search):
* lisp/auth-source.el (read-passwd):
* lisp/subr.el (read-key, read-number):
* lisp/minibuffer.el (read-file-name, read-no-blanks-input):
* lisp/international/mule-cmds.el (read-multilingual-string):
* lisp/language/japan-util.el (read-hiragana-string):
* lisp/files-x.el (read-file-local-variable)
(read-file-local-variable-mode, read-file-local-variable-value):
* lisp/faces.el (read-face-font, read-face-name):
* lisp/simple.el (read-extended-command):
* lisp/env.el (read-envvar-name):
* lisp/files.el (read-directory-name):
* lisp/faces.el (read-color):
* lisp/international/mule-diag.el (read-charset):
* lisp/emacs-lisp/map-ynp.el (read-answer):
* src/coding.c (Fread_coding_system)
(Fread_non_nil_coding_system):
* src/minibuf.c (Fread_command, Fread_from_minibuffer):
* src/lread.c (Fread_char, Fread_char_exclusive, Fread_event): Doc
fixes.

Since the introduction of the 'calln' macro, the 'call1', 'call2', ...,
'call8' macros are just aliases for the former.  This is slightly
misleading and potentially unhelpful.  The number of arguments N can
also easily go out-of-synch with the used alias callN.  There is no
reason not to replace these aliases with using 'calln' directly.

To reduce the risk for mistakes, the tool Coccinelle was used to make
these changes.  See <https://coccinelle.gitlabpages.inria.fr/website/>.

* src/alloc.c, src/androidvfs.c, src/androidfns.c, src/buffer.c:
* src/callint.c, src/callproc.c, src/casefiddle.c, src/charset.c:
* src/chartab.c, src/cmds.c, src/coding.c, src/composite.c:
* src/data.c, src/dbusbind.c, src/dired.c, src/doc.c:
* src/emacs.c, src/eval.c, src/fileio.c, src/filelock.c:
* src/fns.c, src/frame.c, src/gtkutil.c, src/haikufns.c:
* src/haikumenu.c, src/image.c, src/insdel.c, src/intervals.c:
* src/keyboard.c, src/keymap.c, src/lisp.h, src/lread.c:
* src/minibuf.c, src/nsfns.m, src/nsselect.m, src/pgtkfns.c:
* src/pgtkselect.c, src/print.c, src/process.c, src/sort.c:
* src/syntax.c, src/textconv.c, src/textprop.c, src/undo.c:
* src/w32fns.c, src/window.c, src/xfaces.c, src/xfns.c:
* src/xmenu.c, src/xselect.c, src/xterm.c:
Replace all uses of 'call1', 'call2', ..., 'call8' with 'calln'.

Run "TZ=UTC0 admin/update-copyright".

Run "TZ=UTC0 admin/update-copyright".

5e97079cc75 ; Fix call to 'decode_string_utf_8' in  #ifdef'ed-away code
6902673b5b9 ; Improve commentary in calendar.el
08b62132dde Add 'lua-ts-mode' to 'interpreter-mode-alist'
d8ffcf2fbac Document representation of dates in calendar.el
faaa13ec762 Autoload 'shortdoc-help-fns-examples-function'

* src/coding.c (Finternal_decode_string_utf_8): Fix calling
sequence of 'decode_string_utf_8' to adapt to changes in the
latter's signature.

* src/alloc.c (string_bytes, pin_string, valid_lisp_object_p)
(process_mark_stack, survives_gc_p, syms_of_alloc):
* src/androidterm.c (android_term_init): Replace call to
'build_pure_c_string'.
* src/buffer.c (init_buffer_once, syms_of_buffer):
* src/bytecode.c (exec_byte_code):
* src/callint.c (syms_of_callint):
* src/callproc.c (syms_of_callproc):
* src/category.c (Fdefine_category):
* src/coding.c (syms_of_coding):
* src/comp.c (Fcomp__compile_ctxt_to_file0)
(maybe_defer_native_compilation, syms_of_comp):
* src/data.c (Fsetcar, Fsetcdr, Fdefalias, Faset, syms_of_data):
* src/dbusbind.c (syms_of_dbusbind):
* src/doc.c (Fsnarf_documentation):
* src/emacs-module.c (syms_of_module):
* src/eval.c (Finternal__define_uninitialized_variable)
(Fdefconst_1, define_error, syms_of_eval):
* src/fileio.c (syms_of_fileio):
* src/fns.c (Ffillarray, Fclear_string, check_mutable_hash_table):
* src/fontset.c (syms_of_fontset):
* src/frame.c (make_initial_frame):
* src/haikufns.c (syms_of_haikufns):
* src/intervals.c (create_root_interval):
* src/keyboard.c (syms_of_keyboard):
* src/keymap.c (Fmake_sparse_keymap, Fset_keymap_parent)
(store_in_keymap, syms_of_keymap):
* src/lisp.h:
* src/lread.c (Fload, read0, intern_c_string_1, define_symbol)
(Fintern, defsubr, syms_of_lread):
* src/pdumper.c (Fdump_emacs_portable):
* src/pgtkfns.c (syms_of_pgtkfns):
* src/pgtkterm.c (syms_of_pgtkterm):
* src/process.c (syms_of_process):
* src/search.c (syms_of_search):
* src/sqlite.c (syms_of_sqlite):
* src/syntax.c (syms_of_syntax):
* src/treesit.c (syms_of_treesit):
* src/w32fns.c (syms_of_w32fns):
* src/xdisp.c (syms_of_xdisp):
* src/xfaces.c (syms_of_xfaces):
* src/xfns.c (syms_of_xfns):
* src/xftfont.c (syms_of_xftfont):
* src/xterm.c (syms_of_xterm): Remove calls to 'PURE_P', 'CHECK_IMPURE',
'Fpurecopy', and replace calls to 'build_pure_c_string', 'pure_list',
'pure_listn', etc., by impure equivalents.