Re: [AUCTeX-devel] Prompt for optional short caption parameter.

[Matthew Leach]

Mosè Giordano <address@hidden> writes:

> Hi Matt,

Hi Mosè,

> 2016-03-16 1:00 GMT+01:00 Matthew Leach <address@hidden>:
>> Hi all,
>>
>> I quite frequently use the optional short-caption parameter that one can
>> pass LaTeX's \caption macro.  However, when defining a new figure, I'm
>> not prompted for \caption's optional argument and usually have to add
>> this in manually.
>>
>> This patch adds a new prompt when creating a new figure environment that
>> will ask the user for \caption's optional parameter.  However, to
>> prevent this becoming an inconvenience, the optional parameter is only
>> prompted for if the length of the caption parameter is >=
>> `LaTeX-short-caption-prompt-length'.  The default value of the new
>> length parameter has a default value of 40 which I chose somewhat
>> arbitrarily, so can be easily changed if people like or removed
>> altogether.
>>
>> Feedback welcome :-).
>
> I like your idea and above all tying the prompt for an optional
> argument to the length of the full caption: this is indeed the reason
> why one should use a short caption.
>
> I have a couple of comments:
>
> - the caption command is inserted also in style/longtable.el and
> style/psfig.el

Ah, good spot - I missed those.

> - when you add or change a customizable option (or any interesting
> feature in general),  please prove its description for the manual as
> well.  In addition, an entry for doc/changes.texi is warmly
> recommended.  If the option is there but users have to dig into the
> code to discover it (or re-read the manual to find new feature,
> instead of having a clear list of additions) it'll be useful just for
> you ;-)

Yep, all good points.  Please see the attached V2 patch which should
take care of these. :-).

Thanks,
-- 
Matt

>From 9b43ef4afbd08816e8484185a8bf89797df9a354 Mon Sep 17 00:00:00 2001
From: Matthew Leach <address@hidden>
Date: Tue, 15 Mar 2016 23:26:29 +0000
Subject: [PATCH] Prompt for optional short caption parameter.

* latex.el (LaTeX-compose-caption-macro): New.
  (LaTeX-short-caption-prompt-length): New.
  (LaTeX-env-figure): Prompt for optional short caption parameter, when
  the caption length is >= `LaTeX-short-caption-prompt-length', and pass
  to `LaTeX-compose-caption-macro'.
* style/longtable.el ("longtable"): Likewise.
* style/psfig.el (LaTeX-env-psfigure): Likewise.
* doc/auctex.texi (Floats): Document short-caption prompting and
  `LaTeX-short-caption-prompt-length'.
* doc/changes.texi: Likewise.
---
 doc/auctex.texi    | 13 +++++++++++++
 doc/changes.texi   |  6 ++++++
 latex.el           | 37 ++++++++++++++++++++++++++++---------
 style/longtable.el | 12 +++++++-----
 style/psfig.el     | 20 +++++++++++---------
 5 files changed, 65 insertions(+), 23 deletions(-)

diff --git a/doc/auctex.texi b/doc/auctex.texi
index d0d0673..8c5218a 100644
--- a/doc/auctex.texi
+++ b/doc/auctex.texi
@@ -1005,6 +1005,14 @@ at the bottom of the float.  You can specify floats 
where the caption
 should be placed at the top with @code{LaTeX-top-caption-list}.
 @vindex LaTeX-top-caption-list
 
address@hidden short caption
+If the specified caption is greater than a specific length, then a short
+caption is prompted for and it is inserted as an optional argument to
+the @samp{\caption} macro.  The length that a caption needs to be before
+prompting for a short version is controlled by
address@hidden
address@hidden LaTeX-short-caption-prompt-length
+
 @item label
 The label of this float.  The label will have a default prefix, which is
 controlled by the variables @code{LaTeX-figure-label} and
@@ -1037,6 +1045,11 @@ Prefix to use for table labels.
 List of float environments with top caption.
 @end defopt
 
address@hidden LaTeX-short-caption-prompt-length
+Number of chars a caption should be before prompting for a short
+caption.
address@hidden defopt
+
 @node Itemize-like
 @subsection Itemize-like Environments
 @cindex Itemize
diff --git a/doc/changes.texi b/doc/changes.texi
index 141f765..9d39db2 100644
--- a/doc/changes.texi
+++ b/doc/changes.texi
@@ -12,6 +12,12 @@
 
 @itemize @bullet
 @item
+When inserting a new float, @AUCTeX{} will now prompt for a
+short-caption if the length of the caption provided is greater than a
+certain size.  This size is controlled via a new user option
address@hidden
+
address@hidden
 Parsing of the compilation log has been reworked.  You should encounter
 fewer mistaken files while navigating through errors and warnings.
 
diff --git a/latex.el b/latex.el
index 64c0f58..c0b0baf 100644
--- a/latex.el
+++ b/latex.el
@@ -1032,16 +1032,35 @@ The inserted label is returned, nil if it is empty."
              label)
          nil)))))
 
