Re: [O] [RFC] [PATCH] ox-latex: support :float no with caption for minted listings

[Nicolas Goaziou]

Hello,

Aaron Ecay aarone...@gmail.com writes:

 Done on master.

Thanks.

 OK.  I’ll think about this.  One question is what type of caption this
 should be.  (i.e. \captionof{what?}{the caption}).  Using the catch-all
 figure caption type seems most sensible to me, but feedback from other
 latex users is welcome.

FWIW, I think this is a good idea. However, as you suggest, more
feedback would be interesting, too.


Regards,

-- 
Nicolas Goaziou

Re: [O] [RFC] [PATCH] ox-latex: support :float no with caption for minted listings

[Rasmus]

Aaron Ecay aarone...@gmail.com writes:

 Merging the functions might only be worth doing if there were any more
 places where \captionof needed to be used.
 
 That's the intent, yes. It would be a waste not to use a package now
 residing in the default list. Among the transcoders where
 `org-latex--wrap-label' is used, some could probably benefit from
 a non-float caption, if requested by the user.

 OK.  I’ll think about this.  One question is what type of caption this
 should be.  (i.e. \captionof{what?}{the caption}).  Using the catch-all
 figure caption type seems most sensible to me, but feedback from other
 latex users is welcome.

One goal that should be archivable is to get rid of the (horrible)
float package in org-latex-default-packages-alist¹ .  In other words
(I'm guessing here), reinterpret [H] placement instructions and do it
the capt-of way.

—Rasmus


Footnotes: 
¹   float rewrites the float mechanism which can cause trouble.  I
personally never use it.

-- 
Enough with the bla bla!

Re: [O] [RFC] [PATCH] ox-latex: support :float no with caption for minted listings

[Aaron Ecay]

Hi Nicolas,

2014ko irailak 23an, Nicolas Goaziou-ek idatzi zuen:
 
 Hello,
 
 Aaron Ecay aarone...@gmail.com writes:
 
 Thanks for all your feedback.  The patch is now applied on master.
 
 Thank you.
 
 I’m confused about how ‘org-latex--wrap-label’ works.  It tries to
 put \label commands outside of floats.  That will yield links that
 jump to the preceding section, not the specific point in the document
 where the \label command occurs.  Probably this command should insert
 \phantomsection before the \label, so that resultant links jump to
 the right point.  (I’ll make this change if no one objects.)
 
 I have no objection.

Done on master.

 
 Merging the functions might only be worth doing if there were any more
 places where \captionof needed to be used.
 
 That's the intent, yes. It would be a waste not to use a package now
 residing in the default list. Among the transcoders where
 `org-latex--wrap-label' is used, some could probably benefit from
 a non-float caption, if requested by the user.

OK.  I’ll think about this.  One question is what type of caption this
should be.  (i.e. \captionof{what?}{the caption}).  Using the catch-all
figure caption type seems most sensible to me, but feedback from other
latex users is welcome.

Thanks,

-- 
Aaron Ecay

Re: [O] [RFC] [PATCH] ox-latex: support :float no with caption for minted listings

[Nicolas Goaziou]

Hello,

Aaron Ecay aarone...@gmail.com writes:

 Thanks for all your feedback.  The patch is now applied on master.

Thank you.

 I’m confused about how ‘org-latex--wrap-label’ works.  It tries to
 put \label commands outside of floats.  That will yield links that
 jump to the preceding section, not the specific point in the document
 where the \label command occurs.  Probably this command should insert
 \phantomsection before the \label, so that resultant links jump to
 the right point.  (I’ll make this change if no one objects.)

I have no objection.

 Merging the functions might only be worth doing if there were any more
 places where \captionof needed to be used.

