emacs/code/elpa/auctex-13.2.1/style/caption.el

;;; caption.el --- AUCTeX style for `caption.sty' (v3.4a)  -*- lexical-binding: t; -*-

;; Copyright (C) 2015--2023 Free Software Foundation, Inc.

;; Author: Arash Esbati <arash@gnu.org>
;; Maintainer: auctex-devel@gnu.org
;; Created: 2015-02-21
;; Keywords: tex

;; This file is part of AUCTeX.

;; AUCTeX 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, or (at your option)
;; any later version.

;; AUCTeX 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 AUCTeX; see the file COPYING.  If not, write to the Free
;; Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
;; 02110-1301, USA.

;;; Commentary:

;; This file adds support for `caption.sty' (v3.4a) from 2019/10/18.
;; `caption.sty' is part of TeXLive.

;; If things do not work or when in doubt, press `C-c C-n'.  Comments
;; for improvement are welcome.

;;; Code:

(eval-when-compile
  (require 'cl-lib))

;; Needed for compiling `LaTeX-check-insert-macro-default-style':
(require 'latex)

;; Needed for auto-parsing:
(require 'tex)

;; Silence the compiler:
(declare-function font-latex-add-keywords
                  "font-latex"
                  (keywords class))

(declare-function LaTeX-babel-active-languages "babel" ())
(declare-function LaTeX-polyglossia-active-languages "polyglossia" ())
(declare-function LaTeX-newfloat-DeclareFloatingEnvironment-list
                  "newfloat" ())

(defvar LaTeX-bicaption-key-val-options)
(defvar LaTeX-subcaption-key-val-options)

(defvar LaTeX-caption-key-val-options
  '(("aboveskip")
    ("belowskip")
    ("font"   ("scriptsize" "footnotesize" "small" "normalsize" "large"
               "Large" "normalfont" "up" "it" "sl" "sc" "md" "bf" "rm"
               "sf" "tt" "singlespacing" "onehalfspacing" "doublespacing"
               "stretch" "normalcolor" "color" "normal"))
    ("font+"  ("scriptsize" "footnotesize" "small" "normalsize" "large"
               "Large" "normalfont" "up" "it" "sl" "sc" "md" "bf" "rm"
               "sf" "tt" "singlespacing" "onehalfspacing" "doublespacing"
               "stretch" "normalcolor" "color" "normal"))
    ("format" ("plain" "hang"))
    ("hangindent")
    ("hypcap" ("false" "no" "off" "0" "true" "yes" "on" "1"))
    ("hypcapspace")
    ("indention")
    ("justification" ("justified" "centering" "centerlast" "centerfirst"
                      "raggedright" "RaggedRight" "raggedleft"))
    ("labelfont"     ("scriptsize" "footnotesize" "small" "normalsize" "large"
                      "Large" "normalfont" "up" "it" "sl" "sc" "md" "bf" "rm"
                      "sf" "tt" "singlespacing" "onehalfspacing" "doublespacing"
                      "stretch" "normalcolor" "color" "normal"))
    ("labelfont+"    ("scriptsize" "footnotesize" "small" "normalsize" "large"
                      "Large" "normalfont" "up" "it" "sl" "sc" "md" "bf" "rm"
                      "sf" "tt" "singlespacing" "onehalfspacing" "doublespacing"
                      "stretch" "normalcolor" "color" "normal"))
    ("labelformat"   ("default" "empty" "simple" "brace" "parens"
                      "autodot" "unnumbered"))
    ("labelsep"      ("none" "colon" "period" "space" "quad" "newline" "endash"))
    ("list"          ("false" "no" "off" "0" "true" "yes" "on" "1"))
    ("listformat"    ("empty" "simple" "paren" "subsimple" "subparens"))
    ("margin")
    ("margin*")
    ("maxmargin")
    ("minmargin")
    ("name")
    ("oneside")
    ("parindent")
    ("parskip")
    ("position"        ("top" "above" "bottom" "below" "auto"))
    ("singlelinecheck" ("false" "no" "off" "0" "true" "yes" "on" "1"))
    ("slc"             ("false" "no" "off" "0" "true" "yes" "on" "1"))
    ("skip")
    ("strut"      ("false" "no" "off" "0" "true" "yes" "on" "1"))
    ("style"      ("base" "default"))
    ("textfont"   ("scriptsize" "footnotesize" "small" "normalsize" "large"
                   "Large" "normalfont" "up" "it" "sl" "sc" "md" "bf" "rm"
                   "sf" "tt" "singlespacing" "onehalfspacing" "doublespacing"
                   "stretch" "normalcolor" "color" "normal"))
    ("textfont+"  ("scriptsize" "footnotesize" "small" "normalsize" "large"
                   "Large" "normalfont" "up" "it" "sl" "sc" "md" "bf" "rm"
                   "sf" "tt" "singlespacing" "onehalfspacing" "doublespacing"
                   "stretch" "normalcolor" "color" "normal"))
    ("textformat" ("empty" "simple" "period"))
    ("twoside")
    ("type"       ("figure" "table"))
    ("type*"      ("figure" "table"))
    ("width"))
  "Key=value options for caption macros.")

(defun LaTeX-caption-key-val-options ()
  "Return an updated list of key=vals from caption package.
The key=val list will also contain elements from subcaption
package if loaded."
  ;; Update the style list once so we don't run this function more
  ;; than once:
  (TeX-style-list)
  (append
   ;; Check if `subcaption.el' is loaded:
   (when (member "subcaption" TeX-active-styles)
     ;; If loaded, update also the entry for `subrefformat' when
     ;; processing the `labelformat'.  `subrefformat' keys takes the
     ;; same values as `labelformat'.  We have to check if we have an
     ;; entry for `\DeclareCaptionLabelFormat', otherwise there is no
     ;; need to run this procedure:
     (if (and (LaTeX-caption-DeclareCaption-list)
              (string-match
               "\\\\DeclareCaptionLabelFormat"
               (mapconcat #'identity
                          (mapcar #'car
                                  (LaTeX-caption-DeclareCaption-list))
                          "|")))
         (progn
           (let (result)
             (dolist (keyvals (LaTeX-caption-DeclareCaption-list) result)
               (when (string-equal (nth 1 keyvals) "LabelFormat")
                 (let* ((key "subrefformat")
                        (val (nth 2 keyvals))
                        (vals-predefined
                         (cadr (assoc key
                                      LaTeX-subcaption-key-val-options)))
                        (vals-parsed
                         (cadr (assoc key result))))
                   (cl-pushnew (list key (TeX-delete-duplicate-strings
                                          (append vals-predefined
                                                  vals-parsed
                                                  (list val))))
                               result :test #'equal))))))
       LaTeX-subcaption-key-val-options))
   ;; Check if `bicaption.el' is loaded:
   (when (member "bicaption" TeX-active-styles)
     (append
      (cond ((and (member "babel" TeX-active-styles)
                  (LaTeX-babel-active-languages))
             `(,(list "language"
                      (butlast (LaTeX-babel-active-languages)))))
            ((and (member "polyglossia" TeX-active-styles)
                  (LaTeX-polyglossia-active-languages))
             `(,(list "language"
                      (butlast (LaTeX-polyglossia-active-languages)))))
            (t nil))
      LaTeX-bicaption-key-val-options))
   ;; Support for environments defined with `newfloat.sty': These
   ;; environments are added to `type' and `type*' keys:
   (when (and (member "newfloat" TeX-active-styles)
              (LaTeX-newfloat-DeclareFloatingEnvironment-list))
     (let (result)
       (dolist (key '("type" "type*") result)
         (let ((val (mapcar #'car
                            (LaTeX-newfloat-DeclareFloatingEnvironment-list)))
               (vals-predefined
                (cadr (assoc key LaTeX-caption-key-val-options))))
           (cl-pushnew (list key (TeX-delete-duplicate-strings
                                  (append vals-predefined
                                          val)))
                       result :test #'equal)))))
   ;; Update to standard key-vals from `caption.el':
   (when (LaTeX-caption-DeclareCaption-list)
     (let (result)
       (dolist (keyvals (LaTeX-caption-DeclareCaption-list) result)
         (let* ((key (if (string-equal (nth 1 keyvals) "LabelSeparator")
                         (downcase (substring (nth 1 keyvals) 0 8))
                       (downcase (nth 1 keyvals))))
                (val (nth 2 keyvals))
                (vals-predefined
                 (cadr (assoc key LaTeX-caption-key-val-options)))
                (vals-parsed (cadr (assoc key result))))
           ;; For `\DeclareCaptionOption', only add the value
           ;; (remember:      key=^^^^^^, val="defined key")
           (if (string-equal key "option")
               (cl-pushnew (list val) result :test #'equal)
             (cl-pushnew (list key (TeX-delete-duplicate-strings
                                    (append vals-predefined
                                            vals-parsed
                                            (list val))))
                         result :test #'equal))))))
   LaTeX-caption-key-val-options))

(defvar LaTeX-caption-supported-float-types
  '("figure" "table" "ContinuedFloat"   ; Standard caption.sty
    "sub" "subtable" "subfigure"        ; subcaption.sty
    "bi" "bi-first" "bi-second"         ; bicaption.sty
    "ruled" "boxed"                     ; float.sty
    "floatingfigure" "floatingtable"    ; floatflt.sty
    "lstlisting"                        ; listings.sty
    "longtable"                         ; longtable.sty
    "figwindow" "tabwindow"             ; picinpar.sty
    "parpic"                            ; picins.sty
    "SCfigure" "SCtable"                ; sidecap.sty
    "supertabular" "xtabular"           ; supertabular.sty & xtab.sty
    "threeparttable" "measuredfigure"   ; threeparttable.sty
    "wrapfigure" "wraptable")           ; wrapfigure.sty
  "List of float types supported by `caption.sty'.
These types are provided by other LaTeX packages.")

;; Setup for various \DeclareCaption's:
(TeX-auto-add-type "caption-DeclareCaption" "LaTeX")

;; The 2. argument to `DeclareCaption[A-Za-z]' contains (La)TeX code.
;; We deliberately ignore that argument in our regex since it is not
;; needed for this style and would pollute the auto generated
;; `docname.el' file.
(defvar LaTeX-caption-DeclareCaption-regexp
  `(,(concat "\\\\DeclareCaption\\(Font\\|Format\\|Justification"
             "\\|LabelFormat\\|LabelSeparator\\|ListFormat"
             "\\|Option\\|Style\\|TextFormat\\)"
             "\\*?"
             "[ \t\n\r%]*"
             "{\\([^}]+\\)}")
    (0 1 2) LaTeX-auto-caption-DeclareCaption)
  "Matches the arguments of different `\\DeclareCaption*' from `caption.sty'.")

(defun LaTeX-caption-auto-prepare ()
  "Clear `LaTeX-auto-caption-DeclareCaption' before parsing."
  (setq LaTeX-auto-caption-DeclareCaption nil))

(add-hook 'TeX-auto-prepare-hook #'LaTeX-caption-auto-prepare t)
(add-hook 'TeX-update-style-hook #'TeX-auto-parse t)

;; In `LaTeX-caption-DeclareCaption-regexp', we match (0 1 2).  When
;; adding a new `Name', we need something unique for `0'-match until
;; the next `C-c C-n'.  We mimic that regex-match bei concat'ing the
;; elements.  It will vanish upon next `C-c C-n'.
(defun LaTeX-arg-caption-DeclareCaption (optional format)
  "Insert various `\\DeclareCaptionFORMAT' commands.
If OPTIONAL, insert argument in square brackets.  FORMAT is the
suffix of the LaTeX macro."
  (let ((name (TeX-read-string "Name: ")))
    (LaTeX-add-caption-DeclareCaptions
     (list (concat "\\DeclareCaption" format "{" name "}")
           format name))
    (TeX-argument-insert name optional)))

;; Support for an undocumented feature of caption.sty:
;; `\captionbox' sets the width of the caption equal to the width of
;; the contents (a feature provided e.g. by `threeparttable.sty').
;; The starred version typesets the caption without label and without
;; entry to the list of figures or tables.

;; The first mandatory argument {<heading>} contains the caption text
;; and the label.  We used to use `TeX-insert-macro' to do the job
;; (Thanks to M. Giordano for his valuable comments on this!), but now
;; moved to `LaTeX-label'.

;; Syntax:
;; \captionbox[<list entry>]{<heading>}[<width>][<inner-pos>]{<contents>}
;; \captionbox*{<heading>}[<width>][<inner-pos>]{<contents>}

(defun LaTeX-arg-caption-captionbox (optional &optional star)
  "Query for the arguments of \"\\captionbox\" incl. a label and insert them.
If OPTIONAL is non-nil, indicate it while reading the caption.
If STAR is non-nil, then do not query for a \\label and a short
caption, insert only a caption."
  (let* ((currenv (LaTeX-current-environment))
         (caption (TeX-read-string
                   (TeX-argument-prompt optional nil "Caption")))
         (short-caption
          (when (and (not star)
                     (>= (length caption) LaTeX-short-caption-prompt-length))
            (TeX-read-string
             (TeX-argument-prompt t nil "Short caption")))))
    (indent-according-to-mode)
    (when (and short-caption (not (string= short-caption "")))
      (insert LaTeX-optop short-caption LaTeX-optcl))
    (insert TeX-grop caption)
    (unless star (LaTeX-label currenv 'environment))
    (insert TeX-grcl))
  (let* ((TeX-arg-opening-brace "[")
         (TeX-arg-closing-brace "]")
         (TeX-last-optional-rejected nil)
         (width (LaTeX-check-insert-macro-default-style
                 (completing-read (TeX-argument-prompt t nil "Width")
                                  (mapcar (lambda (elt) (concat TeX-esc (car elt)))
                                          (LaTeX-length-list)))))
         (TeX-last-optional-rejected (or (not width)
                                         (and width (string= width ""))))
         (inpos (LaTeX-check-insert-macro-default-style
                 (if (and width (not (string-equal width "")))
                     (completing-read (TeX-argument-prompt t nil "Inner position")
                                      '("c" "l" "r" "s"))
                   ""))))
    (and width (TeX-argument-insert width t))
    (and inpos (TeX-argument-insert inpos t)))
  ;; Fill the paragraph before inserting {}.  We can use
  ;; `LaTeX-fill-paragraph' without messing up the code since
  ;; \caption starts a new paragraph with AUCTeX
  ;; (cf. `paragraph-start').
  (when auto-fill-function (LaTeX-fill-paragraph)))

(defun LaTeX-arg-caption-captionof (optional &optional star)
  "Query for the arguments of \"\\captionof\" macro and insert them.
If OPTIONAL is non-nil, insert the arguments in brackets.  If
STAR is non-nil, do not query for a short-caption and a label."
  (let* ((envtype (completing-read (TeX-argument-prompt optional nil "Float type")
                                   LaTeX-caption-supported-float-types))
         (figtypes '("figure" "subfigure" "floatingfigure"
                     "figwindow" "SCfigure" "measuredfigure" "wrapfigure"))
         (tabtypes '("table"  "subtable" "floatingtable"  "tabwindow" "SCtable"
                     "supertabular" "xtabular" "threeparttable"  "wraptable"))
         (caption (TeX-read-string
                   (TeX-argument-prompt optional nil "Caption")))
         (short-caption
          (when (and (not star)
                     (>= (length caption) LaTeX-short-caption-prompt-length))
            (TeX-read-string
             (TeX-argument-prompt t nil "Short caption")))))
    (indent-according-to-mode)
    (TeX-argument-insert envtype optional)
    (when (and short-caption (not (string= short-caption "")))
      (insert LaTeX-optop short-caption LaTeX-optcl))
    (TeX-argument-insert caption optional)
    (when auto-fill-function (LaTeX-fill-paragraph))
    (when (and (not star)
               ;; Check if `envtype' is a figure or a table, also
               ;; consult `LaTeX-label-alist' for additions from user
               ;; or newfloat.el, then run `LaTeX-label' w/
               ;; 'environment arg, otherwise w/o.
               (save-excursion
                 (if (or (member envtype figtypes)
                         (member envtype tabtypes)
                         (assoc envtype LaTeX-label-alist))
                     (LaTeX-label (cond ((member envtype figtypes)
                                         "figure")
                                        ((member envtype tabtypes)
                                         "table")
                                        (t envtype))
                                  'environment)
                   (LaTeX-label envtype))))
      (LaTeX-newline)
      (indent-according-to-mode)
      (end-of-line))))

(TeX-add-style-hook
 "caption"
 (lambda ()

   ;; Add caption to the parser.
   (TeX-auto-add-regexp LaTeX-caption-DeclareCaption-regexp)

   ;; Run style hook for ltcaption if longtable package is loaded:
   (when (member "longtable" (TeX-style-list))
     (TeX-run-style-hooks "ltcaption"))

   ;; Caption commands:
   (TeX-add-symbols
    '("caption*" t)

    '("captionlistentry"
      [TeX-arg-completing-read LaTeX-caption-supported-float-types
                               "Float type"]
      t)

    '("captionof" LaTeX-arg-caption-captionof)

    '("captionof*" (LaTeX-arg-caption-captionof t))

    '("captionsetup"
      (TeX-arg-conditional (member "bicaption" (TeX-style-list))
          ([LaTeX-arg-bicaption-captionsetup])
        ([TeX-arg-completing-read
          LaTeX-caption-supported-float-types "Float type"]))
      (TeX-arg-key-val (LaTeX-caption-key-val-options)))

    '("captionsetup*"
      (TeX-arg-conditional (member "bicaption" (TeX-style-list))
          ([LaTeX-arg-bicaption-captionsetup])
        ([TeX-arg-completing-read
          LaTeX-caption-supported-float-types "Float type"]))
      (TeX-arg-key-val (LaTeX-caption-key-val-options)))

    '("clearcaptionsetup"
      [TeX-arg-completing-read (LaTeX-caption-key-val-options) "Single key"]
      (TeX-arg-completing-read LaTeX-caption-supported-float-types "Float type"))

    '("clearcaptionsetup*"
      [TeX-arg-completing-read (LaTeX-caption-key-val-options) "Single key"]
      (TeX-arg-completing-read LaTeX-caption-supported-float-types "Float type"))

    '("captionbox"  (LaTeX-arg-caption-captionbox) t)

    '("captionbox*" (LaTeX-arg-caption-captionbox t) t)

    '("continuedfloat" 0)
    '("continuedfloat*" 0)

    '("DeclareCaptionFont"
      (LaTeX-arg-caption-DeclareCaption "Font") t)

    '("DeclareCaptionFormat"
      (LaTeX-arg-caption-DeclareCaption "Format") t)

    '("DeclareCaptionFormat*"
      (LaTeX-arg-caption-DeclareCaption "Format") t)

    '("DeclareCaptionJustification"
      (LaTeX-arg-caption-DeclareCaption "Justification") t)

    '("DeclareCaptionLabelFormat"
      (LaTeX-arg-caption-DeclareCaption "LabelFormat") t)

    '("DeclareCaptionLabelSeparator"
      (LaTeX-arg-caption-DeclareCaption "LabelSeparator") t)

    '("DeclareCaptionLabelSeparator*"
      (LaTeX-arg-caption-DeclareCaption "LabelSeparator") t)

    '("DeclareCaptionListFormat"
      (LaTeX-arg-caption-DeclareCaption "ListFormat") t)

    '("DeclareCaptionOption"
      (LaTeX-arg-caption-DeclareCaption "Option") t)

    '("DeclareCaptionStyle"
      (LaTeX-arg-caption-DeclareCaption "Style")
      [TeX-arg-key-val (LaTeX-caption-key-val-options) "Additional options"]
      (TeX-arg-key-val (LaTeX-caption-key-val-options) "Options"))

    '("DeclareCaptionTextFormat"
      (LaTeX-arg-caption-DeclareCaption "TextFormat") t)

    '("bothIfFirst" 2)

    '("bothIfSecond" 2))

   ;; \caption(box|of) macros should get their own lines
   (LaTeX-paragraph-commands-add-locally '("captionbox" "captionof"))

   ;; Fontification
   (when (and (featurep 'font-latex)
              (eq TeX-install-font-lock 'font-latex-setup))
     (font-latex-add-keywords '(("caption"           "*[{")
                                ("captionlistentry"  "[{")
                                ("captionof"         "*{[{")
                                ("captionbox"        "*[{[["))
                              'textual)
     (font-latex-add-keywords '(("captionsetup"                  "*[[{")
                                ("clearcaptionsetup"             "*[{")
                                ("continuedfloat"                "")
                                ("DeclareCaptionFont"            "{{")
                                ("DeclareCaptionFormat"          "*{{")
                                ("DeclareCaptionJustification"   "{{")
                                ("DeclareCaptionLabelFormat"     "{{")
                                ("DeclareCaptionLabelSeparator"  "*{{")
                                ("DeclareCaptionListFormat"      "{{")
                                ("DeclareCaptionOption"          "{{")
                                ("DeclareCaptionStyle"           "{[{")
                                ("DeclareCaptionTextFormat"      "{{"))
                              'function)) )
 TeX-dialect)

(defvar LaTeX-caption-package-options-list
  (append '(("compatibility"  ("true" "false"))
            ("figureposition" ("top" "above" "bottom" "below"))
            ("tableposition"  ("top" "above" "bottom" "below")))
          LaTeX-caption-key-val-options)
  "Package options for the caption package.")

(defun LaTeX-caption-package-options ()
  "Prompt for package options for the caption package."
  (TeX-read-key-val t LaTeX-caption-package-options-list))

;;; caption.el ends here