bytecomp.el: Rewrite the way we print dynamic docstrings

We used to print dynamic docstrings "manually" for two reasons:

- References should look like `(#$ . POS)` but `prin1` was unable
  to print just `#$` for an sexp.
- `make-docfile` needed to find those docstrings and the object
  to which they belonged.

The second point is moot now that we don't use `make-docfile` on
`.elc` files.  So this patch lifts the first restriction,
using `print-number-table`.

The rest of the patch then simplifies and regularises the
bytecompiler's generation of dynamic docstrings, which can
now also easily be done for "inner" defvars and other places.

* src/print.c (print_preprocess, print_object): Handle strings in
`print-number-table`.
(Vprint_number_table): Improve docstring.

* lisp/emacs-lisp/bytecomp.el:
(byte-compile--list-with-n): New function.
(byte-compile--docstring-style-warn): Rename from
`byte-compile-docstring-style-warn` and change calling convention.
(byte-compile--\#$, byte-compile--docstrings): New vars.
(byte-compile-close-variables): Bind them.
(byte-compile--docstring): New function.
(byte-compile-from-buffer): Set `byte-compile--\#$`.
(byte-compile-output-file-form): Use `byte-compile--\#$` instead
of special casing specific forms.
(byte-compile--output-docform-recurse, byte-compile-output-docform):
Delete functions.
(byte-compile-file-form-autoload, byte-compile-file-form-defalias)
(byte-compile-file-form-defvar-function, byte-compile-lambda):
Use `byte-compile--docstring` and `byte-compile--list-with-n`.
(byte-compile--declare-var): Add optional `not-toplevel` arg.
(byte-compile-defvar): Add `toplevel` arg.  Use `byte-compile--docstring`.
(byte-compile-file-form-defvar): Delegate to `byte-compile-defvar`.
(byte-compile--custom-declare-face): New function.  Use it for
`custom-declare-face`.
(byte-compile-file-form-defmumble): Use `byte-compile-output-file-form`

* src/doc.c (Fdocumentation_stringp): New function.
(syms_of_doc): Defsubr it.
(store_function_docstring): Remove left-over code from when we
used DOC for the docstring of some Lisp files.

* lisp/cus-face.el (custom-declare-face): Accept dynamic docstrings.
* lisp/faces.el (face-documentation): Handle dynamic docstrings.
* lisp/help-fns.el (describe-face): Simplify accordingly.

1 files changed, 11 insertions, 8 deletions

diff --git a/src/print.c b/src/print.c
index c6a3dba3163..c2beff0ed55 100644
--- a/src/print.c
+++ b/src/print.c
@@ -1412,7 +1412,7 @@ print_preprocess (Lisp_Object obj)
                   && SYMBOLP (obj)
                   && !SYMBOL_INTERNED_P (obj)))
             { /* OBJ appears more than once.  Let's remember that.  */
-              if (!FIXNUMP (num))
+              if (SYMBOLP (num)) /* In practice, nil or t.  */
                 {
                   print_number_index++;
                   /* Negative number indicates it hasn't been printed yet.  */
@@ -2265,6 +2265,11 @@ print_object (Lisp_Object obj, Lisp_Object printcharfun, bool escapeflag)
               goto next_obj;
             }
         }
+      else if (STRINGP (num))
+        {
+          strout (SDATA (num), SCHARS (num), SBYTES (num), printcharfun);
+          goto next_obj;
+        }
     }
 
   print_depth++;
@@ -2554,11 +2559,6 @@ print_object (Lisp_Object obj, Lisp_Object printcharfun, bool escapeflag)
           goto next_obj;
         case PVEC_SUB_CHAR_TABLE:
           {
-            /* Make each lowest sub_char_table start a new line.
-               Otherwise we'll make a line extremely long, which
-               results in slow redisplay.  */
-            if (XSUB_CHAR_TABLE (obj)->depth == 3)
-              printchar ('\n', printcharfun);
             print_c_string ("#^^[", printcharfun);
             int n = sprintf (buf, "%d %d",
                              XSUB_CHAR_TABLE (obj)->depth,
@@ -2664,7 +2664,7 @@ print_object (Lisp_Object obj, Lisp_Object printcharfun, bool escapeflag)
                     /* With the print-circle feature.  */
                     Lisp_Object num = Fgethash (next, Vprint_number_table,
                                                 Qnil);
-                    if (FIXNUMP (num))
+                    if (!(NILP (num) || EQ (num, Qt)))
                       {
                         print_c_string (" . ", printcharfun);
                         obj = next;
@@ -2928,7 +2928,10 @@ This variable should not be set with `setq'; bind it with a `let' instead.  */);
   DEFVAR_LISP ("print-number-table", Vprint_number_table,
                doc: /* A vector used internally to produce `#N=' labels and `#N#' references.
 The Lisp printer uses this vector to detect Lisp objects referenced more
-than once.
+than once.  If an entry contains a number, then the corresponding key is
+referenced more than once: a positive sign indicates that it's already been
+printed, and the absolute value indicates the number to use when printing.
+If an entry contains a string, that string is printed instead.
 
 When you bind `print-continuous-numbering' to t, you should probably
 also bind `print-number-table' to nil.  This ensures that the value of