More details about LaTeX setup

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

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
+So far this variable has been used to specify the complete header
-=\documentclass= macro as well as all the =\usepackage= calls
+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
+definition in =org-export-latex-classes= should then not contain
-=\documentclass= macro and packages and macro definitions for
+the corresponding =\usepackage= calls (see below).
-this specific class definition.
 
-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
+If you want more control about which segment is placed where, or
-their =\usepackage= statements by inserting a placeholder
+if you want, for a specific class, have full control over the
-=[PACkAGES]= into the header in =org-export-latex-classes=.
+header and exclude some of the automatic building blocks, you can
+put the following macro-like place holders into the header:
+
+#+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 call that
+should revise that customization and remove any package calls that
-are covered by =org-export-latex-default-packages-alist=.  You
+are covered by =org-export-latex-default-packages-alist=.  This
-can also consider moving packages that you use in all classes to
+applies to the following packages:
-=org-export-latex-packages-alist=.
 
+- 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
 

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.

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,7 +9574,41 @@ 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
+@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}.
+
+@vindex org-export-latex-default-class
+@vindex org-export-latex-classes
+@vindex org-export-latex-default-packages-alist
+@vindex org-export-latex-packages-alist
+@cindex #+LATEX_HEADER
+@cindex #+LATEX_CLASS
+@cindex #+LATEX_CLASS_OPTIONS
+@cindex property, LATEX_CLASS
+@cindex property, LATEX_CLASS_OPTIONS
+You can change this globally by setting a different value for
+@code{org-export-latex-default-class} or locally by adding an option like
+@code{#+LaTeX_CLASS: myclass} in your file, or with a @code{:LaTeX_CLASS:}
+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
+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.  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
@@ -9598,37 +9632,8 @@ 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
-@cindex La@TeX{} class
-@cindex La@TeX{} sectioning structure
 
-By default, the La@TeX{} output uses the class @code{article}.
+@node Tables in LaTeX export, Images in LaTeX export, Quoting LaTeX code, LaTeX and PDF export
-
-@vindex org-export-latex-default-class
-@vindex org-export-latex-classes
-@vindex org-export-latex-default-packages-alist
-@vindex org-export-latex-packages-alist
-@cindex #+LATEX_HEADER
-@cindex #+LATEX_CLASS
-@cindex #+LATEX_CLASS_OPTIONS
-@cindex property, LATEX_CLASS
-@cindex property, LATEX_CLASS_OPTIONS
-You can change this globally by setting a different value for
-@code{org-export-latex-default-class} or locally by adding an option like
-@code{#+LaTeX_CLASS: myclass} in your file, or with a @code{:LaTeX_CLASS:}
-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 
-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.
-
-@node Tables in LaTeX export, Images in LaTeX export, Sectioning structure, LaTeX and PDF export
 @subsection Tables in La@TeX{} export
 @cindex tables, in La@TeX{} export
 

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

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
+It should contain the \\documentclass macro, and anything else that is needed
-setup code that is specific to this class.  This will be augmented by
+for this setup.  To this header, the following commands will be added:
-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
+- 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
+the (reduced) level of the headline, and the headline text.  The function
-returns a cons cell with the (possibly modified) headline text, and the
+must return a cons cell with the (possibly modified) headline text, and the
 sectioning list in the cdr."
   :group 'org-export-latex
   :type '(repeat

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)
+(defun org-splice-latex-header (tpl def-pkg pkg &optional extra)
-  "Fill a LaTeX header template.
+  "Fill a LaTeX header template TPL.
-If TEMPLATE contains the string \"[PACKAGES]\", this is where the packages
+In the template, the following place holders will be recognized:
-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."
+ [DEFAULT-PACKAGES]      \\usepackage statements for DEF-PKG
-  (let ((packages
+ [NO-DEFAULT-PACKAGES]   do not include DEF-PKG
-	 (and (or packages-1 packages-2)
+ [PACKAGES]              \\usepackage statements for PKG 
-	      (mapconcat (lambda(p)
+ [NO-PACKAGES]           do not include PKG
-			   (if (equal "" (car p))
+ [EXTRA]                 the string EXTRA
-			       (format "\\usepackage{%s}" (cadr p))
+ [NO-EXTRA]              do not include EXTRA
-			     (format "\\usepackage[%s]{%s}"
+
-				     (car p) (cadr p))))
+For backward compatibility, if both the positive and the negative place
-			 (append packages-1 packages-2)
+holder is missing, the positive one (without the \"NO-\") will be
-			 "\n"))))
+assumed to be present at the end of the template.
-    (if (string-match "\\[PACKAGES\\]" template)
+DEF-PKG and PKG are assumed to be alists of options/packagename lists.
-	(setq template (replace-match (or packages "") t t template))
+EXTRA is a string."
-      (setq template (concat template "\n" packages)))
+  (let (rpl (end ""))
-    (if (and extra (string-match "\\S-" extra))
+    (if (string-match "^[ \t]*\\[\\(NO-\\)?DEFAULT-PACKAGES\\][ \t]*\n?" tpl)
-	(concat template "\n" extra)
+	(setq rpl (if (or (match-end 1) (not def-pkg))
-      template)))
+		      "" (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."