Generate automatically graphical and textual type hierarchy representation

* etc/syncdoc-type-hierarchy.el: New file.
* doc/lispref/type_hierarchy.txt: Likewise.
* doc/lispref/type_hierarchy.jpg: Likewise.

(cherry picked from commit 3211825fe7cab2c330d703a9e77090d551854d53)

diff --git a/doc/lispref/type_hierarchy.jpg b/doc/lispref/type_hierarchy.jpg
new file mode 100644 (file)
index 0000000..0b551b5
Binary files /dev/null and b/doc/lispref/type_hierarchy.jpg differ

diff --git a/doc/lispref/type_hierarchy.txt b/doc/lispref/type_hierarchy.txt
new file mode 100644 (file)
index 0000000..c6e762b
--- /dev/null
+++ b/doc/lispref/type_hierarchy.txt
@@ -0,0 +1,147 @@
+                         +--------------------+
+                         |       bignum       |
+                         +--------------------+
+                           |
+                           |
+                           v
+     +-------------+     +--------------------+     +----------------------+     +--------+
+     |    fixum    | --> |      integer       | --> |  integer-or-marker   | <-- | marker |
+     +-------------+     +--------------------+     +----------------------+     +--------+
+                           |                          |                            |
+                           |                          |                            |
+                           v                          |                            |
+     +-------------+     +--------------------+       |                            |
+     |    float    | --> |       number       |       |                            |
+     +-------------+     +--------------------+       |                            |
+                           |                          |                            |
+                           |                          |                            |
+                           v                          |                            |
+                         +--------------------+       |                            |            +------------------+          +--------------------+         +----------+           +--------+
+                         |  number-or-marker  | <-----+----------------------------+            | tree-sitter-node |          | tree-sitter-parser |         | user-ptr |           | window |
+                         +--------------------+       |                                         +------------------+          +--------------------+         +----------+           +--------+
+                           |                          |                                           |                             |                              |                      |
+                           |                          |                                           |                             |                              |                      |
+                           v                          v                                           v                             v                              v                      v
+     +-------------+     +-------------------------------------------------------------------------------------------------------------------------------------------------------------------+     +----------------------------+
+     | font-entity | --> |                                                                                                                                                                   | <-- |          overlay           |
+     +-------------+     |                                                                                                                                                                   |     +----------------------------+
+     +-------------+     |                                                                                                                                                                   |     +----------------------------+
+     | font-object | --> |                                                                                                                                                                   | <-- |          process           |
+     +-------------+     |                                                                                                                                                                   |     +----------------------------+
+     +-------------+     |                                                                                                                                                                   |     +----------------------------+
+     |  font-spec  | --> |                                                                                                                                                                   | <-- |         structure          |
+     +-------------+     |                                                                               atom                                                                                |     +----------------------------+
+     +-------------+     |                                                                                                                                                                   |     +----------------------------+
+     |    frame    | --> |                                                                                                                                                                   | <-- |          terminal          |
+     +-------------+     |                                                                                                                                                                   |     +----------------------------+
+     +-------------+     |                                                                                                                                                                   |     +----------------------------+
+     | hash-table  | --> |                                                                                                                                                                   | <-- |           thread           |
+     +-------------+     |                                                                                                                                                                   |     +----------------------------+
+     +-------------+     |                                                                                                                                                                   |     +----------------------------+
+     |    mutex    | --> |                                                                                                                                                                   | <-- | tree-sitter-compiled-query |
+     +-------------+     +-------------------------------------------------------------------------------------------------------------------------------------------------------------------+     +----------------------------+
+                           |                     ^    ^                       ^              ^                        ^                               ^                    ^
+                           |                     |    |                       |              |                        |                               |                    |
+                           v                     |    |                       |              |                        |                               |                    |
+                         +--------------------+  |  +----------------------+  |              |                      +--------+                      +-------+            +---------+
+  +--------------------> |         t          |  |  | window-configuration |  |              |                      | buffer |                      | class |            | condvar |
+  |                      +--------------------+  |  +----------------------+  |              |                      +--------+                      +-------+            +---------+
+  |                      +--------------------+  |                            |              |
+  |                      | byte-code-function |  |                            |              |
+  |                      +--------------------+  |                            |              |
+  |                        |                     |                            |              |
+  |                        |                     |                            |              |
+  |                        v                     |                            |              |
+  |                      +--------------------+  |                            |              |
+  |                      | compiled-function  |  |                            |              |
+  |                      +--------------------+  |                            |              |
+  |                        |                     |                            |              |
+  |                        |                     |                            |              |
+  |                        v                     |                            |              |
+  |                      +--------------------+  |                            |              |
+  |                   +> |      function      | -+                            |              |
+  |                   |  +--------------------+                               |              |
+  |                   |    ^                                                  |              |
+  |                   |    +--------------------------------------------------+--------------+------------------------+
+  |                   |                                                       |              |                        |
+  |                   |  +--------------------+                               |              |                        |
+  |                   |  |   subr-primitive   |                               |              |                        |
+  |                   |  +--------------------+                               |              |                        |
+  |                   |    |                                                  |              |                        |
+  |                   |    |                                                  |              |                        |
+  |                   |    v                                                  |              |                        |
+  |                   |  +--------------------+                               |              |                        |
+  |                   +- |        subr        | <-----------------------------+----+         |                        |
+  |                      +--------------------+                               |    |         |                        |
+  |                      +--------------------+                               |    |         |                        |
+  |                      |      keyword       | -+                            |    |         |                        |
+  |                      +--------------------+  |                            |    |         |                        |
+  |                        |                     |                            |    |         |                        |
+  |                        |                     |                            |    |         |                        |
+  |                        v                     |                            |    |         |                        |
+  |                      +--------------------+  |                            |    |         |                        |
+  |                      |  symbol-with-pos   |  |                            |    |         |                        |
+  |                      +--------------------+  |                            |    |         |                        |
+  |                        |                     |                            |    |         |                        |
+  |                        |                     +----+                       |    |         |                        |
+  |                        v                          |                       |    |         |                        |
+  |                      +--------------------+       |                       |    |         |                        |
+  |                   +> |       symbol       | ------+-----------------------+    |         |                        |
+  |                   |  +--------------------+       |                            |         |                        |
+  |                   |    ^                          |                            |         |                        |
+  |                   |    +--------------------------+                            |         |                        |
+  |                   |                                                            |         |                        |
+  |                   |  +--------------------+                                    |         |                        |
+  |                   |  |        null        | -+                                 |         |                        |
+  |                   |  +--------------------+  |                                 |         |                        |
+  |                   |    |                     |                                 |         |                        |
+  |                   |    |                     |                                 |         |                        |
+  |                   |    v                     |                                 |         |                        |
+  |                   |  +--------------------+  |                                 |         |                        |
+  |                   +- |      boolean       |  |                                 |         |                        |
+  |                      +--------------------+  |                                 |         |                        |
+  |                      +--------------------+  |                                 |         |                        |
+  |                      |        cons        |  |                                 |         |                        |
+  |                      +--------------------+  |                                 |         |                        |
+  |                        |                     |                                 |         |                        |
+  |                        |                     |                                 |         |                        |
+  |                        v                     |                                 |         |                        |
+  |                      +--------------------+  |                                 |         |                        |
+  |                      |        list        | <+                                 |         |                        |
+  |                      +--------------------+                                    |         |                        |
+  |                        |                                                       |         |                        |
+  |                        |                                                       |         |                        |
+  |                        v                                                       |         |                        |
+  |                      +--------------------+                                    |         |                        |
+  +--------------------- |      sequence      |                                    |         |                        |
+                         +--------------------+                                    |         |                        |
+                           ^                                                       |         |                        |
+  +------------------------+                                                       |         |                        |
+  |                                                                                |         |                        |
+  |                      +--------------------+                                    |         |                        |
+  |                      | subr-native-elisp  | -----------------------------------+         |                        |
+  |                      +--------------------+                                              |                        |
+  |                                                                                          |                        |
+  |                                              +-------------------------------------------+                        |
+  |                                              |                                                                    |
+  |                      +--------------------+  |                                                                    |
+  |                      |    bool-vector     |  |                                                                    |
+  |                      +--------------------+  |                                                                    |
+  |                        |                     |                                                                    |
+  |                        |                     |                                                                    |
+  |                        v                     |                                                                    |
+  |  +-------------+     +-------------------------------------------------+                                          |
+  |  |   string    | --> |                      array                      |                                          |
+  |  +-------------+     +-------------------------------------------------+                                          |
+  |                        ^                     |    ^                                                               |
+  |                        |                     |    |                                                               |
+  |                        |                     |    |                                                               |
+  |                      +--------------------+  |  +----------------------+                                          |
+  |                      |       vector       |  |  |      char-table      |                                          |
+  |                      +--------------------+  |  +----------------------+                                          |
+  |                                              |                                                                    |
+  +----------------------------------------------+                                                                    |
+                                                                                                                      |
+                         +--------------------+                                                                       |
+                         |  module-function   | ----------------------------------------------------------------------+
+                         +--------------------+

