Re: Overlong nodes in the Emacs Lisp Manual

[Luc Teirlinck]

Richard Stallman wrote:

   Would someone please look through the Emacs Lisp Manual
   for nodes that are inconveniently long, and send me a list
   of nodes you recommend perhaps splitting?

Note that splitting (or renaming) a node is a very disruptive
operation, because after doing that many xrefs (as well as hyperlinks
from docstrings and Custom buffers) may point to a wrong node (or to
nowhere).  If one splits or renames a node, one should at the very
least carefully grep the lispref and man directories, as well as (for
docstrings and Custom buffers) the src directory and the lisp
directory and all its subdirectories.  There is of course no way to
avoid messing up xrefs or hyperlinks in docs not included with the
Emacs distribution.

We discussed this before and decided then that all the work involved
in systematically splitting all large nodes was not worth holding up
the release and that, moreover, several of the very largest nodes
(including the record holder, `(elisp)Window Frame Parameters', 342
lines), could not be split in any natural way.  It would have been
relatively better to do this before starting to proofread the Elisp
manual, because that way there would have been a better chance of
spotting trouble with bad references before they got included with the
release.

In as far as the recent split of `Minibuf Misc' is concerned, doing
M-x find-grep-dired on the `emacs' directory for the old node name and
then using the Dired `A' command for the old node name with all
potential trouble files marked, turned up two newly incorrect
references, which I already corrected in CVS.  The reason that there
were "only" two was that I already replaced many xrefs to that node
with anchors, which are immune to renaming and splitting.  Otherwise,
there would have been a lot more.

Sincerely,

Luc.