[elpa] externals/auctex e83ca6a072 57/60: Update style/doc.el to package version 3.0h

[Tassilo Horn]

branch: externals/auctex
commit e83ca6a072434e703b84ccc9bb8cae2d73e7028d
Author: Arash Esbati <arash@gnu.org>
Commit: Arash Esbati <arash@gnu.org>

    Update style/doc.el to package version 3.0h
    
    * latex.el (LaTeX-indent-environment-list): Add 2 environments
    from doc.sty.
    
    * style/doc.el (LaTeX-env-doc-no-comment): Update docstring.
    (LaTeX-env-doc-commented): New function used to insert description
    environments like "macro" or "environment" and the ones defined
    with '\NewDocElement'.
    (LaTeX-doc-after-insert-macrocode): Remove "macro" from list of
    environments where this function runs.
    (LaTeX-doc-newdocelement-key-val-options): New variable.
    Add parsing support for '\NewDocElement'.
    ("doc"): Update style hook and add fontification support.
    (LaTeX-doc-package-options): New variable.
---
 latex.el     |   4 +-
 style/doc.el | 483 +++++++++++++++++++++++++++++++++++++++++++++--------------
 2 files changed, 376 insertions(+), 111 deletions(-)

diff --git a/latex.el b/latex.el
index 2d16483249..4527fbafb7 100644
--- a/latex.el
+++ b/latex.el
@@ -3728,7 +3728,9 @@ consideration just as is in the non-commented source 
code."
     ("tabbing")
     ;; envs from amsmath.sty
     ("gather") ("gather*") ("gathered")
-    ("equation*") ("multline") ("multline*"))
+    ("equation*") ("multline") ("multline*")
+    ;; envs from doc.sty
+    ("macrocode") ("macrocode*"))
   "Alist of environments with special indentation.
 The second element in each entry is the function to calculate the
 indentation level in columns.
