From 45102b68ce3c46aa2715e28519184f22b02fd5fa Mon Sep 17 00:00:00 2001 From: Carsten Dominik Date: Wed, 10 Dec 2008 12:50:07 +0100 Subject: [PATCH] Captions and attributes for images and tables during export Tables, and Hyperlinks that represent inlined images, can now be equipped with additional information that will be used during export. The information will be taken from the following special lines in the buffer and apply to the first following table or link. - #+CAPTION: :: The caption of the image or table. This string should be processed according to the export backend, but this is not yet done. - #+LABEL: :: A label to identify the figure/table for cross references. For HTML export, this string will become the ID for the `
' element that encapsulates the image tag and the caption. For LaTeX export, this string will be used as the argument of a `\label{...}' macro. These lables will be available for internal links like `[[label][Table] ]'. - #+ATTR_HTML: :: Attributes for HTML export of image, to be added as attributes into the `' tag. This string will not be processed, so it should have immediately the right format. - #+ATTR_LaTeX: :: Attributes for LaTeX export of images, to be inserted into the optional argument of the `\includegraphics[...]{file}' command, to specify scaling, clipping and other options. This string will not be processed, so it should have immediately the right format, like `width=5cm,angle=90' For LaTeX export, if either a caption or a label is given, the element will be exported as a float, i.e. wrapped into a figure or table environment. --- ORGWEBPAGE/Changes.org | 38 +++++++++++++++++++- doc/ChangeLog | 5 +++ doc/org.texi | 82 +++++++++++++++++++++++++++++++++++-------- lisp/ChangeLog | 20 +++++++++++ lisp/org-exp.el | 90 +++++++++++++++++++++++++++++++++++++++--------- lisp/org-export-latex.el | 56 +++++++++++++++++++++++------- lisp/org.el | 14 ++++++-- 7 files changed, 259 insertions(+), 46 deletions(-) diff --git a/ORGWEBPAGE/Changes.org b/ORGWEBPAGE/Changes.org index ee4be682a..e905f1eb7 100644 --- a/ORGWEBPAGE/Changes.org +++ b/ORGWEBPAGE/Changes.org @@ -11,11 +11,47 @@ #+LINK_HOME: http://orgmode.org -* Version 6.14 +* Version 6.15 (in preparation) :PROPERTIES: :VISIBILITY: content :END: +** Overview +** Incompatible changes +** Details +*** Captions and attributes for figures and tables. + +Tables, and Hyperlinks that represent inlined images, can now be +equipped with additional information that will be used during +export. The information will be taken from the following special +lines in the buffer and apply to the first following table or +link. + + - #+CAPTION: :: The caption of the image or table. This string + should be processed according to the export backend, but + this is not yet done. + - #+LABEL: :: A label to identify the figure/table for cross + references. For HTML export, this string will become the + ID for the ~
~ element that encapsulates + the image tag and the caption. For LaTeX export, this + string will be used as the argument of a ~\label{...}~ + macro. These lables will be available for internal links + like ~[[label][Table] ]~. + - #+ATTR_HTML: :: Attributes for HTML export of image, to be + added as attributes into the ~~ tag. This string + will not be processed, so it should have immediately the + right format. + - #+ATTR_LaTeX: :: Attributes for LaTeX export of images, to + be inserted into the optional argument of the + ~\includegraphics[...]{file}~ command, to specify scaling, + clipping and other options. This string will not be + processed, so it should have immediately the right + format, like =width=5cm,angle=90= + +For LaTeX export, if either a caption or a label is given, the +element will be exported as a float, i.e. wrapped into a figure +or table environment. +* Version 6.14 ** Overview - New relative timer to support timed notes diff --git a/doc/ChangeLog b/doc/ChangeLog index bd1fa590e..738733c7e 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,8 @@ +2008-12-10 Carsten Dominik + + * org.texi (Images in LaTeX export): New section. + (Inlined images, Images in HTML export): Sections renamed. + 2008-12-02 Carsten Dominik * org.texi (Using the mapping API): Fix bug in mapping example. diff --git a/doc/org.texi b/doc/org.texi index 6e9520929..cb842e39e 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -307,6 +307,7 @@ Markup rules * Literal examples:: Source code and other examples * Include files:: Include the contents of a file during export * Tables exported:: Tables are exported richly +* Inlined images:: How to inline images during export * Footnotes:: Numbers like [1] * Emphasis and monospace:: To bold or not to bold * TeX macros and LaTeX fragments:: Create special, rich export. @@ -318,15 +319,16 @@ HTML export * HTML Export commands:: How to invoke HTML export * Quoting HTML tags:: Using direct HTML in Org mode * Links:: Transformation of links for HTML -* Images:: How to include images +* Images in HTML export:: * CSS support:: Changing the appearance of the output * Javascript support:: Info and Folding in a web browser LaTeX and PDF export -* LaTeX/PDF export commands:: +* LaTeX/PDF export commands:: Which key invode which commands * Quoting LaTeX code:: Incorporating literal LaTeX code * Sectioning structure:: Changing sectioning in LaTeX output +* Images in LaTeX export:: How to insert figures into LaTeX output Publishing @@ -7101,6 +7103,7 @@ markup rule used in an Org mode buffer. * Literal examples:: Source code and other examples * Include files:: Include the contents of a file during export * Tables exported:: Tables are exported richly +* Inlined images:: How to inline images during export * Footnotes:: Numbers like [1] * Emphasis and monospace:: To bold or not to bold * TeX macros and LaTeX fragments:: Create special, rich export. @@ -7318,16 +7321,41 @@ item, use Visit the include file at point. @end table -@node Tables exported, Footnotes, Include files, Markup rules +@node Tables exported, Inlined images, Include files, Markup rules @subheading Tables @cindex tables, markup rules Both the native Org mode tables (@pxref{Tables}) and tables formatted with the @file{table.el} package will be exported properly. For Org mode tables, the lines before the first horizontal separator line will become table header -lines. +lines. You can use the following lines somewhere before the table to asssign +a caption and a label for cross references: + +@example +#+CAPTION: This is the caption for the next table (or link) +#+LABEL: tbl:basic-data +@end example + +@node Inlined images, Footnotes, Tables exported, Markup rules +@subheading Inlined Images +@cindex inlined images, markup rules + +Some backends (HTML and LaTeX) allow to directly include images into the +exported document. Org does this, if a link to an image files does not have +a description part, for example @code{[[./img/a.jpg]]}. If you wish to +define a caption for the image and maybe a label for internal cross +references, you can use (before, but close to the link) + +@example +#+CAPTION: This is the caption for the next figure link (or table) +#+LABEL: fig:SED-HR4049 +@end example -@node Footnotes, Emphasis and monospace, Tables exported, Markup rules +You may also define additional attributes for the figure. As this is +backend-specific, see the sections about the individual backends for more +information. + +@node Footnotes, Emphasis and monospace, Inlined images, Markup rules @subheading Footnotes @cindex footnotes, markup rules @cindex @file{footnote.el} @@ -7617,7 +7645,7 @@ language, but with additional support for tables. * HTML Export commands:: How to invoke HTML export * Quoting HTML tags:: Using direct HTML in Org mode * Links:: Transformation of links for HTML -* Images:: How to include images +* Images in HTML export:: * CSS support:: Changing the appearance of the output * Javascript support:: Info and Folding in a web browser @end menu @@ -7704,7 +7732,7 @@ All lines between these markers are exported literally @end example -@node Links, Images, Quoting HTML tags, HTML export +@node Links, Images in HTML export, Quoting HTML tags, HTML export @subsection Links @cindex links, in HTML export @@ -7720,14 +7748,16 @@ files while publishing them to a publishing directory see @ref{Publishing links}. If you want to specify attributes for links, you can do so using a special -syntax. Here is an example that sets @code{alt} and @code{title} attributes -for an inlined image: +@code{#+ATTR_HTML} line to defin attributes that wil be added to the +@code{} or @code{} tags. Here is an example that sets @code{alt} and +@code{title} attributes for an inlined image: @example -[[./img/a.jpg@{@{alt="This is image A" title="Image with no action"@}@}]] +#+ATTR_HTML: alt="This is image A" title="Image with no action" +[[./img/a.jpg]] @end example -@node Images, CSS support, Links, HTML export +@node Images in HTML export, CSS support, Links, HTML export @subsection Images @cindex images, inline in HTML @@ -7751,7 +7781,7 @@ will link to a high resolution version of the image, you could use: @noindent and you could use @code{http} addresses just as well. -@node CSS support, Javascript support, Images, HTML export +@node CSS support, Javascript support, Images in HTML export, HTML export @subsection CSS support @cindex CSS, for HTML export @cindex HTML export, CSS @@ -7864,9 +7894,10 @@ the LaTeX output uses @file{hyperref} to implement links and cross references, the PDF output file will be fully linked. @menu -* LaTeX/PDF export commands:: +* LaTeX/PDF export commands:: Which key invode which commands * Quoting LaTeX code:: Incorporating literal LaTeX code * Sectioning structure:: Changing sectioning in LaTeX output +* Images in LaTeX export:: How to insert figures into LaTeX output @end menu @node LaTeX/PDF export commands, Quoting LaTeX code, LaTeX and PDF export, LaTeX and PDF export @@ -7943,7 +7974,7 @@ All lines between these markers are exported literally #+END_LaTeX @end example -@node Sectioning structure, , Quoting LaTeX code, LaTeX and PDF export +@node Sectioning structure, Images in LaTeX export, Quoting LaTeX code, LaTeX and PDF export @subsection Sectioning structure @cindex LaTeX class @cindex LaTeX sectioning structure @@ -7957,6 +7988,29 @@ You can change this globally by setting a different value for structure for each class, as well as defining additonal classes. +@node Images in LaTeX export, , Sectioning structure, LaTeX and PDF export +@subsection Images in LaTeX export +@cindex images, inline in LaTeX +@cindex inlining images in LaTeX + +Images that are linked to without a description part in the link, like +@samp{[[file:img.jpg]]} or @samp{[[./img.jpg]]} will be inserted into the PDF +output files resulting from LaTeX output. Org will use an +@code{\includegraphics} macro to insert the image. If you have specified a +caption and/or a label as described in @ref{Inlined images}, the figure will +be wrappend into a @code{figure} environment and thus become a floating +element. Finally, you can use an @code{#+ATTR_LaTeX:} line to specify the +options that can be used in the optional argument of the +@code{\includegraphics} macro. + +@example +#+CAPTION: The black-body emission of the disk around HR 4049 +#+LABEL: fig:SED-HR4049 +#+ATTR_LaTeX: width=5cm,angle=90 +[[./img/sed-hr4049.pdf]] +@end example + + @node XOXO export, iCalendar export, LaTeX and PDF export, Exporting @section XOXO export @cindex XOXO export diff --git a/lisp/ChangeLog b/lisp/ChangeLog index d66c98d58..5db546a84 100755 --- a/lisp/ChangeLog +++ b/lisp/ChangeLog @@ -1,3 +1,23 @@ +2008-12-10 Carsten Dominik + + * org-export-latex.el (org-export-latex-tables) + (org-export-latex-links): Implement attribute, label, and caption + handling. + + * org-exp.el (org-export-html-style-default): Add style + definitions for the figure div. + (org-export-preprocess-string, org-export-as-html): Implement + attribute, label, and caption handling. + (org-export-attach-captions-and-attributes): New function. + (org-export-html-format-image): New function. + (org-format-org-table-html): Implement attribute, label, and + caption handling. + + * org.el (org-find-text-property-in-string): New function. + (org-extract-attributes): Use the property org-attr instead of + org-attrobutes, because this property is now set with the #+ATTR + lines. + 2008-12-08 Carsten Dominik * org-compat.el (org-substring-no-properties): Fix for XEmacs, for diff --git a/lisp/org-exp.el b/lisp/org-exp.el index 99ae9198a..a24b43913 100644 --- a/lisp/org-exp.el +++ b/lisp/org-exp.el @@ -545,7 +545,8 @@ Org-mode file." table { border-collapse: collapse; } td, th { vertical-align: top; } dt { font-weight: bold; } - + div.figure { padding: 0.5em; } + div.figure p { text-align: center; } .org-info-js_info-navigation { border-style:none; } #org-info-js_console-label { font-size:10px; font-weight:bold; white-space:nowrap; } @@ -1432,6 +1433,8 @@ on this string to produce the exported version." (let* ((htmlp (plist-get parameters :for-html)) (asciip (plist-get parameters :for-ascii)) (latexp (plist-get parameters :for-LaTeX)) + (backend (cond (htmlp 'html) (latexp 'latex) (asciip 'ascii))) + (archived-trees (plist-get parameters :archived-trees)) (inhibit-read-only t) (drawers org-drawers) @@ -1498,8 +1501,7 @@ on this string to produce the exported version." (org-export-protect-examples (if asciip 'indent nil)) ;; Protect backend specific stuff, throw away the others. - (org-export-select-backend-specific-text - (cond (htmlp 'html) (latexp 'latex) (asciip 'ascii))) + (org-export-select-backend-specific-text backend) ;; Protect quoted subtrees (org-export-protect-quoted-subtrees) @@ -1510,6 +1512,10 @@ on this string to produce the exported version." ;; Blockquotes and verse (org-export-mark-blockquote-and-verse) + ;; Attach captions to the correct opject + (setq target-alist (org-export-attach-captions-and-attributes + backend target-alist)) + ;; Remove comment environment and comment subtrees (org-export-remove-comment-blocks-and-subtrees) @@ -1838,6 +1844,41 @@ These special cookies will later be interpreted by the backend." "ORG-VERSE-END" "ORG-VERSE-START") t t))) +(defun org-export-attach-captions-and-attributes (backend target-alist) + "Move #+CAPTION, #+ATTR_BACKEND, and #+LABEL text into text properties. +If the next thing following is a table, add the text properties to the first +table line. If it is a link, add it to the line containing the link." + (goto-char (point-min)) + (remove-text-properties (point-min) (point-max) + '(org-caption nil org-attributes nil)) + (let ((case-fold-search t) + (re (concat "^#\\+caption:[ \t]+\\(.*\\)" + "\\|" + "^#\\+attr_" (symbol-name backend) ":[ \t]+\\(.*\\)" + "\\|" + "^#\\+label:[ \t]+\\(.*\\)" + "\\|" + "^[ \t]*|[^-]" + "\\|" + "^[ \t]*\\[\\[.*\\]\\][ \t]*$")) + cap attr label) + (while (re-search-forward re nil t) + (cond + ((match-end 1) + (setq cap (concat cap (if cap " " "") (org-trim (match-string 1))))) + ((match-end 2) + (setq attr (concat attr (if attr " " "") (org-trim (match-string 2))))) + ((match-end 3) + (setq label (org-trim (match-string 3)))) + (t + (add-text-properties (point-at-bol) (point-at-eol) + (list 'org-caption cap + 'org-attributes attr + 'org-label label)) + (if label (push (cons label label) target-alist)) + (setq cap nil attr nil label nil))))) + target-alist) + (defun org-export-remove-comment-blocks-and-subtrees () "Remove the comment environment, and also commented subtrees." (let ((re-commented (concat "^\\*+[ \t]+" org-comment-string "\\>")) @@ -3273,9 +3314,8 @@ lang=\"%s\" xml:lang=\"%s\"> (string-match "^\\.\\.?/" path))) "file") (t "internal"))) - (setq path (org-extract-attributes path)) - (setq attr (org-attributes-to-string - (get-text-property 0 'org-attributes path))) + (setq path (org-extract-attributes (org-link-unescape path))) + (setq attr (get-text-property 0 'org-attributes path)) (setq desc1 (if (match-end 5) (match-string 5 line)) desc2 (if (match-end 2) (concat type ":" path) path) descp (and desc1 (not (equal desc1 desc2))) @@ -3304,10 +3344,8 @@ lang=\"%s\" xml:lang=\"%s\"> (if (and (or (eq t org-export-html-inline-images) (and org-export-html-inline-images (not descp))) (org-file-image-p path)) - (setq rpl (concat "\""")) + (setq rpl (org-export-html-format-image + (concat type ":" path))) (setq link (concat type ":" path)) (setq rpl (concat " (or (eq t org-export-html-inline-images) (and org-export-html-inline-images (not descp)))) - (concat "\""") + (org-export-html-format-image thefile) (concat "" (org-export-html-format-desc desc) ""))) @@ -3670,6 +3704,23 @@ lang=\"%s\" xml:lang=\"%s\"> (org-html-do-expand s)) s)) +(defun org-export-html-format-image (src) + "Create image tag with source and attributes." + (save-match-data + (let* ((caption (org-find-text-property-in-string 'org-caption src)) + (attr (org-find-text-property-in-string 'org-attributes src)) + (label (org-find-text-property-in-string 'org-label src))) + (format "
+

+%s +

" + (if label (format "id=\"%s\" " label) "") + src + (if (string-match "\\" caption)))))) + (defvar org-table-colgroup-info nil) (defun org-format-table-ascii (lines) "Format a table for ascii export." @@ -3756,10 +3807,16 @@ lang=\"%s\" xml:lang=\"%s\"> ;; column and the special lines (setq lines (org-table-clean-before-export lines))) - (let ((head (and org-export-highlight-first-table-line + (let ((caption (or (get-text-property 0 'org-caption (car lines)) + (get-text-property (or (next-single-property-change + 0 'org-caption (car lines)) + 0) + 'org-caption (car lines)))) + (head (and org-export-highlight-first-table-line (delq nil (mapcar (lambda (x) (string-match "^[ \t]*|-" x)) (cdr lines))))) + (nlines 0) fnum i tbopen line fields html gr colgropen) (if splice (setq head nil)) @@ -3816,6 +3873,7 @@ lang=\"%s\" xml:lang=\"%s\"> fnum "") html) (if colgropen (setq html (cons (car html) (cons "" (cdr html))))) + (if caption (push (format "%s" caption) html)) (push html-table-tag html)) (concat (mapconcat 'identity html "\n") "\n"))) diff --git a/lisp/org-export-latex.el b/lisp/org-export-latex.el index 12565cc33..ad1a14aa7 100644 --- a/lisp/org-export-latex.el +++ b/lisp/org-export-latex.el @@ -855,8 +855,8 @@ links, keywords, lists, tables, fixed-width" "Export quotation marks depending on language conventions." (let* ((lang (plist-get org-export-latex-options-plist :language)) (quote-rpl (if (equal lang "fr") - '(("\\(\\s-\\)\"" "«~") - ("\\(\\S-\\)\"" "~»") + '(("\\(\\s-\\)\"" "«~") + ("\\(\\S-\\)\"" "~»") ("\\(\\s-\\)'" "`")) '(("\\(\\s-\\)\"" "``") ("\\(\\S-\\)\"" "''") @@ -1035,14 +1035,22 @@ If TIMESTAMPS, convert timestamps, otherwise delete them." (save-excursion (org-table-align)) (let* ((beg (org-table-begin)) (end (org-table-end)) - (raw-table (buffer-substring-no-properties beg end)) - fnum fields line lines olines gr colgropen line-fmt align) + (raw-table (buffer-substring beg end)) + fnum fields line lines olines gr colgropen line-fmt align + caption label attr floatp) (if org-export-latex-tables-verbatim (let* ((tbl (concat "\\begin{verbatim}\n" raw-table "\\end{verbatim}\n"))) (apply 'delete-region (list beg end)) (insert (org-export-latex-protect-string tbl))) (progn + (setq caption (org-find-text-property-in-string + 'org-caption raw-table) + attr (org-find-text-property-in-string + 'org-attributes raw-table) + label (org-find-text-property-in-string + 'org-attributes raw-table) + floatp (or caption label)) (setq lines (split-string raw-table "\n" t)) (apply 'delete-region (list beg end)) (when org-export-table-remove-special-lines @@ -1089,8 +1097,17 @@ If TIMESTAMPS, convert timestamps, otherwise delete them." lines)) (when insert (insert (org-export-latex-protect-string - (orgtbl-to-latex - lines `(:tstart ,(concat "\\begin{tabular}{" align "}")))) + (concat + (if floatp "\\begin{table}[htb]\n") + (if floatp (format + "\\caption{%s%s}\n" + (if label (concat "\\\label{" label "}")) + (or caption ""))) + "\\begin{center}\n" + (orgtbl-to-latex + lines `(:tstart ,(concat "\\begin{tabular}{" align "}"))) + "\n\\end{center}\n" + (if floatp "\\end{table}"))) "\n\n"))))))) (defun org-export-latex-fontify () @@ -1122,10 +1139,17 @@ If TIMESTAMPS, convert timestamps, otherwise delete them." (goto-char (match-beginning 0)) (let* ((re-radio org-export-latex-all-targets-re) (remove (list (match-beginning 0) (match-end 0))) - (type (match-string 2)) (raw-path (org-extract-attributes (match-string 3))) (full-raw-path (concat (match-string 1) raw-path)) (desc (match-string 5)) + (type (or (match-string 2) + (if (or (file-name-absolute-p raw-path) + (string-match "^\\.\\.?/" raw-path)) + "file"))) + (caption (org-find-text-property-in-string 'org-caption raw-path)) + (attr (org-find-text-property-in-string 'org-attributes raw-path)) + (label (org-find-text-property-in-string 'org-label raw-path)) + (floatp (or label caption)) imgp radiop ;; define the path of the link (path (cond @@ -1137,7 +1161,8 @@ If TIMESTAMPS, convert timestamps, otherwise delete them." (concat type ":" raw-path)) ((equal type "file") (if (and (or (org-file-image-p (expand-file-name raw-path)) - (string-match "\\.eps$" raw-path)) + (string-match "\\.\\(pdf\\|jpg\\|ps\\|eps\\)$" + raw-path)) (equal desc full-raw-path)) (setq imgp t) (progn (when (string-match "\\(.+\\)::.+" raw-path) @@ -1150,10 +1175,17 @@ If TIMESTAMPS, convert timestamps, otherwise delete them." ;; process with link inserting (apply 'delete-region remove) (cond ((and imgp (plist-get org-export-latex-options-plist :inline-images)) - (insert (format "\\includegraphics[%s]{%s}" - ;; image option should be set be a comment line - org-export-latex-image-default-option - (expand-file-name raw-path)))) + (insert + (concat + (if floatp "\\begin{figure}[htb]\n") + (format "\\centerline{\\includegraphics[%s]{%s}}\n" + (or attr org-export-latex-image-default-option) + (expand-file-name raw-path)) + (if floatp + (format "\\caption{%s%s}\n" + (if label (concat "\\label{" label "}")) + (or caption ""))) + (if floatp "\\end{figure}\n")))) (radiop (insert (format "\\hyperref[%s]{%s}" (org-solidify-link-text raw-path) desc))) ((not type) diff --git a/lisp/org.el b/lisp/org.el index 3ac7b08af..9406b2bb4 100644 --- a/lisp/org.el +++ b/lisp/org.el @@ -6655,7 +6655,7 @@ used as the link location instead of reading one interactively." (setq key (match-string 1 a) value (match-string 2 a) start (match-end 0) attr (plist-put attr (intern key) value)))) - (org-add-props s nil 'org-attributes attr)) + (org-add-props s nil 'org-attr attr)) s)) (defun org-attributes-to-string (plist) @@ -6663,7 +6663,8 @@ used as the link location instead of reading one interactively." (let ((s "") key value) (while plist (setq key (pop plist) value (pop plist)) - (setq s (concat s " "(symbol-name key) "=\"" value "\""))) + (and value + (setq s (concat s " " (symbol-name key) "=\"" value "\"")))) s)) ;;; Opening/following a link @@ -7740,7 +7741,8 @@ This function can be used in a hook." "BEGIN_EXAMPLE" "END_EXAMPLE" "BEGIN_QUOTE" "END_QUOTE" "BEGIN_VERSE" "END_VERSE" - "BEGIN_SRC" "END_SRC")) + "BEGIN_SRC" "END_SRC" + "CAPTION" "LABEL" "ATTR_HTML" "ATTR_LaTeX")) (defcustom org-structure-template-alist '( @@ -13412,6 +13414,12 @@ With optional NODE, go directly to that node." ;;; Generally useful functions +(defun org-find-text-property-in-string (prop s) + "Return the first non-nil value of property PROP in string S." + (or (get-text-property 0 prop s) + (get-text-property (or (next-single-property-change 0 prop s) 0) + prop s))) + (defun org-display-warning (message) ;; Copied from Emacs-Muse "Display the given MESSAGE as a warning." (if (fboundp 'display-warning) -- 2.11.4.GIT