Re: [Orgmode] PATCH: New options for latex src code export

[Mike McLean]

I just came across this and I must say an enthusiastic Thank You! I
actually "gave up" (time restrictions) on formatting some source code
the way I wanted just a few days ago and the ability to pass package
options to ``minted'' solves exactly the problem I was facing.


On 2/2/11 2:42 PM, Dan Davison wrote:
> 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.
>
>
> _______________________________________________
> Emacs-orgmode mailing list
> Please use `Reply All' to send replies to the list.
> address@hidden
> http://lists.gnu.org/mailman/listinfo/emacs-orgmode