diff --git a/style/doc.el b/style/doc.el
index 6818e0aad0..7bdcb42d0b 100644
--- a/style/doc.el
+++ b/style/doc.el
@@ -1,6 +1,6 @@
 ;;; doc.el --- AUCTeX style for `doc.sty'  -*- lexical-binding: t; -*-
 
-;; Copyright (C) 2004-2021  Free Software Foundation, Inc.
+;; Copyright (C) 2004-2022  Free Software Foundation, Inc.
 
 ;; Author: Frank Küster <frank@kuesterei.ch>
 ;; Maintainer: auctex-devel@gnu.org
@@ -25,21 +25,26 @@
 
 ;;; Commentary:
 
-;; This file adds support for `doc.sty'.
+;; This file adds support for `doc.sty' (v3.0h) dated 2022/06/01.
 
 ;;; Code:
 
 (require 'tex)
 (require 'latex)
 
-(defun LaTeX-env-no-comment (environment)
-  "Insert ENVIRONMENT and make sure there is no commented empty line inside."
-  (LaTeX-insert-environment environment
-                            (when (string-equal environment "macro")
-                              (let ((macroname (TeX-read-string
-                                                (TeX-argument-prompt nil nil 
"Macro")
-                                                TeX-esc)))
-                                (format "{%s}" macroname))))
+;; Silence the compiler:
+(declare-function font-latex-add-keywords
+                  "font-latex"
+                  (keywords class))
+(declare-function font-latex-add-to-syntax-alist
+                  "font-latex"
+                  (list))
+
+(defun LaTeX-env-doc-no-comment (environment)
+  "Insert ENVIRONMENT and make sure there is no commented empty line inside.
+This function is aware of the environments \"macro\" and
+\"environment\" and adjusts the query accordingly."
+  (LaTeX-insert-environment environment)
   (unless (TeX-active-mark)
     (when (save-excursion
             (beginning-of-line)
@@ -48,9 +53,79 @@
       (delete-region (line-beginning-position) (line-end-position))
       (indent-according-to-mode))))
 
+(defun LaTeX-env-doc-commented (environment)
+  "Insert ENVIRONMENT and make sure all parts are in comments.
+This functions search for the begin and the end of the inserted
+environment and makes sure those parts are in comments.  The same
+applies also to the point inside after the insertion."
+  (LaTeX-insert-environment
+   environment
+   (if (string= environment "macro")
+       ;; For 'macro' environment, elements will start with a
+       ;; backslash, so we insert them initially:
+       (progn
+         (let ((opt (mapconcat #'identity
+                               (TeX-completing-read-multiple
+                                (TeX-argument-prompt t nil "Suppress option")
+                                '("noindex" "noprint"))
+                               ","))
+               (mac (TeX-read-string
+                     (TeX-argument-prompt nil nil "Macro(s)")
+                     TeX-esc)))
+           (concat (when (and opt (not (string= opt "")))
+                     (format "[%s]" opt))
+                   (format "{%s}" mac))))
+     ;; For other environments, we don't know about the elements,
+     ;; so do nothing.  For 'environment', we adjust the prompt in
+     ;; minibuffer.
+     (let ((opt (mapconcat #'identity
+                           (TeX-completing-read-multiple
+                            (TeX-argument-prompt t nil "Suppress option")
+                            '("noindex" "noprint"))
+                           ","))
+           (env (TeX-read-string
+                 (TeX-argument-prompt nil nil
+                                      (if (string= environment "environment")
+                                          "Environment(s)"
+                                        "Element(s)")))))
+       (concat
+        (when (and opt (not (string= opt "")))
+          (format "[%s]" opt))
+        (format "{%s}" env)))))
+  ;; Now make sure everything is commented:
+  (let ((p (point-marker))
+        (active-mark (and (TeX-active-mark)
+                          (not (eq (mark) (point)))))
+        (func (lambda ()
+                (if (TeX-in-line-comment)
+                    (indent-according-to-mode)
+                  (delete-horizontal-space)
+                  (beginning-of-line)
+                  (insert "%")
+                  (indent-according-to-mode)))))
+    ;; Go to the start of the env we have inserted:
+    (search-backward (concat "\\begin" TeX-grop environment TeX-grcl)
+                     (if active-mark nil (line-beginning-position 0))
+                     t)
+    ;; If the line is not commented, insert %
+    (funcall func)
+    (goto-char p)
+    ;; Do the same for the end of the environment
+    (search-forward (concat "\\end" TeX-grop environment TeX-grcl)
+                    (if active-mark nil (line-end-position 2))
+                    t)
+    (goto-char (match-beginning 0))
+    (funcall func)
+    ;; Finally for where we started and clean up only when region was
+    ;; not active:
+    (goto-char p)
+    (unless active-mark (funcall func))
+    (set-marker p nil)))
+
 (defun LaTeX-doc-after-insert-macrocode (env start end)
   "Make sure the macrocode environment is properly formatted after insertion."
-  (when (TeX-member env '("macro" "macrocode" "macrocode*") #'string-equal)
+  (when (TeX-member env '("macrocode" "macrocode*")
+                    #'string-equal)
     (save-excursion
       (goto-char end)
       (skip-chars-backward " \t")
@@ -63,134 +138,322 @@
         (insert "%")
         (indent-according-to-mode)))))
 
+(defvar LaTeX-doc-newdocelement-key-val-options
+  '(("macrolike" ("true" "false"))
+    ("envlike" ("true" "false"))
+    ("toplevel" ("true" "false"))
+    ("notoplevel" ("true" "false"))
+    ("idxtype")
+    ("printtype")
+    ("idxgroup")
+    ("noindex" ("true" "false"))
+    ("noprint" ("true" "false")))
+  "Key=value options for '\\NewDocElement' macro.")
+
+;; Setup for \NewDocElement:
+
+(TeX-auto-add-type "doc-NewDocElement" "LaTeX")
+
+(defvar LaTeX-doc-NewDocElement-regexp
+  `(,(concat  "^[ \t%]*"
+              "\\\\NewDocElement"
+              "[ \t\n\r%]*"
+              "\\(?:"
+              (LaTeX-extract-key-value-label 'none)
+              "\\)?"
+              "[ \t\n\r%]*"
+              "{\\([^}]+\\)}"
+              "[ \t\n\r%]*"
+              "{\\([^}]+\\)}")
+    (1 2) LaTeX-auto-doc-NewDocElement)
+  "Matches the arguments of '\\NewDocElement' from doc package.
+AUCTeX parser doesn't look for text parts commented out.
+Therefore, the regexp in this variable explicitly looks for a
+percent sign at the beginning of a line before
+'\\NewDocElement'.")
+
+(defun LaTeX-doc-auto-prepare ()
+  "Clear `LaTeX-auto-doc-NewDocElement' before parsing."
+  (setq LaTeX-auto-doc-NewDocElement nil))
+
+(defun LaTeX-doc-auto-cleanup ()
+  "Process elements defined with '\\NewDocElement'."
+  (when (LaTeX-doc-NewDocElement-list)
+    ;; Make sure `docTeX-indent-inner-fixed' is local:
+    (make-local-variable 'docTeX-indent-inner-fixed)
+
+    ;; \NewDocElement[<options>]{<element-name>}{<env-name>} defines:
+    ;; 1. \Describe<element-name>[<options>]{<element>}
+    ;; 2. \begin{<env-name>}[<options>]{<element>}
+    ;; 3. \PrintDescribe<element-name>{<element>}
+    ;; 4. \Print<element-name>Name
+    (dolist (elt (LaTeX-doc-NewDocElement-list))
+      (let ((eltname (car elt))
+            (envname (cadr elt)))
+        (TeX-add-symbols
+         ;; Cater for \Describe<eltname>[options]{<elements query>}
+         `(,(concat "Describe" eltname)
+           [TeX-arg-eval completing-read
+                         (TeX-argument-prompt t nil "Suppress option")
+                         '("noindex" "noprint")]
+           "Element")
+
+         ;; Cater for \PrintDescribe<eltname>{<elements query>}
+         `(,(concat "PrintDescribe" eltname) "Element")
+
+         ;; Cater for \Print<eltname>Name
+         (concat "Print" eltname "Name"))
+
+        ;; Cater for \begin{<envname>}[options]{<elements query>}
+        (LaTeX-add-environments
+         `(,envname LaTeX-env-doc-commented))
+
+        ;; Make sure we have fixed inner indent for our environments:
+        (add-to-list 'docTeX-indent-inner-fixed
+                     `(,(concat (regexp-quote TeX-esc)
+                                "\\(begin\\|end\\)[ \t]*"
+                                (regexp-quote TeX-grop)
+                                envname
+                                (regexp-quote TeX-grcl))
+                       0 nil)
+                     t)
+        ;; Add fontification:
+        (when (and (featurep 'font-latex)
+                   (eq TeX-install-font-lock 'font-latex-setup))
+          (font-latex-add-keywords `((,(concat "Describe" eltname) "[|{\\" ))
+                                   'variable))))))
+
+(add-hook 'TeX-auto-prepare-hook #'LaTeX-doc-auto-prepare t)
+(add-hook 'TeX-auto-cleanup-hook #'LaTeX-doc-auto-cleanup t)
+(add-hook 'TeX-update-style-hook #'TeX-auto-parse t)
+
 (TeX-add-style-hook
  "doc"
  (lambda ()
-   (add-to-list (make-local-variable 'LaTeX-indent-environment-list)
-                '("macrocode" current-indentation) t)
-   (add-to-list 'LaTeX-indent-environment-list
-                '("macrocode*" current-indentation) t)
-   (add-to-list 'LaTeX-indent-environment-list
-                '("macro" current-indentation) t)
+
+   ;; Add doc to the parser:
+   (TeX-auto-add-regexp LaTeX-doc-NewDocElement-regexp)
+
    (add-hook 'LaTeX-after-insert-env-hook #'LaTeX-doc-after-insert-macrocode
              nil t)
+
    (LaTeX-add-environments
-    "theglossary"
-    '("macrocode" LaTeX-env-no-comment)
-    '("macrocode*" LaTeX-env-no-comment)
-    '("macro" LaTeX-env-no-comment))
+    ;; 2.3 General conventions
+    '("macrocode"  LaTeX-env-doc-no-comment)
+    '("macrocode*" LaTeX-env-doc-no-comment)
+
+    ;; 2.5 Describing the definition of macros and environments
+    '("macro"       LaTeX-env-doc-commented)
+    '("environment" LaTeX-env-doc-commented)
+
+    '("theglossary" LaTeX-env-item))
+
    (TeX-add-symbols
-    "EnableCrossrefs"
-    "DisableCrossrefs"
-    '("DoNotIndex" t)
-    "DontCheckModules"
-    "CheckModules"
-    "Module"
-    '("DescribeMacro" (TeX-arg-eval
-                       (lambda ()
-                         (let ((name (TeX-read-string
-                                      (TeX-argument-prompt nil nil "Macro")
-                                      TeX-esc)))
-                           (format "%s" name)))))
-    '("DescribeEnv" "Environment")
-    "verbatim"
-    "verb"
-    '("parg" "Argument")
-    '("oarg" "Argument")
-    '("marg" "Argument")
-    '("meta" "Text")
-    '("cs" "Name")
-    '("cmd" (TeX-arg-eval
-             (lambda ()
-               (let ((name (TeX-read-string
-                            (TeX-argument-prompt nil nil "Name")
-                            TeX-esc)))
-                 (format "%s" name)))))
-    "makelabel"
-    '("MacroFont" t)
-    '("AltMacroFont" t)
+    ;; 2.1 The driver file
+    '("DocInput"
+      (TeX-arg-eval
+       (lambda ()
+         (let ((file (file-relative-name
+                      (read-file-name
+                       "File to input: " nil nil nil nil
+                       (lambda (x)
+                         (or (file-directory-p x)
+                             (string-match "\\.\\(fdd\\|dtx\\)\\'" x))))
+                      (TeX-master-directory))))
+           (format "%s" file)))))
+
+    '("IndexInput"
+      (TeX-arg-eval
+       (lambda ()
+         (let ((file (file-relative-name
+                      (read-file-name
+                       "File to input: " nil nil nil nil
+                       (lambda (x)
+                         (or (file-directory-p x)
+                             (string-match "\\.\\(tex\\|ltx\\|fdd\\|dtx\\)\\'" 
x))))
+                      (TeX-master-directory))))
+           (format "%s" file)))))
+
+    ;; 2.2 Package options
+    '("SetupDoc" (TeX-arg-eval mapconcat #'identity
+                               (TeX-completing-read-multiple
+                                (TeX-argument-prompt nil nil "Options")
+                                LaTeX-doc-package-options)
+                               ","))
+
+    ;; 2.4 Describing the usage of macros and environments
+    '("DescribeMacro"
+      [TeX-arg-eval completing-read
+                    (TeX-argument-prompt t nil "Suppress option")
+                    '("noindex" "noprint")]
+      (TeX-arg-eval
+       (lambda ()
+         (let ((name (TeX-read-string
+                      (TeX-argument-prompt nil nil "Macro")
+                      TeX-esc)))
+           (format "%s" name)))))
+    '("DescribeEnv"
+      [TeX-arg-eval completing-read
+                    (TeX-argument-prompt t nil "Suppress option")
+                    '("noindex" "noprint")]
+      "Environment")
+
+    ;; 2.5 Describing the definition of macros and environments
+    "MacroFont"
+
+    ;; 2.6 Formatting names in the margin
+    '("PrintDescribeMacro" "Element")
+    '("PrintDescribeEnv"   "Element")
     "PrintMacroName"
-    "PrintDescribeMacro"
-    "PrintDescribeEnv"
     "PrintEnvName"
-    "MakePrivateLetters"
+
+    ;; 2.7 Providing further documentation items
+    '("NewDocElement"
+      [TeX-arg-key-val LaTeX-doc-newdocelement-key-val-options]
+      "Element name" "Environment name")
+
+    ;; 2.8 Displaying sample code verbatim
+    ;; "verbatim" environment and "verb" macro are provided by
+    ;; latex.el, so we don't add them here again.
+
+    ;; 2.9 Using a special escape character
+    '("SpecialEscapechar" "Character")
+
+    ;; 2.10 Cross-referencing all macros used
+    "DisableCrossrefs"
+    "EnableCrossrefs"
+    ;; We don't fontify the next macro since it is a one-liner anyway
+    '("DoNotIndex" t)
+    "CodelineIndex"
+    "PageIndex"
+    "theCodelineNo"
+    "CodelineNumbered"
+
+    ;; 2.11 Producing the actual index entries
     "actualchar"
     "quotechar"
-    "levelchar"
     "encapchar"
-    "verbatimchar"
-    "SpecialIndex"
-    "SpecialMainIndex"
+    "levelchar"
+
+    "SpecialMainMacroIndex"
     "SpecialMainEnvIndex"
-    "SpecialUsageIndex"
+    "SpecialMacroIndex"
     "SpecialEnvIndex"
+    "SpecialIndex"
+    "SpecialShortIndex"
     "SortIndex"
-    "LeftBraceIndex"
-    "RightBraceIndex"
-    "PercentIndex"
-    "OldMakeindex"
-    "PercentIndex"
-    "IndexPrologue"
-    "IndexParms"
+    "verbatimchar"
+
     "subitem"
     "subsubitem"
     "indexspace"
     "efill"
     "pfill"
+
+    ;; 2.12 Setting the index entries: theindex environment is
+    ;; provided by latex.el.
     "PrintIndex"
+    '("IndexPrologue" t)
+    "IndexParms"
+    "main"
+    "usage"
+    "code"
+
+    ;; 2.13 Changing the default values of style parameters
+    "DocstyleParms"
+
+    ;; 2.14 Short input of verbatim text pieces: These macros are
+    ;; provided by 'shortvrb.el' which is run later
+
+    ;; 2.15 Additional bells and whistles
+    "Web"
+    "AmSTeX"
+    "BibTeX"
+    "SliTeX"
+    "PlainTeX"
+    '("meta" "Text")
+    "OnlyDescription"
+    '("StopEventually" t)
+    '("MaybeStop" t)
+    "Finale"
+    "AlsoImplementation"
+    "IndexInput"
     '("changes" "version" TeX-arg-date t)
     "generalname"
     "RecordChanges"
+    "PrintChanges"
     "GlossaryPrologue"
     "GlossaryParms"
-    "PrintChanges"
-    "AlsoImplementation"
-    '("StopEventually" t)
-    "OnlyDescription"
-    "Finale"
-    "IndexInput"
-    "maketitle"
-    "MakeShortVerb"
-    "DeleteShortVerb"
-    "MakeShortverb"
-    "DeleteShortverb"
-    "CheckSum"
-    "CharacterTable"
-    "CharTableChanges"
-    "CodelineNumbered"
-    "CodelineIndex"
-    "PageIndex"
-    "theCodelineNo"
-    "DocstyleParms"
-    "MakePercentIgnore"
-    "MakePercentComment"
-    '("DocInput"
-      (TeX-arg-eval
-       (lambda ()
-         (let ((file (file-relative-name
-                      (read-file-name
-                       "File to input: " nil nil nil nil
-                       (lambda (x)
-                         (string-match "\\.fdd$\\|\\.dtx$" x)))
-                      (TeX-master-directory))))
-           (format "%s" file)))))
-    '("DocInclude"
-      (TeX-arg-eval
-       (lambda ()
-         (let ((file (file-relative-name
-                      (read-file-name
-                       "File to include: " nil nil nil nil
-                       (lambda (x)
-                         (string-match "\\.fdd$\\|\\.dtx$" x)))
-                      (TeX-master-directory))))
-           (format "%s" file)))))
-    "GetFileInfo"
-    "filename"
-    "fileinfo")
+    "bslash"
+    "MakePrivateLetters"
+    "DontCheckModules"
+    "CheckModules"
+    "Module"
+    '("AltMacroFont" t)
+
+    ;; 5.1 makeindex bugs
+    "PercentIndex"
+    ;; 5.2 File transmission issues
+    '("CheckSum" t)
+    '("CharacterTable" t))
+
    (TeX-run-style-hooks "shortvrb")
