emacs-orgmode@gnu.org archives
 help / color / mirror / code / Atom feed
* [RFC] [PATCH] ox-latex: support :float no with caption for minted listings
@ 2014-08-23  7:36 Aaron Ecay
  2014-08-23 19:47 ` Nicolas Goaziou
  0 siblings, 1 reply; 16+ messages in thread
From: Aaron Ecay @ 2014-08-23  7:36 UTC (permalink / raw)
  To: emacs-orgmode

* 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

^ permalink raw reply related	[flat|nested] 16+ messages in thread

* Re: [RFC] [PATCH] ox-latex: support :float no with caption for minted listings
  2014-08-23  7:36 [RFC] [PATCH] ox-latex: support :float no with caption for minted listings Aaron Ecay
@ 2014-08-23 19:47 ` Nicolas Goaziou
  2014-08-23 20:27   ` Aaron Ecay
  0 siblings, 1 reply; 16+ messages in thread
From: Nicolas Goaziou @ 2014-08-23 19:47 UTC (permalink / raw)
  To: Aaron Ecay; +Cc: emacs-orgmode

Hello,

Aaron Ecay <aaronecay@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

^ permalink raw reply	[flat|nested] 16+ messages in thread

* Re: [RFC] [PATCH] ox-latex: support :float no with caption for minted listings
  2014-08-23 19:47 ` Nicolas Goaziou
@ 2014-08-23 20:27   ` Aaron Ecay
  2014-08-23 23:56     ` Nicolas Goaziou
  0 siblings, 1 reply; 16+ messages in thread
From: Aaron Ecay @ 2014-08-23 20:27 UTC (permalink / raw)
  To: Nicolas Goaziou; +Cc: emacs-orgmode

Hi Nicolas,

2014ko abuztuak 23an, Nicolas Goaziou-ek idatzi zuen:
> 
> Hello,
> 
> Aaron Ecay <aaronecay@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

^ permalink raw reply	[flat|nested] 16+ messages in thread

* Re: [RFC] [PATCH] ox-latex: support :float no with caption for minted listings
  2014-08-23 20:27   ` Aaron Ecay
@ 2014-08-23 23:56     ` Nicolas Goaziou
  2014-08-24  0:44       ` Aaron Ecay
  0 siblings, 1 reply; 16+ messages in thread
From: Nicolas Goaziou @ 2014-08-23 23:56 UTC (permalink / raw)
  To: emacs-orgmode

Aaron Ecay <aaronecay@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

^ permalink raw reply	[flat|nested] 16+ messages in thread

* Re: [RFC] [PATCH] ox-latex: support :float no with caption for minted listings
  2014-08-23 23:56     ` Nicolas Goaziou
@ 2014-08-24  0:44       ` Aaron Ecay
  2014-08-24  6:51         ` Nicolas Richard
  2014-08-24 19:54         ` Nicolas Goaziou
  0 siblings, 2 replies; 16+ messages in thread
From: Aaron Ecay @ 2014-08-24  0:44 UTC (permalink / raw)
  To: Nicolas Goaziou, emacs-orgmode

Hi Nicolas,

2014ko abuztuak 23an, Nicolas Goaziou-ek idatzi zuen:
> 
> Aaron Ecay <aaronecay@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

^ permalink raw reply	[flat|nested] 16+ messages in thread

* Re: [RFC] [PATCH] ox-latex: support :float no with caption for minted listings
  2014-08-24  0:44       ` Aaron Ecay
@ 2014-08-24  6:51         ` Nicolas Richard
  2014-08-24 19:54         ` Nicolas Goaziou
  1 sibling, 0 replies; 16+ messages in thread
From: Nicolas Richard @ 2014-08-24  6:51 UTC (permalink / raw)
  To: Nicolas Goaziou; +Cc: emacs-orgmode

Aaron Ecay <aaronecay@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.

^ permalink raw reply	[flat|nested] 16+ messages in thread