That's the intent, yes. It would be a waste not to use a package now
residing in the default list. Among the transcoders where
`org-latex--wrap-label' is used, some could probably benefit from
a non-float caption, if requested by the user.


Regards,

-- 
Nicolas Goaziou

Re: [O] [RFC] [PATCH] ox-latex: support :float no with caption for minted listings

[Aaron Ecay]

Hi Nicolas,

2014ko irailak 19an, Nicolas Goaziou-ek idatzi zuen:

[...]

 
 In any case, I think you can apply the patch once the docstrings
 questions above have been sorted out.

Thanks for all your feedback.  The patch is now applied on master.

 This can do for now. Ultimately, however, I think we could merge
 `org-latex--wrap-label' into `org-latex--caption/label-string' (which
 should then produce \captionof command when appropriate). By then, the
 `replace-regexp-in-string' would not be needed anymore. WDYT?

I’m confused about how ‘org-latex--wrap-label’ works.  It tries to
put \label commands outside of floats.  That will yield links that
jump to the preceding section, not the specific point in the document
where the \label command occurs.  Probably this command should insert
\phantomsection before the \label, so that resultant links jump to
the right point.  (I’ll make this change if no one objects.)

Merging the functions might only be worth doing if there were any more
places where \captionof needed to be used.  As long as it’s just a
particular kind of source block that needs it, I think this can stay as
a little special case in the source block transcoder.  The docstrings
seem to spell out the criteria for using one function vs. the other
well, so there’s little danger of confusion.  Adding \phantomsection to
‘org-latex--wrap-label’ would also make them diverge further in their
internal workings.

Thanks,

-- 
Aaron Ecay

Re: [O] [RFC] [PATCH] ox-latex: support :float no with caption for minted listings

[Aaron Ecay]

Hi Nicolas,

2014ko abuztuak 28an, Nicolas Goaziou-ek idatzi zuen:
 
 Hello,
 
 Aaron Ecay aarone...@gmail.com writes:
 
 The other application I can think of is to allow captioned images and
 tables not to float.  The LaTeX world is full of tutorials on how to
 un-float floating images and tables, but IME the org community doesn’t
 ask for this.  (perhaps they implement their own solutions in latex.)
 
 Given that the capt-of package is just two lines of code, defines just
 one new command, and doesn’t modify any existing code, I’m inclined to
 the belief that adding it to the default packages list is tolerable.
 If capt-of is added to the default packages, then caption, non-float,
 org-latex-listing = nil source blocks can also be handled.  
 
 I agree. Do you want to take care of this? This requires an entry in
 ORG-NEWS and some documentation changes too.

See the attached patch.  I updated ORG-NEWS, but the manual
(info (org) LaTeX specific attributes) is already sufficiently general
IMO.

Thanks,

-- 
Aaron Ecay
From 15ced3a12b8882292f43eb7351988be4ddf3d63f Mon Sep 17 00:00:00 2001
From: Aaron Ecay aarone...@gmail.com
Date: Sat, 23 Aug 2014 03:16:11 -0400
Subject: [PATCH] ox-latex: support :float nil with caption for minted listings
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* lisp/ox-latex.el (org-latex-src-block): Support :float nil with
caption for minted.
(org-latex-listings): Edit docstring to describe this usecase.
* lisp/org.el (org-latex-default-packages-alist): Add “capt-of”
package.

This takes advantage of the capt-of package’s \captionof command,
which allows to insert a caption (with autogenerated number and
\ref-able label) without creating a floating environment.  One example
of where this is useful is in the case of a minted source code listing
that spans more than one page.  (Latex floats can’t be larger than a
page, generally speaking.)

The listings package handles this case using its own mechanism.
---
 etc/ORG-NEWS | 11 +++
 lisp/org.el  |  2 ++
 lisp/ox-latex.el | 18 +-
 3 files changed, 26 insertions(+), 5 deletions(-)

diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS
index 62181cb..08f813b 100644
--- a/etc/ORG-NEWS
+++ b/etc/ORG-NEWS
@@ -84,6 +84,9 @@ parameters are now supported: ~:raw~, ~:backend~.  Moreover, there are
 new parameters specific to some pre-defined translators, e.g.,
 ~:environment~ and ~:booktabs~ for ~orgtbl-to-latex~.  See translators
 docstrings (including ~orgtbl-to-generic~) for details.
+*** Non-floating minted listings in Latex export
+It is not possible to specify =#+attr_latex: :float nil= in conjunction with
+source blocks exported by the minted package.
 ** Miscellaneous
 *** File names in links accept are now compatible with URI syntax
 Absolute file names can now start with =///= in addition to =/=. E.g.,
@@ -137,7 +140,7 @@ So you need to replace
 
 : #+HTML_INCLUDE_STYLE: t
 
-by 
+by
 
 : #+OPTIONS: :html-include-style t
 
@@ -191,13 +194,13 @@ of the list.
   now use =amssymb= symbols by default instead.
 
 *** New functions for paragraph motion
-
+
 The commands =C-down= and =C-up= now invoke special commands
 that use knowledge from the org-elements parser to move the cursor
 in a paragraph-like way.
 
 *** New entities in =org-entities.el=
-
+
 Add support for ell, imath, jmath, varphi, varpi, aleph, gimel, beth,
 dalet, cdots, S (§), dag, ddag, colon, therefore, because, triangleq,
 leq, geq, lessgtr, lesseqgtr, ll, lll, gg, ggg, prec, preceq,
@@ -305,7 +308,7 @@ instructions:
 - when updating through ELPA (either from GNU ELPA or from Org ELPA),
   you have to install Org's ELPA package in a session where no Org
   function has been called already.
-  
+
 When in doubt, run =M-x org-version RET= and see if you have a mixed-up
 installation.
 
diff --git a/lisp/org.el b/lisp/org.el
index cd57ec7..1f023be 100755
--- a/lisp/org.el
+++ b/lisp/org.el
@@ -4000,6 +4000,7 @@ header, or they will be appended.
 ( marvosym  t)
 ( wasysym   t)
 ( amssymb   t)
+( capt-of   nil)
 ( hyperref  nil)
 \\tolerance=1000)
   Alist of default packages to be inserted in the header.
@@ -4021,6 +4022,7 @@ Org mode to function properly:
 - textcomp, marvosymb, wasysym, amssymb: for various symbols used
   for interpreting the entities in `org-entities'.  You can skip
   some of these packages if you don't use any of their symbols.