+(defcustom LaTeX-short-caption-prompt-length 40
+  "The length that the caption of a figure should be before
+  propting for \\caption's optional short-version."
+  :group 'LaTeX-environment
+  :type 'integer)
+
+(defun LaTeX-compose-caption-macro (caption &optional short-caption)
+  "Return a \\caption macro for a given CAPTION as a string.
+If SHORT-CAPTION is non-nil pass it as an optional argument to
+\\caption."
+  (let ((short-caption-string
+         (if (and short-caption
+                  (not (string= short-caption "")))
+             (concat LaTeX-optop short-caption LaTeX-optcl))))
+    (concat TeX-esc "caption" short-caption-string
+            TeX-grop caption TeX-grcl)))
+
 (defun LaTeX-env-figure (environment)
   "Create ENVIRONMENT with \\caption and \\label commands."
-  (let ((float (and LaTeX-float                ; LaTeX-float can be nil, i.e.
+  (let* ((float (and LaTeX-float               ; LaTeX-float can be nil, i.e.
                                        ; do not prompt
-                   (TeX-read-string "(Optional) Float position: " 
LaTeX-float)))
-       (caption (TeX-read-string "Caption: "))
-       (center (y-or-n-p "Center? "))
-       (active-mark (and (TeX-active-mark)
-                         (not (eq (mark) (point)))))
-       start-marker end-marker)
+                     (TeX-read-string "(Optional) Float position: " 
LaTeX-float)))
+         (caption (TeX-read-string "Caption: "))
+         (short-caption (when (>= (length caption) 
LaTeX-short-caption-prompt-length)
+                          (TeX-read-string "(Optional) Short caption: ")))
+         (center (y-or-n-p "Center? "))
+         (active-mark (and (TeX-active-mark)
+                           (not (eq (mark) (point)))))
+         start-marker end-marker)
     (when active-mark
       (if (< (mark) (point))
          (exchange-point-and-mark))
@@ -1064,7 +1083,7 @@ The inserted label is returned, nil if it is empty."
       (if (member environment LaTeX-top-caption-list)
          ;; top caption
          (progn
-           (insert TeX-esc "caption" TeX-grop caption TeX-grcl)
+           (insert (LaTeX-compose-caption-macro caption short-caption))
            ;; If `auto-fill-mode' is active, fill the caption.
            (if auto-fill-function (LaTeX-fill-paragraph))
            (LaTeX-newline)
@@ -1082,7 +1101,7 @@ The inserted label is returned, nil if it is empty."
          ;; If there is an active region point is before the backslash of
          ;; "\end" macro, go one line upwards.
          (when active-mark (forward-line -1) (indent-according-to-mode))
-         (insert TeX-esc "caption" TeX-grop caption TeX-grcl)
+         (insert (LaTeX-compose-caption-macro caption short-caption))
          ;; If `auto-fill-mode' is active, fill the caption.
          (if auto-fill-function (LaTeX-fill-paragraph))
          ;; ask for a label and if necessary insert a new line between caption
diff --git a/style/longtable.el b/style/longtable.el
index 6c9aeaf..7401c8d 100644
--- a/style/longtable.el
+++ b/style/longtable.el
@@ -34,10 +34,12 @@
  (lambda ()
    (LaTeX-add-environments
     '("longtable" (lambda (environment)
-                   (let ((pos (completing-read (TeX-argument-prompt t nil 
"Position")
-                                               '(("l") ("r") ("c"))))
-                         (fmt (TeX-read-string "Format: " 
LaTeX-default-format))
-                         (caption (TeX-read-string "Caption: ")))
+                   (let* ((pos (completing-read (TeX-argument-prompt t nil 
"Position")
+                                                 '(("l") ("r") ("c"))))
+                           (fmt (TeX-read-string "Format: " 
LaTeX-default-format))
+                           (caption (TeX-read-string "Caption: "))
+                           (short-caption (when (>= (length caption) 
LaTeX-short-caption-prompt-length)
+                                            (TeX-read-string "(Optional) Short 
caption: "))))
                      (setq LaTeX-default-format fmt)
                      (LaTeX-insert-environment environment
                                                (concat
@@ -49,7 +51,7 @@
                        ;; the longtable `\caption' is equivalent to a
                        ;; `\multicolumn', so it needs a `\\' at the
                        ;; end of the line
-                       (insert TeX-esc "caption" TeX-grop caption TeX-grcl " 
\\\\")
+                       (insert (LaTeX-compose-caption-macro caption 
short-caption) "\\\\")
                        (LaTeX-newline)
                        (indent-according-to-mode)
                        ;; ask for a label and insert a new line only
diff --git a/style/psfig.el b/style/psfig.el
index f829ef8..e471379 100644
--- a/style/psfig.el
+++ b/style/psfig.el
@@ -45,14 +45,16 @@
 
 (defun LaTeX-env-psfigure (_environment)
   "Create  with \\label and \\caption and \\psfig commands."
-  (let ((float (TeX-read-string "Float to: " LaTeX-float))
-       (caption (TeX-read-string "Caption: "))
-       (label (TeX-read-string "Label: " LaTeX-figure-label))
-        ; gf: ask if this should be centered
-       (psfile (read-file-name "PS-file: " "" "" nil))
-       (figwidth (TeX-read-string "Figure width: "))
-       (figheight (TeX-read-string "Figure height: "))
-       )
+  (let* ((float (TeX-read-string "Float to: " LaTeX-float))
+         (caption (TeX-read-string "Caption: "))
+         (short-caption (when (>= (length caption) 
LaTeX-short-caption-prompt-length)
+                          (TeX-read-string "(Optional) Short caption: ")))
+         (label (TeX-read-string "Label: " LaTeX-figure-label))
+         ; gf: ask if this should be centered
+         (psfile (read-file-name "PS-file: " "" "" nil))
+         (figwidth (TeX-read-string "Figure width: "))
+         (figheight (TeX-read-string "Figure height: "))
+         )
 
     (setq LaTeX-float (if (zerop (length float))
                          LaTeX-float
@@ -71,7 +73,7 @@
     (if (zerop (length caption))
        ()
       (newline-and-indent)
-      (insert TeX-esc "caption" TeX-grop caption TeX-grcl))
+      (insert (LaTeX-compose-caption-macro caption short-caption)))
     (if (or (zerop (length label))
            (equal LaTeX-figure-label label))
        ()
-- 
2.7.3