summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorCarsten Dominik <carsten.dominik@gmail.com>2010-04-05 15:10:22 +0200
committerCarsten Dominik <carsten.dominik@gmail.com>2010-04-05 15:10:22 +0200
commitf2b8c25e7a475bda128ee11d0ce9760b91c20f2e (patch)
tree5605fdd1f0eb93269bec53824a9f98c0db94ae5a
parent0e530ee7955bda6976823f23266356d99bc7fedb (diff)
downloadorg-mode-f2b8c25e7a475bda128ee11d0ce9760b91c20f2e.tar.gz
More details about LaTeX setup
-rw-r--r--ChangeLog4
-rw-r--r--ORGWEBPAGE/Changes.org89
-rw-r--r--doc/ChangeLog5
-rw-r--r--doc/org.texi73
-rwxr-xr-xlisp/ChangeLog8
-rw-r--r--lisp/org-latex.el52
-rw-r--r--lisp/org.el71
7 files changed, 218 insertions, 84 deletions
diff --git a/ChangeLog b/ChangeLog
index 4149623..2cf0833 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,7 @@
+2010-04-05 Carsten Dominik <carsten.dominik@gmail.com>
+
+ * ORGWEBPAGE/Changes.org: More details on LaTeX headers.
+
2010-03-05 Carsten Dominik <carsten.dominik@gmail.com>
* Makefile: Process reference card using pdflayout.sty. Change
diff --git a/ORGWEBPAGE/Changes.org b/ORGWEBPAGE/Changes.org
index bc85a09..aa8d4a6 100644
--- a/ORGWEBPAGE/Changes.org
+++ b/ORGWEBPAGE/Changes.org
@@ -16,23 +16,41 @@
*** Changes to the intended use of =org-export-latex-classes=
-So far this variable has been used to specify the
-=\documentclass= macro as well as all the =\usepackage= calls
+So far this variable has been used to specify the complete header
+of the LaTeX document, including all the =\usepackage= calls
necessary for the document. This setup makes it difficult to
maintain the list of packages that Org itself would like to call,
-for example for the special symbol support it needs.
+for example for the special symbol support it needs. Each time I
+have to add a package, I have to ask people to revise the
+configuration of this variable. In this release, I have tried to
+fix this.
+
+First of all, you can *opt out of this change* in the following
+way: You can say: /I want to have full control over headers, and
+I will take responsibility to include the packages Org needs/.
+If that is what you want, add this to your configuration and skip
+the rest of this section (except maybe for the description of the
+=[EXTRA]= place holder):
+
+#+begin_src emacs-lisp
+ (setq org-export-latex-default-packages-alist nil
+ org-export-latex-packages-alist nil)
+#+end_src
+
+/Continue to read here if you want to go along with the modified
+setup./
There are now two variables that should be used to list the LaTeX
packages that need to be included in all classes. The header
-definition in =org-export-latex-classes= should then contain the
-=\documentclass= macro and packages and macro definitions for
-this specific class definition.
+definition in =org-export-latex-classes= should then not contain
+the corresponding =\usepackage= calls (see below).
-The two variables are:
+The two new variables are:
1. =org-export-latex-default-packages-alist= :: This is the
variable where Org-mode itself puts the packages it needs.
- The only reason to change it is when one of these packages
+ Normally you should not change this variable. The only
+ reason to change it anyway is when one of these packages
causes a conflict with another package you want to use.
Then you can remove that packages and hope that you are not
using Org-mode functionality that needs it.
@@ -49,16 +67,55 @@ document are:
3. =org-export-latex-packages-alist=
4. Buffer-specific things set with =#+LaTeX_HEADER:=
-You can change the location where the two packages variables put
-their =\usepackage= statements by inserting a placeholder
-=[PACkAGES]= into the header in =org-export-latex-classes=.
+If you want more control about which segment is placed where, or
+if you want, for a specific class, have full control over the
+header and exclude some of the automatic building blocks, you can
+put the following macro-like place holders into the header:
-If you have currently customized =org-export-latex-classes=, you
-should revise that customization and remove any package call that
-are covered by =org-export-latex-default-packages-alist=. You
-can also consider moving packages that you use in all classes to
-=org-export-latex-packages-alist=.
+#+begin_example
+[DEFAULT-PACKAGES] \usepackage statements for default packages
+[NO-DEFAULT-PACKAGES] do not include any of the default packages
+[PACKAGES] \usepackage statements for packages
+[NO-PACKAGES] do not include the packages
+[EXTRA] the stuff from #+LaTeX_HEADER
+[NO-EXTRA] do not include #+LaTeX_HEADER stuff
+#+end_example
+If you have currently customized =org-export-latex-classes=, you
+should revise that customization and remove any package calls that
+are covered by =org-export-latex-default-packages-alist=. This
+applies to the following packages:
+
+- inputenc
+- fontenc
+- graphicx
+- longtable
+- float
+- wrapfig
+- soul
+- t1enc
+- textcomp
+- marvosym
+- wasysym
+- latexsym
+- amssymb
+- hyperref
+
+If one of these packages creates a conflict with another package
+you are using, you can remove it from
+=org-export-latex-default-packages-alist=. But then you risk
+that some of the advertised export features of Org will not work
+properly.
+
+You can also consider moving packages that you use in all classes
+to =org-export-latex-packages-alist=. If necessary, put the
+place holders so that the packages get loaded in the right
+sequence. As said above, for backward compatibility, if you omit
+the place holders, all the variables will dump their content at
+the end of the header.
+
+Damn, this has become more complex than I wanted it to be. I
+hope that in practice, this will not be complicated at all.
*** The constant =org-html-entities= is obsolete
diff --git a/doc/ChangeLog b/doc/ChangeLog
index f61fe7c..97cfcbf 100644
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,3 +1,8 @@
+2010-04-05 Carsten Dominik <carsten.dominik@gmail.com>
+
+ * org.texi (LaTeX/PDF export commands): Section renamed and
+ moved.
+
2010-04-04 Carsten Dominik <carsten.dominik@gmail.com>
* org.texi (Sectioning structure): Update.
diff --git a/doc/org.texi b/doc/org.texi
index b236da7..49a6ff6 100644
--- a/doc/org.texi
+++ b/doc/org.texi
@@ -356,8 +356,8 @@ HTML export
La@TeX{} and PDF export
* LaTeX/PDF export commands:: Which key invokes which commands
+* Header and sectioning:: Setting up the export file structure
* Quoting LaTeX code:: Incorporating literal La@TeX{} code
-* Sectioning structure:: Changing sectioning in La@TeX{} output
* Tables in LaTeX export:: Options for exporting tables to La@TeX{}
* Images in LaTeX export:: How to insert figures into La@TeX{} output
* Beamer class export:: Turning the file into a presentation
@@ -9508,14 +9508,14 @@ references, the PDF output file will be fully linked.
@menu
* LaTeX/PDF export commands:: Which key invokes which commands
+* Header and sectioning:: Setting up the export file structure
* Quoting LaTeX code:: Incorporating literal La@TeX{} code
-* Sectioning structure:: Changing sectioning in La@TeX{} output
* Tables in LaTeX export:: Options for exporting tables to La@TeX{}
* Images in LaTeX export:: How to insert figures into La@TeX{} output
* Beamer class export:: Turning the file into a presentation
@end menu
-@node LaTeX/PDF export commands, Quoting LaTeX code, LaTeX and PDF export, LaTeX and PDF export
+@node LaTeX/PDF export commands, Header and sectioning, LaTeX and PDF export, LaTeX and PDF export
@subsection La@TeX{} export commands
@cindex region, active
@@ -9574,34 +9574,13 @@ with a numeric prefix argument. For example,
@noindent
creates two levels of headings and does the rest as items.
-@node Quoting LaTeX code, Sectioning structure, LaTeX/PDF export commands, LaTeX and PDF export
-@subsection Quoting La@TeX{} code
-
-Embedded La@TeX{} as described in @ref{Embedded LaTeX}, will be correctly
-inserted into the La@TeX{} file. This includes simple macros like
-@samp{\ref@{LABEL@}} to create a cross reference to a figure. Furthermore,
-you can add special code that should only be present in La@TeX{} export with
-the following constructs:
-
-@cindex #+LaTeX
-@cindex #+BEGIN_LaTeX
-@example
-#+LaTeX: Literal LaTeX code for export
-@end example
-
-@noindent or
-@cindex #+BEGIN_LaTeX
-
-@example
-#+BEGIN_LaTeX
-All lines between these markers are exported literally
-#+END_LaTeX
-@end example
-
-@node Sectioning structure, Tables in LaTeX export, Quoting LaTeX code, LaTeX and PDF export
-@subsection Sectioning structure
+@node Header and sectioning, Quoting LaTeX code, LaTeX/PDF export commands, LaTeX and PDF export
+@subsection Header and sectioning structure
@cindex La@TeX{} class
@cindex La@TeX{} sectioning structure
+@cindex La@TeX{} header
+@cindex header, for LaTeX files
+@cindex sectioning structure, for LaTeX export
By default, the La@TeX{} output uses the class @code{article}.
@@ -9621,14 +9600,40 @@ property that applies when exporting a region containing only this (sub)tree.
The class must be listed in @code{org-export-latex-classes}. This variable
defines a header template for each class@footnote{Into which the values of
@code{org-export-latex-default-packages-alist} and
-@code{org-export-latex-packages-alist} are spliced.}, and allows you to
+@code{org-export-latex-packages-alist} are spliced.}, and allows you to
define the sectioning structure for each class. You can also define your own
classes there. @code{#+LaTeX_CLASS_OPTIONS} or a @code{LaTeX_CLASS_OPTIONS}
-property can specify the options for the @code{\documentclass} macro.
-You can also use @code{#+LATEX_HEADER: \usepackage@{xyz@}} to add lines to
-the header.
+property can specify the options for the @code{\documentclass} macro. You
+can also use @code{#+LATEX_HEADER: \usepackage@{xyz@}} to add lines to the
+header. See the docstring of @code{org-export-latex-classes} for more
+information.
+
+@node Quoting LaTeX code, Tables in LaTeX export, Header and sectioning, LaTeX and PDF export
+@subsection Quoting La@TeX{} code
+
+Embedded La@TeX{} as described in @ref{Embedded LaTeX}, will be correctly
+inserted into the La@TeX{} file. This includes simple macros like
+@samp{\ref@{LABEL@}} to create a cross reference to a figure. Furthermore,
+you can add special code that should only be present in La@TeX{} export with
+the following constructs:
+
+@cindex #+LaTeX
+@cindex #+BEGIN_LaTeX
+@example
+#+LaTeX: Literal LaTeX code for export
+@end example
+
+@noindent or
+@cindex #+BEGIN_LaTeX
+
+@example
+#+BEGIN_LaTeX
+All lines between these markers are exported literally
+#+END_LaTeX
+@end example
+
-@node Tables in LaTeX export, Images in LaTeX export, Sectioning structure, LaTeX and PDF export
+@node Tables in LaTeX export, Images in LaTeX export, Quoting LaTeX code, LaTeX and PDF export
@subsection Tables in La@TeX{} export
@cindex tables, in La@TeX{} export
diff --git a/lisp/ChangeLog b/lisp/ChangeLog
index b699a94..d59b3e5 100755
--- a/lisp/ChangeLog
+++ b/lisp/ChangeLog
@@ -1,3 +1,11 @@
+2010-04-05 Carsten Dominik <carsten.dominik@gmail.com>
+
+ * org-latex.el (org-export-latex-classes): Update docstring.
+
+ * org.el (org-format-latex-header): Add cookies to the header.
+ (org-splice-latex-header): Implement placement according to
+ cookies.
+
2010-04-04 Carsten Dominik <carsten.dominik@gmail.com>
* org-publish.el (org-publish-aux-preprocess): Control case
diff --git a/lisp/org-latex.el b/lisp/org-latex.el
index 55a4573..3b5d6a6 100644
--- a/lisp/org-latex.el
+++ b/lisp/org-latex.el
@@ -128,16 +128,40 @@ The header string
-----------------
The HEADER-STRING is the header that will be inserted into the LaTeX file.
-It should really only contain the contain the \\documentclass macro, and
-setup code that is specific to this class. This will be augmented by
-call to \\usepackage for all packages mentioned in the variables
-`org-export-latex-default-packages-alist' and
-`org-export-latex-packages-alist'. Normally these package definitions will
-appear at the end of HEADER-STRING, but if HEADER-STRING contains the
-string \"[PACKAGES]\", it will be replaced by the usepackage definitions.
-Lines specified via \"#+LaTeX_HEADER:\" are also added, at the end.
-
-If `org-export-latex-default-packages-alist' contains
+It should contain the \\documentclass macro, and anything else that is needed
+for this setup. To this header, the following commands will be added:
+
+- Calls to \\usepackage for all packages mentioned in the variables
+ `org-export-latex-default-packages-alist' and
+ `org-export-latex-packages-alist'. Thus, your header definitions should
+ avoid to also request these packages.
+
+- Lines specified via \"#+LaTeX_HEADER:\"
+
+If you need more control about the sequence in which the header is built
+up, or if you want to exclude one of these building blocks for a particular
+class, you can use the following macro-like placeholders.
+
+ [DEFAULT-PACKAGES] \usepackage statements for default packages
+ [NO-DEFAULT-PACKAGES] do not include any of the default packages
+ [PACKAGES] \\usepackage statements for packages
+ [NO-PACKAGES] do not include the packages
+ [EXTRA] the stuff from #+LaTeX_HEADER
+ [NO-EXTRA] do not include #+LaTeX_HEADER stuff
+
+So a header like
+
+ \\documentclass{article}
+ [NO-DEFAULT-PACKAGES]
+ [EXTRA]
+ \\providecommand{\\alert}[1]{\\textbf{#1}}
+ [PACKAGES]
+
+will omit the default packages, and will include the #+LaTeX_HEADER lines,
+then have a call to \\providecommand, and then place \\usepackage commands
+based on the content of `org-export-latex-packages-alist'.
+
+If your header or `org-export-latex-default-packages-alist' inserts
\"\\usepackage[AUTO]{inputenc}\", AUTO will automatically be replaced with
a coding system derived from `buffer-file-coding-system'. See also the
variable `org-export-latex-inputenc-alist' for a way to influence this
@@ -147,7 +171,7 @@ The sectioning structure
------------------------
The sectioning structure of the class is given by the elements following
-the header string. For ech sectioning level, a number of strings is
+the header string. For each sectioning level, a number of strings is
specified. A %s formatter is mandatory in each section string and will
be replaced by the title of the section.
@@ -160,14 +184,14 @@ or
(numbered-open numbered-close unnumbered-open unnumbered-close)
-providing opening and closing strings for an environment that should
+providing opening and closing strings for a LaTeX environment that should
represent the document section. The opening clause should have a %s
to represent the section title.
Instead of a list of sectioning commands, you can also specify a
function name. That function will be called with two parameters,
-the (reduced) level of the headline, and the headline text. The functions
-returns a cons cell with the (possibly modified) headline text, and the
+the (reduced) level of the headline, and the headline text. The function
+must return a cons cell with the (possibly modified) headline text, and the
sectioning list in the cdr."
:group 'org-export-latex
:type '(repeat
diff --git a/lisp/org.el b/lisp/org.el
index 48ec349..19bb2a5 100644
--- a/lisp/org.el
+++ b/lisp/org.el
@@ -2911,6 +2911,8 @@ When nil, just push out a message."
\\usepackage{amsmath}
\\usepackage[mathscr]{eucal}
\\pagestyle{empty} % do not remove
+\[PACKAGES]
+\[DEFAULT-PACKAGES]
% The settings below are copied from fullpage.sty
\\setlength{\\textwidth}{\\paperwidth}
\\addtolength{\\textwidth}{-3cm}
@@ -15297,26 +15299,55 @@ Some of the options can be changed using the variable
(delete-file (concat texfilebase e)))
pngfile))))
-(defun org-splice-latex-header (template packages-1 packages-2 &optional extra)
- "Fill a LaTeX header template.
-If TEMPLATE contains the string \"[PACKAGES]\", this is where the packages
-in the lists PACKAGES-1 and PACKAGES-2 will be inserted, otherwise the come
-at the end. If EXTRA is a string, it is also appended."
- (let ((packages
- (and (or packages-1 packages-2)
- (mapconcat (lambda(p)
- (if (equal "" (car p))
- (format "\\usepackage{%s}" (cadr p))
- (format "\\usepackage[%s]{%s}"
- (car p) (cadr p))))
- (append packages-1 packages-2)
- "\n"))))
- (if (string-match "\\[PACKAGES\\]" template)
- (setq template (replace-match (or packages "") t t template))
- (setq template (concat template "\n" packages)))
- (if (and extra (string-match "\\S-" extra))
- (concat template "\n" extra)
- template)))
+(defun org-splice-latex-header (tpl def-pkg pkg &optional extra)
+ "Fill a LaTeX header template TPL.
+In the template, the following place holders will be recognized:
+
+ [DEFAULT-PACKAGES] \\usepackage statements for DEF-PKG
+ [NO-DEFAULT-PACKAGES] do not include DEF-PKG
+ [PACKAGES] \\usepackage statements for PKG
+ [NO-PACKAGES] do not include PKG
+ [EXTRA] the string EXTRA
+ [NO-EXTRA] do not include EXTRA
+
+For backward compatibility, if both the positive and the negative place
+holder is missing, the positive one (without the \"NO-\") will be
+assumed to be present at the end of the template.
+DEF-PKG and PKG are assumed to be alists of options/packagename lists.
+EXTRA is a string."
+ (let (rpl (end ""))
+ (if (string-match "^[ \t]*\\[\\(NO-\\)?DEFAULT-PACKAGES\\][ \t]*\n?" tpl)
+ (setq rpl (if (or (match-end 1) (not def-pkg))
+ "" (org-latex-packages-to-string def-pkg t))
+ tpl (replace-match rpl t t tpl))
+ (if def-pkg (setq end (org-latex-packages-to-string def-pkg))))
+
+ (if (string-match "\\[\\(NO-\\)?PACKAGES\\][ \t]*\n?" tpl)
+ (setq rpl (if (or (match-end 1) (not pkg))
+ "" (org-latex-packages-to-string pkg t))
+ tpl (replace-match rpl t t tpl))
+ (if pkg (setq end (concat end "\n" (org-latex-packages-to-string pkg)))))
+
+ (if (string-match "\\[\\(NO-\\)?EXTRA\\][ \t]*\n?" tpl)
+ (setq rpl (if (or (match-end 1) (not extra))
+ "" (concat extra "\n"))
+ tpl (replace-match rpl t t tpl))
+ (if pkg (setq end (org-latex-packages-to-string pkg))))
+
+ (if (string-match "\\S-" end)
+ (concat tpl "\n" end)
+ tpl)))
+
+(defun org-latex-packages-to-string (pkg &optional newline)
+ "Turn an alist of packages into a string with the \\usepackage macros."
+ (setq pkg (mapconcat (lambda(p)
+ (if (equal "" (car p))
+ (format "\\usepackage{%s}" (cadr p))
+ (format "\\usepackage[%s]{%s}"
+ (car p) (cadr p))))
+ pkg
+ "\n"))
+ (if newline (concat pkg "\n") pkg))
(defun org-dvipng-color (attr)
"Return an rgb color specification for dvipng."