+- capt-of: for captions on `:float nil' source blocks
 - hyperref: for cross references
 
 Therefore you should not modify this variable unless you know
diff --git a/lisp/ox-latex.el b/lisp/ox-latex.el
index f59d6b2..5d0a31c 100644
--- a/lisp/ox-latex.el
+++ b/lisp/ox-latex.el
@@ -725,6 +725,18 @@ using customize, or with
   \(require 'ox-latex)
   \(add-to-list 'org-latex-packages-alist '(\\ \minted\))
 
+You can have listings with a caption which nonetheless do not
+float.  This is useful in case 

Re: [O] [RFC] [PATCH] ox-latex: support :float no with caption for minted listings

[Nicolas Goaziou]

Hello,

Aaron Ecay aarone...@gmail.com writes:

 See the attached patch.

Thanks for the patch.

 I updated ORG-NEWS, but the manual (info (org) LaTeX specific
 attributes) is already sufficiently general IMO.

OK.

 +- capt-of: for captions on `:float nil' source blocks

I think this is too limiting as we might use this package in other
places. for captions outside of floats may be more appropriate.

 +You can have listings with a caption which nonetheless do not
 +float.  This is useful in case the source code takes up more than
 +a page, in which case trying to float it will also truncate it.
 +To achieve this, you should specifying the following attributes
 +on the source block:
 +
 +  #+caption: ...
 +  #+attr_latex: :float no
 +  #+begin_src
 +...
 +  #+end_src