* Re: [RFC] [PATCH] ox-latex: support :float no with caption for minted listings
  2014-08-24  0:44       ` Aaron Ecay
  2014-08-24  6:51         ` Nicolas Richard
@ 2014-08-24 19:54         ` Nicolas Goaziou
  2014-08-28  5:03           ` Aaron Ecay
  1 sibling, 1 reply; 16+ messages in thread
From: Nicolas Goaziou @ 2014-08-24 19:54 UTC (permalink / raw)
  To: emacs-orgmode

Hello,

Aaron Ecay <aaronecay@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

^ permalink raw reply	[flat|nested] 16+ messages in thread

* Re: [RFC] [PATCH] ox-latex: support :float no with caption for minted listings
  2014-08-24 19:54         ` Nicolas Goaziou
@ 2014-08-28  5:03           ` Aaron Ecay
  2014-08-28  9:19             ` Nicolas Goaziou
  0 siblings, 1 reply; 16+ messages in thread
From: Aaron Ecay @ 2014-08-28  5:03 UTC (permalink / raw)
  To: Nicolas Goaziou, emacs-orgmode

Hi Nicolas,

2014ko abuztuak 24an, Nicolas Goaziou-ek idatzi zuen:
> 
> Hello,
> 
> Aaron Ecay <aaronecay@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

^ permalink raw reply	[flat|nested] 16+ messages in thread

* Re: [RFC] [PATCH] ox-latex: support :float no with caption for minted listings
  2014-08-28  5:03           ` Aaron Ecay
@ 2014-08-28  9:19             ` Nicolas Goaziou
  2014-09-19 19:04               ` Aaron Ecay
  0 siblings, 1 reply; 16+ messages in thread
From: Nicolas Goaziou @ 2014-08-28  9:19 UTC (permalink / raw)
  To: emacs-orgmode

Hello,

Aaron Ecay <aaronecay@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

^ permalink raw reply	[flat|nested] 16+ messages in thread

* Re: [RFC] [PATCH] ox-latex: support :float no with caption for minted listings
  2014-08-28  9:19             ` Nicolas Goaziou
@ 2014-09-19 19:04               ` Aaron Ecay
  2014-09-19 20:13                 ` Nicolas Goaziou
  0 siblings, 1 reply; 16+ messages in thread
From: Aaron Ecay @ 2014-09-19 19:04 UTC (permalink / raw)
  To: Nicolas Goaziou, emacs-orgmode

[-- Attachment #1: Type: text/plain, Size: 1104 bytes --]

Hi Nicolas,

2014ko abuztuak 28an, Nicolas Goaziou-ek idatzi zuen:
> 
> Hello,
> 
> Aaron Ecay <aaronecay@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

[-- Attachment #2: 0001-ox-latex-support-float-nil-with-caption-for-minted-l.patch --]
[-- Type: text/x-diff, Size: 5213 bytes --]

From 15ced3a12b8882292f43eb7351988be4ddf3d63f Mon Sep 17 00:00:00 2001
From: Aaron Ecay <aaronecay@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 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 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
@@ -2300,7 +2312,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 (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")
 		      ((string= "multicolumn" float)
 		       (format "\\begin{listing*}\n%%s\n%s\\end{listing*}"
 			       caption-str))
-- 
2.1.0


^ permalink raw reply related	[flat|nested] 16+ messages in thread

* Re: [RFC] [PATCH] ox-latex: support :float no with caption for minted listings
  2014-09-19 19:04               ` Aaron Ecay
@ 2014-09-19 20:13                 ` Nicolas Goaziou
  2014-09-23  3:09                   ` Aaron Ecay
  0 siblings, 1 reply; 16+ messages in thread
From: Nicolas Goaziou @ 2014-09-19 20:13 UTC (permalink / raw)
  To: emacs-orgmode

Hello,

Aaron Ecay <aaronecay@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

^ permalink raw reply	[flat|nested] 16+ messages in thread

