procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Adjust documentation for make-docfile

Browse source 
* doc/lispref/loading.texi (Autoload): We're no longer using
make-docfile for loaddefs.el, but we're retaining the format.
Adjust the documentation.
* lisp/loadup.el: Adjust commentary.
This commit is contained in:
Lars Ingebrigtsen 2022-08-04 08:05:16 +02:00
parent caa88cfebe
commit c17f1a2e89
2 changed files with 10 additions and 16 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

15
doc/lispref/loading.texi
View file

@ -698,14 +698,13 @@ Switch to *doctor* buffer and start giving psychotherapy.
@noindent
@cindex @code{fn} in function's documentation string
The backslash and newline immediately following the double-quote are a
convention used only in the preloaded uncompiled Lisp files such as
@file{loaddefs.el}; they tell @code{make-docfile} to put the
documentation string in the @file{etc/DOC} file. @xref{Building Emacs}.
See also the commentary in @file{lib-src/make-docfile.c}. @samp{(fn)}
in the usage part of the documentation string is replaced with the
function's name when the various help functions (@pxref{Help
Functions}) display it.
While the @file{loaddefs.el} isn't for editing, we try to keep it
somewhat readable for people. For instance, control characters in
@code{defvar} values are escaped, and we insert a backslash and
newline immediately following the double-quote of the doc string to
keep the line length down. @samp{(fn)} in the usage part of the
documentation string is replaced with the function's name when the
various help functions (@pxref{Help Functions}) display it.
If you write a function definition with an unusual macro that is not
one of the known and recognized function definition methods, use of an

11
lisp/loadup.el
View file

@ -32,9 +32,6 @@
;; If you add a file to be loaded here, keep the following points in mind:
;; i) If the file is no-byte-compile, explicitly load the .el version.
;; Such files should (where possible) obey the doc-string conventions
;; expected by make-docfile. They should also be added to the
;; uncompiled[] list in make-docfile.c.
;; ii) If the file is dumped with Emacs (on any platform), put the
;; load statement at the start of a line (leading whitespace is ok).
@ -42,11 +39,9 @@
;; iii) If the file is _not_ dumped with Emacs, make sure the load
;; statement is _not_ at the start of a line. See pcase for an example.
;; These rules are so that src/Makefile can construct lisp.mk automatically.
;; This ensures both that the Lisp files are compiled (if necessary)
;; before the emacs executable is dumped, and that they are passed to
;; make-docfile. (Any that are not processed for DOC will not have
;; doc strings in the dumped Emacs.)
;; These rules are so that src/Makefile can construct lisp.mk
;; automatically. This ensures that the Lisp files are compiled (if
;; necessary) before the emacs executable is dumped.
;;; Code: