From f2b8c25e7a475bda128ee11d0ce9760b91c20f2e Mon Sep 17 00:00:00 2001 From: Carsten Dominik Date: Mon, 5 Apr 2010 15:10:22 +0200 Subject: [PATCH] More details about LaTeX setup --- ChangeLog | 4 +++ ORGWEBPAGE/Changes.org | 89 +++++++++++++++++++++++++++++++++++++++++--------- doc/ChangeLog | 5 +++ doc/org.texi | 73 ++++++++++++++++++++++------------------- lisp/ChangeLog | 8 +++++ lisp/org-latex.el | 52 +++++++++++++++++++++-------- lisp/org.el | 71 ++++++++++++++++++++++++++++------------ 7 files changed, 218 insertions(+), 84 deletions(-) diff --git a/ChangeLog b/ChangeLog index 414962340..2cf083343 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,7 @@ +2010-04-05 Carsten Dominik + + * ORGWEBPAGE/Changes.org: More details on LaTeX headers. + 2010-03-05 Carsten Dominik * Makefile: Process reference card using pdflayout.sty. Change diff --git a/ORGWEBPAGE/Changes.org b/ORGWEBPAGE/Changes.org index bc85a0943..aa8d4a681 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 f61fe7c01..97cfcbfd3 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,8 @@ +2010-04-05 Carsten Dominik + + * org.texi (LaTeX/PDF export commands): Section renamed and + moved. + 2010-04-04 Carsten Dominik * org.texi (Sectioning structure): Update. diff --git a/doc/org.texi b/doc/org.texi index b236da72a..49a6ff66b 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 b699a945e..d59b3e5c5 100755 --- a/lisp/ChangeLog +++ b/lisp/ChangeLog @@ -1,3 +1,11 @@ +2010-04-05 Carsten Dominik + + * 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 * org-publish.el (org-publish-aux-preprocess): Control case diff --git a/lisp/org-latex.el b/lisp/org-latex.el index 55a457351..3b5d6a681 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 48ec349bc..19bb2a580 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." -- 2.11.4.GIT