* Re: [RFC] [PATCH] ox-latex: support :float no with caption for minted listings
  2014-09-19 20:13                 ` Nicolas Goaziou
@ 2014-09-23  3:09                   ` Aaron Ecay
  2014-09-23 19:48                     ` Nicolas Goaziou
  0 siblings, 1 reply; 16+ messages in thread
From: Aaron Ecay @ 2014-09-23  3:09 UTC (permalink / raw)
  To: Nicolas Goaziou, emacs-orgmode

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

^ permalink raw reply	[flat|nested] 16+ messages in thread

* Re: [RFC] [PATCH] ox-latex: support :float no with caption for minted listings
  2014-09-23  3:09                   ` Aaron Ecay
@ 2014-09-23 19:48                     ` Nicolas Goaziou
  2014-09-28  4:07                       ` Aaron Ecay
  0 siblings, 1 reply; 16+ messages in thread
From: Nicolas Goaziou @ 2014-09-23 19:48 UTC (permalink / raw)
  To: emacs-orgmode

Hello,

Aaron Ecay <aaronecay@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

^ permalink raw reply	[flat|nested] 16+ messages in thread

* Re: [RFC] [PATCH] ox-latex: support :float no with caption for minted listings
  2014-09-23 19:48                     ` Nicolas Goaziou
@ 2014-09-28  4:07                       ` Aaron Ecay
  2014-09-28  7:09                         ` Nicolas Goaziou
  2014-09-28 12:00                         ` Rasmus
  0 siblings, 2 replies; 16+ messages in thread
From: Aaron Ecay @ 2014-09-28  4:07 UTC (permalink / raw)
  To: Nicolas Goaziou, emacs-orgmode

Hi Nicolas,

2014ko irailak 23an, Nicolas Goaziou-ek idatzi zuen:
> 
> Hello,
> 
> Aaron Ecay <aaronecay@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

^ permalink raw reply	[flat|nested] 16+ messages in thread

* Re: [RFC] [PATCH] ox-latex: support :float no with caption for minted listings
  2014-09-28  4:07                       ` Aaron Ecay
@ 2014-09-28  7:09                         ` Nicolas Goaziou
  2014-09-28 12:00                         ` Rasmus
  1 sibling, 0 replies; 16+ messages in thread
From: Nicolas Goaziou @ 2014-09-28  7:09 UTC (permalink / raw)
  To: emacs-orgmode

Hello,

Aaron Ecay <aaronecay@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

^ permalink raw reply	[flat|nested] 16+ messages in thread

* Re: [RFC] [PATCH] ox-latex: support :float no with caption for minted listings
  2014-09-28  4:07                       ` Aaron Ecay
  2014-09-28  7:09                         ` Nicolas Goaziou
@ 2014-09-28 12:00                         ` Rasmus
  1 sibling, 0 replies; 16+ messages in thread
From: Rasmus @ 2014-09-28 12:00 UTC (permalink / raw)
  To: emacs-orgmode

Aaron Ecay <aaronecay@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!

^ permalink raw reply	[flat|nested] 16+ messages in thread

end of thread, other threads:[~2014-09-28 12:01 UTC | newest]

Thread overview: 16+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2014-08-23  7:36 [RFC] [PATCH] ox-latex: support :float no with caption for minted listings Aaron Ecay
2014-08-23 19:47 ` Nicolas Goaziou
2014-08-23 20:27   ` Aaron Ecay
2014-08-23 23:56     ` Nicolas Goaziou
2014-08-24  0:44       ` Aaron Ecay
2014-08-24  6:51         ` Nicolas Richard
2014-08-24 19:54         ` Nicolas Goaziou
2014-08-28  5:03           ` Aaron Ecay
2014-08-28  9:19             ` Nicolas Goaziou
2014-09-19 19:04               ` Aaron Ecay
2014-09-19 20:13                 ` Nicolas Goaziou
2014-09-23  3:09                   ` Aaron Ecay
2014-09-23 19:48                     ` Nicolas Goaziou
2014-09-28  4:07                       ` Aaron Ecay
2014-09-28  7:09                         ` Nicolas Goaziou
2014-09-28 12:00                         ` Rasmus

Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).