emacs-orgmode@gnu.org archives
 help / color / mirror / code / Atom feed
* PATCH: New options for latex src code export
@ 2011-02-02 19:42 Dan Davison
  2011-02-16 11:12 ` Bastien
  2011-02-17 14:20 ` Mike McLean
  0 siblings, 2 replies; 4+ messages in thread
From: Dan Davison @ 2011-02-02 19:42 UTC (permalink / raw)
  To: emacs org-mode mailing list

Tom Dye and I have been working on providing more user control over
latex export of src code via the listings and minted latex packages. The
main code change is 2 commits in branch "minted" of the org repo, and
pasted below as a single patch for patchwork. These changes allow Org
users to set all the available options for the \lstset
and \begin{minted} commands[1], and also to specify custom latex
environments on a per-language basis to be used for exporting src
blocks.

I'd like to ask for advice on a couple of things:

Currently, in order for a user to use minted for colored latex export of
src code, s/he would

1. install pygments
   - linux ::  apt-get install python-pygments
   - OSX / linux :: 'pip install pygments' or 'easy_install pygments'

2. (setq org-export-latex-listings 'minted)

3. Add the minted package to `org-export-latex-packages-alist', via
   customize, or

#+begin_src emacs-lisp
(require 'org-latex)
(add-to-list 'org-export-latex-packages-alist '("" "minted"))
#+end_src

4. Configure `org-latex-to-pdf-process' so that the -shell-escape option
   is passed to pdflatex.


My questions are

1. It would be nice if users didn't have to worry about step 4. Can
   anyone suggest a sensible way to have the "-shell-escape" option
   passed to pdflatex under the appropriate circumstances? These
   conditions include:
   1. minted is being used for export
   2. pdflatex is being used, a.o.t. e.g. rubber or some other latex
      make tool.

2. Regarding step (2), it might be preferable to have a variable
   `org-export-latex-src' which takes a single value in the set
   '(listings minted). Does anyone think it's worth making such a
   backward-incompatible change?


Minted support has been in Org for a while, but I think I'm guilty of
not having properly described it on list.  See C-h v
org-export-latex-listings. It has the advantage over listings of
creating pretty coloured pdf export of source code without any user
latex customization. My understanding is that minted.sty is in major
latex distributions (e.g. TexLive, MacTex).

Patch and commit log follow. ('git show -w' shows the changes more
helpfully.)

Dan

Footnotes:
[1] It might be possible to code all the available options into the
Customize interface?

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


    New UI for configuring latex src code export.
    
    Three new user-customizable variables:
    
    org-export-latex-listings-options (default nil)
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    Association list of options for the latex listings package.
    
    These options are supplied as a comma-separated list to the
    \\lstset command. Each element of the association list should be
    a list containing two strings: the name of the option, and the
    value. For example,
    
      (setq org-export-latex-listings-options
        '((\"basicstyle\" \"\\small\")
          (\"keywordstyle\" \"\\color{black}\\bfseries\\underbar\")))
    
    will typeset the code in a small size font with underlined, bold
    black keywords.
    
    Note that the same options will be applied to blocks of all
    languages.
    
    See ftp://ftp.tex.ac.uk/tex-archive/macros/latex/contrib/listings/listings.pdf
    
    customization group: org-export-latex
    
    org-export-latex-minted-options (default nil)
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    Association list of options for the latex minted package.
    
    These options are supplied within square brackets in
    \\begin{minted} environments. Each element of the alist should be
    a list containing two strings: the name of the option, and the
    value. For example,
    
      (setq org-export-latex-minted-options
        '((\"bgcolor\" \"bg\") (\"frame\" \"lines\")))
    
    will result in src blocks being exported with
    
    \\begin{minted}[bgcolor=bg,frame=lines]{<LANG>}
    
    as the start of the minted environment. Note that the same
    options will be applied to blocks of all languages."
    
    customization group: org-export-latex
    
    See minted.googlecode.com/files/minted.pdf
    
    org-export-latex-custom-lang-environments (default nil)
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    Association list mapping languages to language-specific latex
    environments used during export of src blocks by the listings
    and minted latex packages. For example,
    
      (setq org-export-latex-custom-lang-environments
         '((python \"pythoncode\")))
    
    * lisp/org-exp.el (org-export-format-source-code-or-example):
      Support new user-customizable options
    (org-export-latex-custom-lang-environments): Ensure new variable is defined
    (org-export-latex-listings-options): Ensure new variable is defined
    (org-export-latex-minted-options): Ensure new variable is defined
    
    * lisp/org-latex.el (org-export-latex-listings-options): New variable
    (org-export-latex-minted-options): New variable
    (org-export-latex-custom-lang-environments): New variable

diff --git a/lisp/org-exp.el b/lisp/org-exp.el
index 97f17e5..e11bb2c 100644
--- a/lisp/org-exp.el
+++ b/lisp/org-exp.el
@@ -2284,6 +2284,10 @@ in the list) and remove property and value from the list in LISTVAR."
 (defvar org-export-latex-listings-langs) ;; defined in org-latex.el
 (defvar org-export-latex-listings-w-names) ;; defined in org-latex.el
 (defvar org-export-latex-minted-langs) ;; defined in org-latex.el
+(defvar org-export-latex-custom-lang-environments) ;; defined in org-latex.el
+(defvar org-export-latex-listings-options) ;; defined in org-latex.el
+(defvar org-export-latex-minted-options) ;; defined in org-latex.el
+
 (defun org-export-format-source-code-or-example
   (backend lang code &optional opts indent caption)
   "Format CODE from language LANG and return it formatted for export.
@@ -2410,66 +2414,75 @@ INDENT was the original indentation of the block."
 	      (concat "\n#+BEGIN_HTML\n" (org-add-props rtn '(org-protected t org-example t)) "\n#+END_HTML\n\n"))
 	     ((eq backend 'latex)
 	      (setq rtn (org-export-number-lines rtn 'latex 0 0 num cont rpllbl fmt))
-	      (concat "#+BEGIN_LaTeX\n"
-		      (org-add-props
-                          (cond
-			   ((and org-export-latex-listings
-				 (not (eq org-export-latex-listings 'minted)))
-			    (concat
-			     (if lang
-				 (let*
-				     ((lang-sym (intern lang))
-				      (lstlang
-				       (or (cadr
-					    (assq
-					     lang-sym
-					     org-export-latex-listings-langs))
-					   lang)))
-				   (format "\\lstset{language=%s}\n" lstlang))
-			       "\n")
-			     (when (and caption
-					org-export-latex-listings-w-names)
-			       (format "\n%s $\\equiv$ \n"
-				       (replace-regexp-in-string
-					"_" "\\\\_" caption)))
-			     "\\begin{lstlisting}\n"
-			     rtn "\\end{lstlisting}\n"))
-			   ((eq org-export-latex-listings 'minted)
-			    (if lang
-				(let*
-				    ((lang-sym (intern lang))
-				     (minted-lang
-				      (or (cadr
-					   (assq
-					    lang-sym
-					    org-export-latex-minted-langs))
-					  (downcase lang))))
-				  (concat
-				   (when (and caption
-					      org-export-latex-listings-w-names)
-				     (format "\n%s $\\equiv$ \n"
-					     (replace-regexp-in-string
-					      "_" "\\\\_" caption)))
-				   (format "\\begin{minted}{%s}\n" minted-lang)
-				   rtn "\\end{minted}\n"))))
-			    (t (concat (car org-export-latex-verbatim-wrap)
-				       rtn (cdr org-export-latex-verbatim-wrap))))
-			   '(org-protected t org-example t))
-			  "#+END_LaTeX\n"))
-	      ((eq backend 'ascii)
-	       ;; This is not HTML or LaTeX, so just make it an example.
-	       (setq rtn (org-export-number-lines rtn 'ascii 0 0 num cont rpllbl fmt))
-	       (concat caption "\n"
-		      "#+BEGIN_ASCII\n"
-		      (org-add-props
-			  (concat
-			   (mapconcat
-			    (lambda (l) (concat "  " l))
-			    (org-split-string rtn "\n")
-			    "\n")
-			   "\n")
-			  '(org-protected t org-example t))
-		      "#+END_ASCII\n"))))
+	      (concat
+	       "#+BEGIN_LaTeX\n"
+	       (org-add-props
+		   (cond
+		    ((and lang org-export-latex-listings)
+                     (flet ((make-option-string
+                             (pair)
+                             (concat (first pair)
+				     (if (> (length (second pair)) 0)
+					 (concat "=" (second pair))))))
+		       (let* ((lang-sym (intern lang))
+			      (minted-p (eq org-export-latex-listings 'minted))
+			      (listings-p (not minted-p))
+			      (backend-lang
+			       (or (cadr
+				    (assq
+				     lang-sym
+				     (cond
+				      (minted-p org-export-latex-minted-langs)
+				      (listings-p org-export-latex-listings-langs))))
+				   lang))
+			      (custom-environment
+			       (cadr
+				(assq
+				 lang-sym
+				 org-export-latex-custom-lang-environments))))
+			 (concat
+			  (when (and listings-p (not custom-environment))
+			    (format
+			     "\\lstset{%s}\n"
+			     (mapconcat
+			      #'make-option-string
+			      (append org-export-latex-listings-options
+				      `(("language" ,backend-lang))) ",")))
+			  (when (and caption org-export-latex-listings-w-names)
+			    (format
+			     "\n%s $\\equiv$ \n"
+			     (replace-regexp-in-string "_" "\\\\_" caption)))
+			  (cond
+			   (custom-environment
+			    (format "\\begin{%s}\n%s\\end{%s}\n"
+				    custom-environment rtn custom-environment))
+			   (listings-p
+			    (format "\\begin{%s}\n%s\\end{%s}\n"
+				    "lstlisting" rtn "lstlisting"))
+			   (minted-p
+			    (format
+			     "\\begin{minted}[%s]{%s}\n%s\\end{minted}\n"
+			     (mapconcat #'make-option-string
+					org-export-latex-minted-options ",")
+			     backend-lang rtn)))))))
+                    (t (concat (car org-export-latex-verbatim-wrap)
+                               rtn (cdr org-export-latex-verbatim-wrap))))
+                   '(org-protected t org-example t))
+               "#+END_LaTeX\n"))
+             ((eq backend 'ascii)
+              ;; This is not HTML or LaTeX, so just make it an example.
+              (setq rtn (org-export-number-lines rtn 'ascii 0 0 num cont rpllbl fmt))
+              (concat caption "\n"
+                      "#+BEGIN_ASCII\n"
+                      (org-add-props
+                          (concat
+                           (mapconcat
+                            (lambda (l) (concat "  " l))
+                            (org-split-string rtn "\n")
+                            "\n")
+                           "\n")
+                          '(org-protected t org-example t))
+                      "#+END_ASCII\n"))))
       (org-add-props rtn nil 'original-indentation indent))))
 
 (defun org-export-number-lines (text backend
diff --git a/lisp/org-latex.el b/lisp/org-latex.el
index 4d2d79a..9ea4f91 100644
--- a/lisp/org-latex.el
+++ b/lisp/org-latex.el
@@ -460,6 +460,67 @@ pygmentize -L lexers
 	   (symbol :tag "Major mode       ")
 	   (string :tag "Listings language"))))
 
+(defcustom org-export-latex-listings-options nil
+  "Association list of options for the latex listings package.
+
+These options are supplied as a comma-separated list to the
+\\lstset command. Each element of the association list should be
+a list containing two strings: the name of the option, and the
+value. For example,
+
+  (setq org-export-latex-listings-options
+    '((\"basicstyle\" \"\\small\")
+      (\"keywordstyle\" \"\\color{black}\\bfseries\\underbar\")))
+
+will typeset the code in a small size font with underlined, bold
+black keywords.
+
+Note that the same options will be applied to blocks of all
+languages."
+  :group 'org-export-latex
+  :type '(repeat
+	  (list
+	   (string :tag "Listings option name ")
+	   (string :tag "Listings option value"))))
+
+(defcustom org-export-latex-minted-options nil
+  "Association list of options for the latex minted package.
+
+These options are supplied within square brackets in
+\\begin{minted} environments. Each element of the alist should be
+a list containing two strings: the name of the option, and the
+value. For example,
+
+  (setq org-export-latex-minted-options
+    '((\"bgcolor\" \"bg\") (\"frame\" \"lines\")))
+
+will result in src blocks being exported with
+
+\\begin{minted}[bgcolor=bg,frame=lines]{<LANG>}
+
+as the start of the minted environment. Note that the same
+options will be applied to blocks of all languages."
+  :group 'org-export-latex
+  :type '(repeat
+	  (list
+	   (string :tag "Minted option name ")
+	   (string :tag "Minted option value"))))
+
+(defvar org-export-latex-custom-lang-environments nil
+  "Association list mapping languages to language-specific latex
+  environments used during export of src blocks by the listings
+  and minted latex packages. For example,
+
+  (setq org-export-latex-custom-lang-environments
+     '((python \"pythoncode\")))
+
+  would have the effect that if org encounters begin_src python
+  during latex export it will output
+
+  \\begin{pythoncode}
+  <src block body>
+  \\end{pythoncode}")
+
 (defcustom org-export-latex-remove-from-headlines
   '(:todo nil :priority nil :tags nil)
   "A plist of keywords to remove from headlines.  OBSOLETE.

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

end of thread, other threads:[~2011-06-11 20:48 UTC | newest]

Thread overview: 4+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2011-02-02 19:42 PATCH: New options for latex src code export Dan Davison
2011-02-16 11:12 ` Bastien
2011-06-11 20:48   ` Dan Davison
2011-02-17 14:20 ` Mike McLean

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).