-   (LaTeX-add-lengths "MacrocodeTopsep" "MacroTopsep" "MacroIndent"))
+
+   (LaTeX-add-lengths "MacrocodeTopsep" "MacroTopsep" "MacroIndent"
+                      "IndexMin" "GlossaryMin")
+   (LaTeX-add-counters "IndexColumns" "GlossaryColumns" "StandardModuleDepth")
+
+   ;; Macros which should be on their own line:
+   (LaTeX-paragraph-commands-add-locally '("changes"))
+
+   ;; Fontification
+   (when (and (featurep 'font-latex)
+              (eq TeX-install-font-lock 'font-latex-setup))
+     (font-latex-add-keywords '(("SetupDoc"           "{")
+                                ("NewDocElement"      "[{{")
+                                ("RenewDocElement"    "[{{")
+                                ("SpecialEscapechar"  "{")
+                                ("DisableCrossrefs"   "")
+                                ("EnableCrossrefs"    "")
+                                ("CodelineIndex"      "")
+                                ("PageIndex"          "")
+                                ("CodelineNumbered"   "")
+                                ("PrintIndex"         "")
+                                ("IndexPrologue"      "")
+                                ("AmSTeX"             "")
+                                ("BibTeX"             "")
+                                ("SliTeX"             "")
+                                ("PlainTeX"           "")
+                                ("OnlyDescription"    "")
+                                ("StopEventually"     "")
+                                ("MaybeStop"          "")
+                                ("Finale"             "")
+                                ("AlsoImplementation" "")
+                                ("changes"            "{{{")
+                                ("PrintChanges"       "")
+                                ("RecordChanges"      ""))
+                              'function)
+     (font-latex-add-keywords '(("DescribeMacro" "[|{\\")
+                                ("DescribeEnv"   "[{"))
+                              'variable)
+     (font-latex-add-keywords '(("meta"       "{"))
+                              'textual)
+     (font-latex-add-keywords '(("DocInput"   "{")
+                                ("DocInclude" "{" )
+                                ("IndexInput" "{"))
+                              'reference)))
  TeX-dialect)
 
+(defvar LaTeX-doc-package-options
+  '("hyperref" "nohyperref"
+    "multicol" "nomulticol"
+    "debugshow"
+    "noindex" "noprint"
+    "reportchangedates")
+  "Package options for the doc package.")
+
 ;; Local Variables:
 ;; coding: utf-8
 ;; End:
+
+;;; doc.el ends here