I wonder if this is even needed. :float nil is described in the
manual, and capt-of is loaded by default. IOW there's no real need to
warn the user about a natural feature which doesn't require any
intervention.

 + (cond ((and (not float) (plist-member attributes :float) 
 caption)
 +(format %%s\n%s (replace-regexp-in-string
 +   caption \\captionof{listing}
 +   caption-str t t)))
 +   ((and (not float) (plist-member attributes :float)) %s)

This can do for now. Ultimately, however, I think we could merge
`org-latex--wrap-label' into `org-latex--caption/label-string' (which
should then produce \captionof command when appropriate). By then, the
`replace-regexp-in-string' would not be needed anymore. WDYT?

In any case, I think you can apply the patch once the docstrings
questions above have been sorted out.


Regards,

-- 
Nicolas Goaziou

Re: [O] [RFC] [PATCH] ox-latex: support :float no with caption for minted listings

[Nicolas Goaziou]

Hello,

Aaron Ecay aarone...@gmail.com writes:

 The other application I can think of is to allow captioned images and
 tables not to float.  The LaTeX world is full of tutorials on how to
 un-float floating images and tables, but IME the org community doesn’t
 ask for this.  (perhaps they implement their own solutions in latex.)

 Given that the capt-of package is just two lines of code, defines just
 one new command, and doesn’t modify any existing code, I’m inclined to
 the belief that adding it to the default packages list is tolerable.
 If capt-of is added to the default packages, then caption, non-float,
 org-latex-listing = nil source blocks can also be handled.  

I agree. Do you want to take care of this? This requires an entry in
ORG-NEWS and some documentation changes too.

  Note there is also :caption attribute which is used in tables and
  special blocks, but not in source blocks, which may come handy
  here.

 I can’t tell what this is for.  It looks like merely a backend-specific
 alternative to specifying the caption using org syntax (#+caption:).  Am
 I missing something?

It permits to use a different caption command (e.g., \bicaption{}{}). It
is similar to using \captionof instead of \caption. But I think adding
capt-of to default packages list is better.


Regards,

-- 
Nicolas Goaziou

Re: [O] [RFC] [PATCH] ox-latex: support :float no with caption for minted listings

[Aaron Ecay]

Hi Nicolas,

2014ko abuztuak 24an, Nicolas Goaziou-ek idatzi zuen:
 
 Hello,
 
 Aaron Ecay aarone...@gmail.com writes:
 
 Why is the compatibility=false option needed?  I can’t figure this
 out.
 
 This is in my local copy of the minted manual, in 7 Known issues. It
 may be outdated, though.

Hmm.  I had not seen that in the manual; good catch.  There didn’t seem
to be any problems in the test documents I worked with, but they were
very minimalistic so perhaps don’t exercise the problem areas.

Anyway, the suggestion from Nicolas R. of using the capt-of package
makes this moot.

 
 “Pretty” source code export in all cases requires adding certain packages
 to the default, as explained in the docstring of ‘org-latex-listings’.
 The patch adds discussion of the caption requirement there, so there is
 no “if” about the documentation.
 
 I don’t understand what you’re saying about introducing “support” for
 the caption package.  The patch uses one specific feature of the caption
 package in one specific place to accomplish one specific goal.  There
 are no other changes needed anywhere else in the codebase than these
 couple of lines in one function (plus the documentation).
 
 With your patch latex back-end can produce \captionof macros. This is
 what I call (partial) support from Org: knowing the macro.
 
 Again, using this macro is an error in the default configuration.
 Besides not doing using it at all, there are usually two ways to solve
 the problem:
 
   1. Add the package in the default package list, so the combination
  still works out of the box for anyone. E.g., `rotating' package.
  Use with care, more packages is a higher risk of incompatibilites
  between them. The lighter counterpart of `caption' package may be
  safe though.
 
  OTOH, once the package is in the default package list, it can be
  used everywhere in the back-end. This can be an advantage if there
  are several places that could use \captionof.

The other application I can think of is to allow captioned images and
tables not to float.  The LaTeX world is full of tutorials on how to
un-float floating images and tables, but IME the org community doesn’t
ask for this.  (perhaps they implement their own solutions in latex.)

Given that the capt-of package is just two lines of code, defines just
one new command, and doesn’t modify any existing code, I’m inclined to
the belief that adding it to the default packages list is tolerable.

If capt-of is added to the default packages, then caption, non-float,
org-latex-listing = nil source blocks can also be handled.  My original
patch did not handle this case, on the theory that default option values
should always generate output that complies, even if it’s not correct in
other ways.

 
   2. Suggest, through docstring or manual, to the user to require
  a specific package if he wants to benefit from the feature. E.g.,
  `booktabs'.
 
  Usually, the situation makes it obvious that such a package is
  required (e.g. :environment longtabu or :booktabs t).
  Unfortunately, this is not the case here. Under some
  circumstances, :float nil needs `caption' (or its lighter
  counterpart). I find it a bit too magical.

I see your point.  But, the \captionof command will only be emitted
if the user has changed org-latex-listings to a non-default value
(i.e. 'minted), necessitating the addition of the minted package to
org-latex-packages-alist.  The patch adds a note about the caption
(- capt-of) package to the same docstring, so hopefully it will be
obvious enough.  So this is hopefully a workable backup option to an
addition to the default list.

 
  Note there is also :caption attribute which is used in tables and
  special blocks, but not in source blocks, which may come handy
  here.

I can’t tell what this is for.  It looks like merely a backend-specific
alternative to specifying the caption using org syntax (#+caption:).  Am
I missing something?

(Actually there seems to be subtle inconsistencies with respect to the
handling of attr_latex :caption in the present code, which I will work
on a patch to fix...)

Thanks,

-- 
Aaron Ecay

Re: [O] [RFC] [PATCH] ox-latex: support :float no with caption for minted listings

[Nicolas Richard]

Aaron Ecay aarone...@gmail.com writes:

 With your patch, when encountering the combination above, the export
 back-end will introduce a captionof command, which requires loading
 caption package with a specific option (i.e., compatibility=false).

 Why is the compatibility=false option needed?  I can’t figure this
 out.

I didn't read the rest of this thread, but if all we need is \captionof,
please use the capt-of package instead. It'll avoid compatibility issues
with other classes/packages a user might load.

-- 
Nico.

Re: [O] [RFC] [PATCH] ox-latex: support :float no with caption for minted listings

[Nicolas Goaziou]

Hello,

Aaron Ecay aarone...@gmail.com writes:

 Why is the compatibility=false option needed?  I can’t figure this
 out.

This is in my local copy of the minted manual, in 7 Known issues. It
may be outdated, though.

 “Pretty” source code export in all cases requires adding certain packages
 to the default, as explained in the docstring of ‘org-latex-listings’.
 The patch adds discussion of the caption requirement there, so there is
 no “if” about the documentation.

 I don’t understand what you’re saying about introducing “support” for
 the caption package.  The patch uses one specific feature of the caption
 package in one specific place to accomplish one specific goal.  There
 are no other changes needed anywhere else in the codebase than these
 couple of lines in one function (plus the documentation).

With your patch latex back-end can produce \captionof macros. This is
what I call (partial) support from Org: knowing the macro.

Again, using this macro is an error in the default configuration.
Besides not doing using it at all, there are usually two ways to solve
the problem:

  1. Add the package in the default package list, so the combination
 still works out of the box for anyone. E.g., `rotating' package.
 Use with care, more packages is a higher risk of incompatibilites
 between them. The lighter counterpart of `caption' package may be
 safe though.

 OTOH, once the package is in the default package list, it can be
 used everywhere in the back-end. This can be an advantage if there
 are several places that could use \captionof.

  2. Suggest, through docstring or manual, to the user to require
 a specific package if he wants to benefit from the feature. E.g.,
 `booktabs'.

 Usually, the situation makes it obvious that such a package is
 required (e.g. :environment longtabu or :booktabs t).
 Unfortunately, this is not the case here. Under some
 circumstances, :float nil needs `caption' (or its lighter
 counterpart). I find it a bit too magical.

 Note there is also :caption attribute which is used in tables and
 special blocks, but not in source blocks, which may come handy
 here.


WDYT?


Regards,

-- 
Nicolas Goaziou

[O] [RFC] [PATCH] ox-latex: support :float no with caption for minted listings

[Aaron Ecay]

* lisp/ox-latex.el (org-latex-src-block): Support :float no with
caption for minted.
(org-latex-listings): Edit docstring to describe this usecase.

This takes advantage of the caption package’s \captionof command,
which allows to insert a caption (with autogenerated number and
\ref-able label) without creating a floating environment.  One example
of where this is useful is in the case of a minted source code listing
that spans more than one page.  (Latex floats can’t be larger than a
page, generally speaking.)

I haven’t done much testing, but the documentation of the listings
package seems to indicate that it already handles this case without
any special arrangement by org.
---
 lisp/ox-latex.el | 26 +-
 1 file changed, 25 insertions(+), 1 deletion(-)

diff --git a/lisp/ox-latex.el b/lisp/ox-latex.el
index c14d6dc..e29c6d2 100644
--- a/lisp/ox-latex.el
+++ b/lisp/ox-latex.el
@@ -727,6 +727,26 @@ using customize, or with
   \(require 'ox-latex)
   \(add-to-list 'org-latex-packages-alist '(\\ \minted\))

+You can have listings with a caption which nonetheless do not
+float.  This is useful in case the source code takes up more than
+a page, in which case trying to float it will also truncate it.
+To achieve this, you should specifying the following attributes
+on the source block:
+
+  #+caption: ...
+  #+attr_latex: :float no
+  #+begin_src
+...
+  #+end_src
+
+In this case, if you are using minted you must add the
+\caption\ latex package to your document:
+
+  \(add-to-list 'org-latex-packages-alist '(\\ \caption\))
+
+The listings package handles this case correctly with no
+additional packages.
+
 In addition, it is necessary to install pygments
 \(http://pygments.org), and to configure the variable
 `org-latex-pdf-process' so that the -shell-escape option is
