diff --git a/contrib/lisp/org-contacts.el b/contrib/lisp/org-contacts.el index 65eeea8a4..a3c4aed6f 100644 --- a/contrib/lisp/org-contacts.el +++ b/contrib/lisp/org-contacts.el @@ -81,6 +81,12 @@ When set to nil, all your Org files will be used." :type 'string :group 'org-contacts) +(defcustom org-contacts-alias-property "ALIAS" + "Name of the property for contact name alias." + :type 'string + :group 'org-contacts) + + (defcustom org-contacts-birthday-format "Birthday: %l (%Y)" "Format of the anniversary agenda entry. The following replacements are available: @@ -129,6 +135,7 @@ The following replacements are available: (defcustom org-contacts-matcher (mapconcat 'identity (list org-contacts-email-property + org-contacts-alias-property org-contacts-tel-property org-contacts-address-property org-contacts-birthday-property) diff --git a/doc/org.texi b/doc/org.texi index 6c34fd84f..ac66b793a 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -11,7 +11,7 @@ @set txicodequotebacktick @c Version and Contact Info -@set MAINTAINERSITE @uref{http://orgmode.org,maintainers webpage} +@set MAINTAINERSITE @uref{http://orgmode.org,maintainers web page} @set AUTHOR Carsten Dominik @set MAINTAINER Bastien Guerry @set MAINTAINEREMAIL @email{bzg at gnu dot org} @@ -288,7 +288,8 @@ modify this GNU manual.'' @subtitle Release @value{VERSION} @author by Carsten Dominik -with contributions by David O'Toole, Bastien Guerry, Philip Rooke, Dan Davison, Eric Schulte, Thomas Dye and Jambunathan K. +with contributions by David O'Toole, Bastien Guerry, Philip Rooke, Dan +Davison, Eric Schulte, Thomas Dye, Jambunathan K and Nicolas Goaziou. @c The following two commands start the copyright page. @page @@ -536,7 +537,8 @@ Presentation and sorting * Categories:: Not all tasks are equal * Time-of-day specifications:: How the agenda knows the time -* Sorting of agenda items:: The order of things +* Sorting agenda items:: The order of things +* Filtering/limiting agenda items:: Dynamically narrow the agenda Custom agenda views @@ -551,7 +553,7 @@ Markup for rich export * Literal examples:: Source code examples with special formatting * Include files:: Include additional files into a document * Index entries:: Making an index -* Macro replacement:: Use macros to create complex output +* Macro replacement:: Use macros to create templates * Embedded @LaTeX{}:: LaTeX can be freely used inside Org documents Structural markup elements @@ -576,9 +578,9 @@ Embedded @LaTeX{} Exporting -* Selective export:: Using tags to select and exclude trees -* Export options:: Per-file export settings -* The export dispatcher:: How to access exporter commands +* The Export Dispatcher:: The main exporter interface +* Export formats:: Available export formats +* Export settings:: Generic export settings * ASCII/Latin-1/UTF-8 export:: Exporting to flat files with encoding * HTML export:: Exporting to HTML * @LaTeX{} and PDF export:: Exporting to @LaTeX{}, and processing to PDF @@ -603,8 +605,7 @@ HTML export * @LaTeX{}/PDF export commands:: * Header and sectioning:: Setting up the export file structure * Quoting @LaTeX{} code:: Incorporating literal @LaTeX{} code -* Tables in @LaTeX{} export:: Options for exporting tables to @LaTeX{} -* Images in @LaTeX{} export:: How to insert figures into @LaTeX{} output +* @LaTeX{} specific attributes:: Controlling @LaTeX{} output * Beamer class export:: Turning the file into a presentation OpenDocument Text export @@ -743,12 +744,13 @@ Hacking * Hooks:: How to reach into Org's internals * Add-on packages:: Available extensions * Adding hyperlink types:: New custom link types +* Adding export back-ends:: How to write new export back-ends * Context-sensitive commands:: How to add functionality to such commands * Tables in arbitrary syntax:: Orgtbl for @LaTeX{} and other programs * Dynamic blocks:: Automatically filled blocks * Special agenda views:: Customized views * Speeding up your agendas:: Tips on how to speed up your agendas -* Extracting agenda information:: Postprocessing of agenda information +* Extracting agenda information:: Post-processing of agenda information * Using the property API:: Writing programs that use entry properties * Using the mapping API:: Mapping over all or selected entries @@ -831,7 +833,7 @@ ends, for example: @pindex GTD, Getting Things Done @r{@bullet{} an environment in which to implement David Allen's GTD system} @r{@bullet{} a simple hypertext system, with HTML and @LaTeX{} export} -@r{@bullet{} a publishing tool to create a set of interlinked webpages} +@r{@bullet{} a publishing tool to create a set of interlinked web pages} @r{@bullet{} an environment for literate programming} @end example @@ -882,17 +884,17 @@ You can download Org latest release from @uref{http://orgmode.org/, Org's website}. In this case, make sure you set the load-path correctly in your @file{.emacs}: -@example +@lisp (add-to-list 'load-path "~/path/to/orgdir/lisp") -@end example +@end lisp The downloaded archive contains contributed libraries that are not included in Emacs. If you want to use them, add the @file{contrib} directory to your load-path: -@example +@lisp (add-to-list 'load-path "~/path/to/orgdir/contrib/lisp" t) -@end example +@end lisp Optionally, you can compile the files and/or install them in your system. Run @code{make help} to list compilation and installation options. @@ -1029,7 +1031,7 @@ is not necessary. In that case it is sufficient to start Emacs as @code{emacs -Q}. The @code{minimal-org.el} setup file can have contents as shown below. -@example +@lisp ;;; Minimal setup to load latest `org-mode' ;; activate debugging @@ -1040,7 +1042,7 @@ shown below. ;; add latest org-mode to load path (add-to-list 'load-path (expand-file-name "/path/to/org-mode/lisp")) (add-to-list 'load-path (expand-file-name "/path/to/org-mode/contrib/lisp" t)) -@end example +@end lisp If an error occurs, a backtrace can be very useful (see below on how to create one). Often a small example file helps, along with clear information @@ -1363,7 +1365,7 @@ entries. @vindex org-catch-invisible-edits @cindex edits, catching invisible -Sometimes you may inadvertantly edit an invisible part of the buffer and be +Sometimes you may inadvertently edit an invisible part of the buffer and be confused on what as been edited and how to undo the mistake. Setting @code{org-catch-invisible-edits} to non-nil will help prevent this. See the docstring of this option on how Org should catch invisible edits and process @@ -1437,7 +1439,7 @@ headline is created before the current line. If the command is used at the @emph{end} of a folded subtree (i.e., behind the ellipses at the end of a headline), then a headline like the current one will be inserted after the end of the subtree. Calling this command with -@kbd{C-u C-u} will inconditionnally respect the headline's content and +@kbd{C-u C-u} will unconditionally respect the headline's content and create a new item at the end of the parent subtree. @orgcmd{C-@key{RET},org-insert-heading-respect-content} Just like @kbd{M-@key{RET}}, except when adding a new heading below the @@ -1764,7 +1766,7 @@ similar effect. @item M-up @itemx M-down Move the item including subitems up/down@footnote{See -@code{org-liste-use-circular-motion} for a cyclic behavior.} (swap with +@code{org-list-use-circular-motion} for a cyclic behavior.} (swap with previous/next item of same indentation). If the list is ordered, renumbering is automatic. @kindex M-@key{left} @@ -1873,6 +1875,12 @@ want to store a quick note in the LOGBOOK drawer, in a similar way to state chan Add a time-stamped note to the LOGBOOK drawer. @end table +@vindex org-export-with-drawers +You can select the name of the drawers which should be exported with +@var{org-export-with-drawers}. In that case, drawer contents will appear in +export output. Property drawers are not affected by this variable and are +never exported. + @node Blocks, Footnotes, Drawers, Document Structure @section Blocks @@ -1977,8 +1985,7 @@ n @r{Normalize the footnotes by collecting all definitions (including} @r{inline definitions) into a special section, and then numbering them} @r{in sequence. The references will then also be numbers. This is} @r{meant to be the final step before finishing a document (e.g., sending} - @r{off an email). The exporters do this automatically, and so could} - @r{something like @code{message-send-hook}.} + @r{off an email).} d @r{Delete the footnote at point, and all definitions of and references} @r{to it.} @end example @@ -2599,7 +2606,7 @@ numbers. @cindex references, to a different table @cindex name, of column or field @cindex constants, in calculations -@cindex #+TBLNAME +@cindex #+NAME, for table You may also reference constants, fields and ranges from a different table, either in the current file or even in a different file. The syntax is @@ -2610,7 +2617,7 @@ remote(NAME-OR-ID,REF) @noindent where NAME can be the name of a table in the current file as set by a -@code{#+TBLNAME: NAME} line before the table. It can also be the ID of an +@code{#+NAME: Name} line before the table. It can also be the ID of an entry, even in a different file, and the reference then refers to the first table in that entry. REF is an absolute field or range reference as described above for example @code{@@3$3} or @code{$somename}, valid in the @@ -2880,7 +2887,7 @@ Searches for the first element @code{S} in list @code{S-LIST} for which is @code{t}; returns the value from the corresponding position in list @code{R-LIST}. The default @code{PREDICATE} is @code{equal}. Note that the parameters @code{VAL} and @code{S} are passed to @code{PREDICATE} in the same -order as the correspoding parameters are in the call to +order as the corresponding parameters are in the call to @code{org-lookup-first}, where @code{VAL} precedes @code{S-LIST}. If @code{R-LIST} is @code{nil}, the matching element @code{S} of @code{S-LIST} is returned. @@ -5006,7 +5013,8 @@ will display headlines tagged with at least one of the members of the group. This makes tag searches and filters even more flexible. You can set group tags by inserting a colon between the group tag and other -tags, like this: +tags---beware that all whitespaces are mandatory so that Org can parse this +line correctly: @example #+TAGS: @{ @@read : @@read_book @@read_ebook @} @@ -5027,6 +5035,8 @@ You can also use the @code{:grouptags} keyword directly when setting (:endgroup . nil))) @end lisp +You cannot nest group tags or use a group tag as a tag in another group. + @kindex C-c C-x q @vindex org-group-tags If you want to ignore group tags temporarily, toggle group tags support @@ -5882,13 +5892,12 @@ w4 @result{} ISO week for of the current year @b{2006} 2012-w04-5 @result{} Same as above @end example -Furthermore you can specify a relative date by giving, as the -@emph{first} thing in the input: a plus/minus sign, a number and a -letter ([dwmy]) to indicate change in days, weeks, months, or years. With a -single plus or minus, the date is always relative to today. With a -double plus or minus, it is relative to the default date. If instead of -a single letter, you use the abbreviation of day name, the date will be -the Nth such day, e.g.: +Furthermore you can specify a relative date by giving, as the @emph{first} +thing in the input: a plus/minus sign, a number and a letter ([hdwmy]) to +indicate change in hours, days, weeks, months, or years. With a single plus +or minus, the date is always relative to today. With a double plus or minus, +it is relative to the default date. If instead of a single letter, you use +the abbreviation of day name, the date will be the Nth such day, e.g.: @example +0 @result{} today @@ -6068,9 +6077,9 @@ the task will automatically be forwarded until completed. If you want to @emph{delay} the display of this task in the agenda, use @code{SCHEDULED: <2004-12-25 Sat -2d>}: the task is still scheduled on the 25th but will appear two days later. In case the task contains a repeater, -the delay is considered to affect all occurrences; if you want it to affect -only the first scheduled occurrence of the task, use @code{--2d} instead. -See @code{org-scheduled-delay-days} and +the delay is considered to affect all occurrences; if you want the delay to +only affect the first scheduled occurrence of the task, use @code{--2d} +instead. See @code{org-scheduled-delay-days} and @code{org-agenda-skip-scheduled-delay-if-deadline} for details on how to control this globally or per agenda. @@ -6785,10 +6794,12 @@ a global key@footnote{Please select your own key, @kbd{C-c c} is only a suggestion.} for capturing new material. @vindex org-default-notes-file -@example +@smalllisp +@group (setq org-default-notes-file (concat org-directory "/notes.org")) (define-key global-map "\C-cc" 'org-capture) -@end example +@end group +@end smalllisp @node Using capture, Capture templates, Setting up capture, Capture @subsection Using capture @@ -6867,13 +6878,15 @@ your file @file{~/org/gtd.org}. Also, a date tree in the file @file{journal.org} should capture journal entries. A possible configuration would look like: -@example +@smalllisp +@group (setq org-capture-templates '(("t" "Todo" entry (file+headline "~/org/gtd.org" "Tasks") "* TODO %?\n %i\n %a") ("j" "Journal" entry (file+datetree "~/org/journal.org") "* %?\nEntered on %U\n %i\n %a"))) -@end example +@end group +@end smalllisp @noindent If you then press @kbd{C-c c t}, Org will prepare the template for you like this: @@ -6918,9 +6931,9 @@ single key, or @code{"bt"} for selection with two keys. When using several keys, keys using the same prefix key must be sequential in the list and preceded by a 2-element entry explaining the prefix key, for example -@example +@smalllisp ("b" "Templates for marking stuff to buy") -@end example +@end smalllisp @noindent If you do not define a template for the @kbd{C} key, this key will be used to open the customize buffer for this complex variable. @@ -7137,18 +7150,18 @@ context, you can customize @var{org-capture-templates-contexts}. Let's say for example that you have a capture template @code{"p"} for storing Gnus emails containing patches. Then you would configure this option like this: -@example +@smalllisp (setq org-capture-templates-contexts '(("p" (in-mode . "message-mode")))) -@end example +@end smalllisp You can also tell that the command key @code{"p"} should refer to another template. In that case, add this command key like this: -@example +@smalllisp (setq org-capture-templates-contexts '(("p" "q" (in-mode . "message-mode")))) -@end example +@end smalllisp See the docstring of the variable for more information. @@ -7252,12 +7265,14 @@ web to import tasks into Org. To access feeds, configure the variable @code{org-feed-alist}. The docstring of this variable has detailed information. Here is just an example: -@example +@smalllisp +@group (setq org-feed-alist '(("Slashdot" "http://rss.slashdot.org/Slashdot/slashdot" "~/txt/org/feeds.org" "Slashdot Entries"))) -@end example +@end group +@end smalllisp @noindent will configure that new items from the feed provided by @@ -8201,7 +8216,8 @@ associated with the item. @menu * Categories:: Not all tasks are equal * Time-of-day specifications:: How the agenda knows the time -* Sorting of agenda items:: The order of things +* Sorting agenda items:: The order of things +* Filtering/limiting agenda items:: Dynamically narrow the agenda @end menu @node Categories, Time-of-day specifications, Presentation and sorting, Presentation and sorting @@ -8238,7 +8254,7 @@ longer than 10 characters. You can set up icons for category by customizing the @code{org-agenda-category-icon-alist} variable. -@node Time-of-day specifications, Sorting of agenda items, Categories, Presentation and sorting +@node Time-of-day specifications, Sorting agenda items, Categories, Presentation and sorting @subsection Time-of-day specifications @cindex time-of-day specification @@ -8289,8 +8305,8 @@ The time grid can be turned on and off with the variable @code{org-agenda-use-time-grid}, and can be configured with @code{org-agenda-time-grid}. -@node Sorting of agenda items, , Time-of-day specifications, Presentation and sorting -@subsection Sorting of agenda items +@node Sorting agenda items, Filtering/limiting agenda items, Time-of-day specifications, Presentation and sorting +@subsection Sorting agenda items @cindex sorting, of agenda items @cindex priorities, of agenda items Before being inserted into a view, the items are sorted. How this is @@ -8323,6 +8339,189 @@ Sorting can be customized using the variable @code{org-agenda-sorting-strategy}, and may also include criteria based on the estimated effort of an entry (@pxref{Effort estimates}). +@node Filtering/limiting agenda items, , Sorting agenda items, Presentation and sorting +@subsection Filtering/limiting agenda items + +Agenda built-in or customized commands are statically defined. Agenda +filters and limits provide two ways of dynamically narrowing down the list of +agenda entries: @emph{fitlers} and @emph{limits}. Filters only act on the +display of the items, while limits take effect before the list of agenda +entries is built. Filter are more often used interactively, while limits are +mostly useful when defined as local variables within custom agenda commands. + +@subsubheading Filtering in the agenda +@cindex filtering, by tag, category, top headline and effort, in agenda +@cindex tag filtering, in agenda +@cindex category filtering, in agenda +@cindex top headline filtering, in agenda +@cindex effort filtering, in agenda +@cindex query editing, in agenda + +@table @kbd +@orgcmd{/,org-agenda-filter-by-tag} +@vindex org-agenda-tag-filter-preset +Filter the agenda view with respect to a tag and/or effort estimates. The +difference between this and a custom agenda command is that filtering is very +fast, so that you can switch quickly between different filters without having +to recreate the agenda.@footnote{Custom commands can preset a filter by +binding the variable @code{org-agenda-tag-filter-preset} as an option. This +filter will then be applied to the view and persist as a basic filter through +refreshes and more secondary filtering. The filter is a global property of +the entire agenda view---in a block agenda, you should only set this in the +global options section, not in the section of an individual block.} + +You will be prompted for a tag selection letter; @key{SPC} will mean any tag at +all. Pressing @key{TAB} at that prompt will offer use completion to select a +tag (including any tags that do not have a selection character). The command +then hides all entries that do not contain or inherit this tag. When called +with prefix arg, remove the entries that @emph{do} have the tag. A second +@kbd{/} at the prompt will turn off the filter and unhide any hidden entries. +If the first key you press is either @kbd{+} or @kbd{-}, the previous filter +will be narrowed by requiring or forbidding the selected additional tag. +Instead of pressing @kbd{+} or @kbd{-} after @kbd{/}, you can also +immediately use the @kbd{\} command. + +@vindex org-sort-agenda-noeffort-is-high +In order to filter for effort estimates, you should set up allowed +efforts globally, for example +@lisp +(setq org-global-properties + '(("Effort_ALL". "0 0:10 0:30 1:00 2:00 3:00 4:00"))) +@end lisp +You can then filter for an effort by first typing an operator, one of +@kbd{<}, @kbd{>}, and @kbd{=}, and then the one-digit index of an effort +estimate in your array of allowed values, where @kbd{0} means the 10th value. +The filter will then restrict to entries with effort smaller-or-equal, equal, +or larger-or-equal than the selected value. If the digits 0--9 are not used +as fast access keys to tags, you can also simply press the index digit +directly without an operator. In this case, @kbd{<} will be assumed. For +application of the operator, entries without a defined effort will be treated +according to the value of @code{org-sort-agenda-noeffort-is-high}. To filter +for tasks without effort definition, press @kbd{?} as the operator. + +Org also supports automatic, context-aware tag filtering. If the variable +@code{org-agenda-auto-exclude-function} is set to a user-defined function, +that function can decide which tags should be excluded from the agenda +automatically. Once this is set, the @kbd{/} command then accepts @kbd{RET} +as a sub-option key and runs the auto exclusion logic. For example, let's +say you use a @code{Net} tag to identify tasks which need network access, an +@code{Errand} tag for errands in town, and a @code{Call} tag for making phone +calls. You could auto-exclude these tags based on the availability of the +Internet, and outside of business hours, with something like this: + +@smalllisp +@group +(defun org-my-auto-exclude-function (tag) + (and (cond + ((string= tag "Net") + (/= 0 (call-process "/sbin/ping" nil nil nil + "-c1" "-q" "-t1" "mail.gnu.org"))) + ((or (string= tag "Errand") (string= tag "Call")) + (let ((hour (nth 2 (decode-time)))) + (or (< hour 8) (> hour 21))))) + (concat "-" tag))) + +(setq org-agenda-auto-exclude-function 'org-my-auto-exclude-function) +@end group +@end smalllisp + +@orgcmd{\\,org-agenda-filter-by-tag-refine} +Narrow the current agenda filter by an additional condition. When called with +prefix arg, remove the entries that @emph{do} have the tag, or that do match +the effort criterion. You can achieve the same effect by pressing @kbd{+} or +@kbd{-} as the first key after the @kbd{/} command. + +@c +@kindex [ +@kindex ] +@kindex @{ +@kindex @} +@item [ ] @{ @} +@table @i +@item @r{in} search view +add new search words (@kbd{[} and @kbd{]}) or new regular expressions +(@kbd{@{} and @kbd{@}}) to the query string. The opening bracket/brace will +add a positive search term prefixed by @samp{+}, indicating that this search +term @i{must} occur/match in the entry. The closing bracket/brace will add a +negative search term which @i{must not} occur/match in the entry for it to be +selected. +@end table + +@orgcmd{<,org-agenda-filter-by-category} +@vindex org-agenda-category-filter-preset + +Filter the current agenda view with respect to the category of the item at +point. Pressing @code{<} another time will remove this filter. You can add +a filter preset through the option @code{org-agenda-category-filter-preset} +(see below.) + +@orgcmd{^,org-agenda-filter-by-top-headline} +Filter the current agenda view and only display the siblings and the parent +headline of the one at point. + +@orgcmd{=,org-agenda-filter-by-regexp} +@vindex org-agenda-regexp-filter-preset + +Filter the agenda view by a regular expression: only show agenda entries +matching the regular expression the user entered. When called with a prefix +argument, it will filter @emph{out} entries matching the regexp. With two +universal prefix arguments, it will remove all the regexp filters, which can +be accumulated. You can add a filter preset through the option +@code{org-agenda-category-filter-preset} (see below.) + +@orgcmd{|,org-agenda-filter-remove-all} +Remove all filters in the current agenda view. +@end table + +@subsubheading Setting limits for the agenda +@cindex limits, in agenda +@vindex org-agenda-max-entries +@vindex org-agenda-max-effort +@vindex org-agenda-max-todos +@vindex org-agenda-max-tags + +Here is a list of options that you can set, either globally, or locally in +your custom agenda views@pxref{Custom agenda views}. + +@table @var +@item org-agenda-max-entries +Limit the number of entries. +@item org-agenda-max-effort +Limit the duration of accumulated efforts (as minutes). +@item org-agenda-max-todos +Limit the number of entries with TODO keywords. +@item org-agenda-max-tags +Limit the number of tagged entries. +@end table + +When set to a positive integer, each option will exclude entries from other +catogories: for example, @code{(setq org-agenda-max-effort 100)} will limit +the agenda to 100 minutes of effort and exclude any entry that as no effort +property. If you want to include entries with no effort property, use a +negative value for @var{org-agenda-max-effort}. + +One useful setup is to use @var{org-agenda-max-entries} locally in a custom +command. For example, this custom command will display the next five entries +with a @code{NEXT} TODO keyword. + +@smalllisp +(setq org-agenda-custom-commands + '(("n" todo "NEXT" + ((org-agenda-max-entries 5))))) +@end smalllisp + +Once you mark one of these five entry as @code{DONE}, rebuilding the agenda +will again the next five entries again, including the first entry that was +excluded so far. + +You can also dynamically set temporary limits@footnote{Those temporary limits +are lost when rebuilding the agenda.}: + +@table @kbd +@orgcmd{~,org-agenda-limit-interactively} +This prompts for the type of limit to apply and its value. +@end table + @node Agenda commands, Custom agenda views, Presentation and sorting, Agenda Views @section Commands in the agenda buffer @cindex commands, in agenda buffer @@ -8436,7 +8635,7 @@ entries that have been clocked on that day. You can configure the entry types that should be included in log mode using the variable @code{org-agenda-log-mode-items}. When called with a @kbd{C-u} prefix, show all possible logbook entries, including state changes. When called with two -prefix args @kbd{C-u C-u}, show only logging information, nothing else. +prefix arguments @kbd{C-u C-u}, show only logging information, nothing else. @kbd{v L} is equivalent to @kbd{C-u v l}. @c @orgcmdkskc{v [,[,org-agenda-manipulate-query-add} @@ -8454,7 +8653,7 @@ press @kbd{v a} again. @vindex org-agenda-start-with-clockreport-mode @vindex org-clock-report-include-clocking-task Toggle Clockreport mode. In Clockreport mode, the daily/weekly agenda will -always show a table with the clocked times for the timespan and file scope +always show a table with the clocked times for the time span and file scope covered by the current agenda view. The initial setting for this mode in new agenda buffers can be set with the variable @code{org-agenda-start-with-clockreport-mode}. By using a prefix argument @@ -8513,119 +8712,39 @@ that entry would be in the original buffer (taken from a property, from a Remove the restriction lock on the agenda, if it is currently restricted to a file or subtree (@pxref{Agenda files}). -@tsubheading{Secondary filtering and query editing} -@cindex filtering, by tag category and effort, in agenda -@cindex tag filtering, in agenda -@cindex category filtering, in agenda -@cindex effort filtering, in agenda -@cindex query editing, in agenda +@tsubheading{Secondary filtering and query editing@footnote{See +@pxref{Filtering/limiting agenda items} for a detailed description of these +commands.}} + +@orgcmd{/,org-agenda-filter-by-tag} +@vindex org-agenda-tag-filter-preset +Filter the agenda view with respect to a tag and/or effort estimates. + +@orgcmd{\\,org-agenda-filter-by-tag-refine} +Narrow the current agenda filter by an additional condition. @orgcmd{<,org-agenda-filter-by-category} @vindex org-agenda-category-filter-preset Filter the current agenda view with respect to the category of the item at -point. Pressing @code{<} another time will remove this filter. You can add -a filter preset through the option @code{org-agenda-category-filter-preset} -(see below.) +point. Pressing @code{<} another time will remove this filter. -@orgcmd{|,org-agenda-filter-by-regexp} +@orgcmd{^,org-agenda-filter-by-top-headline} +Filter the current agenda view and only display the siblings and the parent +headline of the one at point. + +@orgcmd{=,org-agenda-filter-by-regexp} @vindex org-agenda-regexp-filter-preset Filter the agenda view by a regular expression: only show agenda entries matching the regular expression the user entered. When called with a prefix argument, it will filter @emph{out} entries matching the regexp. With two universal prefix arguments, it will remove all the regexp filters, which can -be cumulated. You can add a filter preset through the option +be accumulated. You can add a filter preset through the option @code{org-agenda-category-filter-preset} (see below.) -@orgcmd{/,org-agenda-filter-by-tag} -@vindex org-agenda-tag-filter-preset -Filter the agenda view with respect to a tag and/or effort estimates. The -difference between this and a custom agenda command is that filtering is very -fast, so that you can switch quickly between different filters without having -to recreate the agenda.@footnote{Custom commands can preset a filter by -binding the variable @code{org-agenda-tag-filter-preset} as an option. This -filter will then be applied to the view and persist as a basic filter through -refreshes and more secondary filtering. The filter is a global property of -the entire agenda view---in a block agenda, you should only set this in the -global options section, not in the section of an individual block.} - -You will be prompted for a tag selection letter; @key{SPC} will mean any tag at -all. Pressing @key{TAB} at that prompt will offer use completion to select a -tag (including any tags that do not have a selection character). The command -then hides all entries that do not contain or inherit this tag. When called -with prefix arg, remove the entries that @emph{do} have the tag. A second -@kbd{/} at the prompt will turn off the filter and unhide any hidden entries. -If the first key you press is either @kbd{+} or @kbd{-}, the previous filter -will be narrowed by requiring or forbidding the selected additional tag. -Instead of pressing @kbd{+} or @kbd{-} after @kbd{/}, you can also -immediately use the @kbd{\} command. - -@vindex org-sort-agenda-noeffort-is-high -In order to filter for effort estimates, you should set up allowed -efforts globally, for example -@lisp -(setq org-global-properties - '(("Effort_ALL". "0 0:10 0:30 1:00 2:00 3:00 4:00"))) -@end lisp -You can then filter for an effort by first typing an operator, one of -@kbd{<}, @kbd{>}, and @kbd{=}, and then the one-digit index of an effort -estimate in your array of allowed values, where @kbd{0} means the 10th value. -The filter will then restrict to entries with effort smaller-or-equal, equal, -or larger-or-equal than the selected value. If the digits 0--9 are not used -as fast access keys to tags, you can also simply press the index digit -directly without an operator. In this case, @kbd{<} will be assumed. For -application of the operator, entries without a defined effort will be treated -according to the value of @code{org-sort-agenda-noeffort-is-high}. To filter -for tasks without effort definition, press @kbd{?} as the operator. - -Org also supports automatic, context-aware tag filtering. If the variable -@code{org-agenda-auto-exclude-function} is set to a user-defined function, -that function can decide which tags should be excluded from the agenda -automatically. Once this is set, the @kbd{/} command then accepts @kbd{RET} -as a sub-option key and runs the auto exclusion logic. For example, let's -say you use a @code{Net} tag to identify tasks which need network access, an -@code{Errand} tag for errands in town, and a @code{Call} tag for making phone -calls. You could auto-exclude these tags based on the availability of the -Internet, and outside of business hours, with something like this: - -@lisp -@group -(defun org-my-auto-exclude-function (tag) - (and (cond - ((string= tag "Net") - (/= 0 (call-process "/sbin/ping" nil nil nil - "-c1" "-q" "-t1" "mail.gnu.org"))) - ((or (string= tag "Errand") (string= tag "Call")) - (let ((hour (nth 2 (decode-time)))) - (or (< hour 8) (> hour 21))))) - (concat "-" tag))) - -(setq org-agenda-auto-exclude-function 'org-my-auto-exclude-function) -@end group -@end lisp - -@orgcmd{\\,org-agenda-filter-by-tag-refine} -Narrow the current agenda filter by an additional condition. When called with -prefix arg, remove the entries that @emph{do} have the tag, or that do match -the effort criterion. You can achieve the same effect by pressing @kbd{+} or -@kbd{-} as the first key after the @kbd{/} command. - -@c -@kindex [ -@kindex ] -@kindex @{ -@kindex @} -@item [ ] @{ @} -@table @i -@item @r{in} search view -add new search words (@kbd{[} and @kbd{]}) or new regular expressions -(@kbd{@{} and @kbd{@}}) to the query string. The opening bracket/brace will -add a positive search term prefixed by @samp{+}, indicating that this search -term @i{must} occur/match in the entry. The closing bracket/brace will add a -negative search term which @i{must not} occur/match in the entry for it to be -selected. -@end table +@orgcmd{|,org-agenda-filter-remove-all} +Remove all filters in the current agenda view. @tsubheading{Remote editing} @cindex remote editing, from agenda @@ -8783,40 +8902,55 @@ these special timestamps. By default, marks are removed after the bulk. If you want them to persist, set @code{org-agenda-bulk-persistent-marks} to @code{t} or hit @kbd{p} at the prompt. -@example -* @r{Toggle persistent marks.} -$ @r{Archive all selected entries.} -A @r{Archive entries by moving them to their respective archive siblings.} -t @r{Change TODO state. This prompts for a single TODO keyword and} - @r{changes the state of all selected entries, bypassing blocking and} - @r{suppressing logging notes (but not timestamps).} -+ @r{Add a tag to all selected entries.} -- @r{Remove a tag from all selected entries.} -s @r{Schedule all items to a new date. To shift existing schedule dates} - @r{by a fixed number of days, use something starting with double plus} - @r{at the prompt, for example @samp{++8d} or @samp{++2w}.} -d @r{Set deadline to a specific date.} -r @r{Prompt for a single refile target and move all entries. The entries} - @r{will no longer be in the agenda; refresh (@kbd{g}) to bring them back.} -S @r{Reschedule randomly into the coming N days. N will be prompted for.} - @r{With prefix arg (@kbd{C-u B S}), scatter only across weekdays.} -f @r{Apply a function@footnote{You can also create persistent custom functions through@code{org-agenda-bulk-custom-functions}.} to marked entries.} - @r{For example, the function below sets the CATEGORY property of the} - @r{entries to web.} - @r{(defun set-category ()} - @r{ (interactive "P")} - @r{ (let* ((marker (or (org-get-at-bol 'org-hd-marker)} - @r{ (org-agenda-error)))} - @r{ (buffer (marker-buffer marker)))} - @r{ (with-current-buffer buffer} - @r{ (save-excursion} - @r{ (save-restriction} - @r{ (widen)} - @r{ (goto-char marker)} - @r{ (org-back-to-heading t)} - @r{ (org-set-property "CATEGORY" "web"))))))} -@end example +@table @kbd +@item * +Toggle persistent marks. +@item $ +Archive all selected entries. +@item A +Archive entries by moving them to their respective archive siblings. +@item t +Change TODO state. This prompts for a single TODO keyword and changes the +state of all selected entries, bypassing blocking and suppressing logging +notes (but not timestamps). +@item + +Add a tag to all selected entries. +@item - +Remove a tag from all selected entries. +@item s +Schedule all items to a new date. To shift existing schedule dates by a +fixed number of days, use something starting with double plus at the prompt, +for example @samp{++8d} or @samp{++2w}. +@item d +Set deadline to a specific date. +@item r +Prompt for a single refile target and move all entries. The entries will no +longer be in the agenda; refresh (@kbd{g}) to bring them back. +@item S +Reschedule randomly into the coming N days. N will be prompted for. With +prefix arg (@kbd{C-u B S}), scatter only across weekdays. +@item f +Apply a function@footnote{You can also create persistent custom functions +through@code{org-agenda-bulk-custom-functions}.} to marked entries. For +example, the function below sets the CATEGORY property of the entries to web. +@lisp +@group +(defun set-category () + (interactive "P") + (let* ((marker (or (org-get-at-bol 'org-hd-marker) + (org-agenda-error))) + (buffer (marker-buffer marker))) + (with-current-buffer buffer + (save-excursion + (save-restriction + (widen) + (goto-char marker) + (org-back-to-heading t) + (org-set-property "CATEGORY" "web")))))) +@end group +@end lisp +@end table @tsubheading{Calendar commands} @cindex calendar commands, from agenda @@ -9113,18 +9247,18 @@ say for example that you have an agenda commands @code{"o"} displaying a view that you only need when reading emails. Then you would configure this option like this: -@example +@lisp (setq org-agenda-custom-commands-contexts '(("o" (in-mode . "message-mode")))) -@end example +@end lisp You can also tell that the command key @code{"o"} should refer to another command key @code{"r"}. In that case, add this command key like this: -@example +@lisp (setq org-agenda-custom-commands-contexts '(("o" "r" (in-mode . "message-mode")))) -@end example +@end lisp See the docstring of the variable for more information. @@ -9335,19 +9469,20 @@ spent (via @code{CLOCKSUM}) and with the planned total effort for it. @chapter Markup for rich export When exporting Org mode documents, the exporter tries to reflect the -structure of the document as accurately as possible in the backend. Since +structure of the document as accurately as possible in the back-end. Since export targets like HTML, @LaTeX{} allow much richer formatting, Org mode has rules on how to prepare text for rich export. This section summarizes the markup rules used in an Org mode buffer. @menu * Structural markup elements:: The basic structure as seen by the exporter -* Images and tables:: Tables and Images will be included +* Images and tables:: Images, tables and caption mechanism * Literal examples:: Source code examples with special formatting * Include files:: Include additional files into a document * Index entries:: Making an index -* Macro replacement:: Use macros to create complex output +* Macro replacement:: Use macros to create templates * Embedded @LaTeX{}:: LaTeX can be freely used inside Org documents +* Special blocks:: Containers targeted at export back-ends @end menu @node Structural markup elements, Images and tables, Markup, Markup @@ -9424,8 +9559,8 @@ with a line like #+OPTIONS: toc:nil (no TOC at all) @end example -The same @code{TOC} keyword can also generate a list of all tables (resp. all -listings) with a caption in the buffer. +The same @code{TOC} keyword can also generate a list of all tables (resp.@: +all listings) with a caption in the buffer. @example #+TOC: listings (build a list of listings) @@ -9434,7 +9569,7 @@ listings) with a caption in the buffer. @cindex property, ALT_TITLE The headline's title usually determines its corresponding entry in a table of -contents. However, it is possible to specifify an alternative title by +contents. However, it is possible to specify an alternative title by setting @code{ALT_TITLE} property accordingly. It will then be used when building the table. @@ -9442,8 +9577,8 @@ building the table. @subheading Lists @cindex lists, markup rules -Plain lists as described in @ref{Plain lists}, are translated to the backend's -syntax for such lists. Most backends support unordered, ordered, and +Plain lists as described in @ref{Plain lists}, are translated to the back-end's +syntax for such lists. Most back-ends support unordered, ordered, and description lists. @node Paragraphs, Footnote markup, Lists, Structural markup elements @@ -9495,7 +9630,7 @@ but not any simpler @cindex @file{footnote.el} Footnotes defined in the way described in @ref{Footnotes}, will be exported -by all backends. Org allows multiple references to the same note, and +by all back-ends. Org allows multiple references to the same note, and multiple footnotes side by side. @node Emphasis and monospace, Horizontal rules, Footnote markup, Structural markup elements @@ -9509,15 +9644,19 @@ multiple footnotes side by side. @cindex strike-through text, markup rules @vindex org-fontify-emphasized-text @vindex org-emphasis-regexp-components +@vindex org-emphasis-alist You can make words @b{*bold*}, @i{/italic/}, _underlined_, @code{=code=} and @code{~verbatim~}, and, if you must, @samp{+strike-through+}. Text in the code and verbatim string is not processed for Org mode specific -syntax; it is exported verbatim. +syntax, it is exported verbatim. To turn off fontification for marked up text, you can set -@code{org-fontify-emphasized-text} to @code{nil}. To fine tune what -characters are allowed before and after the special characters, see -@code{org-emphasis-regexp-components}. +@code{org-fontify-emphasized-text} to @code{nil}. To narrow down the list of +available markup syntax, you can customize @var{org-emphasis-alist}. To fine +tune what characters are allowed before and after the markup characters, you +can tweak @code{org-emphasis-regexp-components}. Beware that changing one of +the above variables will no take effect until you reload Org, for which you +may need to restart Emacs. @node Horizontal rules, Comment lines, Emphasis and monospace, Structural markup elements @subheading Horizontal rules @@ -9570,7 +9709,7 @@ Optionally, the caption can take the form: @end example @cindex inlined images, markup rules -Some backends allow you to directly include images into the exported +Some back-ends allow you 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 @@ -9623,7 +9762,7 @@ Here is an example If the example is source code from a programming language, or any other text that can be marked up by font-lock in Emacs, you can ask for the example to look like the fontified Emacs buffer@footnote{This works automatically for -the HTML backend (it requires version 1.34 of the @file{htmlize.el} package, +the HTML back-end (it requires version 1.34 of the @file{htmlize.el} package, which is distributed with Org). Fontified code chunks in @LaTeX{} can be achieved using either the listings or the @url{http://code.google.com/p/minted, minted,} package. Refer to @@ -9802,7 +9941,7 @@ and to the modification time of the file being exported, respectively. Macro expansion takes place during export. -@node Embedded @LaTeX{}, , Macro replacement, Markup +@node Embedded @LaTeX{}, Special blocks , Macro replacement, Markup @section Embedded @LaTeX{} @cindex @TeX{} interpretation @cindex @LaTeX{} interpretation @@ -9815,7 +9954,7 @@ Donald E. Knuth's @TeX{} system. Many of the features described here as distinction.} is widely used to typeset scientific documents. Org mode supports embedding @LaTeX{} code into its files, because many academics are used to writing and reading @LaTeX{} source code, and because it can be -readily processed to produce pretty output for a number of export backends. +readily processed to produce pretty output for a number of export back-ends. @menu * Special symbols:: Greek letters and other symbols @@ -9865,6 +10004,7 @@ variable @code{org-pretty-entities}, or on a per-file base with the @code{#+STARTUP} option @code{entitiespretty}.}: @table @kbd +@cindex @code{entitiespretty}, STARTUP keyword @kindex C-c C-x \ @item C-c C-x \ Toggle display of entities as UTF-8 characters. This does not change the @@ -9967,7 +10107,7 @@ either $$ a=+\sqrt@{2@} $$ or \[ a=-\sqrt@{2@} \]. @vindex org-export-with-latex @LaTeX{} processing can be configured with the variable @code{org-export-with-latex}. The default setting is @code{t} which means -@file{MathJax} for HTML, and no processing for ASCII and @LaTeX{} backends. +@file{MathJax} for HTML, and no processing for ASCII and @LaTeX{} back-ends. You can also set this variable on a per-file basis using one of these lines: @@ -10083,28 +10223,40 @@ modification will work only inside @LaTeX{} fragments; outside the quote is normal. @end itemize +@node Special blocks, , Embedded @LaTeX{}, Markup +@section Special blocks +@cindex Special blocks + +Org syntax includes pre-defined blocks (@pxref{Paragraphs} and @ref{Literal +examples}). It is also possible to create blocks containing raw code +targeted at a specific back-ends (e.g., @samp{#+BEGIN_LATEX}). + +Any other block is a @emph{special block}. Each export back-end decides if +they should be exported, and how. When the block is ignored, its contents +are still exported, as if the block were not there. For example, when +exporting a @samp{#+BEGIN_TEST} block, HTML back-end wraps its contents +within @samp{
} tag. Refer to back-end specific +documentation for more information. + @node Exporting, Publishing, Markup, Top @chapter Exporting @cindex exporting -Org mode documents can be exported into a variety of other formats. For -printing and sharing notes, ASCII export produces a readable and simple +Org mode documents can be exported into a variety of other formats. + +For printing and sharing notes, ASCII export produces a readable and simple version of an Org file. HTML export allows you to publish a notes file on the web. @LaTeX{} export lets you use Org mode and its structured editing functions to easily create @LaTeX{} files. OpenDocument Text (ODT) export allows seamless collaboration across organizational boundaries. To incorporate entries with associated times like deadlines or appointments into a desktop calendar program like iCal, Org mode can also produce extracts in -the iCalendar format. Currently, Org mode only supports export, not import -of these different formats. - -Org supports export of selected regions when @code{transient-mark-mode} is -enabled (default in Emacs 23). +the iCalendar format. @menu -* Selective export:: Using tags to select and exclude trees -* Export options:: Per-file export settings -* The export dispatcher:: How to access exporter commands +* The Export Dispatcher:: The main exporter interface +* Export formats:: Available export formats +* Export settings:: Generic export settings * ASCII/Latin-1/UTF-8 export:: Exporting to flat files with encoding * HTML export:: Exporting to HTML * @LaTeX{} and PDF export:: Exporting to @LaTeX{}, and processing to PDF @@ -10112,187 +10264,320 @@ enabled (default in Emacs 23). * iCalendar export:: Exporting in iCalendar format @end menu -@node Selective export, Export options, Exporting, Exporting -@section Selective export -@cindex export, selective by tags or TODO keyword +@node The Export Dispatcher, Export formats, Exporting, Exporting +@section The Export Dispatcher +@vindex org-export-dispatch-use-expert-ui +@cindex Export, dispatcher -@vindex org-export-select-tags -@vindex org-export-exclude-tags -@cindex org-export-with-tasks -You may use tags to select the parts of a document that should be exported, -or to exclude parts from export. This behavior is governed by two variables: -@code{org-export-select-tags} and @code{org-export-exclude-tags}, -respectively defaulting to @code{'(:export:)} and @code{'(:noexport:)}. +The main entry point for any export related task is the dispatcher, a +hierarchical menu@footnote{It is also possible to use a less intrusive +interface by setting @var{org-export-dispatch-use-expert-ui} to a non-nil +value. In that case, only a prompt is visible from the minibuffer. From +there one can still switch back to regular menu with @kbd{?} key.} from +which it is possible to select an export format and to toggle export +options. -@enumerate -@item -Org first checks if any of the @emph{select} tags is present in the -buffer. If yes, all trees that do not carry one of these tags will be -excluded. If a selected tree is a subtree, the heading hierarchy above it -will also be selected for export, but not the text below those headings. +@c @quotation +@table @asis +@orgcmd{C-c C-e,org-export-dispatch} -@item -If none of the select tags is found, the whole buffer will be selected for -export. +Dispatch for export and publishing commands. When called with @kbd{C-u} +prefix argument, repeat last command, preserving toggled options, on +current buffer. If the active buffer hasn't changed and subtree export was +activated, the command will affect that same subtree. +@end table +@c @end quotation -@item -Finally, all subtrees that are marked by any of the @emph{exclude} tags will -be removed from the export buffer. -@end enumerate +Normally the entire buffer is exported, but if there is an active region +only that part of the buffer will be exported. -The variable @var{org-export-with-tasks} can be configured to select which -kind of tasks should be included for export. See the docstring of the -variable for more information. - -@node Export options, The export dispatcher, Selective export, Exporting -@section Export options -@cindex options, for export - -@cindex completion, of option keywords -The exporter recognizes special lines in the buffer which provide -additional information. These lines may be put anywhere in the file. -The whole set of lines can be inserted into the buffer with @kbd{C-c -C-e t}. For individual lines, a good way to make sure the keyword is -correct is to type @samp{#+} and then use @kbd{M-@key{TAB}} completion -(@pxref{Completion}). For a summary of other in-buffer settings not -specifically related to export, see @ref{In-buffer settings}. - -In particular, note that you can place commonly-used (export) options in -a separate file which can be included using @code{#+SETUPFILE}. - -@cindex #+TITLE -@cindex #+AUTHOR -@cindex #+DATE -@cindex #+EMAIL -@cindex #+DESCRIPTION -@cindex #+KEYWORDS -@cindex #+LANGUAGE -@cindex #+TEXT -@cindex #+OPTIONS -@cindex #+BIND -@cindex #HTML_HEAD -@cindex #+HTML_LINK_UP -@cindex #+HTML_LINK_HOME -@cindex #+SELECT_TAGS -@cindex #+EXCLUDE_TAGS -@cindex #+LATEX_HEADER -@cindex #+LATEX_HEADER_EXTRA -@vindex user-full-name -@vindex user-mail-address -@vindex org-export-default-language -@vindex org-export-allow-bind-keywords -@example -#+TITLE: the title to be shown (default is the buffer name) -#+AUTHOR: the author (default taken from @code{user-full-name}) -#+DATE: a date, an Org timestamp@footnote{@code{org-export-date-timestamp-format} defines how this timestamp will be exported.}, or a format string for @code{format-time-string} -#+EMAIL: his/her email address (default from @code{user-mail-address}) -#+DESCRIPTION: the page description, e.g., for the XHTML meta tag -#+KEYWORDS: the page keywords, e.g., for the XHTML meta tag -#+LANGUAGE: language for HTML, e.g., @samp{en} (@code{org-export-default-language}) -#+OPTIONS: H:2 num:t toc:t \n:nil @@:t ::t |:t ^:t f:t TeX:t ... -#+BIND: lisp-var lisp-val, e.g., @code{org-latex-image-default-width ".7\\linewidth"} - @r{Configure @code{org-export-allow-bind-keywords} to use this} -#+HTML_HEAD: Additional line to the @samp{...} of the HTML output -#+HTML_LINK_UP: the ``up'' link of an exported page -#+HTML_LINK_HOME: the ``home'' link of an exported page -#+LATEX_HEADER: extra line(s) for the @LaTeX{} header, like \usepackage@{xyz@} -#+LATEX_HEADER_EXTRA: similar to #+LATEX_HEADER, but ignored when previewing math snippets -#+SELECT_TAGS: Tags that select a tree for export -#+EXCLUDE_TAGS: Tags that exclude a tree from export -@end example - -@noindent -The @code{#+OPTIONS} line is a compact@footnote{If you want to configure many options -this way, you can use several @code{#+OPTIONS} lines.} form to specify export -settings. Here you can: -@cindex headline levels -@cindex section-numbers -@cindex table of contents -@cindex line-break preservation -@cindex quoted HTML tags -@cindex fixed-width sections -@cindex tables -@cindex @TeX{}-like syntax for sub- and superscripts -@cindex footnotes -@cindex special strings -@cindex emphasized text -@cindex @TeX{} macros -@cindex @LaTeX{} fragments -@cindex author info, in export -@cindex time info, in export -@vindex org-export-author-info -@vindex org-export-creator-info -@vindex org-export-email-info -@vindex org-export-time-stamp-file -@example -H: @r{set the number of headline levels for export} -num: @r{turn on/off section-numbers} -toc: @r{turn on/off table of contents, or set level limit (integer)} -\n: @r{turn on/off line-break-preservation (DOES NOT WORK)} -@@: @r{turn on/off quoted HTML tags} -:: @r{turn on/off fixed-width sections} -|: @r{turn on/off tables} -^: @r{turn on/off @TeX{}-like syntax for sub- and superscripts. If} - @r{you write "^:@{@}", @code{a_@{b@}} will be interpreted, but} - @r{the simple @code{a_b} will be left as it is.} --: @r{turn on/off conversion of special strings.} -f: @r{turn on/off footnotes like this[1].} -todo: @r{turn on/off inclusion of TODO keywords into exported text} -tasks: @r{turn on/off inclusion of tasks (TODO items), can be nil to remove} - @r{all tasks, @code{todo} to remove DONE tasks, or list of kwds to keep} -pri: @r{turn on/off priority cookies} -tags: @r{turn on/off inclusion of tags, may also be @code{not-in-toc}} -<: @r{turn on/off inclusion of any time/date stamps like DEADLINES} -*: @r{turn on/off emphasized text (bold, italic, underlined)} -TeX: @r{turn on/off simple @TeX{} macros in plain text} -LaTeX: @r{configure export of @LaTeX{} fragments. Default @code{auto}} -skip: @r{turn on/off skipping the text before the first heading} -author: @r{turn on/off inclusion of author name/email into exported file} -email: @r{turn on/off inclusion of author email into exported file} -creator: @r{turn on/off inclusion of creator info into exported file} -timestamp: @r{turn on/off inclusion creation time into exported file} -d: @r{turn on/off inclusion of drawers, or list drawers to include} -@end example -@noindent -These options take effect in both the HTML and @LaTeX{} export, except for -@code{TeX} and @code{LaTeX} options, which are respectively @code{t} and -@code{nil} for the @LaTeX{} export. - -When exporting only a single subtree by selecting it with @kbd{C-c @@} before -calling an export command, the subtree can overrule some of the file's export -settings with properties @code{EXPORT_FILE_NAME}, @code{EXPORT_TITLE}, -@code{EXPORT_TEXT}, @code{EXPORT_AUTHOR}, @code{EXPORT_DATE}, and -@code{EXPORT_OPTIONS}. - -@node The export dispatcher, ASCII/Latin-1/UTF-8 export, Export options, Exporting -@section The export dispatcher -@cindex dispatcher, for export commands - -All export commands can be reached using the export dispatcher, which is a -prefix key that prompts for an additional key specifying the command. -Normally the entire file is exported, but if there is an active region that -contains one outline tree, the first heading is used as document title and -the subtrees are exported. +Export options can also, among other things, affect the scope of export +process. They are toggled from the dispatcher with appropriate key +combinations: @table @kbd -@orgcmd{C-c C-e,org-export} -Dispatcher for export and publishing commands. Displays a help-window -listing the additional key(s) needed to launch an export or publishing -command. The prefix arg is passed through to the exporter. A double prefix -@kbd{C-u C-u} causes most commands to be executed in the background, in a -separate Emacs process@footnote{To make this behavior the default, customize -the variable @code{org-export-run-in-background}.}. -@orgcmd{C-c C-e C-v,org-export-visible} -Like @kbd{C-c C-e}, but only export the text that is currently visible -(i.e., not hidden by outline visibility). -@orgcmd{C-u C-u C-c C-e,org-export} +@item C-a +@vindex org-export-async-init-file @vindex org-export-run-in-background -Call the exporter, but reverse the setting of -@code{org-export-run-in-background}, i.e., request background processing if -not set, or force processing in the current Emacs process if set. +Toggles asynchronous export. The export happens in an external Emacs +process@footnote{Configure @var{org-export-async-init-file} to properly set +it up.}. + +In this case, no output is displayed automatically. It is stored in a list +called the export stack, and can be viewed from there. The stack can be +reached by calling the dispatcher with a double @kbd{C-u} prefix argument, +or with @kbd{&} key from the dispatcher. + +To make this behaviour the default, customize the variable successfully +@var{org-export-run-in-background}. + +@item C-b +Toggles body-only export. Its effect, if any, depends on the back-end +used. Its purpose is to remove all meta-data from output and focus on the +real contents. + +@item C-s +@vindex org-export-initial-scope +Toggles subtree export. The top heading becomes the document title and is +removed from the contents. + +You can change the default state of this option by setting +@var{org-export-initial-scope}. + +@item C-v +Toggles visible-only export. Only export the text that is currently +visible, i.e. not hidden by outline visibility in the buffer. + @end table -@node ASCII/Latin-1/UTF-8 export, HTML export, The export dispatcher, Exporting +@vindex org-export-copy-to-kill-ring +Unless it happened asynchronously, a successful export process usually +stores its output into the kill-ring. You can configure +@var{org-export-copy-to-kill-ring} in order to change this behaviour. + +@node Export formats, Export settings, The Export Dispatcher, Exporting +@section Export formats +@cindex Export, formats + +Libraries translating an Org buffer into a foreign format are called export +back-ends. An export format is not available until the proper back-end has +been loaded. + +@vindex org-export-backends +By default, the following four back-ends are ready to use: @code{ascii}, +@code{html}, @code{icalendar} and @code{latex}. It is possible to add more +(or remove some) by customizing @var{org-export-backends}. + +Core back-ends include: + +@itemize +@item ascii (ASCII format) +@item beamer (@LaTeX{} Beamer format) +@item html (HTML format) +@item icalendar (iCalendar format) +@item latex (@LaTeX{} format) +@item man (Man page format) +@item md (Markdown format) +@item odt (OpenDocument Text format) +@item texinfo (Texinfo format) +@end itemize + +More are available from the @code{contrib/} directory available from the +distribution archives or from GNU/Org ELPA. + +@node Export settings, ASCII/Latin-1/UTF-8 export, Export formats, Exporting +@section Export settings +@cindex Export, settings + +Export output can be controlled through a number of export options. These +can be set globally with variables, and overridden on a per-buffer basis +with keywords. Such keywords may be put anywhere in the file. For +individual lines, a good way to make sure the keyword is correct is to type +@code{#+} and then use @kbd{M-} completion. + +Here is an exhaustive list of such keywords along with the equivalent +global variable. Only options available for every back-end are discussed +in this section. + +@table @samp +@item AUTHOR +@vindex user-full-name +the author (@var{user-full-name}). + +@item CREATOR +@vindex org-export-creator-string +entity responsible for output generation (@var{org-export-creator-string}). + +@item DATE +@vindex org-export-date-timestamp-format +A date or a time-stamp@footnote{The variable +@var{org-export-date-timestamp-format} defines how this time-stamp will be +exported.}. + +@item DESCRIPTION +the page description, e.g., for the XHTML meta tag. + +@item EMAIL +@vindex user-mail-address +email address (@var{user-mail-address}). + +@item EXCLUDE_TAGS +Tags that exclude a tree from export + +@item KEYWORDS +keywords defining the contents, e.g., for the XHTML meta tag. + +@item LANGUAGE +@vindex org-export-default-language +language used for translation of some strings +(@var{org-export-default-language}). + +@item SELECT_TAGS +@vindex org-export-select-tags +Tags that select a tree for export (@var{org-export-select-tags}). + +@item TITLE +the title to be shown (otherwise derived from buffer's name). +@end table + +Additionally, the @code{OPTIONS} keyword is a compact@footnote{If you want +to configure many options this way, you can use several @code{#+OPTIONS} +lines.} form to specify export settings. Here you can: + +@table @code +@item ': +@vindex org-export-with-smart-quotes +toggle smart quotes (@var{org-export-with-smart-quotes}). + +@item *: +toggle emphasized text (@var{org-export-with-emphasize}). + +@item -: +@vindex org-export-with-special-strings +toggle conversion of special strings +(@var{org-export-with-special-strings}). + +@item :: +@vindex org-export-with-fixed-width +toggle fixed-width sections +(@var{org-export-with-fixed-width}). + +@item <: +@vindex org-export-with-timestamps +toggle inclusion of any time/date stamps like DEADLINES +(@var{org-export-with-timestamps}). + +@item : +@vindex org-export-preserve-breaks +toggle line-break-preservation (@var{org-export-preserve-breaks}). + +@item ^: +@vindex org-export-with-sub-superscripts +toggle @TeX{}-like syntax for sub- and superscripts. If you write "^:@{@}", +@samp{a_@{b@}} will be interpreted, but the simple @samp{a_b} will be left as +it is (@var{org-export-with-sub-superscripts}). + +@item arch: +@vindex org-export-with-archived-trees +configure export of archived trees. Can be set to @code{headline} to only +process the headline, skipping its contents +(@var{org-export-with-archived-trees}). + +@item author: +@vindex org-export-with-author +toggle inclusion of author name into exported file +(@var{org-export-with-author}). + +@item c: +@vindex org-export-with-clocks +toggle inclusion of CLOCK keywords (@var{org-export-with-clocks}). + +@item creator: +@vindex org-export-with-creator +configure inclusion of creator info into exported file. It may be set to +@code{comment} (@var{org-export-with-creator}). + +@item d: +@vindex org-export-with-drawers +toggle inclusion of drawers, or list drawers to include +(@var{org-export-with-drawers}). + +@item e: +@vindex org-export-with-entities +toggle inclusion of entities (@var{org-export-with-entities}). + +@item email: +@vindex org-export-with-email +toggle inclusion of author email into exported file +(@var{org-export-with-email}). + +@item f: +@vindex org-export-with-footnotes +toggle footnotes (@var{org-export-with-footnotes}). + +@item H: +@vindex org-export-headline-levels +set the number of headline levels for export +(@var{org-export-headline-levels}). + +@item inline: +@vindex org-export-with-inlinetasks +toggle inclusion of inlinetasks (@var{org-export-with-inlinetasks}). + +@item num: +@vindex org-export-with-section-numbers +toggle section-numbers (@var{org-export-with-section-numbers}). + +@item p: +@vindex org-export-with-planning +toggle export of planning information (e.g. deadlines) +(@var{org-export-with-planning}). + +@item pri: +@vindex org-export-with-priority +toggle priority cookies (@var{org-export-with-priority}). + +@item stat: +@vindex org-export-with-statistics-cookies +toggle inclusion of statistics cookies +(@var{org-export-with-statistics-cookies}). + +@item tags: +@vindex org-export-with-tags +toggle inclusion of tags, may also be @code{not-in-toc} +(@var{org-export-with-tags}). + +@item tasks: +@vindex org-export-with-tasks +toggle inclusion of tasks (TODO items), can be @code{nil} to remove all +tasks, @code{todo} to remove DONE tasks, or a list of keywords to keep +(@var{org-export-with-tasks}). + +@item tex: +@vindex org-export-with-latex +configure export of @LaTeX{} fragments and environments. It may be set to +@code{verbatim} (@var{org-export-with-latex}). + +@item timestamp: +@vindex org-export-time-stamp-file +toggle inclusion creation time into exported file +(@var{org-export-time-stamp-file}). + +@item toc: +@vindex org-export-with-toc +toggle table of contents, or set level limit (@var{org-export-with-toc}). + +@item todo: +@vindex org-export-with-todo-keywords +toggle inclusion of TODO keywords into exported text +(@var{org-export-with-todo-keywords}). + +@item |: +@vindex org-export-with-tables +toggle tables (@var{org-export-with-tables}). + +@end table + +A more general mechanism is also provided. Indeed, Emacs variables can +become buffer-local during export by using the BIND keyword. Its syntax is +@samp{#+BIND: variable value}. This is particularly useful for in-buffer +settings that cannot be changed using specific keywords. + +You can place commonly-used export settings in a separate file which can be +included using @samp{#+SETUPFILE: filename} syntax. + +These settings affect all buffer's export processes. Though, it is +possible to override them locally when exporting only a subtree. This is +done by adding a headline property named after the keyword with the +@samp{EXPORT_} prefix. For example, @samp{DATE} and @samp{OPTIONS} +keywords become, respectively @samp{EXPORT_DATE} and @samp{EXPORT_OPTIONS} +properties. Subtree export also supports the self-explicit +@samp{EXPORT_FILE_NAME} property@footnote{There is no buffer-wide +equivalent for this property. The file name in this case is derived from +the file associated to the buffer, if possible, or asked to the user +otherwise.}. + +@node ASCII/Latin-1/UTF-8 export, HTML export, Export settings, Exporting @section ASCII/Latin-1/UTF-8 export @cindex ASCII export @cindex Latin-1 export @@ -10302,51 +10587,59 @@ ASCII export produces a simple and very readable version of an Org mode file, containing only plain ASCII@. Latin-1 and UTF-8 export augment the file with special characters and symbols available in these encodings. -@cindex region, active -@cindex active region -@cindex transient-mark-mode +@vindex org-ascii-links-to-notes +Links are exported in a footnote-like style, with the descriptive part in the +text and the link in a note before the next heading. See the variable +@code{org-ascii-links-to-notes} for details and other options. + +@subheading ASCII export commands + @table @kbd -@orgcmd{C-c C-e t a,org-ascii-export-to-ascii} -@cindex property, EXPORT_FILE_NAME +@orgcmd{C-c C-e t a/l/u,org-ascii-export-to-ascii} Export as an ASCII file. For an Org file, @file{myfile.org}, the ASCII file -will be @file{myfile.txt}. The file will be overwritten without -warning. If there is an active region@footnote{This requires -@code{transient-mark-mode} be turned on.}, only the region will be -exported. If the selected region is a single tree@footnote{To select the -current subtree, use @kbd{C-c @@}.}, the tree head will -become the document title. If the tree head entry has or inherits an -@code{EXPORT_FILE_NAME} property, that name will be used for the -export. -@orgcmd{C-c C-e t A,org-ascii-export-as-ascii} +will be @file{myfile.txt}. The file will be overwritten without warning. +When the original file is @file{myfile.txt}, the resulting file becomes +@file{myfile.txt.txt} in order to prevent data loss. +@orgcmd{C-c C-e t A/L/U,org-ascii-export-as-ascii} Export to a temporary buffer. Do not create a file. -@item C-c C-e C-v t a/t A -Export only the visible part of the document. @end table -@c FIXME Exporting sublevels -@c @cindex headline levels, for exporting -@c In the exported version, the first 3 outline levels will become -@c headlines, defining a general document structure. Additional levels -@c will be exported as itemized lists. If you want that transition to occur -@c at a different level, specify it with a prefix argument. For example, +@subheading Header and sectioning structure -@c @example -@c @kbd{C-1 C-c C-e a} -@c @end example +In the exported version, the first three outline levels become headlines, +defining a general document structure. Additional levels are exported as +lists. The transition can also occur at a different level (@pxref{Export +settings}). -@c @noindent -@c creates only top level headlines and exports the rest as items. When -@c headlines are converted to items, the indentation of the text following -@c the headline is changed to fit nicely under the item. This is done with -@c the assumption that the first body line indicates the base indentation of -@c the body text. Any indentation larger than this is adjusted to preserve -@c the layout relative to the first line. Should there be lines with less -@c indentation than the first one, these are left alone. +@subheading Quoting ASCII text -@vindex org-ascii-links-to-notes -Links will be exported in a footnote-like style, with the descriptive part in -the text and the link in a note before the next heading. See the variable -@code{org-ascii-links-to-notes} for details and other options. +You can insert text that will only appear when using @code{ASCII} back-end +with the following constructs: + +@cindex #+ASCII +@cindex #+BEGIN_ASCII +@example +Text @@@@ascii:and additional text@@@@ within a paragraph. + +#+ASCII: Some text + +#+BEGIN_ASCII +All lines in this block will appear only when using this back-end. +#+END_ASCII +@end example + +@subheading ASCII specific attributes +@cindex #+ATTR_ASCII +@cindex horizontal rules, in ASCII export + +@code{ASCII} back-end only understands one attribute, @code{:width}, which +specifies the length, in characters, of a given horizontal rule. It must be +specified using an @code{ATTR_ASCII} line, directly preceding the rule. + +@example +#+ATTR_ASCII: :width 10 +----- +@end example @node HTML export, @LaTeX{} and PDF export, ASCII/Latin-1/UTF-8 export, Exporting @section HTML export @@ -10426,22 +10719,17 @@ The default value for @code{org-html-preamble} is @code{t}, which means that the preamble is inserted depending on the relevant format string in @code{org-html-preamble-format}. -Setting @code{org-html-preamble} to a string will override the default -format string. Setting it to a function, will insert the output of the -function, which must be a string; such a function takes no argument but you -can check against the value of @code{opt-plist}, which contains the list of -publishing properties for the current file. Setting to @code{nil} will not -insert any preamble. +Setting @code{org-html-preamble} to a string will override the default format +string. If you set it to a function, it will insert the output of the +function, which must be a string. Setting to @code{nil} will not insert any +preamble. -The default value for @code{org-html-postamble} is @code{'auto}, which -means that the HTML exporter will look for the value of -@code{org-export-author-info}, @code{org-export-email-info}, -@code{org-export-creator-info} and @code{org-export-time-stamp-file}, -@code{org-html-validation-link} and build the postamble from these -values. Setting @code{org-html-postamble} to @code{t} will insert the -postamble from the relevant format string found in -@code{org-html-postamble-format}. Setting it to @code{nil} will not -insert any postamble. +The default value for @code{org-html-postamble} is @code{'auto}, which means +that the HTML exporter will look for information about the author, the email, +the creator and the date, and build the postamble from these values. Setting +@code{org-html-postamble} to @code{t} will insert the postamble from the +relevant format string found in @code{org-html-postamble-format}. Setting it +to @code{nil} will not insert any postamble. @node Quoting HTML tags, Links in HTML export, HTML preamble and postamble, HTML export @subsection Quoting HTML tags @@ -10492,27 +10780,32 @@ and @code{style} attributes for a link: @cindex #+ATTR_HTML @example -#+ATTR_HTML: title="The Org mode homepage" style="color:red;" +#+ATTR_HTML: :title The Org mode homepage :style color:red; [[http://orgmode.org]] @end example @node Tables in HTML export, Images in HTML export, Links in HTML export, HTML export @subsection Tables @cindex tables, in HTML -@vindex org-html-table-tag +@vindex org-html-table-default-attributes -Org mode tables are exported to HTML using the table tag defined in -@code{org-html-table-tag}. The default setting makes tables without -cell borders and frame. If you would like to change this for individual -tables, place something like the following before the table: +Org mode tables are exported to HTML using the table attributes defined in +@code{org-html-table-default-attributes}. The default setting makes tables +without cell borders and frame. If you would like to change this for +individual tables, place something like the following before the table: @cindex #+CAPTION @cindex #+ATTR_HTML @example #+CAPTION: This is a table with lines around and between cells -#+ATTR_HTML: border="2" rules="all" frame="border" +#+ATTR_HTML: :border 2 :rules all :frame border @end example +@vindex org-html-table-row-tags +You can also modify the default tags used for each row by setting +@var{org-html-table-row-tags}. See the docstring for an example on +how to use this option. + @node Images in HTML export, Math formatting in HTML export, Tables in HTML export, HTML export @subsection Images in HTML export @@ -10543,7 +10836,7 @@ support text viewers and accessibility, and align it to the right. @cindex #+ATTR_HTML @example #+CAPTION: A black cat stalking a spider -#+ATTR_HTML: alt="cat/spider image" title="Action!" align="right" +#+ATTR_HTML: :alt cat/spider image :title Action! :align right [[./img/a.jpg]] @end example @@ -10699,15 +10992,12 @@ as well, press @kbd{?} for an overview of the available keys). The second view type is a @emph{folding} view much like Org provides inside Emacs. The script is available at @url{http://orgmode.org/org-info.js} and you can find the documentation for it at @url{http://orgmode.org/worg/code/org-info-js/}. -We host the script at our site, but if you use it a lot, you might -not want to be dependent on @url{orgmode.org} and prefer to install a local +We host the script at our site, but if you use it a lot, you might not want +to be dependent on @url{http://orgmode.org} and prefer to install a local copy on your own web server. -To use the script, you need to make sure that the @file{org-jsinfo.el} module -gets loaded. It should be loaded by default, but you can try @kbd{M-x -customize-variable @key{RET} org-modules @key{RET}} to convince yourself that -this is indeed the case. All it then takes to make use of the program is -adding a single line to the Org file: +All it then takes to use this program is adding a single line to the Org +file: @cindex #+INFOJS_OPT @example @@ -10757,73 +11047,51 @@ pages, configure the variable @code{org-html-use-infojs}. @section @LaTeX{} and PDF export @cindex @LaTeX{} export @cindex PDF export -@cindex Guerry, Bastien Org mode contains a @LaTeX{} exporter. With further processing@footnote{The default @LaTeX{} output is designed for processing with @code{pdftex} or @LaTeX{}. It includes packages that are not compatible with @code{xetex} and possibly @code{luatex}. See the variables @code{org-latex-default-packages-alist} and -@code{org-latex-packages-alist}.}, this backend is also used to produce PDF +@code{org-latex-packages-alist}.}, this back-end is also used to produce PDF output. Since the @LaTeX{} output uses @file{hyperref} to implement links -and cross references, the PDF output file will be fully linked. Beware of -the fact that your @code{org} file has to be properly structured in order to -be correctly exported: respect the hierarchy of sections. +and cross references, the PDF output file will be fully linked. + +As is @LaTeX{}, blank lines are meaningful for this back-end: a paragraph +will not be started if two contiguous syntactical elements are not separated +by an empty line. + +This back-end also offers enhanced support for footnotes. Thus, it handles +nested footnotes, footnotes in tables and footnotes in items' description. @menu * @LaTeX{}/PDF export commands:: * Header and sectioning:: Setting up the export file structure * Quoting @LaTeX{} code:: Incorporating literal @LaTeX{} code -* Tables in @LaTeX{} export:: Options for exporting tables to @LaTeX{} -* Images in @LaTeX{} export:: How to insert figures into @LaTeX{} output +* @LaTeX{} specific attributes:: Controlling @LaTeX{} output * Beamer class export:: Turning the file into a presentation @end menu @node @LaTeX{}/PDF export commands, Header and sectioning, @LaTeX{} and PDF export, @LaTeX{} and PDF export @subsection @LaTeX{} export commands -@cindex region, active -@cindex active region -@cindex transient-mark-mode @table @kbd @orgcmd{C-c C-e l l,org-latex-export-to-latex} -@cindex property EXPORT_FILE_NAME -Export as a @LaTeX{} file. For an Org file -@file{myfile.org}, the @LaTeX{} file will be @file{myfile.tex}. The file will -be overwritten without warning. If there is an active region@footnote{This -requires @code{transient-mark-mode} be turned on.}, only the region will be -exported. If the selected region is a single tree@footnote{To select the -current subtree, use @kbd{C-c @@}.}, the tree head will become the document -title. If the tree head entry has or inherits an @code{EXPORT_FILE_NAME} -property, that name will be used for the export. +Export as a @LaTeX{} file. For an Org file @file{myfile.org}, the @LaTeX{} +file will be @file{myfile.tex}. The file will be overwritten without +warning. @orgcmd{C-c C-e l L,org-latex-export-as-latex} Export to a temporary buffer. Do not create a file. -@item C-c C-e C-v l/L -Export only the visible part of the document. @orgcmd{C-c C-e l p,org-latex-export-to-pdf} Export as @LaTeX{} and then process to PDF. -@kbd{C-c C-e l o} +@item C-c C-e l o Export as @LaTeX{} and then process to PDF, then open the resulting PDF file. @end table -@c FIXME Exporting sublevels -@c @cindex headline levels, for exporting -@c @vindex org-latex-low-levels -@c In the exported version, the first 3 outline levels will become -@c headlines, defining a general document structure. Additional levels -@c will be exported as description lists. The exporter can ignore them or -@c convert them to a custom string depending on -@c @code{org-latex-low-levels}. - -@c If you want that transition to occur at a different level, specify it -@c with a numeric prefix argument. For example, - -@c @example -@c @kbd{C-2 C-c C-e l} -@c @end example - -@c @noindent -@c creates two levels of headings and does the rest as items. +In the exported version, the first three outline levels become headlines, +defining a general document structure. Additional levels are exported as +@code{itemize} or @code{enumerate} lists. The transition can also occur at +a different level (@pxref{Export settings}). @node Header and sectioning, Quoting @LaTeX{} code, @LaTeX{}/PDF export commands, @LaTeX{} and PDF export @subsection Header and sectioning structure @@ -10839,154 +11107,260 @@ By default, the @LaTeX{} output uses the class @code{article}. @vindex org-latex-classes @vindex org-latex-default-packages-alist @vindex org-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-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-latex-classes}. This variable -defines a header template for each class@footnote{Into which the values of -@code{org-latex-default-packages-alist} and -@code{org-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. The -options to documentclass have to be provided, as expected by @LaTeX{}, within -square brackets. You can also use @code{#+LaTeX_HEADER: \usepackage@{xyz@}} -to add lines to the header. See the docstring of -@code{org-latex-classes} for more information. An example is shown -below. +@code{#+LATEX_CLASS: myclass} in your file, or with +a @code{EXPORT_LATEX_CLASS} property that applies when exporting a region +containing only this (sub)tree. The class must be listed in +@code{org-latex-classes}. This variable defines a header template for each +class@footnote{Into which the values of +@code{org-latex-default-packages-alist} and @code{org-latex-packages-alist} +are spliced.}, and allows you to define the sectioning structure for each +class. You can also define your own classes there. + +@cindex #+LATEX_CLASS +@cindex #+LATEX_CLASS_OPTIONS +@cindex property, EXPORT_LATEX_CLASS +@cindex property, EXPORT_LATEX_CLASS_OPTIONS +@code{LATEX_CLASS_OPTIONS} keyword or @code{EXPORT_LATEX_CLASS_OPTIONS} +property can specify the options for the @code{\documentclass} macro. These +options have to be provided, as expected by @LaTeX{}, within square brackets. + +@cindex #+LATEX_HEADER +@cindex #+LATEX_HEADER_EXTRA +You can also use LATEX_HEADER and LATEX_HEADER_EXTRA keywords in order to add +lines to the header. See the docstring of @code{org-latex-classes} for more +information. + +An example is shown below. @example -#+LaTeX_CLASS: article -#+LaTeX_CLASS_OPTIONS: [a4paper] -#+LaTeX_HEADER: \usepackage@{xyz@} +#+LATEX_CLASS: article +#+LATEX_CLASS_OPTIONS: [a4paper] +#+LATEX_HEADER: \usepackage@{xyz@} * Headline 1 some text @end example -@node Quoting @LaTeX{} code, Tables in @LaTeX{} export, Header and sectioning, @LaTeX{} and PDF export +@node Quoting @LaTeX{} code, @LaTeX{} specific attributes, Header and sectioning, @LaTeX{} and PDF export @subsection Quoting @LaTeX{} code Embedded @LaTeX{} as described in @ref{Embedded @LaTeX{}}, will be correctly -inserted into the @LaTeX{} 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 @LaTeX{} export with -the following constructs: +inserted into the @LaTeX{} file. Furthermore, you can add special code that +should only be present in @LaTeX{} export with the following constructs: -@cindex #+LaTeX -@cindex #+BEGIN_LaTeX +@cindex #+LATEX +@cindex #+BEGIN_LATEX @example -#+LaTeX: Literal @LaTeX{} code for export -@end example +Code within @@@@latex:some code@@@@ a paragraph. -@noindent or -@cindex #+BEGIN_LaTeX +#+LATEX: Literal @LaTeX{} code for export -@example -#+BEGIN_LaTeX +#+BEGIN_LATEX All lines between these markers are exported literally -#+END_LaTeX +#+END_LATEX @end example -@node Tables in @LaTeX{} export, Images in @LaTeX{} export, Quoting @LaTeX{} code, @LaTeX{} and PDF export -@subsection Tables in @LaTeX{} export +@node @LaTeX{} specific attributes, Beamer class export, Quoting @LaTeX{} code, @LaTeX{} and PDF export +@subsection @LaTeX{} specific attributes +@cindex #+ATTR_LATEX + +@LaTeX{} understands attributes specified in an @code{ATTR_LATEX} line. They +affect tables, images, plain lists, special blocks and source blocks. + +@subsubheading Tables in @LaTeX{} export @cindex tables, in @LaTeX{} export -For @LaTeX{} export of a table, you can specify a label, a caption and -placement options (@pxref{Images and tables}). You can also use the -@code{ATTR_LaTeX} line to request a @code{longtable} environment for the -table, so that it may span several pages, or to change the default table -environment from @code{table} to @code{table*} or to change the default inner -tabular environment to @code{tabularx} or @code{tabulary}. Finally, you can -set the alignment string, and (with @code{tabularx} or @code{tabulary}) the -width: +For @LaTeX{} export of a table, you can specify a label and a caption +(@pxref{Images and tables}). You can also use attributes to control table +layout and contents. Valid properties are: + +@table @code +@item :mode +@vindex org-latex-default-table-mode +Nature of table's contents. It can be set to @code{table}, @code{math}, +@code{inline-math} or @code{verbatim}. In particular, when in @code{math} or +@code{inline-math} mode, every cell is exported as-is, horizontal rules are +ignored and the table will be wrapped in a math environment. Also, +contiguous tables sharing the same math mode will be wrapped within the same +environment. Default mode is determined in +@var{org-latex-default-table-mode}. +@item :environment +@vindex org-latex-default-table-environment +Environment used for the table. It can be to any @LaTeX{} table +environment, like @code{tabularx}, @code{longtable}, @code{array}, +@code{tabu}, @code{bmatrix}@enddots{} It defaults to +@var{org-latex-default-table-environment} value. +@item :float +Float environment for the table. Possible values are @code{sidewaystable}, +@code{multicolumn} and @code{table}. If unspecified, a table with a caption +will have a @code{table} environment. Moreover, @code{:placement} attribute +can specify the positioning of the float. +@item :align +@itemx :font +@itemx :width +set, respectively, the alignment string of the table, its font size and its +width. They only apply on regular tables. +@item :spread +Boolean specific to the @code{tabu} and @code{longtabu} environments, and +only takes effect when used in conjunction with the @code{:width} attribute. +When @code{:spread} is non-nil, the table will be spread or shrunk by the +value of @code{:width}. +@item :booktabs +@itemx :center +@itemx :rmlines +@vindex org-latex-tables-booktabs +@vindex org-latex-tables-centered +They toggle, respectively, @code{booktabs} usage (assuming the package is +properly loaded), table centering and removal of every horizontal rule but +the first one (in a "table.el" table only). In particular, +@var{org-latex-tables-booktabs} (resp.@: @var{org-latex-tables-centered}) +activates the first (resp.@: second) attribute globally. +@item :math-prefix +@itemx :math-suffix +@itemx :math-arguments +string which will be inserted, respectively, before the table within the math +environment, after the table within the math environment, and between the +macro name and the contents of the table. The latter attribute is necessary +to matrix macros that require more than one argument (e.g., +@code{qbordermatrix}). +@end table + +Thus, attributes can be used in a wide array of situations, like writing +a table that will span over multiple pages, or a matrix product: -@cindex #+CAPTION -@cindex #+LABEL -@cindex #+ATTR_LaTeX @example -#+CAPTION: A long table -#+LABEL: tbl:long -#+ATTR_LaTeX: longtable align=l|lp@{3cm@}r|l +#+ATTR_LATEX: :environment longtable :align l|lp@{3cm@}r|l | ..... | ..... | | ..... | ..... | + +#+ATTR_LATEX: :mode math :environment bmatrix :math-suffix \times +| a | b | +| c | d | +#+ATTR_LATEX: :mode math :environment bmatrix +| 1 | 2 | +| 3 | 4 | @end example -or to specify a multicolumn table with @code{tabulary} - -@cindex #+CAPTION -@cindex #+LABEL -@cindex #+ATTR_LaTeX -@example -#+CAPTION: A wide table with tabulary -#+LABEL: tbl:wide -#+ATTR_LaTeX: table* tabulary width=\textwidth -| ..... | ..... | -| ..... | ..... | -@end example - -@node Images in @LaTeX{} export, Beamer class export, Tables in @LaTeX{} export, @LaTeX{} and PDF export -@subsection Images in @LaTeX{} export +@subsubheading 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 file resulting from @LaTeX{} processing. 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{Images and tables}, the figure -will be wrapped into a @code{figure} environment and thus become a floating -element. You can use an @code{#+ATTR_LaTeX:} line to specify various other -options. You can ask org to export an image as a float without specifying -a label or a caption by using the keyword @code{float} in this line. Various -optional arguments to the @code{\includegraphics} macro can also be specified -in this fashion. To modify the placement option of the floating environment, -add something like @samp{placement=[h!]} to the attributes. It is to be noted -this option can be used with tables as well@footnote{One can also take -advantage of this option to pass other, unrelated options into the figure or -table environment. For an example see the section ``Exporting org files'' in -@url{http://orgmode.org/worg/org-hacks.html}}. +@code{\includegraphics} macro to insert the image@footnote{In the case of +TikZ (@url{http://sourceforge.net/projects/pgf/}) images, it will become an +@code{\input} macro wrapped within a @code{tikzpicture} environment.}. -If you would like to let text flow around the image, add the word @samp{wrap} -to the @code{#+ATTR_LaTeX:} line, which will make the figure occupy the left -half of the page. To fine-tune, the @code{placement} field will be the set -of additional arguments needed by the @code{wrapfigure} environment. Note -that if you change the size of the image, you need to use compatible settings -for @code{\includegraphics} and @code{wrapfigure}. +You can specify specify image width or height with, respectively, +@code{:width} and @code{:height} attributes. It is also possible to add any +other option with the @code{:options} attribute, as shown in the following +example: -@cindex #+CAPTION -@cindex #+LABEL -@cindex #+ATTR_LaTeX @example -#+CAPTION: The black-body emission of the disk around HR 4049 -#+LABEL: fig:SED-HR4049 -#+ATTR_LaTeX: width=5cm,angle=90 +#+ATTR_LATEX: :width 5cm :options angle=90 [[./img/sed-hr4049.pdf]] +@end example -#+ATTR_LaTeX: width=0.38\textwidth wrap placement=@{r@}@{0.4\textwidth@} +If you have specified a caption as described in @ref{Images and tables}, the +picture will be wrapped into a @code{figure} environment and thus become +a floating element. You can also ask Org to export an image as a float +without specifying caption by setting the @code{:float} attribute. You may +also set it to: +@itemize @minus +@item +@code{wrap}: if you would like to let text flow around the image. It will +make the figure occupy the left half of the page. +@item +@code{multicolumn}: if you wish to include an image which spans multiple +columns in a page. This will export the image wrapped in a @code{figure*} +environment. +@end itemize +@noindent +To modify the placement option of any floating environment, set the +@code{placement} attribute. + +@example +#+ATTR_LATEX: :float wrap :width 0.38\textwidth :placement @{r@}@{0.4\textwidth@} [[./img/hst.png]] @end example -If you wish to include an image which spans multiple columns in a page, you -can use the keyword @code{multicolumn} in the @code{#+ATTR_LaTeX} line. This -will export the image wrapped in a @code{figure*} environment. +Eventually, in the @code{:comment-include} attributes has a non-nil value, +the code actually including the image will be commented out. -If you need references to a label created in this way, write -@samp{\ref@{fig:SED-HR4049@}} just like in @LaTeX{}. +@subsubheading Plain lists in @LaTeX{} export +@cindex plain lists, in @LaTeX{} export -@node Beamer class export, , Images in @LaTeX{} export, @LaTeX{} and PDF export +Plain lists accept two optional attributes: @code{:environment} and +@code{:options}. The first one allows to use a non-standard environment +(e.g., @samp{inparaenum}). The second one allows to specify optional +arguments for that environment (square brackets may be omitted). + +@example +#+ATTR_LATEX: :environment compactitem :options $\circ$ +- you need ``paralist'' package to reproduce this example. +@end example + +@subsubheading Source blocks in @LaTeX{} export +@cindex source blocks, in @LaTeX{} export + +In addition to syntax defined in @ref{Literal examples}, names and captions +(@pxref{Images and tables}), source blocks also accept @code{:long-listing} +attribute, which prevents the block to become a float when non nil. + +@example +#+ATTR_LATEX: :long-listing t +#+BEGIN_SRC emacs-lisp +Code that may not fit in a single page. +#+END_SRC +@end example + +@subsubheading Special blocks in @LaTeX{} export +@cindex special blocks, in @LaTeX{} export + +In @LaTeX{} back-end, special blocks become environments of the same name. +Value of @code{:options} attribute will be appended as-is to that +environment's opening string. For example: + +@example +#+ATTR_LATEX: :options [Proof of important theorem] +#+BEGIN_PROOF +... +Therefore, any natural number above 4 is the sum of two primes. +#+END_PROOF +@end example + +@noindent +becomes + +@example +\begin@{proof@}[Proof of important theorem] +... +Therefore, any natural number above 4 is the sum of two primes. +\end@{proof@} +@end example + +@subsubheading Horizontal rules +@cindex horizontal rules, in @LaTeX{} export + +Width and thickness of a given horizontal rule can be controlled with, +respectively, @code{:width} and @code{:thickness} attributes: + +@example +#+ATTR_LATEX: :width .6\textwidth :thickness 0.8pt +----- +@end example + +@node Beamer class export, , @LaTeX{} specific attributes, @LaTeX{} and PDF export @subsection Beamer class export -The @LaTeX{} class @file{beamer} allows production of high quality presentations -using @LaTeX{} and pdf processing. Org mode has special support for turning an -Org mode file or tree into a @file{beamer} presentation. +The @LaTeX{} class @file{beamer} allows production of high quality +presentations using @LaTeX{} and pdf processing. Org mode has special +support for turning an Org mode file or tree into a @file{beamer} +presentation. When the @LaTeX{} class for the current buffer (as set with @code{#+LaTeX_CLASS: beamer}) or subtree (set with a @code{LaTeX_CLASS} property) is @@ -11000,7 +11374,7 @@ different level---then the hierarchy above frames will produce the sectioning structure of the presentation. A template for useful in-buffer settings or properties can be inserted into -the buffer with @kbd{M-x org-insert-beamer-options-template}. Among other +the buffer with @kbd{M-x org-beamer-insert-options-template}. Among other things, this will install a column view format which is very handy for editing special properties used by beamer. @@ -11161,7 +11535,7 @@ output. Check the availability of this program before proceeding further. Export as OpenDocument Text file. -@vindex org-export-odt-preferred-output-format +@vindex org-odt-preferred-output-format If @code{org-preferred-output-format} is specified, automatically convert the exported file to that format. @xref{x-export-to-other-formats, , Automatically exporting to other formats}. @@ -11179,8 +11553,8 @@ export. Export as an OpenDocument Text file and open the resulting file. @vindex org-odt-preferred-output-format -If @code{org-preferred-output-format} is specified, open the converted file -instead. @xref{x-export-to-other-formats, , Automatically exporting to +If @code{org-odt-preferred-output-format} is specified, open the converted +file instead. @xref{x-export-to-other-formats, , Automatically exporting to other formats}. @end table @@ -11197,7 +11571,7 @@ one format (say @samp{csv}) to another format (say @samp{ods} or @samp{xls}). If you have a working installation of LibreOffice, a document converter is pre-configured for you and you can use it right away. If you would like to use @file{unoconv} as your preferred converter, customize the variable -@code{org-export-odt-convert-process} to point to @code{unoconv}. You can +@code{org-odt-convert-process} to point to @code{unoconv}. You can also use your own favorite converter or tweak the default settings of the @file{LibreOffice} and @samp{unoconv} converters. @xref{Configuring a document converter}. @@ -11205,12 +11579,12 @@ document converter}. @subsubsection Automatically exporting to other formats @anchor{x-export-to-other-formats} -@vindex org-export-odt-preferred-output-format +@vindex org-odt-preferred-output-format Very often, you will find yourself exporting to ODT format, only to immediately save the exported document to other formats like @samp{doc}, @samp{docx}, @samp{rtf}, @samp{pdf} etc. In such cases, you can specify your preferred output format by customizing the variable -@code{org-export-odt-preferred-output-format}. This way, the export commands +@code{org-odt-preferred-output-format}. This way, the export commands (@pxref{x-export-to-odt,,Exporting to ODT}) can be extended to export to a format that is of immediate interest to you. @@ -11223,10 +11597,10 @@ ODT format. LibreOffice converter, mentioned above, is one such converter. Once a converter is configured, you can interact with it using the following command. -@vindex org-export-odt-convert +@vindex org-odt-convert @table @kbd -@item M-x org-export-odt-convert +@item M-x org-odt-convert Convert an existing document from one format to another. With a prefix argument, also open the newly produced file. @end table @@ -11263,8 +11637,8 @@ OpenDocument Text (@file{.odt}) or OpenDocument Template (@file{.ott}) file. @item @cindex #+ODT_STYLES_FILE -@vindex org-export-odt-styles-file -Customize the variable @code{org-export-odt-styles-file} and point it to the +@vindex org-odt-styles-file +Customize the variable @code{org-odt-styles-file} and point it to the newly created file. For additional configuration options @pxref{x-overriding-factory-styles,,Overriding factory styles}. @@ -11387,7 +11761,7 @@ You can control the size and scale of the embedded images using the @code{#+ATTR_ODT} attribute. @cindex identify, ImageMagick -@vindex org-export-odt-pixels-per-inch +@vindex org-odt-pixels-per-inch The exporter specifies the desired size of the image in the final document in units of centimeters. In order to scale the embedded images, the exporter queries for pixel dimensions of the images using one of a) ImageMagick's @@ -11397,7 +11771,7 @@ routinely produce documents that have large images or you export your Org files that has images using a Emacs batch script, then the use of @file{ImageMagick} is mandatory.} The pixel dimensions are subsequently converted in to units of centimeters using -@code{org-export-odt-pixels-per-inch}. The default value of this variable is +@code{org-odt-pixels-per-inch}. The default value of this variable is set to @code{display-pixels-per-inch}. You can tweak this variable to achieve the best results. @@ -11506,10 +11880,10 @@ You can use the following commands to quickly verify the reliability of the @LaTeX{}-to-MathML converter. @table @kbd -@item M-x org-export-as-odf +@item M-x org-odt-export-as-odf Convert a @LaTeX{} math snippet to an OpenDocument formula (@file{.odf}) file. -@item M-x org-export-as-odf-and-open +@item M-x org-odt-export-as-odf-and-open Convert a @LaTeX{} math snippet to an OpenDocument formula (@file{.odf}) file and open the formula file with the system-registered application. @end table @@ -11572,15 +11946,15 @@ It could be rendered as shown below in the exported document. Figure 2: Bell curve @end example -@vindex org-export-odt-category-strings +@vindex org-odt-category-map-alist You can modify the category component of the caption by customizing the -variable @code{org-export-odt-category-strings}. For example, to tag all -embedded images with the string @samp{Illustration} (instead of the default -@samp{Figure}) use the following setting. +option @code{org-odt-category-map-alist}. For example, to tag all embedded +images with the string @samp{Illustration} (instead of the default +@samp{Figure}) use the following setting: @lisp -(setq org-export-odt-category-strings - '(("en" "Table" "Illustration" "Equation" "Equation"))) +(setq org-odt-category-map-alist + (("__Figure__" "Illustration" "value" "Figure" org-odt--enumerable-image-p))) @end lisp With this, previous image will be captioned as below in the exported @@ -11601,14 +11975,14 @@ fontification to be turned on.} The auto-generated styles have @samp{OrgSrc} as prefix and inherit their color from the faces used by Emacs @code{font-lock} library for the source language. -@vindex org-export-odt-fontify-srcblocks -If you prefer to use your own custom styles for fontification, you can do so -by customizing the variable -@code{org-export-odt-create-custom-styles-for-srcblocks}. +@vindex org-odt-fontify-srcblocks +If you prefer to use your own custom styles for fontification, you can do +so by customizing the variable +@code{org-odt-create-custom-styles-for-srcblocks}. -@vindex org-export-odt-create-custom-styles-for-srcblocks +@vindex org-odt-create-custom-styles-for-srcblocks You can turn off fontification of literal examples by customizing the -variable @code{org-export-odt-fontify-srcblocks}. +option @code{org-odt-fontify-srcblocks}. @node Advanced topics in ODT export, , Literal examples in ODT export, OpenDocument Text export @subsection Advanced topics in ODT export @@ -11639,27 +12013,27 @@ like to tweak the default converter settings, proceed as below. @enumerate @item Register the converter -@vindex org-export-odt-convert-processes -Name your converter and add it to the list of known converters by customizing -the variable @code{org-export-odt-convert-processes}. Also specify how the -converter can be invoked via command-line to effect the conversion. +@vindex org-odt-convert-processes +Name your converter and add it to the list of known converters by +customizing the option @code{org-odt-convert-processes}. Also specify how +the converter can be invoked via command-line to effect the conversion. @item Configure its capabilities -@vindex org-export-odt-convert-capabilities -@anchor{x-odt-converter-capabilities} -Specify the set of formats the converter can handle by customizing the -variable @code{org-export-odt-convert-capabilities}. Use the default value -for this variable as a guide for configuring your converter. As suggested by -the default setting, you can specify the full set of formats supported by the +@vindex org-odt-convert-capabilities +@anchor{x-odt-converter-capabilities} Specify the set of formats the +converter can handle by customizing the variable +@code{org-odt-convert-capabilities}. Use the default value for this +variable as a guide for configuring your converter. As suggested by the +default setting, you can specify the full set of formats supported by the converter and not limit yourself to specifying formats that are related to just the OpenDocument Text format. @item Choose the converter -@vindex org-export-odt-convert-process +@vindex org-odt-convert-process Select the newly added converter as the preferred one by customizing the -variable @code{org-export-odt-convert-process}. +option @code{org-odt-convert-process}. @end enumerate @node Working with OpenDocument style files, Creating one-off styles, Configuring a document converter, Advanced topics in ODT export @@ -11727,9 +12101,9 @@ customize these variables to override the factory styles used by the exporter. @itemize -@anchor{x-org-export-odt-styles-file} +@anchor{x-org-odt-styles-file} @item -@code{org-export-odt-styles-file} +@code{org-odt-styles-file} Use this variable to specify the @file{styles.xml} that will be used in the final output. You can specify one of the following values: @@ -11758,9 +12132,9 @@ like header and footer images. Use the default @file{styles.xml} @end enumerate -@anchor{x-org-export-odt-content-template-file} +@anchor{x-org-odt-content-template-file} @item -@code{org-export-odt-content-template-file} +@code{org-odt-content-template-file} Use this variable to specify the blank @file{content.xml} that will be used in the final output. @@ -11810,7 +12184,7 @@ custom @samp{PageBreak} style as shown below. @example + style:parent-style-name="Text_20_body"> @end example @@ -11847,22 +12221,21 @@ OpenDocument-v1.2 specification.@footnote{@url{http://docs.oasis-open.org/office/v1.2/OpenDocument-v1.2.html, OpenDocument-v1.2 Specification}} - - @subsubheading Custom table styles: an illustration -To have a quick preview of this feature, install the below setting and export -the table that follows. +@vindex org-odt-table-styles +To have a quick preview of this feature, install the below setting and +export the table that follows: @lisp -(setq org-export-odt-table-styles - (append org-export-odt-table-styles - '(("TableWithHeaderRowAndColumn" "Custom" - ((use-first-row-styles . t) - (use-first-column-styles . t))) - ("TableWithFirstRowandLastRow" "Custom" - ((use-first-row-styles . t) - (use-last-row-styles . t)))))) +(setq org-odt-table-styles + (append org-odt-table-styles + '(("TableWithHeaderRowAndColumn" "Custom" + ((use-first-row-styles . t) + (use-first-column-styles . t))) + ("TableWithFirstRowandLastRow" "Custom" + ((use-first-row-styles . t) + (use-last-row-styles . t)))))) @end lisp @example @@ -11875,9 +12248,9 @@ the table that follows. In the above example, you used a template named @samp{Custom} and installed two table styles with the names @samp{TableWithHeaderRowAndColumn} and @samp{TableWithFirstRowandLastRow}. (@strong{Important:} The OpenDocument -styles needed for producing the above template have been pre-defined for you. -These styles are available under the section marked @samp{Custom Table -Template} in @file{OrgOdtContentTemplate.xml} +styles needed for producing the above template have been pre-defined for +you. These styles are available under the section marked @samp{Custom +Table Template} in @file{OrgOdtContentTemplate.xml} (@pxref{x-orgodtcontenttemplate-xml,,Factory styles}). If you need additional templates you have to define these styles yourselves. @@ -11961,9 +12334,9 @@ Define a table style@footnote{See the attributes @code{table:template-name}, @code{table:use-banding-column-styles} of the @code{} element in the OpenDocument-v1.2 specification} -@vindex org-export-odt-table-styles +@vindex org-odt-table-styles To define a table style, create an entry for the style in the variable -@code{org-export-odt-table-styles} and specify the following: +@code{org-odt-table-styles} and specify the following: @itemize @minus @item the name of the table template created in step (1) @@ -11976,14 +12349,14 @@ based on the same template @samp{Custom}. The styles achieve their intended effect by selectively activating the individual cell styles in that template. @lisp -(setq org-export-odt-table-styles - (append org-export-odt-table-styles - '(("TableWithHeaderRowAndColumn" "Custom" - ((use-first-row-styles . t) - (use-first-column-styles . t))) - ("TableWithFirstRowandLastRow" "Custom" - ((use-first-row-styles . t) - (use-last-row-styles . t)))))) +(setq org-odt-table-styles + (append org-odt-table-styles + '(("TableWithHeaderRowAndColumn" "Custom" + ((use-first-row-styles . t) + (use-first-column-styles . t))) + ("TableWithFirstRowandLastRow" "Custom" + ((use-first-row-styles . t) + (use-last-row-styles . t)))))) @end lisp @item @@ -12014,12 +12387,11 @@ nothing but @samp{zip} archives}: @inforef{File Archives,,emacs}. For general help with validation (and schema-sensitive editing) of XML files: @inforef{Introduction,,nxml-mode}. -@vindex org-export-odt-schema-dir +@vindex org-odt-schema-dir If you have ready access to OpenDocument @file{.rnc} files and the needed schema-locating rules in a single folder, you can customize the variable -@code{org-export-odt-schema-dir} to point to that directory. The -ODT exporter will take care of updating the -@code{rng-schema-locating-files} for you. +@code{org-odt-schema-dir} to point to that directory. The ODT exporter +will take care of updating the @code{rng-schema-locating-files} for you. @c end opendocument @@ -12171,7 +12543,7 @@ and where to put published files. @tab Directory containing publishing source files @item @code{:publishing-directory} @tab Directory where output files will be published. You can directly -publish to a webserver using a file name syntax appropriate for +publish to a web server using a file name syntax appropriate for the Emacs @file{tramp} package. Or you can publish to a local directory and use external tools to upload your website (@pxref{Uploading files}). @item @code{:preparation-function} @@ -12222,27 +12594,32 @@ possibly transformed in the process. The default transformation is to export Org files as HTML files, and this is done by the function @code{org-html-publish-to-html} which calls the HTML exporter (@pxref{HTML export}). But you also can publish your content as PDF files using -@code{org-latex-publish-to-pdf}, or as @code{ascii}, @code{latin1} or -@code{utf8} encoded files using the corresponding functions. If you want to -publish the Org file itself, but with @i{archived}, @i{commented}, and -@i{tag-excluded} trees removed, use @code{org-org-publish-to-org} and set the -parameters @code{:plain-source} and/or @code{:htmlized-source}. This will -produce @file{file.org} and @file{file.org.html} in the publishing -directory@footnote{@file{file-source.org} and @file{file-source.org.html} if -source and publishing directories are equal. Note that with this kind of -setup, you need to add @code{:exclude "-source\\.org"} to the project -definition in @code{org-publish-project-alist} to prevent the published -source files from being considered as new org files the next time the project -is published.}. Other files like images only need to be copied to the -publishing destination; for this you may use @code{org-publish-attachment}. -For non-Org files, you always need to specify the publishing function: +@code{org-latex-publish-to-pdf} or as @code{ascii}, @code{Texinfo}, etc., +using the corresponding functions. + +If you want to publish the Org file itself but with the @i{archived}, +@i{commented} and @i{tag-excluded} trees removed, use the function +@code{org-org-publish-to-org}. This will produce @file{file.org}. If you +want a htmlized version of this file, set the parameter +@code{:htmlized-source} to @code{t}, it will produce @file{file.org.html} in +the publishing directory. + +@c @footnote{@file{file-source.org} and @file{file-source.org.html} if source +@c and publishing directories are equal. Note that with this kind of setup, you +@c need to add @code{:exclude "-source\\.org"} to the project definition in +@c @code{org-publish-project-alist} to prevent the published source files from +@c being considered as new org files the next time the project is published.}. + +Other files like images only need to be copied to the publishing destination; +for this you may use @code{org-publish-attachment}. For non-Org files, you +always need to specify the publishing function: @multitable @columnfractions 0.3 0.7 @item @code{:publishing-function} @tab Function executing the publication of a file. This may also be a list of functions, which will all be called in turn. -@item @code{:plain-source} -@tab Non-nil means, publish plain source. +@c @item @code{:plain-source} +@c @tab Non-nil means, publish plain source. @item @code{:htmlized-source} @tab Non-nil means, publish htmlized source. @end multitable @@ -12254,163 +12631,131 @@ should take the specified file, make the necessary transformation (if any) and place the result into the destination folder. @node Publishing options, Publishing links, Publishing action, Configuration -@subsection Options for the HTML/@LaTeX{} exporters +@subsection Options for the exporters @cindex options, for publishing -The property list can be used to set many export options for the HTML -and @LaTeX{} exporters. In most cases, these properties correspond to user -variables in Org. The table below lists these properties along -with the variable they belong to. See the documentation string for the -respective variable for details. +The property list can be used to set many export options for the exporters. +In most cases, these properties correspond to user variables in Org. The +first table below lists these properties along with the variable they belong +to. The second table list HTML specific properties. See the documentation +string for the respective variable for details. -@vindex org-html-link-up -@vindex org-html-link-home -@vindex org-export-default-language -@vindex org-display-custom-times -@vindex org-export-headline-levels -@vindex org-export-with-section-numbers -@vindex org-export-section-number-format -@vindex org-export-with-toc -@vindex org-export-preserve-breaks @vindex org-export-with-archived-trees -@vindex org-export-with-emphasize -@vindex org-export-with-sub-superscripts -@vindex org-export-with-special-strings -@vindex org-export-with-footnotes +@vindex org-export-with-author +@vindex org-export-with-creator +@vindex org-display-custom-times @vindex org-export-with-drawers -@vindex org-export-with-tags -@vindex org-export-with-todo-keywords -@vindex org-export-with-tasks -@vindex org-export-with-done-tasks -@vindex org-export-with-priority -@vindex org-export-with-TeX-macros -@vindex org-export-with-latex -@vindex org-export-skip-text-before-1st-heading -@vindex org-export-with-fixed-width -@vindex org-export-with-timestamps -@vindex org-export-author-info -@vindex org-export-email-info -@vindex org-export-creator-info -@vindex org-export-time-stamp-file -@vindex org-export-with-tables -@vindex org-export-highlight-first-table-line -@vindex org-html-style-include-default -@vindex org-html-style-include-scripts -@vindex org-html-style -@vindex org-html-style-extra -@vindex org-html-link-org-files-as-html -@vindex org-html-inline-images -@vindex org-html-extension -@vindex org-html-table-tag -@vindex org-export-publishing-directory -@vindex org-html-preamble -@vindex org-html-postamble -@vindex user-full-name +@vindex org-export-with-email @vindex user-mail-address -@vindex org-export-select-tags +@vindex org-export-with-emphasize @vindex org-export-exclude-tags +@vindex org-export-with-fixed-width +@vindex org-export-with-footnotes +@vindex org-export-headline-levels +@vindex org-export-default-language +@vindex org-export-with-latex +@vindex org-export-preserve-breaks +@vindex org-export-with-priority +@vindex org-export-publishing-directory +@vindex org-export-with-section-numbers +@vindex org-export-select-tags +@vindex org-export-with-special-strings +@vindex org-export-with-sub-superscripts +@vindex org-export-with-toc +@vindex org-export-with-tables +@vindex org-export-with-tags +@vindex org-export-with-tasks +@vindex org-export-with-timestamps +@vindex org-export-with-todo-keywords @multitable @columnfractions 0.32 0.68 -@item @code{:link-up} @tab @code{org-html-link-up} -@item @code{:link-home} @tab @code{org-html-link-home} -@item @code{:language} @tab @code{org-export-default-language} -@item @code{:customtime} @tab @code{org-display-custom-times} -@item @code{:headline-levels} @tab @code{org-export-headline-levels} -@item @code{:section-numbers} @tab @code{org-export-with-section-numbers} -@item @code{:section-number-format} @tab @code{org-export-section-number-format} -@item @code{:table-of-contents} @tab @code{org-export-with-toc} -@item @code{:preserve-breaks} @tab @code{org-export-preserve-breaks} @item @code{:archived-trees} @tab @code{org-export-with-archived-trees} -@item @code{:emphasize} @tab @code{org-export-with-emphasize} -@item @code{:sub-superscript} @tab @code{org-export-with-sub-superscripts} -@item @code{:special-strings} @tab @code{org-export-with-special-strings} -@item @code{:footnotes} @tab @code{org-export-with-footnotes} +@item @code{:author} @tab @code{org-export-with-author} +@item @code{:creator} @tab @code{org-export-with-creator} +@item @code{:customtime} @tab @code{org-display-custom-times} @item @code{:drawers} @tab @code{org-export-with-drawers} -@item @code{:tags} @tab @code{org-export-with-tags} -@item @code{:todo-keywords} @tab @code{org-export-with-todo-keywords} -@item @code{:tasks} @tab @code{org-export-with-tasks} -@item @code{:priority} @tab @code{org-export-with-priority} -@item @code{:TeX-macros} @tab @code{org-export-with-TeX-macros} -@item @code{:LaTeX-fragments} @tab @code{org-export-with-latex} -@item @code{:latex-listings} @tab @code{org-latex-listings} -@item @code{:skip-before-1st-heading} @tab @code{org-export-skip-text-before-1st-heading} -@item @code{:fixed-width} @tab @code{org-export-with-fixed-width} -@item @code{:timestamps} @tab @code{org-export-with-timestamps} -@item @code{:author} @tab @code{user-full-name} +@item @code{:email} @tab @code{org-export-with-email} @item @code{:email} @tab @code{user-mail-address} : @code{addr;addr;..} -@item @code{:author-info} @tab @code{org-export-author-info} -@item @code{:email-info} @tab @code{org-export-email-info} -@item @code{:creator-info} @tab @code{org-export-creator-info} +@item @code{:emphasize} @tab @code{org-export-with-emphasize} +@item @code{:exclude-tags} @tab @code{org-export-exclude-tags} +@item @code{:fixed-width} @tab @code{org-export-with-fixed-width} +@item @code{:footnotes} @tab @code{org-export-with-footnotes} +@item @code{:headline-levels} @tab @code{org-export-headline-levels} +@item @code{:language} @tab @code{org-export-default-language} +@item @code{:latex-fragments} @tab @code{org-export-with-latex} +@item @code{:preserve-breaks} @tab @code{org-export-preserve-breaks} +@item @code{:priority} @tab @code{org-export-with-priority} +@item @code{:publishing-directory} @tab @code{org-export-publishing-directory} +@item @code{:section-numbers} @tab @code{org-export-with-section-numbers} +@item @code{:select-tags} @tab @code{org-export-select-tags} +@item @code{:special-strings} @tab @code{org-export-with-special-strings} +@item @code{:sub-superscript} @tab @code{org-export-with-sub-superscripts} +@item @code{:table-of-contents} @tab @code{org-export-with-toc} @item @code{:tables} @tab @code{org-export-with-tables} -@item @code{:table-auto-headline} @tab @code{org-export-highlight-first-table-line} -@item @code{:style-include-default} @tab @code{org-html-style-include-default} -@item @code{:style-include-scripts} @tab @code{org-html-style-include-scripts} -@item @code{:style} @tab @code{org-html-style} -@item @code{:style-extra} @tab @code{org-html-style-extra} -@item @code{:convert-org-links} @tab @code{org-html-link-org-files-as-html} -@item @code{:inline-images} @tab @code{org-html-inline-images} +@item @code{:tags} @tab @code{org-export-with-tags} +@item @code{:tasks} @tab @code{org-export-with-tasks} +@item @code{:timestamps} @tab @code{org-export-with-timestamps} +@item @code{:todo-keywords} @tab @code{org-export-with-todo-keywords} +@end multitable + +@vindex org-html-doctype +@vindex org-html-xml-declaration +@vindex org-html-link-up +@vindex org-html-link-home +@vindex org-html-link-org-files-as-html +@vindex org-html-head +@vindex org-html-head-extra +@vindex org-html-inline-images +@vindex org-html-extension +@vindex org-html-preamble +@vindex org-html-postamble +@vindex org-html-table-default-attributes +@vindex org-html-style-include-default +@vindex org-html-style-include-scripts +@multitable @columnfractions 0.32 0.68 +@item @code{:html-doctype} @tab @code{org-html-doctype} +@item @code{:html-xml-declaration} @tab @code{org-html-xml-declaration} +@item @code{:html-link-up} @tab @code{org-html-link-up} +@item @code{:html-link-home} @tab @code{org-html-link-home} +@item @code{:html-link-org-as-html} @tab @code{org-html-link-org-files-as-html} +@item @code{:html-head} @tab @code{org-html-head} +@item @code{:html-head-extra} @tab @code{org-html-head-extra} +@item @code{:html-inline-images} @tab @code{org-html-inline-images} @item @code{:html-extension} @tab @code{org-html-extension} @item @code{:html-preamble} @tab @code{org-html-preamble} @item @code{:html-postamble} @tab @code{org-html-postamble} -@item @code{:xml-declaration} @tab @code{org-html-xml-declaration} -@item @code{:html-table-tag} @tab @code{org-html-table-tag} -@item @code{:publishing-directory} @tab @code{org-export-publishing-directory} -@item @code{:select-tags} @tab @code{org-export-select-tags} -@item @code{:exclude-tags} @tab @code{org-export-exclude-tags} -@item @code{:latex-image-options} @tab @code{org-latex-image-default-option} +@item @code{:html-table-attributes} @tab @code{org-html-table-default-attributes} +@item @code{:html-head-include-default-style} @tab @code{org-html-style-include-default} +@item @code{:html-head-include-scripts} @tab @code{org-html-style-include-scripts} @end multitable -Most of the @code{org-export-with-*} variables have the same effect in -both HTML and @LaTeX{} exporters, except for @code{:TeX-macros} and -@code{:LaTeX-fragments} options, respectively @code{nil} and @code{t} in the -@LaTeX{} export. See @code{org-export-plist-vars} to check this list of -options. - - +Most of the @code{org-export-with-*} variables have the same effect in each +exporter. @vindex org-publish-project-alist -When a property is given a value in @code{org-publish-project-alist}, -its setting overrides the value of the corresponding user variable (if -any) during publishing. Options set within a file (@pxref{Export -options}), however, override everything. +When a property is given a value in @code{org-publish-project-alist}, its +setting overrides the value of the corresponding user variable (if any) +during publishing. Options set within a file (@pxref{Export settings}), +however, override everything. @node Publishing links, Sitemap, Publishing options, Configuration @subsection Links between published files @cindex links, publishing -To create a link from one Org file to another, you would use -something like @samp{[[file:foo.org][The foo]]} or simply -@samp{file:foo.org.} (@pxref{Hyperlinks}). When published, this link -becomes a link to @file{foo.html}. In this way, you can interlink the -pages of your "org web" project and the links will work as expected when -you publish them to HTML@. If you also publish the Org source file and want -to link to that, use an @code{http:} link instead of a @code{file:} link, -because @code{file:} links are converted to link to the corresponding -@file{html} file. +To create a link from one Org file to another, you would use something like +@samp{[[file:foo.org][The foo]]} or simply @samp{file:foo.org.} +(@pxref{Hyperlinks}). When published, this link becomes a link to +@file{foo.html}. You can thus interlink the pages of your "org web" project +and the links will work as expected when you publish them to HTML@. If you +also publish the Org source file and want to link to it, use an @code{http:} +link instead of a @code{file:} link, because @code{file:} links are converted +to link to the corresponding @file{html} file. You may also link to related files, such as images. Provided you are careful with relative file names, and provided you have also configured Org to upload the related files, these links will work too. See @ref{Complex example}, for an example of this usage. -Sometimes an Org file to be published may contain links that are -only valid in your production environment, but not in the publishing -location. In this case, use the property - -@multitable @columnfractions 0.4 0.6 -@item @code{:link-validation-function} -@tab Function to validate links -@end multitable - -@noindent -to define a function for checking link validity. This function must -accept two arguments, the file name and a directory relative to which -the file name is interpreted in the production environment. If this -function returns @code{nil}, then the HTML generator will only insert a -description into the HTML file, but no link. One option for this -function is @code{org-publish-validate-link} which checks if the given -file is part of any project in @code{org-publish-project-alist}. - @node Sitemap, Generating an index, Publishing links, Configuration @subsection Generating a sitemap @cindex sitemap, of published pages @@ -12710,7 +13055,7 @@ src_[
]@{@} @table @code @item <#+NAME: name> This line associates a name with the code block. This is similar to the -@code{#+TBLNAME: NAME} lines that can be used to name tables in Org mode +@code{#+NAME: Name} lines that can be used to name tables in Org mode files. Referencing the name of a code block makes it possible to evaluate the block from other places in the file, from other files, or from Org mode table formulas (see @ref{The spreadsheet}). Names are assumed to be unique @@ -13079,7 +13424,7 @@ blocks. @lisp (setq org-babel-default-header-args (cons '(:noweb . "yes") - (assq-delete-all :noweb org-babel-default-header-args))) + (assq-delete-all :noweb org-babel-default-header-args))) @end lisp @node Language-specific header arguments, Buffer-wide header arguments, System-wide header arguments, Using header arguments @@ -13267,11 +13612,10 @@ syntax used to specify arguments is the same across all languages. In every case, variables require a default value when they are declared. The values passed to arguments can either be literal values, references, or -Emacs Lisp code (see @ref{var, Emacs Lisp evaluation of variables}). References -include anything in the Org mode file that takes a @code{#+NAME:}, -@code{#+TBLNAME:}, or @code{#+RESULTS:} line. This includes tables, lists, -@code{#+BEGIN_EXAMPLE} blocks, other code blocks, and the results of other -code blocks. +Emacs Lisp code (see @ref{var, Emacs Lisp evaluation of variables}). +References include anything in the Org mode file that takes a @code{#+NAME:} +or @code{#+RESULTS:} line: tables, lists, @code{#+BEGIN_EXAMPLE} blocks, +other code blocks and the results of other code blocks. Note: When a reference is made to another code block, the referenced block will be evaluated unless it has current cached results (see @ref{cache}). @@ -13296,10 +13640,10 @@ Here are examples of passing values by reference: @table @dfn @item table -an Org mode table named with either a @code{#+NAME:} or @code{#+TBLNAME:} line +an Org mode table named with either a @code{#+NAME:} line @example -#+TBLNAME: example-table +#+NAME: example-table | 1 | | 2 | | 3 | @@ -13579,7 +13923,7 @@ into the Org mode buffer as a file link. E.g., @code{:results value file}. @subsubheading Format The following options are mutually exclusive and specify what type of results -the code block will return. By default, results are inserted accoring to the +the code block will return. By default, results are inserted according to the type as specified above. @itemize @bullet @@ -14020,7 +14364,7 @@ variable and raises an error. Setting @code{:hlines no} or relying on the default value yields the following results. @example -#+TBLNAME: many-cols +#+NAME: many-cols | a | b | c | |---+---+---| | d | e | f | @@ -14042,7 +14386,7 @@ default value yields the following results. Leaves hlines in the table. Setting @code{:hlines yes} has this effect. @example -#+TBLNAME: many-cols +#+NAME: many-cols | a | b | c | |---+---+---| | d | e | f | @@ -14079,7 +14423,7 @@ names will be removed from the table before processing, then reapplied to the results. @example -#+TBLNAME: less-cols +#+NAME: less-cols | a | |---| | b | @@ -14126,7 +14470,7 @@ The first column of the table is removed from the table before processing, and is then reapplied to the results. @example -#+TBLNAME: with-rownames +#+NAME: with-rownames | one | 1 | 2 | 3 | 4 | 5 | | two | 6 | 7 | 8 | 9 | 10 | @@ -14201,7 +14545,7 @@ argument. @example #+name: attr_wrap #+begin_src sh :var data="" :var width="\\textwidth" :results output - echo "#+ATTR_LATEX width=$width" + echo "#+ATTR_LATEX :width $width" echo "$data" #+end_src @@ -14216,7 +14560,7 @@ argument. #+RESULTS: :RESULTS: -#+ATTR_LATEX width=5cm +#+ATTR_LATEX :width 5cm [[file:/tmp/it.png]] :END: @end example @@ -14672,11 +15016,11 @@ ask and nil not to ask. For example, here is how to execute "ditaa" code (which is considered safe) without asking: -@example +@lisp (defun my-org-confirm-babel-evaluate (lang body) (not (string= lang "ditaa"))) ; don't ask for ditaa (setq org-confirm-babel-evaluate 'my-org-confirm-babel-evaluate) -@end example +@end lisp @item Following @code{shell} and @code{elisp} links Org has two link types that can directly evaluate code (@pxref{External @@ -14992,7 +15336,7 @@ This line contains the formulas for the table directly above the line. Table can have multiple lines containing @samp{#+TBLFM:}. Note that only the first line of @samp{#+TBLFM:} will be applied when -you reculculate the table. For more details see @ref{Using +you recalculate the table. For more details see @ref{Using multiple #+TBLFM lines} in @ref{Editing and debugging formulas}. @item #+TITLE:, #+AUTHOR:, #+EMAIL:, #+LANGUAGE:, #+DATE:, @@ -15002,7 +15346,7 @@ multiple #+TBLFM lines} in @ref{Editing and debugging formulas}. @itemx #+HTML_HEAD:, #+HTML_LINK_UP:, #+HTML_LINK_HOME:, @itemx #+SELECT_TAGS:, #+EXCLUDE_TAGS: These lines provide settings for exporting files. For more details see -@ref{Export options}. +@ref{Export settings}. @item #+TODO: #+SEQ_TODO: #+TYP_TODO: @vindex org-todo-keywords These lines set the TODO keywords and their interpretation in the @@ -15047,7 +15391,7 @@ If the cursor is in a property line or at the start or end of a property drawer, offer property commands. @item If the cursor is at a footnote reference, go to the corresponding -definition, and vice versa. +definition, and @emph{vice versa}. @item If the cursor is on a statistics cookie, update it. @item @@ -15411,10 +15755,10 @@ Then, tell Org mode what to do with the new function: @lisp (add-hook 'org-mode-hook (lambda () - (make-variable-buffer-local 'yas/trigger-key) - (setq yas/trigger-key [tab]) - (add-to-list 'org-tab-first-hook 'yas/org-very-safe-expand) - (define-key yas/keymap [tab] 'yas/next-field))) + (make-variable-buffer-local 'yas/trigger-key) + (setq yas/trigger-key [tab]) + (add-to-list 'org-tab-first-hook 'yas/org-very-safe-expand) + (define-key yas/keymap [tab] 'yas/next-field))) @end lisp @item @file{windmove.el} by Hovav Shacham @@ -15463,7 +15807,7 @@ customize the @code{org-crypt-tag-matcher} setting. To use org-crypt it is suggested that you have the following in your @file{.emacs}: -@example +@lisp (require 'org-crypt) (org-crypt-use-before-save-magic) (setq org-tags-exclude-from-inheritance (quote ("crypt"))) @@ -15481,7 +15825,7 @@ To use org-crypt it is suggested that you have the following in your ;; To turn it off only locally, you can insert this: ;; ;; # -*- buffer-auto-save-file-name: nil; -*- -@end example +@end lisp Excluding the crypt tag from inheritance prevents already encrypted text being encrypted again. @@ -15497,12 +15841,13 @@ Org. * Hooks:: How to reach into Org's internals * Add-on packages:: Available extensions * Adding hyperlink types:: New custom link types +* Adding export back-ends:: How to write new export back-ends * Context-sensitive commands:: How to add functionality to such commands * Tables in arbitrary syntax:: Orgtbl for @LaTeX{} and other programs * Dynamic blocks:: Automatically filled blocks * Special agenda views:: Customized views * Speeding up your agendas:: Tips on how to speed up your agendas -* Extracting agenda information:: Postprocessing of agenda information +* Extracting agenda information:: Post-processing of agenda information * Using the property API:: Writing programs that use entry properties * Using the mapping API:: Mapping over all or selected entries @end menu @@ -15530,7 +15875,7 @@ documentation about each package, is maintained by the Worg project at -@node Adding hyperlink types, Context-sensitive commands, Add-on packages, Hacking +@node Adding hyperlink types, Adding export back-ends, Add-on packages, Hacking @section Adding hyperlink types @cindex hyperlinks, adding new types @@ -15633,7 +15978,37 @@ When it makes sense for your new link type, you may also define a function support for inserting such a link with @kbd{C-c C-l}. Such a function should not accept any arguments, and return the full link with prefix. -@node Context-sensitive commands, Tables in arbitrary syntax, Adding hyperlink types, Hacking +@node Adding export back-ends, Context-sensitive commands, Adding hyperlink types, Hacking +@section Adding export back-ends +@cindex Export, writing back-ends + +Org 8.0 comes with a completely rewritten export engine which makes it easy +to write new export back-ends, either from scratch, or from deriving them +from existing ones. + +Your two entry points are respectively @code{org-export-define-backend} and +@code{org-export-define-derived-backend}. To grok these functions, you +should first have a look at @file{ox-latex.el} (for how to define a new +back-end from scratch) and @file{ox-beamer.el} (for how to derive a new +back-end from an existing one. + +When creating a new back-end from scratch, the basic idea is to set the name +of the back-end (as a symbol) and an an alist of elements and export +functions. On top of this, you will need to set additional keywords like +@code{:menu-entry} (to display the back-end in the export dispatcher), +@code{:export-block} (to specify what blocks should not be exported by this +back-end), and @code{:options-alist} (to let the user set export options that +are specific to this back-end.) + +Deriving a new back-end is similar, except that you need to set +@code{:translate-alist} to an alist of export functions that should be used +instead of the parent back-end functions. + +For a complete reference documentation, see +@url{http://orgmode.org/worg/dev/org-export-reference.html, the Org Export +Reference on Worg}. + +@node Context-sensitive commands, Tables in arbitrary syntax, Adding export back-ends, Hacking @section Context-sensitive commands @cindex context-sensitive commands, hooks @cindex add-ons, context-sensitive commands @@ -16058,7 +16433,7 @@ The corresponding block writer function could look like this: (defun org-dblock-write:block-update-time (params) (let ((fmt (or (plist-get params :format) "%d. %m. %Y"))) (insert "Last block update at: " - (format-time-string fmt (current-time))))) + (format-time-string fmt (current-time))))) @end lisp If you want to make sure that all dynamic blocks are always up-to-date, @@ -16185,7 +16560,7 @@ to become slow. Below are some tips on how to speed up the agenda commands. @enumerate @item Reduce the number of Org agenda files: this will reduce the slowliness caused -by accessing to a harddrive. +by accessing to a hard drive. @item Reduce the number of DONE and archived headlines: this way the agenda does not need to skip them. @@ -16712,7 +17087,7 @@ of his great @file{remember.el}. Without Sebastian, the HTML/XHTML publishing of Org would be the pitiful work of an ignorant amateur. Sebastian has pushed this part of Org onto a much higher level. He also wrote @file{org-info.js}, a Java script for displaying -webpages derived from Org using an Info-like or a folding interface with +web pages derived from Org using an Info-like or a folding interface with single-key navigation. @end table @@ -16741,9 +17116,13 @@ Eric is maintaining the Babel parts of Org. His reactivity here kept me away from worrying about possible bugs here and let me focus on other parts. @item Nicolas Goaziou -Nicolas is maintaining the consistency of the deepest parts of Org. His work -on @file{org-element.el} and @file{org-export.el} has been outstanding, and -opened the doors for many new ideas and features. +Nicolas is maintaining the consistency of the deepest parts of Org. His +work on @file{org-element.el} and @file{ox.el} has been outstanding, and +opened the doors for many new ideas and features. He rewrote many of the +old exporters to use the new export engine, and helped with documenting +this major change. More importantly (if that's possible), he has been more +than reliable during all the work done for Org 8.0, and always very +reactive on the mailing list. @item Achim Gratz Achim rewrote the building process of Org, turning some @emph{ad hoc} tools diff --git a/lisp/ob-core.el b/lisp/ob-core.el index 8994b81cc..b8d93f237 100644 --- a/lisp/ob-core.el +++ b/lisp/ob-core.el @@ -317,7 +317,7 @@ Do not query the user." (defsubst org-babel-confirm-evaluate (info) "Confirm evaluation of the code block INFO. -If the variable `org-babel-confirm-evaluate-answer-no´ is bound +If the variable `org-babel-confirm-evaluate-answer-no' is bound to a non-nil value, auto-answer with \"no\". This query can also be suppressed by setting the value of @@ -2514,9 +2514,8 @@ appropriate." (if (and (stringp cell) (not (equal cell ""))) (or (org-babel-number-p cell) (if (and (not inhibit-lisp-eval) - (member (substring cell 0 1) '("(" "'" "`" "[" "*")) - (or (not (equal (substring cell 0 1) "*")) - (equal (substring cell (- (length cell) 1)) "*"))) + (or (member (substring cell 0 1) '("(" "'" "`" "[")) + (string= cell "*this*"))) (eval (read cell)) (if (string= (substring cell 0 1) "\"") (read cell) diff --git a/lisp/ob-exp.el b/lisp/ob-exp.el index 0d98690bd..e74b80315 100644 --- a/lisp/ob-exp.el +++ b/lisp/ob-exp.el @@ -92,8 +92,8 @@ process." (defun org-babel-exp-src-block (&rest headers) "Process source block for export. -Depending on the 'export' headers argument in replace the source -code block with... +Depending on the 'export' headers argument, replace the source +code block like this: both ---- display the code and the results @@ -103,7 +103,7 @@ code ---- the default, display the code inside the block but do results - just like none only the block is run on export ensuring that it's results are present in the org-mode buffer -none ----- do not display either code or results upon export +none ---- do not display either code or results upon export Assume point is at the beginning of block's starting line." (interactive) diff --git a/lisp/ob-lob.el b/lisp/ob-lob.el index 4c894852a..40e4a2a79 100644 --- a/lisp/ob-lob.el +++ b/lisp/ob-lob.el @@ -116,6 +116,7 @@ if so then run the appropriate source block from the Library." (list (length (if (= (length (match-string 12)) 0) (match-string 2) (match-string 11))))))))) +(defvar org-babel-default-header-args:emacs-lisp) ; Defined in ob-emacs-lisp.el (defun org-babel-lob-execute (info) "Execute the lob call specified by INFO." (let* ((mkinfo (lambda (p) (list "emacs-lisp" "results" p nil nil (nth 2 info)))) diff --git a/lisp/ob-ref.el b/lisp/ob-ref.el index 7b9293609..a2814eae3 100644 --- a/lisp/ob-ref.el +++ b/lisp/ob-ref.el @@ -40,7 +40,7 @@ ;; So an example of a simple src block referencing table data in the ;; same file would be -;; #+TBLNAME: sandbox +;; #+NAME: sandbox ;; | 1 | 2 | 3 | ;; | 4 | org-babel | 6 | ;; diff --git a/lisp/org-agenda.el b/lisp/org-agenda.el index 1afdf9f3a..e72d7e94f 100644 --- a/lisp/org-agenda.el +++ b/lisp/org-agenda.el @@ -2472,12 +2472,12 @@ This undoes changes both in the agenda buffer and in the remote buffer that have been changed along." (interactive) (or org-agenda-allow-remote-undo - (error "Check the variable `org-agenda-allow-remote-undo' to activate remote undo")) + (user-error "Check the variable `org-agenda-allow-remote-undo' to activate remote undo")) (if (not (eq this-command last-command)) (setq org-agenda-undo-has-started-in nil org-agenda-pending-undo-list org-agenda-undo-list)) (if (not org-agenda-pending-undo-list) - (error "No further undo information")) + (user-error "No further undo information")) (let* ((entry (pop org-agenda-pending-undo-list)) buf line cmd rembuf) (setq cmd (pop entry) line (pop entry)) @@ -2787,7 +2787,7 @@ Pressing `<' twice means to restrict to the current subtree or region (org-let lprops '(funcall type org-match))) ((fboundp type) (org-let lprops '(funcall type org-match))) - (t (error "Invalid custom agenda command type %s" type)))) + (t (user-error "Invalid custom agenda command type %s" type)))) (org-agenda-run-series (nth 1 entry) (cddr entry)))) ((equal org-keys "C") (setq org-agenda-custom-commands org-agenda-custom-commands-orig) @@ -2818,14 +2818,14 @@ Pressing `<' twice means to restrict to the current subtree or region t t)) ((equal org-keys "L") (unless (derived-mode-p 'org-mode) - (error "This is not an Org-mode file")) + (user-error "This is not an Org-mode file")) (unless restriction (put 'org-agenda-files 'org-restrict (list bfn)) (org-call-with-arg 'org-timeline arg))) ((equal org-keys "#") (call-interactively 'org-agenda-list-stuck-projects)) ((equal org-keys "/") (call-interactively 'org-occur-in-agenda-files)) ((equal org-keys "!") (customize-variable 'org-stuck-projects)) - (t (error "Invalid agenda key")))))) + (t (user-error "Invalid agenda key")))))) (defun org-agenda-append-agenda () "Append another agenda view to the current one. @@ -2833,11 +2833,12 @@ This function allows interactive building of block agendas. Agenda views are separated by `org-agenda-block-separator'." (interactive) (unless (derived-mode-p 'org-agenda-mode) - (error "Can only append from within agenda buffer")) + (user-error "Can only append from within agenda buffer")) (let ((org-agenda-multi t)) (org-agenda) (widen) (org-agenda-finalize) + (setq buffer-read-only t) (org-agenda-fit-window-to-buffer))) (defun org-agenda-normalize-custom-commands (cmds) @@ -3040,7 +3041,7 @@ L Timeline for current buffer # List stuck projects (!=configure) (org-agenda-get-restriction-and-command prefix-descriptions)) ((equal c ?q) (error "Abort")) - (t (error "Invalid key %c" c)))))))) + (t (user-error "Invalid key %c" c)))))))) (defun org-agenda-fit-window-to-buffer () "Fit the window to the buffer size." @@ -3302,7 +3303,7 @@ If AGENDA-BUFFER-NAME, use this as the buffer name for the agenda to write." (and (file-exists-p file) (if (called-interactively-p 'any) (not (y-or-n-p (format "Overwrite existing file %s? " file)))))) - (error "Cannot write agenda to file %s" file)) + (user-error "Cannot write agenda to file %s" file)) (org-let (if nosettings nil org-agenda-exporter-settings) '(save-excursion (save-window-excursion @@ -4331,7 +4332,8 @@ items if they have an hour specification like [h]h:mm." (t n))) (defun org-agenda-span-to-ndays (span &optional start-day) - "Return ndays from SPAN, possibly starting at START-DAY." + "Return ndays from SPAN, possibly starting at START-DAY. +START-DAY is an absolute time value." (cond ((numberp span) span) ((eq span 'day) 1) ((eq span 'week) 7) @@ -7723,23 +7725,31 @@ Negative selection means regexp must not match for selection of an entry." (let* ((org-read-date-prefer-future (eval org-agenda-jump-prefer-future)) (date (org-read-date)) + (day (time-to-days (org-time-string-to-time date))) (org-agenda-sticky-orig org-agenda-sticky) (org-agenda-buffer-tmp-name (buffer-name)) (args (get-text-property (min (1- (point-max)) (point)) 'org-last-args)) (0-arg (or current-prefix-arg (car args))) (2-arg (nth 2 args)) + (with-hour-p (nth 4 org-agenda-redo-command)) (newcmd (list 'org-agenda-list 0-arg date - (org-agenda-span-to-ndays 2-arg))) + (org-agenda-span-to-ndays + 2-arg (org-time-string-to-absolute date)) + with-hour-p)) (newargs (cdr newcmd)) (inhibit-read-only t) org-agenda-sticky) (if (not (org-agenda-check-type t 'agenda)) - (error "Not available in non-agenda blocks") + (error "Not available in non-agenda views") (add-text-properties (point-min) (point-max) `(org-redo-cmd ,newcmd org-last-args ,newargs)) (org-agenda-redo) - (setq org-agenda-sticky org-agenda-sticky-orig - org-agenda-this-buffer-is-sticky org-agenda-sticky)))) + (goto-char (point-min)) + (while (not (or (= (or (get-text-property (point) 'day) 0) day) + (save-excursion (move-beginning-of-line 2) (eobp)))) + (move-beginning-of-line 2)) + (setq org-agenda-sticky org-agenda-sticky-orig + org-agenda-this-buffer-is-sticky org-agenda-sticky)))) (defun org-agenda-goto-today () "Go to today." @@ -9230,7 +9240,7 @@ ARG is passed through to `org-deadline'." "Cancel the currently running clock." (interactive "P") (unless (marker-buffer org-clock-marker) - (error "No running clock")) + (user-error "No running clock")) (org-with-remote-undo (marker-buffer org-clock-marker) (org-clock-cancel))) @@ -9258,7 +9268,7 @@ buffer, display it in another window." (setq d1 (calendar-cursor-to-date t) d2 (car calendar-mark-ring)) (setq dp1 (get-text-property (point-at-bol) 'day)) - (unless dp1 (error "No date defined in current line")) + (unless dp1 (user-error "No date defined in current line")) (setq d1 (calendar-gregorian-from-absolute dp1) d2 (and (ignore-errors (mark)) (save-excursion @@ -9282,7 +9292,7 @@ buffer, display it in another window." ((equal char ?b) (setq text (read-string "Block entry: ")) (unless (and d1 d2 (not (equal d1 d2))) - (error "No block of days selected")) + (user-error "No block of days selected")) (org-agenda-add-entry-to-org-agenda-diary-file 'block text d1 d2) (and (equal (buffer-name) org-agenda-buffer-name) (org-agenda-redo))) ((equal char ?j) @@ -9291,7 +9301,7 @@ buffer, display it in another window." (require 'org-datetree) (org-datetree-find-date-create d1) (org-reveal t)) - (t (error "Invalid selection character `%c'" char))))) + (t (user-error "Invalid selection character `%c'" char))))) (defcustom org-agenda-insert-diary-strategy 'date-tree "Where in `org-agenda-diary-file' should new entries be added? @@ -9451,11 +9461,11 @@ entries in that Org-mode file." (point (point)) (mark (or (mark t) (point)))) (unless cmd - (error "No command associated with <%c>" char)) + (user-error "No command associated with <%c>" char)) (unless (and (get-text-property point 'day) (or (not (equal ?b char)) (get-text-property mark 'day))) - (error "Don't know which date to use for diary entry")) + (user-error "Don't know which date to use for diary entry")) ;; We implement this by hacking the `calendar-cursor-to-date' function ;; and the `calendar-mark-ring' variable. Saves a lot of code. (let ((calendar-mark-ring @@ -9476,7 +9486,7 @@ entries in that Org-mode file." (org-agenda-check-type t 'agenda 'timeline) (require 'diary-lib) (unless (get-text-property (min (1- (point-max)) (point)) 'day) - (error "Don't know which date to use for the calendar command")) + (user-error "Don't know which date to use for the calendar command")) (let* ((oldf (symbol-function 'calendar-cursor-to-date)) (point (point)) (date (calendar-gregorian-from-absolute @@ -9525,7 +9535,7 @@ argument, latitude and longitude will be prompted for." (interactive) (org-agenda-check-type t 'agenda 'timeline) (let* ((day (or (get-text-property (min (1- (point-max)) (point)) 'day) - (error "Don't know which date to open in calendar"))) + (user-error "Don't know which date to open in calendar"))) (date (calendar-gregorian-from-absolute day)) (calendar-move-hook nil) (calendar-view-holidays-initially-flag nil) @@ -9548,7 +9558,7 @@ This is a command that has to be installed in `calendar-mode-map'." (let ((day (get-text-property (min (1- (point-max)) (point)) 'day)) date s) (unless day - (error "Don't know which date to convert")) + (user-error "Don't know which date to convert")) (setq date (calendar-gregorian-from-absolute day)) (setq s (concat "Gregorian: " (calendar-date-string date) "\n" @@ -9584,7 +9594,7 @@ This is a command that has to be installed in `calendar-mode-map'." (let* ((m (org-get-at-bol 'org-hd-marker)) ov) (unless (org-agenda-bulk-marked-p) - (unless m (error "Nothing to mark at point")) + (unless m (user-error "Nothing to mark at point")) (push m org-agenda-bulk-marked-entries) (setq ov (make-overlay (point-at-bol) (+ 2 (point-at-bol)))) (org-overlay-display ov (concat org-agenda-bulk-mark-char " ") @@ -9676,14 +9686,14 @@ bulk action." The prefix arg is passed through to the command if possible." (interactive "P") ;; Make sure we have markers, and only valid ones - (unless org-agenda-bulk-marked-entries (error "No entries are marked")) + (unless org-agenda-bulk-marked-entries (user-error "No entries are marked")) (mapc (lambda (m) (unless (and (markerp m) (marker-buffer m) (buffer-live-p (marker-buffer m)) (marker-position m)) - (error "Marker %s for bulk command is invalid" m))) + (user-error "Marker %s for bulk command is invalid" m))) org-agenda-bulk-marked-entries) ;; Prompt for the bulk command @@ -9762,7 +9772,7 @@ The prefix arg is passed through to the command if possible." ((equal action ?S) (if (not (org-agenda-check-type nil 'agenda 'timeline 'todo)) - (error "Can't scatter tasks in \"%s\" agenda view" org-agenda-type) + (user-error "Can't scatter tasks in \"%s\" agenda view" org-agenda-type) (let ((days (read-number (format "Scatter tasks across how many %sdays: " (if arg "week" "")) 7))) @@ -9800,7 +9810,7 @@ The prefix arg is passed through to the command if possible." (org-icompleting-read "Function: " obarray 'fboundp t nil nil))))) - (t (error "Invalid bulk action"))) + (t (user-error "Invalid bulk action"))) ;; Sort the markers, to make sure that parents are handled before children (setq entries (sort entries @@ -9856,7 +9866,7 @@ tag and (if present) the flagging note." (win (selected-window)) note heading newhead) (unless hdmarker - (error "No linked entry at point")) + (user-error "No linked entry at point")) (if (and (eq this-command last-command) (y-or-n-p "Unflag and remove any flagging note? ")) (progn @@ -9866,7 +9876,7 @@ tag and (if present) the flagging note." (message "Entry unflagged")) (setq note (org-entry-get hdmarker "THEFLAGGINGNOTE")) (unless note - (error "No flagging note")) + (user-error "No flagging note")) (org-kill-new note) (org-switch-to-buffer-other-window "*Flagging Note*") (erase-buffer) diff --git a/lisp/org-clock.el b/lisp/org-clock.el index 2a41e93f3..62ddc5e2a 100644 --- a/lisp/org-clock.el +++ b/lisp/org-clock.el @@ -514,46 +514,51 @@ of a different task.") "Hook called in task selection just before prompting the user.") (defun org-clock-select-task (&optional prompt) - "Select a task that recently was associated with clocking." + "Select a task that was recently associated with clocking." (interactive) - (let (sel-list rpl (i 0) s) - (save-window-excursion - (org-switch-to-buffer-other-window - (get-buffer-create "*Clock Task Select*")) - (erase-buffer) - (when (marker-buffer org-clock-default-task) - (insert (org-add-props "Default Task\n" nil 'face 'bold)) - (setq s (org-clock-insert-selection-line ?d org-clock-default-task)) - (push s sel-list)) - (when (marker-buffer org-clock-interrupted-task) - (insert (org-add-props "The task interrupted by starting the last one\n" nil 'face 'bold)) - (setq s (org-clock-insert-selection-line ?i org-clock-interrupted-task)) - (push s sel-list)) - (when (org-clocking-p) - (insert (org-add-props "Current Clocking Task\n" nil 'face 'bold)) - (setq s (org-clock-insert-selection-line ?c org-clock-marker)) - (push s sel-list)) - (insert (org-add-props "Recent Tasks\n" nil 'face 'bold)) - (mapc - (lambda (m) - (when (marker-buffer m) - (setq i (1+ i) - s (org-clock-insert-selection-line - (if (< i 10) - (+ i ?0) - (+ i (- ?A 10))) m)) - (if (fboundp 'int-to-char) (setf (car s) (int-to-char (car s)))) - (push s sel-list))) - org-clock-history) - (run-hooks 'org-clock-before-select-task-hook) - (org-fit-window-to-buffer) - (message (or prompt "Select task for clocking:")) - (setq rpl (read-char-exclusive)) - (cond - ((eq rpl ?q) nil) - ((eq rpl ?x) nil) - ((assoc rpl sel-list) (cdr (assoc rpl sel-list))) - (t (error "Invalid task choice %c" rpl)))))) + (let ((chl (length org-clock-history)) sel-list rpl (i 0) s) + (if (zerop chl) + (user-error "No recent clock") + (save-window-excursion + (org-switch-to-buffer-other-window + (get-buffer-create "*Clock Task Select*")) + (erase-buffer) + (when (marker-buffer org-clock-default-task) + (insert (org-add-props "Default Task\n" nil 'face 'bold)) + (setq s (org-clock-insert-selection-line ?d org-clock-default-task)) + (push s sel-list)) + (when (marker-buffer org-clock-interrupted-task) + (insert (org-add-props "The task interrupted by starting the last one\n" nil 'face 'bold)) + (setq s (org-clock-insert-selection-line ?i org-clock-interrupted-task)) + (push s sel-list)) + (when (org-clocking-p) + (insert (org-add-props "Current Clocking Task\n" nil 'face 'bold)) + (setq s (org-clock-insert-selection-line ?c org-clock-marker)) + (push s sel-list)) + (insert (org-add-props "Recent Tasks\n" nil 'face 'bold)) + (mapc + (lambda (m) + (when (marker-buffer m) + (setq i (1+ i) + s (org-clock-insert-selection-line + (if (< i 10) + (+ i ?0) + (+ i (- ?A 10))) m)) + (if (fboundp 'int-to-char) (setf (car s) (int-to-char (car s)))) + (push s sel-list))) + org-clock-history) + (run-hooks 'org-clock-before-select-task-hook) + (goto-char (point-min)) + ;; Set min-height relatively to circumvent a possible but in + ;; `fit-window-to-buffer' + (fit-window-to-buffer nil nil (if (< chl 10) chl (+ 5 chl))) + (message (or prompt "Select task for clocking:")) + (setq cursor-type nil rpl (read-char-exclusive)) + (cond + ((eq rpl ?q) nil) + ((eq rpl ?x) nil) + ((assoc rpl sel-list) (cdr (assoc rpl sel-list))) + (t (user-error "Invalid task choice %c" rpl))))))) (defun org-clock-insert-selection-line (i marker) "Insert a line for the clock selection menu. @@ -580,7 +585,7 @@ pointing to it." org-odd-levels-only) (length prefix))))))) (when (and cat task) - (insert (format "[%c] %-15s %s\n" i cat task)) + (insert (format "[%c] %-12s %s\n" i cat task)) (cons i marker))))) (defvar org-clock-task-overrun nil @@ -926,19 +931,23 @@ was started." (with-output-to-temp-buffer "*Org Clock*" (princ "Select a Clock Resolution Command: -i/q/C-g Ignore this question; the same as keeping all the idle time. +i/q Ignore this question; the same as keeping all the idle time. k/K Keep X minutes of the idle time (default is all). If this amount is less than the default, you will be clocked out that many minutes after the time that idling began, and then clocked back in at the present time. + g/G Indicate that you \"got back\" X minutes ago. This is quite different from 'k': it clocks you out from the beginning of the idle period and clock you back in X minutes ago. + s/S Subtract the idle time from the current clock. This is the same as keeping 0 minutes. + C Cancel the open timer altogether. It will be as though you never clocked in. + j/J Jump to the current clock, to make manual adjustments. For all these options, using uppercase makes your final state diff --git a/lisp/org-element.el b/lisp/org-element.el index e09d2cb52..73d0b46c9 100644 --- a/lisp/org-element.el +++ b/lisp/org-element.el @@ -3393,7 +3393,7 @@ LIMIT bounds the search. Return value is a cons cell whose CAR is `table-cell' and CDR is beginning position." - (when (looking-at "[ \t]*.*?[ \t]+|") (cons 'table-cell (point)))) + (when (looking-at "[ \t]*.*?[ \t]*|") (cons 'table-cell (point)))) ;;;; Target diff --git a/lisp/org-footnote.el b/lisp/org-footnote.el index 02af43f50..b014cd89a 100644 --- a/lisp/org-footnote.el +++ b/lisp/org-footnote.el @@ -138,13 +138,13 @@ will be used to define the footnote at the reference position." "Non-nil means define automatically new labels for footnotes. Possible values are: -nil prompt the user for each label -t create unique labels of the form [fn:1], [fn:2], ... -confirm like t, but let the user edit the created value. In particular, - the label can be removed from the minibuffer, to create +nil Prompt the user for each label. +t Create unique labels of the form [fn:1], [fn:2], etc. +confirm Like t, but let the user edit the created value. + The label can be removed from the minibuffer to create an anonymous footnote. random Automatically generate a unique, random label. -plain Automatically create plain number labels like [1]" +plain Automatically create plain number labels like [1]." :group 'org-footnote :type '(choice (const :tag "Prompt for label" nil) diff --git a/lisp/org-macs.el b/lisp/org-macs.el index 1c9b8ee26..cc837d0bb 100644 --- a/lisp/org-macs.el +++ b/lisp/org-macs.el @@ -162,18 +162,17 @@ We use a macro so that the test can happen at compilation time." (cons (if (fboundp 'with-no-warnings) 'with-no-warnings 'progn) body)) (def-edebug-spec org-no-warnings (body)) -;; FIXME: Normalize argument names -(defmacro org-with-remote-undo (_buffer &rest _body) +(defmacro org-with-remote-undo (buffer &rest body) "Execute BODY while recording undo information in two buffers." (org-with-gensyms (cline cmd buf1 buf2 undo1 undo2 c1 c2) `(let ((,cline (org-current-line)) (,cmd this-command) (,buf1 (current-buffer)) - (,buf2 ,_buffer) + (,buf2 ,buffer) (,undo1 buffer-undo-list) - (,undo2 (with-current-buffer ,_buffer buffer-undo-list)) + (,undo2 (with-current-buffer ,buffer buffer-undo-list)) ,c1 ,c2) - ,@_body + ,@body (when org-agenda-allow-remote-undo (setq ,c1 (org-verify-change-for-undo ,undo1 (with-current-buffer ,buf1 buffer-undo-list)) diff --git a/lisp/org-mobile.el b/lisp/org-mobile.el index 24a4112ac..7cdaf3445 100644 --- a/lisp/org-mobile.el +++ b/lisp/org-mobile.el @@ -1066,13 +1066,13 @@ be returned that indicates what went wrong." (t (error "Heading changed in MobileOrg and on the computer"))))) ((eq what 'addheading) - (if (org-on-heading-p) ; if false we are in top-level of file + (if (org-at-heading-p) ; if false we are in top-level of file (progn ;; Workaround a `org-insert-heading-respect-content' bug ;; which prevents correct insertion when point is invisible (org-show-subtree) (end-of-line 1) - (org-insert-heading-respect-content '(4) t) + (org-insert-heading-respect-content '(16) t) (org-demote)) (beginning-of-line) (insert "* ")) @@ -1081,7 +1081,7 @@ be returned that indicates what went wrong." ((eq what 'refile) (org-copy-subtree) (org-with-point-at (org-mobile-locate-entry new) - (if (org-on-heading-p) ; if false we are in top-level of file + (if (org-at-heading-p) ; if false we are in top-level of file (progn (setq level (org-get-valid-level (funcall outline-level) 1)) (org-end-of-subtree t t) diff --git a/lisp/org-mouse.el b/lisp/org-mouse.el index fac43e4bc..fbdc7fb85 100644 --- a/lisp/org-mouse.el +++ b/lisp/org-mouse.el @@ -1056,7 +1056,7 @@ This means, between the beginning of line and the point." ["Convert" org-agenda-convert-date (org-agenda-check-type nil 'agenda 'timeline)] "--" - ["Create iCalendar file" org-export-icalendar-combine-agenda-files t]) + ["Create iCalendar file" org-icalendar-combine-agenda-files t]) "--" ["Day View" org-agenda-day-view :active (org-agenda-check-type nil 'agenda) diff --git a/lisp/org-table.el b/lisp/org-table.el index bdf4ad869..441870479 100644 --- a/lisp/org-table.el +++ b/lisp/org-table.el @@ -1118,7 +1118,7 @@ copying. In the case of a timestamp, increment by one day." (interactive "p") (let* ((colpos (org-table-current-column)) (col (current-column)) - (field (org-table-get-field)) + (field (save-excursion (org-table-get-field))) (non-empty (string-match "[^ \t]" field)) (beg (org-table-begin)) (orig-n n) @@ -2929,7 +2929,10 @@ list, 'literal is for the format specifier L." (if lispp (if (eq lispp 'literal) elements - (prin1-to-string (if numbers (string-to-number elements) elements))) + (if (and (eq elements "") (not keep-empty)) + "" + (prin1-to-string + (if numbers (string-to-number elements) elements)))) (if (string-match "\\S-" elements) (progn (when numbers (setq elements (number-to-string @@ -2942,7 +2945,7 @@ list, 'literal is for the format specifier L." (delq nil (mapcar (lambda (x) (if (string-match "\\S-" x) x nil)) elements)))) - (setq elements (or elements '(""))) + (setq elements (or elements '())) ; if delq returns nil then we need '() (if lispp (mapconcat (lambda (x) @@ -4963,11 +4966,11 @@ it here: http://gnuvola.org/software/j/aa2u/ascii-art-to-unicode.el." (defun org-table-get-remote-range (name-or-id form) "Get a field value or a list of values in a range from table at ID. -NAME-OR-ID may be the name of a table in the current file as set by -a \"#+TBLNAME:\" directive. The first table following this line +NAME-OR-ID may be the name of a table in the current file as set +by a \"#+NAME:\" directive. The first table following this line will then be used. Alternatively, it may be an ID referring to -any entry, also in a different file. In this case, the first table -in that entry will be referenced. +any entry, also in a different file. In this case, the first +table in that entry will be referenced. FORM is a field or range descriptor like \"@2$3\" or \"B3\" or \"@I$2..@II$2\". All the references must be absolute, not relative. diff --git a/lisp/org.el b/lisp/org.el index 14ca84aee..bbbeb7afe 100644 --- a/lisp/org.el +++ b/lisp/org.el @@ -1340,9 +1340,8 @@ default the value to be used for all contexts not explicitly (defcustom org-insert-heading-respect-content nil "Non-nil means insert new headings after the current subtree. When nil, the new heading is created directly after the current line. -The commands \\[org-insert-heading-respect-content] and -\\[org-insert-todo-heading-respect-content] turn this variable on -for the duration of the command." +The commands \\[org-insert-heading-respect-content] and \\[org-insert-todo-heading-respect-content] turn +this variable on for the duration of the command." :group 'org-structure :type 'boolean) @@ -4011,7 +4010,7 @@ After a match, the match groups contain these elements: (body1 (concat body "*?")) (markers (mapconcat 'car org-emphasis-alist "")) (vmarkers (mapconcat - (lambda (x) (if (eq (nth 4 x) 'verbatim) (car x) "")) + (lambda (x) (if (eq (nth 2 x) 'verbatim) (car x) "")) org-emphasis-alist ""))) ;; make sure special characters appear at the right position in the class (if (string-match "\\^" markers) @@ -4051,7 +4050,10 @@ After a match, the match groups contain these elements: "\\3\\)" "\\([" post "]\\|$\\)"))))) -(defcustom org-emphasis-regexp-components +;; This used to be a defcustom (Org <8.0) but allowing the users to +;; set this option proved cumbersome. See this message/thread: +;; http://article.gmane.org/gmane.emacs.orgmode/68681 +(defvar org-emphasis-regexp-components '(" \t('\"{" "- \t.,:!?;'\")}\\" " \t\r\n,\"'" "." 1) "Components used to build the regular expression for emphasis. This is a list with five entries. Terminology: In an emphasis string @@ -4067,43 +4069,32 @@ body-regexp A regexp like \".\" to match a body character. Don't use non-shy groups here, and don't allow newline here. newline The maximum number of newlines allowed in an emphasis exp. -Use customize to modify this, or restart Emacs after changing it." - :group 'org-appearance - :set 'org-set-emph-re - :type '(list - (sexp :tag "Allowed chars in pre ") - (sexp :tag "Allowed chars in post ") - (sexp :tag "Forbidden chars in border ") - (sexp :tag "Regexp for body ") - (integer :tag "number of newlines allowed") - (option (boolean :tag "Please ignore this button")))) +You need to reload Org or to restart Emacs after customizing this.") (defcustom org-emphasis-alist - `(("*" bold "" "") - ("/" italic "" "") - ("_" underline "" "") - ("=" org-code "" "" verbatim) - ("~" org-verbatim "" "" verbatim) - ("+" ,(if (featurep 'xemacs) 'org-table '(:strike-through t)) - "" "") - ) - "Special syntax for emphasized text. -Text starting and ending with a special character will be emphasized, for -example *bold*, _underlined_ and /italic/. This variable sets the marker -characters, the face to be used by font-lock for highlighting in Org-mode -Emacs buffers, and the HTML tags to be used for this. -For LaTeX export, see the variable `org-export-latex-emphasis-alist'. -Use customize to modify this, or restart Emacs after changing it." + `(("*" bold) + ("/" italic) + ("_" underline) + ("=" org-code verbatim) + ("~" org-verbatim verbatim) + ("+" ,(if (featurep 'xemacs) 'org-table '(:strike-through t)))) + "Alist of characters and faces to emphasize text. +Text starting and ending with a special character will be emphasized, +for example *bold*, _underlined_ and /italic/. This variable sets the +marker characters and the face to be used by font-lock for highlighting +in Org-mode Emacs buffers. + +You need to reload Org or to restart Emacs after customizing this." :group 'org-appearance :set 'org-set-emph-re + :version "24.4" + :package-version '(Org . "8.0") :type '(repeat (list (string :tag "Marker character") (choice (face :tag "Font-lock-face") (plist :tag "Face property list")) - (string :tag "HTML start tag") - (string :tag "HTML end tag") (option (const verbatim))))) (defvar org-protecting-blocks @@ -5145,10 +5136,9 @@ Support for group tags is controlled by the option "Return the contents of FILE, as a string." (if (or (not file) (not (file-readable-p file))) - (if (not noerror) - (error "Cannot read file \"%s\"" file) - (message "Cannot read file \"%s\"" file) - (sit-for 3)) + (if noerror + (message "Cannot read file \"%s\"" file) + (error "Cannot read file \"%s\"" file)) (with-temp-buffer (insert-file-contents file) (buffer-string)))) @@ -5687,36 +5677,27 @@ The time stamps may be either active or inactive.") If there is an active region, change that region to a new emphasis. If there is no region, just insert the marker characters and position the cursor between them. -CHAR should be either the marker character, or the first character of the -HTML tag associated with that emphasis. If CHAR is a space, the means -to remove the emphasis of the selected region. -If char is not given (for example in an interactive call) it -will be prompted for." +CHAR should be the marker character. If it is a space, it means to +remove the emphasis of the selected region. +If CHAR is not given (for example in an interactive call) it will be +prompted for." (interactive) - (let ((eal org-emphasis-alist) e det - (erc org-emphasis-regexp-components) + (let ((erc org-emphasis-regexp-components) (prompt "") - (string "") beg end move tag c s) + (string "") beg end move c s) (if (org-region-active-p) (setq beg (region-beginning) end (region-end) string (buffer-substring beg end)) (setq move t)) - (while (setq e (pop eal)) - (setq tag (car (org-split-string (nth 2 e) "[ <>/]+")) - c (aref tag 0)) - (push (cons c (string-to-char (car e))) det) - (setq prompt (concat prompt (format " [%s%c]%s" (car e) c - (substring tag 1))))) - (setq det (nreverse det)) (unless char - (message "%s" (concat "Emphasis marker or tag:" prompt)) + (message "Emphasis marker or tag: [%s]" + (mapconcat (lambda(e) (car e)) org-emphasis-alist "")) (setq char (read-char-exclusive))) - (setq char (or (cdr (assoc char det)) char)) (if (equal char ?\ ) (setq s "" move nil) (unless (assoc (char-to-string char) org-emphasis-alist) - (error "No such emphasis marker: \"%c\"" char)) + (user-error "No such emphasis marker: \"%c\"" char)) (setq s (char-to-string char))) (while (and (> (length string) 1) (equal (substring string 0 1) (substring string -1)) @@ -7522,11 +7503,13 @@ This is important for non-interactive uses of the command." (if (org-previous-line-empty-p) "" "\n") (if (org-in-src-block-p) ",* " "* ")) (run-hooks 'org-insert-heading-hook)) - ((or arg (not (org-insert-item - (save-excursion - (beginning-of-line) - (looking-at org-list-full-item-re) - (match-string 3))))) + ((or arg + org-insert-heading-respect-content + (not (org-insert-item + (save-excursion + (beginning-of-line) + (looking-at org-list-full-item-re) + (match-string 3))))) (let (begn endn) (when (org-buffer-narrowed-p) (setq begn (point-min) endn (point-max)) @@ -7537,6 +7520,8 @@ This is important for non-interactive uses of the command." (or (not (null arg)) org-insert-heading-respect-content)) (level nil) (on-heading (org-at-heading-p)) + (on-empty-line + (save-excursion (beginning-of-line 1) (looking-at "^\\s-*$"))) (head (save-excursion (condition-case nil (progn @@ -7589,6 +7574,11 @@ This is important for non-interactive uses of the command." tags pos) (cond ;; Insert a new line, possibly at end of parent subtree + ((and (not arg) (not on-heading) (not on-empty-line) + (not (save-excursion + (beginning-of-line 1) + (looking-at org-list-full-item-re)))) + (beginning-of-line 1)) (org-insert-heading-respect-content (if (not eops) (progn @@ -7638,7 +7628,9 @@ This is important for non-interactive uses of the command." (org-set-tags nil 'align)))) (t (or split (end-of-line 1)) - (newline (if blank 2 1)))))) + (newline (cond ((and blank (not on-empty-line)) 2) + (blank 1) + (on-empty-line 0) (t 1))))))) (insert head) (just-one-space) (setq pos (point)) (end-of-line 1) @@ -10122,23 +10114,6 @@ from." (org-add-props s nil 'org-attr attr)) s)) -(defun org-extract-attributes-from-string (tag) - (let (key value attr) - (while (string-match "\\([a-zA-Z]+\\)=\"\\([^\"]*\\)\"\\s-?" tag) - (setq key (match-string 1 tag) value (match-string 2 tag) - tag (replace-match "" t t tag) - attr (plist-put attr (intern key) value))) - (cons tag attr))) - -(defun org-attributes-to-string (plist) - "Format a property list into an HTML attribute list." - (let ((s "") key value) - (while plist - (setq key (pop plist) value (pop plist)) - (and value - (setq s (concat s " " (symbol-name key) "=\"" value "\"")))) - s)) - ;;; Opening/following a link (defvar org-link-search-failed nil) @@ -12250,9 +12225,10 @@ For calling through lisp, arg is also interpreted in the following way: (nth 2 (assoc this org-todo-log-states)))) (if (and (eq dolog 'note) (eq org-inhibit-logging 'note)) (setq dolog 'time)) - (when (and org-state - (member org-state org-not-done-keywords) - (not (member this org-not-done-keywords))) + (when (or (not org-state) + (and org-state + (member org-state org-not-done-keywords) + (not (member this org-not-done-keywords)))) ;; This is now a todo state and was not one before ;; If there was a CLOSED time stamp, get rid of it. (org-add-planning-info nil nil 'closed)) @@ -13242,7 +13218,7 @@ EXTRA is additional text that will be inserted into the notes buffer." (org-switch-to-buffer-other-window "*Org Note*") (erase-buffer) (if (memq org-log-note-how '(time state)) - (let (current-prefix-arg) (org-store-log-note)) + (let (current-prefix-arg) (org-store-log-note)) (let ((org-inhibit-startup t)) (org-mode)) (insert (format "# Insert note for %s. # Finish with C-c C-c, or cancel with C-c C-k.\n\n" @@ -13343,12 +13319,19 @@ EXTRA is additional text that will be inserted into the notes buffer." (insert (pop lines)))) (message "Note stored") (org-back-to-heading t) - (org-cycle-hide-drawers 'children)))))) - (set-window-configuration org-log-note-window-configuration) - (with-current-buffer (marker-buffer org-log-note-return-to) - (goto-char org-log-note-return-to)) - (move-marker org-log-note-return-to nil) - (and org-log-post-message (message "%s" org-log-post-message))) + (org-cycle-hide-drawers 'children)) + ;; Fix `buffer-undo-list' when `org-store-log-note' is called + ;; from within `org-add-log-note' because `buffer-undo-list' + ;; is then modified outside of `org-with-remote-undo'. + (when (eq this-command 'org-agenda-todo) + (setcdr buffer-undo-list (cddr buffer-undo-list))))))) + ;; Don't add undo information when called from `org-agenda-todo' + (let ((buffer-undo-list (eq this-command 'org-agenda-todo))) + (set-window-configuration org-log-note-window-configuration) + (with-current-buffer (marker-buffer org-log-note-return-to) + (goto-char org-log-note-return-to)) + (move-marker org-log-note-return-to nil) + (and org-log-post-message (message "%s" org-log-post-message)))) (defun org-remove-empty-drawer-at (drawer pos) "Remove an empty drawer DRAWER at position POS. @@ -13969,9 +13952,12 @@ See also `org-scan-tags'. (unless (boundp 'todo-only) (error "`org-make-tags-matcher' expects todo-only to be scoped in")) (unless match - ;; Get a new match request, with completion + ;; Get a new match request, with completion against the global + ;; tags table and the local tags in current buffer (let ((org-last-tags-completion-table - (org-global-tags-completion-table))) + (org-uniquify + (delq nil (append (org-get-buffer-tags) + (org-global-tags-completion-table)))))) (setq match (org-completing-read-no-i "Match: " 'org-tags-completion-function nil nil nil 'org-tags-history)))) @@ -14098,14 +14084,14 @@ This replaces every group tag in MATCH with a regexp tag search. For example, a group tag \"Work\" defined as { Work : Lab Conf } will be replaced like this: - Work => {\(?:Work\|Lab\|Conf\} - +Work => +{\(?:Work\|Lab\|Conf\} - -Work => -{\(?:Work\|Lab\|Conf\} + Work => {\\(?:Work\\|Lab\\|Conf\\)} + +Work => +{\\(?:Work\\|Lab\\|Conf\\)} + -Work => -{\\(?:Work\\|Lab\\|Conf\\)} Replacing by a regexp preserves the structure of the match. E.g., this expansion - Work|Home => {\(?:Work\|Lab\|Conf\}|Home + Work|Home => {\\(?:Work\\|Lab\\|Conf\\}|Home will match anything tagged with \"Lab\" and \"Home\", or tagged with \"Conf\" and \"Home\" or tagged with \"Work\" and \"home\". @@ -14120,23 +14106,26 @@ When DOWNCASE is non-nil, expand downcased TAGS." (stable org-mode-syntax-table) (tal (or org-tag-groups-alist-for-agenda org-tag-groups-alist)) - (tal (if downcased (mapcar (lambda(tg) (mapcar 'downcase tg)) tal) tal)) + (tal (if downcased + (mapcar (lambda(tg) (mapcar 'downcase tg)) tal) tal)) (tml (mapcar 'car tal)) (rtnmatch match) rpl) ;; @ and _ are allowed as word-components in tags (modify-syntax-entry ?@ "w" stable) (modify-syntax-entry ?_ "w" stable) - (while (and tml (string-match - (concat "\\(?1:[+-]?\\)\\(?2:\\<" (regexp-opt tml) "\\>\\)") - rtnmatch)) + (while (and tml + (string-match + (concat "\\(?1:[+-]?\\)\\(?2:\\<" + (regexp-opt tml) "\\>\\)") rtnmatch)) (let* ((dir (match-string 1 rtnmatch)) (tag (match-string 2 rtnmatch)) (tag (if downcased (downcase tag) tag))) (setq tml (delete tag tml)) - (setq rpl (append (org-uniquify rpl) (assoc tag tal))) - (setq rtnmatch - (replace-match - (concat dir "{" (regexp-opt rpl) "}") t t rtnmatch)))) + (when (not (get-text-property 0 'grouptag (match-string 2 rtnmatch))) + (setq rpl (append (org-uniquify rpl) (assoc tag tal))) + (setq rpl (concat dir "{\\<" (regexp-opt rpl) "\\>}")) + (if (stringp rpl) (org-add-props rpl '(grouptag t))) + (setq rtnmatch (replace-match rpl t t rtnmatch))))) (if single-as-list (or (reverse rpl) (list rtnmatch)) rtnmatch)) @@ -14487,7 +14476,9 @@ This works in the agenda, and also in an org-mode buffer." (list (region-beginning) (region-end) (let ((org-last-tags-completion-table (if (derived-mode-p 'org-mode) - (org-get-buffer-tags) + (org-uniquify + (delq nil (append (org-get-buffer-tags) + (org-global-tags-completion-table)))) (org-global-tags-completion-table)))) (org-icompleting-read "Tag: " 'org-tags-completion-function nil nil nil @@ -17464,7 +17455,9 @@ The format is determined by `org-time-clocksum-format', `org-time-clocksum-use-fractional' and `org-time-clocksum-fractional-format' and `org-time-clocksum-use-effort-durations'." - (let ((clocksum "") h d w mo y fmt n) + (let ((clocksum "") + (m (round m)) ; Don't allow fractions of minutes + h d w mo y fmt n) (setq h (if org-time-clocksum-use-effort-durations (cdr (assoc "h" org-effort-durations)) 60) d (if org-time-clocksum-use-effort-durations @@ -21594,14 +21587,12 @@ for the search purpose." "Return the reverse of STRING." (apply 'string (reverse (string-to-list string)))) -(defun org-uniquify (list) - "Remove duplicate elements from LIST." - (let (res) - (mapc (lambda (x) (add-to-list 'res x 'append)) list) - res)) +(defsubst org-uniquify (list) + "Non-destructively remove duplicate elements from LIST." + (let ((res (copy-seq list))) (delete-dups res))) (defun org-uniquify-alist (alist) - "Merge duplicate elements of an alist. + "Merge duplicate elements of ALIST. For example, in this alist: @@ -23029,8 +23020,8 @@ non-nil it will also look at invisible ones." 're-search-forward)) (count (if arg (abs arg) 1)) (result (point))) - (forward-char (if (and arg (< arg 0)) -1 1)) - (while (and (> count 0) + (while (and (prog1 (> count 0) + (forward-char (if (and arg (< arg 0)) -1 1))) (funcall f org-outline-regexp-bol nil 'move)) (let ((l (- (match-end 0) (match-beginning 0) 1))) (cond ((< l level) (setq count 0)) diff --git a/lisp/ox-html.el b/lisp/ox-html.el index 39b0ec96c..0ad3dc333 100644 --- a/lisp/ox-html.el +++ b/lisp/ox-html.el @@ -112,6 +112,7 @@ (org-open-file (org-html-export-to-html nil s v b))))))) :options-alist '((:html-extension nil nil org-html-extension) + (:html-link-org-as-html nil nil org-html-link-org-files-as-html) (:html-doctype "HTML_DOCTYPE" nil org-html-doctype) (:html-container "HTML_CONTAINER" nil org-html-container-element) (:html-link-home "HTML_LINK_HOME" nil org-html-link-home) @@ -123,7 +124,10 @@ (:html-head-extra "HTML_HEAD_EXTRA" nil org-html-head-extra newline) (:html-head-include-default-style "HTML_INCLUDE_STYLE" nil org-html-head-include-default-style newline) (:html-head-include-scripts "HTML_INCLUDE_SCRIPTS" nil org-html-head-include-scripts newline) - (:html-table-tag nil nil org-html-table-tag) + (:html-table-attributes nil nil org-html-table-default-attributes) + (:html-table-row-tags nil nil org-html-table-row-tags) + (:html-xml-declaration nil nil org-html-xml-declaration) + (:html-inline-images nil nil org-html-inline-images) (:infojs-opt "INFOJS_OPT" nil nil) ;; Redefine regular options. (:creator "CREATOR" nil org-html-creator-string) @@ -135,10 +139,6 @@ (defvar org-html-format-table-no-css) (defvar htmlize-buffer-places) ; from htmlize.el -(defvar org-html--timestamp-format "%Y-%m-%d %a %H:%M" - "FORMAT used by `format-time-string' for timestamps in -preamble, postamble and metadata.") - (defvar org-html--pre/postamble-class "status" "CSS class used for pre/postamble") @@ -695,16 +695,9 @@ be linked only." ("http" . "\\.\\(jpeg\\|jpg\\|png\\|gif\\|svg\\)\\'") ("https" . "\\.\\(jpeg\\|jpg\\|png\\|gif\\|svg\\)\\'")) "Rules characterizing image files that can be inlined into HTML. - A rule consists in an association whose key is the type of link to consider, and value is a regexp that will be matched against -link's path. - -Note that, by default, the image extension *actually* allowed -depend on the way the HTML file is processed. When used with -pdflatex, pdf, jpg and png images are OK. When processing -through dvi to Postscript, only ps and eps are allowed. The -default we use here encompasses both." +link's path." :group 'org-export-html :version "24.4" :package-version '(Org . "8.0") @@ -750,13 +743,16 @@ in all modes you want. Then, use the command ;;;; Table -(defcustom org-html-table-tag - "" - "The HTML tag that is used to start a table. -This must be a
tag, but you may change the options like -borders and spacing." +(defcustom org-html-table-default-attributes + '(:border "2" :cellspacing "0" :cellpadding "6" :rules "groups" :frame "hsides") + "Default attributes and values which will be used in table tags. +This is a plist where attributes are symbols, starting with +colons, and values are strings." :group 'org-export-html - :type 'string) + :version "24.4" + :package-version '(Org . "8.0") + :type '(plist :key-type (symbol :tag "Property") + :value-type (string :tag "Value"))) (defcustom org-html-table-header-tags '("") "The opening tag for table header fields. @@ -786,6 +782,7 @@ evaluated for each row in order to construct the table row tags. During evaluation, these variables will be dynamically bound so that you can reuse them: + `row-number': row number (0 is the first row) `rowgroup-number': group number of current row `start-rowgroup-p': non-nil means the row starts a group `end-rowgroup-p': non-nil means the row ends a group @@ -794,11 +791,17 @@ you can reuse them: For example: - (setq org-html-table-row-tags - (cons '(cond (top-row-p \"\") - (bottom-row-p \"\")))) +\(setq org-html-table-row-tags + (cons '(cond (top-row-p \"\") + (bottom-row-p \"\") + (t (if (= (mod row-number 2) 1) + \"\" + \"\"))) + \"\")) -will use the \"tr-top\" and \"tr-bottom\" classes for top and bottom row." +will use the \"tr-top\" and \"tr-bottom\" classes for the top row +and the bottom row, and otherwise alternate between \"tr-odd\" and +\"tr-even\" for odd and even rows." :group 'org-export-html :type '(cons (choice :tag "Opening tag" @@ -914,6 +917,14 @@ org-info.js for your website." (list :tag "Postamble" (const :format "" postamble) (string :tag " id") (string :tag "element")))) +(defcustom org-html-metadata-timestamp-format "%Y-%m-%d %a %H:%M" + "Format used for timestamps in preamble, postamble and metadata. +See `format-time-string' for more information on its components." + :group 'org-export-html + :version "24.4" + :package-version '(Org . "8.0") + :type 'string) + ;;;; Template :: Mathjax (defcustom org-html-mathjax-options @@ -1228,6 +1239,19 @@ CSS classes, then this prefix can be very useful." ;;; Internal Functions +(defun org-html--make-attribute-string (attributes) + "Return a list of attributes, as a string. +ATTRIBUTES is a plist where values are either strings or nil. An +attributes with a nil value will be omitted from the result." + (let (output) + (dolist (item attributes (mapconcat 'identity (nreverse output) " ")) + (cond ((null item) (pop output)) + ((symbolp item) (push (substring (symbol-name item) 1) output)) + (t (let ((key (car output)) + (value (replace-regexp-in-string + "\"" """ (org-html-encode-plain-text item)))) + (setcar output (format "%s=\"%s\"" key value)))))))) + (defun org-html-format-inline-image (src &optional caption label attr standalone-p) "Format an inline image from SRC. @@ -1287,32 +1311,6 @@ ELEMENT is either a src block or an example block." ;;;; Table -(defun org-html-splice-attributes (tag attributes) - "Return a HTML TAG edited wrt ATTRIBUTES." - (if (not attributes) - tag - (let (oldatt newatt) - (setq oldatt (org-extract-attributes-from-string tag) - tag (pop oldatt) - newatt (cdr (org-extract-attributes-from-string attributes))) - (while newatt - (setq oldatt (plist-put oldatt (pop newatt) (pop newatt)))) - (if (string-match ">" tag) - (setq tag - (replace-match (concat (org-attributes-to-string oldatt) ">") - t t tag))) - tag))) - -(defun org-export-splice-style (style extra) - "Return STYLE updated wrt EXTRA." - (if (and (stringp extra) - (string-match "\\S-" extra) - (string-match "" style)) - (concat (substring style 0 (match-beginning 0)) - "\n" extra "\n" - (substring style (match-beginning 0))) - style)) - (defun org-html-htmlize-region-for-paste (beg end) "Convert the region between BEG and END to HTML, using htmlize.el. This is much like `htmlize-region-for-paste', only that it uses @@ -1434,7 +1432,7 @@ INFO is a plist used as a communication channel." (format (when :time-stamp-file (format-time-string - (concat "\n")))) + (concat "\n")))) (format "\n" (or (and org-html-coding-system @@ -1502,7 +1500,7 @@ INFO is a plist used as a communication channel." used in the preamble or postamble." `((?t . ,(org-export-data (plist-get info :title) info)) (?d . ,(org-export-data (org-export-get-date info) info)) - (?T . ,(format-time-string org-html--timestamp-format)) + (?T . ,(format-time-string org-html-metadata-timestamp-format)) (?a . ,(org-export-data (plist-get info :author) info)) (?e . ,(mapconcat (lambda (e) @@ -1511,7 +1509,7 @@ used in the preamble or postamble." ", ")) (?c . ,(plist-get info :creator)) (?C . ,(let ((file (plist-get info :input-file))) - (format-time-string org-html--timestamp-format + (format-time-string org-html-metadata-timestamp-format (if file (nth 5 (file-attributes file)) (current-time))))) (?v . ,(or org-html-validation-link "")))) @@ -1554,10 +1552,9 @@ communication channel." (format "

%s: %s

\n" (org-html--translate "Created" info) - (format-time-string org-html--timestamp-format))) + (format-time-string org-html-metadata-timestamp-format))) (when (plist-get info :with-creator) - (format "

%s

\n" - creator)) + (format "

%s

\n" creator)) (format "

%s

\n" validation-link)))) (t (format-spec @@ -2194,7 +2191,7 @@ holding contextual information." "div") (format "outline-container-%s" (or (org-element-property :CUSTOM_ID headline) - section-number)) + (concat "sec-" section-number))) (concat (format "outline-%d" level1) (and extra-class " ") extra-class) (format "\n%s%s\n" @@ -2418,6 +2415,7 @@ CONTENTS is nil. INFO is a plist holding contextual information." (defun org-html-link--inline-image (link desc info) "Return HTML code for an inline image. + LINK is the link pointing to the inline image. INFO is a plist used as a communication channel. @@ -2433,20 +2431,12 @@ Inline images can have these attributes: (t raw-path))) (parent (org-export-get-parent-element link)) (caption (org-export-data (org-export-get-caption parent) info)) - (label (org-element-property :name parent)) - (attrs (org-export-read-attribute :attr_html parent)) - (alt (plist-get attrs :alt)) - (width (plist-get attrs :width)) - (height (plist-get attrs :height)) - (options (plist-get attrs :options))) + (label (org-element-property :name parent))) ;; Return proper string, depending on DISPOSITION. (org-html-format-inline-image path caption label - (mapconcat 'identity - (delq nil (list (if width (format "width=\"%s\"" width)) - (if alt (format "alt=\"%s\"" alt)) - (if height (format "height=\"%s\"" height)) - options)) " ") + (org-html--make-attribute-string + (org-export-read-attribute :attr_html parent)) (org-html-standalone-image-p link info)))) (defvar org-html-standalone-image-predicate) @@ -2547,20 +2537,19 @@ INFO is a plist holding contextual information. See numbers "-")))))) (t raw-path)))) (t raw-path))) - attributes protocol) - ;; Extract attributes from parent's paragraph. HACK: Only do this - ;; for the first link in parent. This is needed as long as - ;; attributes cannot be set on a per link basis. - (and (setq attributes - (let ((parent (org-export-get-parent-element link))) - (if (not (eq (org-element-map parent 'link 'identity info t) - link)) - "" - (let ((att (org-export-read-attribute :attr_html parent :options))) - (unless (and desc att (string-match (regexp-quote att) desc)) - (or att "")))))) - (unless (string= attributes "") - (setq attributes (concat " " attributes)))) + ;; Extract attributes from parent's paragraph. HACK: Only do + ;; this for the first link in parent. This is needed as long + ;; as attributes cannot be set on a per link basis. + (attributes + (let ((parent (org-export-get-parent-element link))) + (if (not (eq (org-element-map parent 'link 'identity info t) link)) + "" + (let ((att (org-html--make-attribute-string + (org-export-read-attribute :attr_html parent)))) + (cond ((not (org-string-nw-p att)) "") + ((and desc (string-match (regexp-quote att) desc)) "") + (t (concat " " att))))))) + protocol) (cond ;; Image file. ((and (or (eq t org-html-inline-images) @@ -2964,6 +2953,7 @@ communication channel." ;; borders of the current row. (when (eq (org-element-property :type table-row) 'standard) (let* ((rowgroup-number (org-export-table-row-group table-row info)) + (row-number (org-export-table-row-number table-row info)) (start-rowgroup-p (org-export-table-row-starts-rowgroup-p table-row info)) (end-rowgroup-p @@ -3040,7 +3030,11 @@ contextual information." (let* ((label (org-element-property :name table)) (caption (org-export-get-caption table)) (attributes - (org-export-read-attribute :attr_html table :options)) + (org-html--make-attribute-string + (org-combine-plists + (and label (list :id (org-export-solidify-link-text label))) + (plist-get info :html-table-attributes) + (org-export-read-attribute :attr_html table)))) (alignspec (if (and (boundp 'org-html-format-table-no-css) org-html-format-table-no-css) @@ -3063,20 +3057,9 @@ contextual information." (when (org-export-table-cell-ends-colgroup-p table-cell info) "\n")))) - (org-html-table-first-row-data-cells table info) "\n")))) - (table-attributes - (let ((table-tag (plist-get info :html-table-tag))) - (concat - (and (string-match "" table-tag) - (match-string 1 table-tag)) - (and label (format " id=\"%s\"" - (org-export-solidify-link-text label))) - (unless (string= attributes "") - (concat " " attributes)))))) - ;; Remove last blank line. - (setq contents (substring contents 0 -1)) - (format "\n%s\n%s\n%s\n
" . "
" - table-attributes + (org-html-table-first-row-data-cells table info) "\n"))))) + (format "\n%s\n%s\n%s" + (if (equal attributes "") "" (concat " " attributes)) (if (not caption) "" (format "%s" (org-export-data caption info))) diff --git a/lisp/ox-icalendar.el b/lisp/ox-icalendar.el index 00055d25e..49299b014 100644 --- a/lisp/ox-icalendar.el +++ b/lisp/ox-icalendar.el @@ -897,7 +897,8 @@ The file is stored under the name chosen in "Export current agenda view to an iCalendar FILE. This function assumes major mode for current buffer is `org-agenda-mode'." - (let ((org-icalendar-combined-agenda-file file) + (let (org-export-babel-evaluate ; Don't evaluate Babel block + (org-icalendar-combined-agenda-file file) (marker-list ;; Collect the markers pointing to entries in the current ;; agenda buffer. @@ -971,7 +972,7 @@ files to build the calendar from." (lambda (m-list dummy) (mapc (lambda (m) (org-entry-put - m "ICALENDAR_MARK" "t")) + m "ICALENDAR-MARK" "t")) m-list)) (sort marks '>)) org-export-before-processing-hook))) diff --git a/lisp/ox-latex.el b/lisp/ox-latex.el index 9c0469568..5975ce2ba 100644 --- a/lisp/ox-latex.el +++ b/lisp/ox-latex.el @@ -294,13 +294,13 @@ ("\\subsection{%s}" . "\\subsection*{%s}") ("\\subsubsection{%s}" . "\\subsubsection*{%s}"))) "Alist of LaTeX classes and associated header and structure. -If #+LaTeX_CLASS is set in the buffer, use its value and the +If #+LATEX_CLASS is set in the buffer, use its value and the associated information. Here is the structure of each cell: \(class-name header-string - \(numbered-section . unnumbered-section\) - ...\) + \(numbered-section . unnumbered-section) + ...) The header string ----------------- @@ -315,7 +315,8 @@ following commands will be added: `org-latex-packages-alist'. Thus, your header definitions should avoid to also request these packages. -- Lines specified via \"#+LaTeX_HEADER:\" +- Lines specified via \"#+LATEX_HEADER:\" and + \"#+LATEX_HEADER_EXTRA:\" keywords. 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 @@ -326,8 +327,8 @@ macro-like placeholders. [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 + [EXTRA] the stuff from #+LATEX_HEADER + [NO-EXTRA] do not include #+LATEX_HEADER stuff So a header like @@ -338,9 +339,9 @@ So a header like [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-latex-packages-alist'. +#+LATEX_HEADER and #+LATEX_HEADER_EXTRA lines, then have a call +to \\providecommand, and then place \\usepackage commands based +on the content of `org-latex-packages-alist'. If your header, `org-latex-default-packages-alist' or `org-latex-packages-alist' inserts @@ -357,14 +358,14 @@ following 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. -Instead of a cons cell \(numbered . unnumbered\), you can also +Instead of a cons cell (numbered . unnumbered), you can also provide a list of 2 or 4 elements, - \(numbered-open numbered-close\) + \(numbered-open numbered-close) or - \(numbered-open numbered-close unnumbered-open unnumbered-close\) + \(numbered-open numbered-close unnumbered-open unnumbered-close) providing opening and closing strings for a LaTeX environment that should represent the document section. The opening clause @@ -372,7 +373,7 @@ 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 a predicate +parameters, the (reduced) level of the headline, and a predicate non-nil when the headline should be numbered. It must return a format string in which the section title will be added." :group 'org-export-latex @@ -1814,7 +1815,6 @@ used as a communication channel." ;; ATTR_LATEX line, and also via default variables. (width (cond ((plist-get attr :width)) ((plist-get attr :height) "") - ((eq float 'figure) "0.7\\textwidth") ((eq float 'wrap) "0.48\\textwidth") (t org-latex-image-default-width))) (height (cond ((plist-get attr :height)) @@ -2561,7 +2561,7 @@ This function assumes TABLE has `org' as its `:type' property and `inline-math' or `math' as its `:mode' attribute.." (let* ((caption (org-latex--caption/label-string table info)) (attr (org-export-read-attribute :attr_latex table)) - (inlinep (eq (plist-get attr :mode) 'inline-math)) + (inlinep (equal (plist-get attr :mode) "inline-math")) (env (or (plist-get attr :environment) org-latex-default-table-environment)) (contents diff --git a/lisp/ox-odt.el b/lisp/ox-odt.el index 394530c2d..7e1390ef0 100644 --- a/lisp/ox-odt.el +++ b/lisp/ox-odt.el @@ -2760,6 +2760,8 @@ INFO is a plist holding contextual information. See (concat "file://" (expand-file-name raw-path)) (concat "file://" raw-path))) (t raw-path))) + ;; Convert & to & for correct XML representation + (path (replace-regexp-in-string "&" "&" path)) protocol) (cond ;; Image file. diff --git a/lisp/ox-publish.el b/lisp/ox-publish.el index 213c76747..194e16962 100644 --- a/lisp/ox-publish.el +++ b/lisp/ox-publish.el @@ -179,6 +179,7 @@ included. See the back-end documentation for more information. :with-tags `org-export-with-tags' :with-tasks `org-export-with-tasks' :with-timestamps `org-export-with-timestamps' + :with-planning `org-export-with-planning' :with-todo-keywords `org-export-with-todo-keywords' The following properties may be used to control publishing of diff --git a/lisp/ox.el b/lisp/ox.el index 22da0b337..7a00541d4 100644 --- a/lisp/ox.el +++ b/lisp/ox.el @@ -131,7 +131,7 @@ (:with-footnotes nil "f" org-export-with-footnotes) (:with-inlinetasks nil "inline" org-export-with-inlinetasks) (:with-latex nil "tex" org-export-with-latex) - (:with-plannings nil "p" org-export-with-planning) + (:with-planning nil "p" org-export-with-planning) (:with-priority nil "pri" org-export-with-priority) (:with-smart-quotes nil "'" org-export-with-smart-quotes) (:with-special-strings nil "-" org-export-with-special-strings) @@ -1345,7 +1345,7 @@ The back-end could then be called with, for example: ;; - category :: option ;; - type :: symbol (`verbatim', nil, t) ;; -;; + `:with-plannings' :: Non-nil means transcoding should include +;; + `:with-planning' :: Non-nil means transcoding should include ;; planning info. ;; - category :: option ;; - type :: symbol (nil, t) @@ -2005,7 +2005,7 @@ a tree with a select tag." (not (eq todo-type with-tasks))) (and (consp with-tasks) (not (member todo with-tasks)))))))) ((latex-environment latex-fragment) (not (plist-get options :with-latex))) - (planning (not (plist-get options :with-plannings))) + (planning (not (plist-get options :with-planning))) (statistics-cookie (not (plist-get options :with-statistics-cookies))) (table-cell (and (org-export-table-has-special-column-p @@ -3423,24 +3423,31 @@ that property within attributes. This function assumes attributes are defined as \":keyword value\" pairs. It is appropriate for `:attr_html' like -properties. All values will become strings except the empty -string and \"nil\", which will become nil." - (let ((attributes - (let ((value (org-element-property attribute element))) - (when value - (let ((s (mapconcat 'identity value " ")) result) - (while (string-match - "\\(?:^\\|[ \t]+\\)\\(:[-a-zA-Z0-9_]+\\)\\([ \t]+\\|$\\)" - s) - (let ((value (substring s 0 (match-beginning 0)))) - (push (and (not (member value '("nil" ""))) value) result)) - (push (intern (match-string 1 s)) result) - (setq s (substring s (match-end 0)))) - ;; Ignore any string before the first property with `cdr'. - (cdr (nreverse (cons (and (org-string-nw-p s) - (not (equal s "nil")) - s) - result)))))))) +properties. + +All values will become strings except the empty string and +\"nil\", which will become nil. Also, values containing only +double quotes will be read as-is, which means that \"\" value +will become the empty string." + (let* ((prepare-value + (lambda (str) + (cond ((member str '(nil "" "nil")) nil) + ((string-match "^\"\\(\"+\\)?\"$" str) + (or (match-string 1 str) "")) + (t str)))) + (attributes + (let ((value (org-element-property attribute element))) + (when value + (let ((s (mapconcat 'identity value " ")) result) + (while (string-match + "\\(?:^\\|[ \t]+\\)\\(:[-a-zA-Z0-9_]+\\)\\([ \t]+\\|$\\)" + s) + (let ((value (substring s 0 (match-beginning 0)))) + (push (funcall prepare-value value) result)) + (push (intern (match-string 1 s)) result) + (setq s (substring s (match-end 0)))) + ;; Ignore any string before first property with `cdr'. + (cdr (nreverse (cons (funcall prepare-value s) result)))))))) (if property (plist-get attributes property) attributes))) (defun org-export-get-caption (element &optional shortp) @@ -4640,6 +4647,21 @@ INFO is a plist used as a communication channel." (org-export-table-row-ends-rowgroup-p table-row info) (= (org-export-table-row-group table-row info) 1))) +(defun org-export-table-row-number (table-row info) + "Return TABLE-ROW number. +INFO is a plist used as a communication channel. Return value is +zero-based and ignores separators. The function returns nil for +special colums and separators." + (when (and (eq (org-element-property :type table-row) 'standard) + (not (org-export-table-row-is-special-p table-row info))) + (let ((number 0)) + (org-element-map (org-export-get-parent-table table-row) 'table-row + (lambda (row) + (cond ((eq row table-row) number) + ((eq (org-element-property :type row) 'standard) + (incf number) nil))) + info 'first-match)))) + (defun org-export-table-dimensions (table info) "Return TABLE dimensions. @@ -4677,13 +4699,7 @@ function returns nil for other cells." (eq (car (org-element-contents table-row)) table-cell))) (cons ;; Row number. - (let ((row-count 0)) - (org-element-map table 'table-row - (lambda (row) - (cond ((eq (org-element-property :type row) 'rule) nil) - ((eq row table-row) row-count) - (t (incf row-count) nil))) - info 'first-match)) + (org-export-table-row-number (org-export-get-parent table-cell) info) ;; Column number. (let ((col-count 0)) (org-element-map table-row 'table-cell diff --git a/testing/lisp/test-org-table.el b/testing/lisp/test-org-table.el index 01adf52c0..2dd5f3811 100644 --- a/testing/lisp/test-org-table.el +++ b/testing/lisp/test-org-table.el @@ -339,7 +339,7 @@ reference (with row). No format specifier." | 0 | 1 | 0 | #ERROR | #ERROR | #ERROR | 2 | 2 | | z | 1 | z | #ERROR | #ERROR | #ERROR | 2 | 2 | | | 1 | | #ERROR | #ERROR | #ERROR | 1 | 1 | -| | | | #ERROR | #ERROR | #ERROR | 1 | 1 | +| | | | #ERROR | 0 | 0 | 0 | 0 | " 1 lisp) (org-test-table-target-expect @@ -348,7 +348,7 @@ reference (with row). No format specifier." | 0 | 1 | 0 | 1 | 1 | 1 | 2 | 2 | | z | 1 | z | z + 1 | z + 1 | z + 1 | 2 | 2 | | | 1 | 0 | 1 | 1 | 1 | 1 | 1 | -| | | 0 | 0 | 0 | 0 | 1 | 1 | +| | | 0 | 0 | 0 | 0 | 0 | 0 | " 1 calc) (org-test-table-target-expect @@ -381,7 +381,7 @@ reference (with row). Format specifier N." | 0 | 1 | 0 | 1 | 1 | 1 | 2 | 2 | | z | 1 | 0 | 1 | 1 | 1 | 2 | 2 | | | 1 | 0 | 1 | 1 | 1 | 1 | 1 | -| | | 0 | 0 | 0 | 0 | 1 | 1 | +| | | 0 | 0 | 0 | 0 | 0 | 0 | " 1 lisp calc) (org-test-table-target-expect @@ -455,20 +455,34 @@ reference (with row). Format specifier N." ;; Empty fields in simple and complex range reference: Suppress them ;; ($5 and $6) or keep them and use 0 ($7 and $8) - (org-test-table-target-expect - "\n| | | 5 | 7 | replace | replace | replace | replace |\n" - "\n| | | 5 | 7 | 6 | 6 | 3 | 3 |\n" - 1 - ;; Calc formula - (concat "#+TBLFM: " - "$5 = vmean($1..$4) :: $6 = vmean(@0$1..@0$4) :: " - "$7 = vmean($1..$4); EN :: $8 = vmean(@0$1..@0$4); EN") - ;; Lisp formula - (concat "#+TBLFM: " - "$5 = '(/ (+ $1..$4 ) (length '( $1..$4 ))); N :: " - "$6 = '(/ (+ @0$1..@0$4) (length '(@0$1..@0$4))); N :: " - "$7 = '(/ (+ $1..$4 ) (length '( $1..$4 ))); EN :: " - "$8 = '(/ (+ @0$1..@0$4) (length '(@0$1..@0$4))); EN")) + (let ((calc (concat + "#+TBLFM: " + "$5 = vmean($1..$4) :: " + "$6 = vmean(@0$1..@0$4) :: " + "$7 = vmean($1..$4); EN :: " + "$8 = vmean(@0$1..@0$4); EN")) + (lisp (concat + "#+TBLFM: " + "$5 = '(/ (+ $1..$4 ) (length '( $1..$4 ))); N :: " + "$6 = '(/ (+ @0$1..@0$4) (length '(@0$1..@0$4))); N :: " + "$7 = '(/ (+ $1..$4 ) (length '( $1..$4 ))); EN :: " + "$8 = '(/ (+ @0$1..@0$4) (length '(@0$1..@0$4))); EN"))) + (org-test-table-target-expect + "\n| | | 5 | 7 | replace | replace | replace | replace |\n" + "\n| | | 5 | 7 | 6 | 6 | 3 | 3 |\n" + 1 calc lisp) + + ;; The mean value of a range with only empty fields is not defined + (let ((target + "\n| | | | | replace | replace | replace | replace |\n")) + (org-test-table-target-expect + target + "\n| | | | | vmean([]) | vmean([]) | 0 | 0 |\n" + 1 calc) + (org-test-table-target-expect + target + "\n| | | | | #ERROR | #ERROR | 0 | 0 |\n" + 1 lisp))) ;; Test if one field is empty, else do a calculation (org-test-table-target-expect @@ -667,11 +681,11 @@ reference (with row). Format specifier N." ;; For Lisp formula (should (equal "\"0\"" (f "0" nil nil t))) (should (equal "\"z\"" (f "z" nil nil t))) - (should (equal "\"\"" (f "" nil nil t))) + (should (equal "" (f "" nil nil t))) (should (equal "\"0\" \"1\"" (f '("0" "1") nil nil t))) (should (equal "\"z\" \"1\"" (f '("z" "1") nil nil t))) (should (equal "\"1\"" (f '("" "1") nil nil t))) - (should (equal "\"\"" (f '("" "" ) nil nil t))) + (should (equal "" (f '("" "" ) nil nil t))) ;; For Calc formula (should (equal "(0)" (f "0" nil nil nil))) (should (equal "(z)" (f "z" nil nil nil))) @@ -679,7 +693,7 @@ reference (with row). Format specifier N." (should (equal "[0,1]" (f '("0" "1") nil nil nil))) (should (equal "[z,1]" (f '("z" "1") nil nil nil))) (should (equal "[1]" (f '("" "1") nil nil nil))) - (should (equal "[0]" (f '("" "" ) nil nil nil))) + (should (equal "[]" (f '("" "" ) nil nil nil))) ;; For Calc formula, special numbers (should (equal "(nan)" (f "nan" nil nil nil))) (should (equal "(uinf)" (f "uinf" nil nil nil))) @@ -695,11 +709,11 @@ reference (with row). Format specifier N." ;; For Lisp formula (should (equal "0" (f "0" nil t t))) (should (equal "0" (f "z" nil t t))) - (should (equal "0" (f "" nil t t))) + (should (equal "" (f "" nil t t))) (should (equal "0 1" (f '("0" "1") nil t t))) (should (equal "0 1" (f '("z" "1") nil t t))) (should (equal "1" (f '("" "1") nil t t))) - (should (equal "0" (f '("" "" ) nil t t))) + (should (equal "" (f '("" "" ) nil t t))) ;; For Calc formula (should (equal "(0)" (f "0" nil t nil))) (should (equal "(0)" (f "z" nil t nil))) @@ -707,7 +721,7 @@ reference (with row). Format specifier N." (should (equal "[0,1]" (f '("0" "1") nil t nil))) (should (equal "[0,1]" (f '("z" "1") nil t nil))) (should (equal "[1]" (f '("" "1") nil t nil))) - (should (equal "[0]" (f '("" "" ) nil t nil))) + (should (equal "[]" (f '("" "" ) nil t nil))) ;; For Calc formula, special numbers (should (equal "(0)" (f "nan" nil t nil))) (should (equal "(0)" (f "uinf" nil t nil))) diff --git a/testing/lisp/test-ox.el b/testing/lisp/test-ox.el index d02384566..46531a179 100644 --- a/testing/lisp/test-ox.el +++ b/testing/lisp/test-ox.el @@ -383,10 +383,10 @@ Paragraph" (org-test-with-temp-text "CLOSED: [2012-04-29 sun. 10:45]" (org-test-with-backend test (should - (equal (org-export-as 'test nil nil nil '(:with-plannings t)) + (equal (org-export-as 'test nil nil nil '(:with-planning t)) "CLOSED: [2012-04-29 sun. 10:45]\n")) (should - (equal (org-export-as 'test nil nil nil '(:with-plannings nil)) + (equal (org-export-as 'test nil nil nil '(:with-planning nil)) ""))))) ;; Statistics cookies. (should @@ -687,6 +687,20 @@ body\n"))) :attr_html (org-test-with-temp-text "#+ATTR_HTML: :a :b\nParagraph" (org-element-at-point))))) + ;; Return empty string when value is "". + (should + (equal '(:a "") + (org-export-read-attribute + :attr_html + (org-test-with-temp-text "#+ATTR_HTML: :a \"\"\nParagraph" + (org-element-at-point))))) + ;; Return \"\" when value is """". + (should + (equal '(:a "\"\"") + (org-export-read-attribute + :attr_html + (org-test-with-temp-text "#+ATTR_HTML: :a \"\"\"\"\nParagraph" + (org-element-at-point))))) ;; Ignore text before first property. (should-not (member "ignore" @@ -1911,6 +1925,35 @@ Another text. (ref:text) (mapcar (lambda (row) (org-export-table-row-group row info)) (org-element-map tree 'table-row 'identity)))))) +(ert-deftest test-org-export/table-row-number () + "Test `org-export-table-row-number' specifications." + ;; Standard test. Number is 0-indexed. + (should + (equal '(0 1) + (org-test-with-parsed-data "| a | b | c |\n| d | e | f |" + (org-element-map tree 'table-row + (lambda (row) (org-export-table-row-number row info)) info)))) + ;; Number ignores separators. + (should + (equal '(0 1) + (org-test-with-parsed-data " +| a | b | c | +|---+---+---| +| d | e | f |" + (org-element-map tree 'table-row + (lambda (row) (org-export-table-row-number row info)) info)))) + ;; Number ignores special rows. + (should + (equal '(0 1) + (org-test-with-parsed-data " +| / | < | > | +| | b | c | +|---+-----+-----| +| | | | +| | e | f |" + (org-element-map tree 'table-row + (lambda (row) (org-export-table-row-number row info)) info))))) + (ert-deftest test-org-export/table-cell-width () "Test `org-export-table-cell-width' specifications." ;; 1. Width is primarily determined by width cookies. If no cookie