diff --git a/etc/syncdoc-type-hierarchy.el b/etc/syncdoc-type-hierarchy.el
new file mode 100644 (file)
index 0000000..eebb092
--- /dev/null
+++ b/etc/syncdoc-type-hierarchy.el
@@ -0,0 +1,72 @@
+;;;  syncdoc-type-hierarchy.el--- -*- lexical-binding: t -*-
+
+;; Copyright (C) 2023-2024 Free Software Foundation, Inc.
+
+;; Author: Andrea Corallo <acorallo@gnu.org>
+;; Keywords: documentation
+
+;; This file is part of GNU Emacs.
+
+;; GNU Emacs is free software: you can redistribute it and/or modify
+;; it under the terms of the GNU General Public License as published by
+;; the Free Software Foundation, either version 3 of the License, or
+;; (at your option) any later version.
+
+;; GNU Emacs is distributed in the hope that it will be useful,
+;; but WITHOUT ANY WARRANTY; without even the implied warranty of
+;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+;; GNU General Public License for more details.
+
+;; You should have received a copy of the GNU General Public License
+;; along with GNU Emacs.  If not, see <https://www.gnu.org/licenses/>.
+
+;;; Commentary:
+
+;; This file is used to keep the type hierarchy representation present
+;; in the elisp manual in sync with the current type hierarchy.  This
+;; is specified in `cl--type-hierarchy' in cl-preloaded.el, so each
+;; time `cl--type-hierarchy' is modified
+;; `syncdoc-update-type-hierarchy' must be run before the
+;; documentation is regenerated.
+
+;; We do not call this directly from make docs in order not to add a
+;; dependency on the tools "dot" and "graph-easy".
+
+;;; Code:
+
+(require 'cl-lib)
+
+(eval-and-compile
+  (defconst syncdoc-lispref-dir (concat (file-name-directory
+                                         (or load-file-name
+                                             buffer-file-name))
+                                        "../doc/lispref/")))
+
+(defun syncdoc-insert-dot-content (rankdir)
+  (maphash (lambda (child parents)
+              (cl-loop for parent in parents
+                       do (insert " \"" (symbol-name child) "\" -> \""
+                                  (symbol-name parent) "\";\n")))
+           cl--direct-supertypes-of-type)
+  (sort-lines nil (point-min) (point-max))
+
+  (goto-char (point-min))
+  (insert "digraph {\n rankdir=\"" rankdir "\";\n")
+  (goto-char (point-max))
+  (insert "}\n"))
+
+(defun syncdoc-update-type-hierarchy ()
+  "Update the type hierarchy representation used by the elisp manual."
+  (interactive)
+  (with-temp-buffer
+    (syncdoc-insert-dot-content "LR")
+    (call-process-region nil nil "dot" t (current-buffer) nil "-Tjpg" "-o"
+                         (expand-file-name "type_hierarchy.jpg"
+                                           syncdoc-lispref-dir)))
+  (with-temp-buffer
+    (syncdoc-insert-dot-content "TB")
+    (call-process-region nil nil "graph-easy" t (current-buffer) nil "--output"
+                         (expand-file-name "type_hierarchy.txt"
+                                           syncdoc-lispref-dir))))
+
+;;; syncdoc-type-hierarchy.el ends here