@@ -2301,7 +2321,11 @@ contextual information.
((eq listings 'minted)
(let* ((caption-str (org-latex--caption/label-string src-block info))
   (float-env
-   (cond ((and (not float) (plist-member attributes :float)) %s)
+   (cond ((and (string= no float) caption)
+  (format %%s\n%s (replace-regexp-in-string
+ caption \\captionof{listing}
+ caption-str t t)))
+ ((string= no float) %s)
  ((string= multicolumn float)
   (format \\begin{listing*}\n%%s\n%s\\end{listing*}
   caption-str))
--
2.0.4

Re: [O] [RFC] [PATCH] ox-latex: support :float no with caption for minted listings

[Nicolas Goaziou]

Hello,

Aaron Ecay aarone...@gmail.com writes:

 * lisp/ox-latex.el (org-latex-src-block): Support :float no with
 caption for minted.
 (org-latex-listings): Edit docstring to describe this usecase.

There is already :float nil, which is documented in the manual.

 + (cond ((and (string= no float) caption)
 +(format %%s\n%s (replace-regexp-in-string
 +   caption \\captionof{listing}
 +   caption-str t t)))

I think this should be a (trivial) filter. Is there any reason to
support captionof package out of the box?


Regards,

-- 
Nicolas Goaziou

Re: [O] [RFC] [PATCH] ox-latex: support :float no with caption for minted listings

[Aaron Ecay]

Hi Nicolas,

2014ko abuztuak 23an, Nicolas Goaziou-ek idatzi zuen:
 
 Hello,
 
 Aaron Ecay aarone...@gmail.com writes:
 
 * lisp/ox-latex.el (org-latex-src-block): Support :float no with
 caption for minted.
 (org-latex-listings): Edit docstring to describe this usecase.
 
 There is already :float nil, which is documented in the manual.

You’re right – this was confusion on my part induced by babel header
args, which use yes and no instead of t and nil.  I’ll fix it.

 
 +(cond ((and (string= no float) caption)
 +   (format %%s\n%s (replace-regexp-in-string
 +  caption \\captionof{listing}
 +  caption-str t t)))
 
 I think this should be a (trivial) filter. Is there any reason to
 support captionof package out of the box?

It’s not adding any new functionality to the exporter, but rather
covering one particular combination of already-existing options (caption
provided, :float nil, org-latex-listings = minted) that does not produce
sensible output presently.  Should I fix the nil/no issue and send a new
patch?

Thanks for your feedback,

-- 
Aaron Ecay

Re: [O] [RFC] [PATCH] ox-latex: support :float no with caption for minted listings

[Nicolas Goaziou]

Aaron Ecay aarone...@gmail.com writes:

 It’s not adding any new functionality to the exporter,

Well, it is, since captionof command doesn't exist in Org default
packages.

 but rather covering one particular combination of already-existing
 options (caption provided, :float nil, org-latex-listings = minted)
 that does not produce sensible output presently. Should I fix the
 nil/no issue and send a new patch?

With your patch, when encountering the combination above, the export
back-end will introduce a captionof command, which requires loading
caption package with a specific option (i.e., compatibility=false).

If this is explained nowhere, it is hardly a fix. If you document it,
you introduce support for caption package in Org. Is there a strong
reason for that?


Regards,

-- 
Nicolas Goaziou

Re: [O] [RFC] [PATCH] ox-latex: support :float no with caption for minted listings

[Aaron Ecay]

Hi Nicolas,

2014ko abuztuak 23an, Nicolas Goaziou-ek idatzi zuen:
 
 Aaron Ecay aarone...@gmail.com writes:
 
 It’s not adding any new functionality to the exporter,
 
 Well, it is, since captionof command doesn't exist in Org default
 packages.

I guess this was unclear.  What I meant was that the patch is not
introducing any new expressivity on the org-mode side.  There is a
situation (described in my previous mail) that is a valid combination of
org configuration variables and buffer text, which produces inconsistent
latex output.  This patch fixes that.

 
 but rather covering one particular combination of already-existing
 options (caption provided, :float nil, org-latex-listings = minted)
 that does not produce sensible output presently. Should I fix the
 nil/no issue and send a new patch?
 
 With your patch, when encountering the combination above, the export
 back-end will introduce a captionof command, which requires loading
 caption package with a specific option (i.e., compatibility=false).

Why is the compatibility=false option needed?  I can’t figure this
out.

 
 If this is explained nowhere, it is hardly a fix. If you document it,
 you introduce support for caption package in Org. Is there a strong
 reason for that?

“Pretty” source code export in all cases requires adding certain packages
to the default, as explained in the docstring of ‘org-latex-listings’.
The patch adds discussion of the caption requirement there, so there is
no “if” about the documentation.

I don’t understand what you’re saying about introducing “support” for
the caption package.  The patch uses one specific feature of the caption
package in one specific place to accomplish one specific goal.  There
are no other changes needed anywhere else in the codebase than these
couple of lines in one function (plus the documentation).

The motivating reason is described in my first paragraph above – making
the output consistent for all combinations of options.

Thanks,

-- 
Aaron Ecay