Nicolas Goaziou <m...@nicolasgoaziou.fr> writes: > Hello, > > Eric Abrahamsen <e...@ericabrahamsen.net> writes: > >> This will get there eventually! Because there's likely to be more >> tweaking, I haven't touched the manual or the tests yet, just reworked >> the option and function: > > Thank you. Some comments follow. > >> #+BEGIN_SRC elisp >> (defcustom org-structure-template-alist >> '((?s . "SRC") >> (?e . "EXAMPLE") >> (?E . "EXPORT") >> (?q . "QUOTE") >> (?v . "VERSE") >> (?V . "VERBATIM") > > This block type doesn't exist. You can remove it. > >> (?c . "CENTER") >> (?C . "COMMENT") >> (?l . "EXPORT latex") >> (?L . "#+LaTeX") > > #+LATEX or #+latex (see below) > >> (?h . "EXPORT html") >> (?H . "#+HTML") >> (?a . "EXPORT ascii") >> (?A . "#+ASCII") >> (?i . "#+INDEX") >> (?I . "#+INCLUDE")) > > As suggested by Rasmus once, maybe we could get away from FORTRAN touch > and insert everything lowercase.
Sounds good to me. >> "Structure completion elements. >> This is an alist of characters and values. When >> `org-insert-structure-template' is called, an additional key is >> read. The key is first looked up in this alist, and the >> corresponding structure is inserted. Hitting <TAB> will prompt >> for a structure. > > I would remove "Hitting <TAB> prompts for a structure." which belongs to > the function's docstring, not to variable's. > >> Structure strings prefixed with a \"#+\" are inserted with no >> further processing. Strings without this prefix are used to >> create a block structure, with \"#+BEGIN\" and \"#+END\" added >> automatically. > > I'm not sure about this part. I understand the backward-compatibility > concern, but it sounds a bit alien to the purpose of the function, i.e., > there is no wrapping around, it is not an "environment" either. WDYT? It was a hack; I was trying to make the smallest change possible. But that does turn it into a bit of a Frankenstein, and I would prefer to remove it. As you mentioned earlier, Emacs already has mechanism for inserting snippets. The "include" case is a little different, since it does provide some extra convenience. I've still taken it out in the next version below, though. >> WHAT TO DO ABOUT THIS PART? >> There are two templates for each key, the first uses the original Org >> syntax, > > You can remove it. > >> the second uses Emacs Muse-like syntax tags. These Muse-like tags become >> the default when the /org-mtags.el/ module has been loaded. See also the >> variable `org-mtags-prefer-muse-templates'." >> :group 'org-completion >> :type '(repeat >> (cons >> (character :tag "Key") >> (string :tag "Template"))) >> :version "26.1" >> :package-version '(Org . "8.3")) > > You need to update :version and :package-version. Technically, > if :package-version is provided, we should only use it, IIUC. I've never really understood the difference. Current version is 9.1.2, will this function be present in 9.1.3, or 9.2.0? I've assumed 9.2.0 in the next version of the patch. >> (defun org-insert-structure-template (&optional type) >> "Insert a block structure of the type #+BEGIN_FOO/#+END_FOO. >> This function first reads a character, which can be one of the >> keys in `org-structure-template-alist'. It can also be <TAB>, in >> which case the user is prompted for a string to use. > > "When it is <TAB>, prompt the user for a string to use." > >> (interactive) >> (let* ((key (read-key "Key: ")) >> (struct-string >> (or (cdr-safe (assq key org-structure-template-alist)) > > `cdr-safe' -> `cdr' > >> (when (= key ?\t) >> (read-string "Structure type: ")) > > Nitpick: (and (eq key ?\t) (read-string ...)) Out of curiosity is this a style thing, or semantics, or performance? >> (error "'%c' has no structure definition" key)))) >> (if (string-prefix-p "#+" struct-string) >> (progn >> (insert (format "%s: " struct-string)) >> (when (string= "#+INCLUDE" struct-string) >> (insert >> (format "\"%s\"" >> (abbreviate-file-name >> (read-file-name "Include file: ")))))) > If we take out special handling of "#+" strings, this part is gone anyway. Here's a new version with all the above changes made, and the docs tweaked accordingly.
>From 086733d275ebfb10726144e92ccd30be605c5516 Mon Sep 17 00:00:00 2001 From: Eric Abrahamsen <e...@ericabrahamsen.net> Date: Mon, 30 Oct 2017 09:19:15 -0700 Subject: [PATCH] Replacing easy templates with function org-insert-structure-template * lisp/org.el (org-insert-structure-template): New function for wrapping region (or element at point) in a begin/end block. (org-structure-predefined-blocks): New option holding predefined blocks, for completion. (org-try-structure-completion, org-complete-expand-structure-template): Remove functions. * doc/org.texi (Inserting structure templates): Document. * testing/lisp/test-org.el (test-org/insert-template): New test. --- doc/org.texi | 749 +++++++++++++++++++++++------------------------ etc/ORG-NEWS | 4 + lisp/org.el | 132 ++++----- testing/lisp/test-org.el | 46 +++ 4 files changed, 488 insertions(+), 443 deletions(-) diff --git a/doc/org.texi b/doc/org.texi index 77da6d335..e08e843ad 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -652,7 +652,7 @@ Texinfo export * Texinfo specific export settings:: Setting the environment. * Texinfo file header:: Generating the header. * Texinfo title and copyright page:: Creating preamble pages. -* Info directory file:: Installing a manual in Info file hierarchy. +* Info directory file:: Installing a manual in Info file hierarchy. * Headings and sectioning structure:: Building document structure. * Indices:: Creating indices. * Quoting Texinfo code:: Incorporating literal Texinfo code. @@ -749,7 +749,7 @@ Specific header arguments Miscellaneous * Completion:: M-TAB guesses completions -* Easy templates:: Quick insertion of structural elements +* Inserting structure templates:: Wrapping text in code blocks * Speed keys:: Electric commands at the beginning of a headline * Code evaluation security:: Org mode files evaluate inline code * Customization:: Adapting Org to changing tastes @@ -796,7 +796,7 @@ MobileOrg @end detailmenu @end menu -@node Introduction +@node Introduction, Document structure, Top, Top @chapter Introduction @cindex introduction @@ -808,7 +808,7 @@ MobileOrg * Conventions:: Typesetting conventions in the manual @end menu -@node Summary +@node Summary, Installation, Introduction, Introduction @section Summary @cindex summary @@ -864,7 +864,7 @@ Network Theory Ltd.} @page -@node Installation +@node Installation, Activation, Summary, Introduction @section Installation @cindex installation @@ -940,7 +940,7 @@ For more detailed explanations on Org's build system, please check the Org Build System page on @uref{http://orgmode.org/worg/dev/org-build-system.html, Worg}. -@node Activation +@node Activation, Feedback, Installation, Introduction @section Activation @cindex activation @cindex autoload @@ -991,7 +991,7 @@ the default. If you do not like @code{transient-mark-mode}, you can create an active region by using the mouse to select a region, or pressing @kbd{C-@key{SPC}} twice before moving the cursor. -@node Feedback +@node Feedback, Conventions, Activation, Introduction @section Feedback @cindex feedback @cindex bug reports @@ -1091,7 +1091,7 @@ screen. Save this buffer to a file (for example using @kbd{C-x C-w}) and attach it to your bug report. @end enumerate -@node Conventions +@node Conventions, , Feedback, Introduction @section Typesetting conventions used in this manual @subsubheading TODO keywords, tags, properties, etc. @@ -1141,7 +1141,7 @@ will be listed to call @code{org-table-move-column-right}. If you prefer, you can compile the manual without the command names by unsetting the flag @code{cmdnames} in @file{org.texi}. -@node Document structure +@node Document structure, Tables, Introduction, Top @chapter Document structure @cindex document structure @cindex structure of document @@ -1164,7 +1164,7 @@ edit the structure of the document. * Org syntax:: Formal description of Org's syntax @end menu -@node Outlines +@node Outlines, Headlines, Document structure, Document structure @section Outlines @cindex outlines @cindex Outline mode @@ -1178,7 +1178,7 @@ currently being worked on. Org greatly simplifies the use of outlines by compressing the entire show/hide functionality into a single command, @command{org-cycle}, which is bound to the @key{TAB} key. -@node Headlines +@node Headlines, Visibility cycling, Outlines, Document structure @section Headlines @cindex headlines @cindex outline tree @@ -1220,7 +1220,7 @@ least two empty lines, one empty line will remain visible after folding the subtree, in order to structure the collapsed view. See the variable @code{org-cycle-separator-lines} to modify this behavior. -@node Visibility cycling +@node Visibility cycling, Motion, Headlines, Document structure @section Visibility cycling @cindex cycling, visibility @cindex visibility cycling @@ -1234,7 +1234,7 @@ variable @code{org-cycle-separator-lines} to modify this behavior. * Catching invisible edits:: Preventing mistakes when editing invisible parts @end menu -@node Global and local cycling +@node Global and local cycling, Initial visibility, Visibility cycling, Visibility cycling @subsection Global and local cycling Outlines make it possible to hide parts of the text in the buffer. @@ -1315,7 +1315,7 @@ a @kbd{C-u} prefix, do not remove the previously used indirect buffer. Copy the @i{visible} text in the region into the kill ring. @end table -@node Initial visibility +@node Initial visibility, Catching invisible edits, Global and local cycling, Visibility cycling @subsection Initial visibility @cindex visibility, initialize @@ -1355,7 +1355,7 @@ requested by startup options and @samp{VISIBILITY} properties in individual entries. @end table -@node Catching invisible edits +@node Catching invisible edits, , Initial visibility, Visibility cycling @subsection Catching invisible edits @vindex org-catch-invisible-edits @@ -1366,7 +1366,7 @@ confused on what has been edited and how to undo the mistake. Setting docstring of this option on how Org should catch invisible edits and process them. -@node Motion +@node Motion, Structure editing, Visibility cycling, Document structure @section Motion @cindex motion, between headlines @cindex jumping, to headlines @@ -1406,7 +1406,7 @@ q @r{Quit} See also the option @code{org-goto-interface}. @end table -@node Structure editing +@node Structure editing, Sparse trees, Motion, Document structure @section Structure editing @cindex structure editing @cindex headline, promotion and demotion @@ -1542,7 +1542,7 @@ inside a table (@pxref{Tables}), the Meta-Cursor keys have different functionality. -@node Sparse trees +@node Sparse trees, Plain lists, Structure editing, Document structure @section Sparse trees @cindex sparse trees @cindex trees, sparse @@ -1609,7 +1609,7 @@ To print a sparse tree, you can use the Emacs command document. Or you can use @kbd{C-c C-e C-v} to export only the visible part of the document and print the resulting file. -@node Plain lists +@node Plain lists, Drawers, Sparse trees, Document structure @section Plain lists @cindex plain lists @cindex lists, plain @@ -1813,7 +1813,7 @@ numerically, alphabetically, by time, by checked status for check lists, or by a custom function. @end table -@node Drawers +@node Drawers, Blocks, Plain lists, Document structure @section Drawers @cindex drawers @cindex visibility cycling, drawers @@ -1866,7 +1866,7 @@ You can select the name of the drawers which should be exported with export output. Property drawers are not affected by this variable: configure @code{org-export-with-properties} instead. -@node Blocks +@node Blocks, Footnotes, Drawers, Document structure @section Blocks @vindex org-hide-block-startup @@ -1885,7 +1885,7 @@ or on a per-file basis by using #+STARTUP: nohideblocks @end example -@node Footnotes +@node Footnotes, Orgstruct mode, Blocks, Document structure @section Footnotes @cindex footnotes @@ -1990,7 +1990,7 @@ a separate window. The window can be closed by pressing @kbd{C-c '}. @end table -@node Orgstruct mode +@node Orgstruct mode, Org syntax, Footnotes, Document structure @section The Orgstruct minor mode @cindex Orgstruct mode @cindex minor mode for structure editing @@ -2025,7 +2025,7 @@ Lisp files, you will be able to fold and unfold headlines in Emacs Lisp commented lines. Some commands like @code{org-demote} are disabled when the prefix is set, but folding/unfolding will work correctly. -@node Org syntax +@node Org syntax, , Orgstruct mode, Document structure @section Org syntax @cindex Org syntax @@ -2051,7 +2051,7 @@ rely on the syntactic meaning of the surrounding context. @cindex linter You can check syntax in your documents using @code{org-lint} command. -@node Tables +@node Tables, Hyperlinks, Document structure, Top @chapter Tables @cindex tables @cindex editing tables @@ -2069,7 +2069,7 @@ calculations are supported using the Emacs @file{calc} package * Org-Plot:: Plotting from org tables @end menu -@node Built-in table editor +@node Built-in table editor, Column width and alignment, Tables, Tables @section The built-in table editor @cindex table editor, built-in @@ -2289,7 +2289,7 @@ it off with @noindent Then the only table command that still works is @kbd{C-c C-c} to do a manual re-align. -@node Column width and alignment +@node Column width and alignment, Column groups, Built-in table editor, Tables @section Column width and alignment @cindex narrow columns in tables @cindex alignment in tables @@ -2380,7 +2380,7 @@ alignment and field width like this: @samp{<r10>}. Lines which only contain these formatting cookies are removed automatically upon exporting the document. -@node Column groups +@node Column groups, Orgtbl mode, Column width and alignment, Tables @section Column groups @cindex grouping columns in tables @@ -2415,7 +2415,7 @@ every vertical line you would like to have: | / | < | | | < | | @end example -@node Orgtbl mode +@node Orgtbl mode, The spreadsheet, Column groups, Tables @section The Orgtbl minor mode @cindex Orgtbl mode @cindex minor mode for tables @@ -2436,7 +2436,7 @@ construct @LaTeX{} tables with the underlying ease and power of Orgtbl mode, including spreadsheet capabilities. For details, see @ref{Tables in arbitrary syntax}. -@node The spreadsheet +@node The spreadsheet, Org-Plot, Orgtbl mode, Tables @section The spreadsheet @cindex calculations, in tables @cindex spreadsheet capabilities @@ -2465,7 +2465,7 @@ formula, moving these references by arrow keys * Advanced features:: Field and column names, parameters and automatic recalc @end menu -@node References +@node References, Formula syntax for Calc, The spreadsheet, The spreadsheet @subsection References @cindex references @@ -2657,7 +2657,7 @@ table. For example @code{remote($1, @@>$2)} => @code{remote(year_2013, @@>$1)}. The format @code{B3} is not supported because it can not be distinguished from a plain table name or ID. -@node Formula syntax for Calc +@node Formula syntax for Calc, Formula syntax for Lisp, References, The spreadsheet @subsection Formula syntax for Calc @cindex formula syntax, Calc @cindex syntax, of formulas @@ -2772,7 +2772,7 @@ should be padded with 0 to the full size. You can add your own Calc functions defined in Emacs Lisp with @code{defmath} and use them in formula syntax for Calc. -@node Formula syntax for Lisp +@node Formula syntax for Lisp, Durations and time values, Formula syntax for Calc, The spreadsheet @subsection Emacs Lisp forms as formulas @cindex Lisp forms, as table formulas @@ -2808,7 +2808,7 @@ Add columns 1 and 2, equivalent to Calc's @code{$1+$2}. Compute the sum of columns 1 to 4, like Calc's @code{vsum($1..$4)}. @end table -@node Durations and time values +@node Durations and time values, Field and range formulas, Formula syntax for Lisp, The spreadsheet @subsection Durations and time values @cindex Duration, computing @cindex Time, computing @@ -2843,7 +2843,7 @@ third formula in the example above). Negative duration values can be manipulated as well, and integers will be considered as seconds in addition and subtraction. -@node Field and range formulas +@node Field and range formulas, Column formulas, Durations and time values, The spreadsheet @subsection Field and range formulas @cindex field formula @cindex range formula @@ -2899,7 +2899,7 @@ can also be used to assign a formula to some but not all fields in a row. Named field, see @ref{Advanced features}. @end table -@node Column formulas +@node Column formulas, Lookup functions, Field and range formulas, The spreadsheet @subsection Column formulas @cindex column formula @cindex formula, for table column @@ -2938,7 +2938,7 @@ stores it. With a numeric prefix argument(e.g., @kbd{C-5 C-c =}) the command will apply it to that many consecutive fields in the current column. @end table -@node Lookup functions +@node Lookup functions, Editing and debugging formulas, Column formulas, The spreadsheet @subsection Lookup functions @cindex lookup functions in tables @cindex table lookup functions @@ -2982,7 +2982,7 @@ matching cells, rank results, group data etc. For practical examples see @uref{http://orgmode.org/worg/org-tutorials/org-lookups.html, this tutorial on Worg}. -@node Editing and debugging formulas +@node Editing and debugging formulas, Updating the table, Lookup functions, The spreadsheet @subsection Editing and debugging formulas @cindex formula editing @cindex editing, of table formulas @@ -3135,7 +3135,7 @@ turn on formula debugging in the @code{Tbl} menu and repeat the calculation, for example by pressing @kbd{C-u C-u C-c = @key{RET}} in a field. Detailed information will be displayed. -@node Updating the table +@node Updating the table, Advanced features, Editing and debugging formulas, The spreadsheet @subsection Updating the table @cindex recomputing table fields @cindex updating, table @@ -3172,7 +3172,7 @@ Iterate all tables in the current buffer, in order to converge table-to-table dependencies. @end table -@node Advanced features +@node Advanced features, , Updating the table, The spreadsheet @subsection Advanced features If you want the recalculation of fields to happen automatically, or if you @@ -3277,7 +3277,7 @@ functions. @end group @end example -@node Org-Plot +@node Org-Plot, , The spreadsheet, Tables @section Org-Plot @cindex graph, in tables @cindex plot tables using Gnuplot @@ -3409,7 +3409,7 @@ The formula is an elisp call: @end table -@node Hyperlinks +@node Hyperlinks, TODO items, Tables, Top @chapter Hyperlinks @cindex hyperlinks @@ -3427,7 +3427,7 @@ other files, Usenet articles, emails, and much more. * Custom searches:: When the default search is not enough @end menu -@node Link format +@node Link format, Internal links, Hyperlinks, Hyperlinks @section Link format @cindex link format @cindex format, of links @@ -3458,7 +3458,7 @@ missing bracket hides the link internals again. To show the internal structure of all links, use the menu entry @code{Org->Hyperlinks->Literal links}. -@node Internal links +@node Internal links, External links, Link format, Hyperlinks @section Internal links @cindex internal links @cindex links, internal @@ -3529,7 +3529,7 @@ earlier. * Radio targets:: Make targets trigger links in plain text @end menu -@node Radio targets +@node Radio targets, , Internal links, Internal links @subsection Radio targets @cindex radio targets @cindex targets, radio @@ -3545,7 +3545,7 @@ for radio targets only when the file is first loaded into Emacs. To update the target list during editing, press @kbd{C-c C-c} with the cursor on or at a target. -@node External links +@node External links, Handling links, Internal links, Hyperlinks @section External links @cindex links, external @cindex external links @@ -3648,7 +3648,7 @@ as links. If spaces must be part of the link (for example in @samp{bbdb:Richard Stallman}), or if you need to remove ambiguities about the end of the link, enclose them in square brackets. -@node Handling links +@node Handling links, Using links outside Org, External links, Hyperlinks @section Handling links @cindex links, handling @@ -3846,7 +3846,7 @@ to @kbd{C-n} and @kbd{C-p} @end lisp @end table -@node Using links outside Org +@node Using links outside Org, Link abbreviations, Handling links, Hyperlinks @section Using links outside Org You can insert and follow links that have Org syntax not only in @@ -3859,7 +3859,7 @@ yourself): (global-set-key "\C-c o" 'org-open-at-point-global) @end lisp -@node Link abbreviations +@node Link abbreviations, Search options, Using links outside Org, Hyperlinks @section Link abbreviations @cindex link abbreviations @cindex abbreviation, links @@ -3933,7 +3933,7 @@ link with prefix. You can add a completion function to a link like this: @end lisp -@node Search options +@node Search options, Custom searches, Link abbreviations, Hyperlinks @section Search options in file links @cindex search option in file links @cindex file links, searching @@ -3985,7 +3985,7 @@ to search the current file. For example, @code{[[file:::find me]]} does a search for @samp{find me} in the current file, just as @samp{[[find me]]} would. -@node Custom searches +@node Custom searches, , Search options, Hyperlinks @section Custom Searches @cindex custom search strings @cindex search strings, custom @@ -4009,7 +4009,7 @@ variables for more information. Org actually uses this mechanism for Bib@TeX{} database files, and you can use the corresponding code as an implementation example. See the file @file{org-bibtex.el}. -@node TODO items +@node TODO items, Tags, Hyperlinks, Top @chapter TODO items @cindex TODO items @@ -4034,7 +4034,7 @@ methods to give you an overview of all the things that you have to do. * Checkboxes:: Tick-off lists @end menu -@node TODO basics +@node TODO basics, TODO extensions, TODO items, TODO items @section Basic TODO functionality Any headline becomes a TODO item when it starts with the word @@ -4108,7 +4108,7 @@ Insert a new TODO entry below the current one. Changing a TODO state can also trigger tag changes. See the docstring of the option @code{org-todo-state-tags-triggers} for details. -@node TODO extensions +@node TODO extensions, Progress logging, TODO basics, TODO items @section Extended use of TODO keywords @cindex extended TODO keywords @@ -4132,7 +4132,7 @@ TODO items in particular (@pxref{Tags}). * TODO dependencies:: When one task needs to wait for others @end menu -@node Workflow states +@node Workflow states, TODO types, TODO extensions, TODO extensions @subsection TODO keywords as workflow states @cindex TODO workflow @cindex workflow states as TODO keywords @@ -4163,7 +4163,7 @@ define many keywords, you can use in-buffer completion buffer. Changing a TODO state can be logged with a timestamp, see @ref{Tracking TODO state changes}, for more information. -@node TODO types +@node TODO types, Multiple sets in one file, Workflow states, TODO extensions @subsection TODO keywords as types @cindex TODO types @cindex names as TODO keywords @@ -4195,7 +4195,7 @@ has to do, you would use @kbd{C-3 C-c / t}. To collect Lucy's items from all agenda files into a single buffer, you would use the numeric prefix argument as well when creating the global TODO list: @kbd{C-3 C-c a t}. -@node Multiple sets in one file +@node Multiple sets in one file, Fast access to TODO states, TODO types, TODO extensions @subsection Multiple keyword sets in one file @cindex TODO keyword sets @@ -4244,7 +4244,7 @@ from @code{DONE} to @code{REPORT} in the example above. See also @code{shift-selection-mode}. @end table -@node Fast access to TODO states +@node Fast access to TODO states, Per-file keywords, Multiple sets in one file, TODO extensions @subsection Fast access to TODO states If you would like to quickly change an entry to an arbitrary TODO state @@ -4269,7 +4269,7 @@ state through the tags interface (@pxref{Setting tags}), in case you like to mingle the two concepts. Note that this means you need to come up with unique keys across both sets of keywords.} -@node Per-file keywords +@node Per-file keywords, Faces for TODO keywords, Fast access to TODO states, TODO extensions @subsection Setting up keywords for individual files @cindex keyword options @cindex per-file keywords @@ -4315,7 +4315,7 @@ Org mode is activated after visiting a file. @kbd{C-c C-c} with the cursor in a line starting with @samp{#+} is simply restarting Org mode for the current buffer.}. -@node Faces for TODO keywords +@node Faces for TODO keywords, TODO dependencies, Per-file keywords, TODO extensions @subsection Faces for TODO keywords @cindex faces, for TODO keywords @@ -4343,7 +4343,7 @@ special face and use that. A string is interpreted as a color. The option @code{org-faces-easy-properties} determines if that color is interpreted as a foreground or a background color. -@node TODO dependencies +@node TODO dependencies, , Faces for TODO keywords, TODO extensions @subsection TODO dependencies @cindex TODO dependencies @cindex dependencies, of TODO states @@ -4416,7 +4416,7 @@ between entries in different trees or files, check out the contributed module @file{org-depend.el}. @page -@node Progress logging +@node Progress logging, Priorities, TODO extensions, TODO items @section Progress logging @cindex progress logging @cindex logging, of progress @@ -4434,7 +4434,7 @@ work time}. * Tracking your habits:: How consistent have you been? @end menu -@node Closing items +@node Closing items, Tracking TODO state changes, Progress logging, Progress logging @subsection Closing items The most basic logging is to keep track of @emph{when} a certain TODO @@ -4465,7 +4465,7 @@ lognotedone}.} You will then be prompted for a note, and that note will be stored below the entry with a @samp{Closing Note} heading. -@node Tracking TODO state changes +@node Tracking TODO state changes, Tracking your habits, Closing items, Progress logging @subsection Tracking TODO state changes @cindex drawer, for state change recording @@ -4548,7 +4548,7 @@ settings like @code{TODO(!)}. For example :END: @end example -@node Tracking your habits +@node Tracking your habits, , Tracking TODO state changes, Progress logging @subsection Tracking your habits @cindex habits @@ -4648,7 +4648,7 @@ temporarily be disabled and they won't appear at all. Press @kbd{K} again to bring them back. They are also subject to tag filtering, if you have habits which should only be done in certain contexts, for example. -@node Priorities +@node Priorities, Breaking down tasks, Progress logging, TODO items @section Priorities @cindex priorities @@ -4706,7 +4706,7 @@ priority): #+PRIORITIES: A C B @end example -@node Breaking down tasks +@node Breaking down tasks, Checkboxes, Priorities, TODO items @section Breaking tasks down into subtasks @cindex tasks, breaking down @cindex statistics, for TODO items @@ -4767,7 +4767,7 @@ Another possibility is the use of checkboxes to identify (a hierarchy of) a large number of subtasks (@pxref{Checkboxes}). -@node Checkboxes +@node Checkboxes, , Breaking down tasks, TODO items @section Checkboxes @cindex checkboxes @@ -4876,7 +4876,7 @@ changing TODO states. If you delete boxes/entries or add/change them by hand, use this command to get things back into sync. @end table -@node Tags +@node Tags, Properties and columns, TODO items, Top @chapter Tags @cindex tags @cindex headline tagging @@ -4904,7 +4904,7 @@ You may specify special faces for specific tags using the option * Tag searches:: Searching for combinations of tags @end menu -@node Tag inheritance +@node Tag inheritance, Setting tags, Tags, Tags @section Tag inheritance @cindex tag inheritance @cindex inheritance, of tags @@ -4958,7 +4958,7 @@ with inherited tags. Set @code{org-agenda-use-tag-inheritance} to control this: the default value includes all agenda types, but setting this to @code{nil} can really speed up agenda generation. -@node Setting tags +@node Setting tags, Tag hierarchy, Tag inheritance, Tags @section Setting tags @cindex setting tags @cindex tags, setting @@ -5145,7 +5145,7 @@ instead of @kbd{C-c C-c}). If you set the variable to the value @code{expert}, the special window is not even shown for single-key tag selection, it comes up only when you press an extra @kbd{C-c}. -@node Tag hierarchy +@node Tag hierarchy, Tag searches, Setting tags, Tags @section Tag hierarchy @cindex group tags @@ -5250,7 +5250,7 @@ If you want to ignore group tags temporarily, toggle group tags support with @command{org-toggle-tags-groups}, bound to @kbd{C-c C-x q}. If you want to disable tag groups completely, set @code{org-group-tags} to @code{nil}. -@node Tag searches +@node Tag searches, , Tag hierarchy, Tags @section Tag searches @cindex tag searches @cindex searching for tags @@ -5282,7 +5282,7 @@ properties. For a complete description with many examples, see @ref{Matching tags and properties}. -@node Properties and columns +@node Properties and columns, Dates and times, Tags, Top @chapter Properties and columns @cindex properties @@ -5312,7 +5312,7 @@ Properties can be conveniently edited and viewed in column view * Property API:: Properties for Lisp programmers @end menu -@node Property syntax +@node Property syntax, Special properties, Properties and columns, Properties and columns @section Property syntax @cindex property syntax @cindex drawer, for properties @@ -5436,7 +5436,7 @@ Compute the property at point, using the operator and scope from the nearest column format definition. @end table -@node Special properties +@node Special properties, Property searches, Property syntax, Properties and columns @section Special properties @cindex properties, special @@ -5481,7 +5481,7 @@ TIMESTAMP_IA @r{The first inactive timestamp in the entry.} TODO @r{The TODO keyword of the entry.} @end example -@node Property searches +@node Property searches, Property inheritance, Special properties, Properties and columns @section Property searches @cindex properties, searching @cindex searching, of properties @@ -5518,7 +5518,7 @@ value. If you enclose the value in curly braces, it is interpreted as a regular expression and matched against the property values. @end table -@node Property inheritance +@node Property inheritance, Column view, Property searches, Properties and columns @section Property Inheritance @cindex properties, inheritance @cindex inheritance, of properties @@ -5562,7 +5562,7 @@ The LOGGING property may define logging settings for an entry or a subtree (@pxref{Tracking TODO state changes}). @end table -@node Column view +@node Column view, Property API, Property inheritance, Properties and columns @section Column view A great way to view and edit properties in an outline tree is @@ -5585,7 +5585,7 @@ queries have collected selected items, possibly from a number of files. * Capturing column view:: A dynamic block for column view @end menu -@node Defining columns +@node Defining columns, Using column view, Column view, Column view @subsection Defining columns @cindex column view, for properties @cindex properties, column view @@ -5598,7 +5598,7 @@ done by defining a column format line. * Column attributes:: Appearance and content of a column @end menu -@node Scope of column definitions +@node Scope of column definitions, Column attributes, Defining columns, Defining columns @subsubsection Scope of column definitions To define a column format for an entire file, use a line like @@ -5625,7 +5625,7 @@ you can define columns on level 1 that are general enough for all sublevels, and more specific columns further down, when you edit a deeper part of the tree. -@node Column attributes +@node Column attributes, , Scope of column definitions, Defining columns @subsubsection Column attributes A column definition sets the attributes of a column. The general definition looks like this: @@ -5731,7 +5731,7 @@ an @samp{[X]} status if all children have been checked. The sums of CLOCK intervals in the subtree, either for all clocks or just for today. -@node Using column view +@node Using column view, Capturing column view, Defining columns, Column view @subsection Using column view @table @kbd @@ -5790,7 +5790,7 @@ Insert a new column, to the left of the current column. Delete the current column. @end table -@node Capturing column view +@node Capturing column view, , Using column view, Column view @subsection Capturing column view Since column view is just an overlay over a buffer, it cannot be @@ -5869,7 +5869,7 @@ distributed with the main distribution of Org (visit properties from entries in a certain scope, and arbitrary Lisp expressions to process these values before inserting them into a table or a dynamic block. -@node Property API +@node Property API, , Column view, Properties and columns @section The Property API @cindex properties, API @cindex API, for properties @@ -5879,7 +5879,7 @@ be used by Emacs Lisp programs to work with properties and to implement features based on them. For more information see @ref{Using the property API}. -@node Dates and times +@node Dates and times, Capture - Refile - Archive, Properties and columns, Top @chapter Dates and times @cindex dates @cindex times @@ -5903,7 +5903,7 @@ is used in a much wider sense. @end menu -@node Timestamps +@node Timestamps, Creating timestamps, Dates and times, Dates and times @section Timestamps, deadlines, and scheduling @cindex timestamps @cindex ranges, time @@ -5997,7 +5997,7 @@ angular ones. These timestamps are inactive in the sense that they do @end table -@node Creating timestamps +@node Creating timestamps, Deadlines and scheduling, Timestamps, Dates and times @section Creating timestamps @cindex creating timestamps @cindex timestamps, creating @@ -6068,7 +6068,7 @@ the following column). * Custom time format:: Making dates look different @end menu -@node The date/time prompt +@node The date/time prompt, Custom time format, Creating timestamps, Creating timestamps @subsection The date/time prompt @cindex date, reading in minibuffer @cindex time, reading in minibuffer @@ -6198,7 +6198,7 @@ on, the current interpretation of your input will be displayed live in the minibuffer@footnote{If you find this distracting, turn the display off with @code{org-read-date-display-live}.}. -@node Custom time format +@node Custom time format, , The date/time prompt, Creating timestamps @subsection Custom time format @cindex custom date/time format @cindex time format, custom @@ -6246,7 +6246,7 @@ format is shorter, things do work as expected. @end itemize -@node Deadlines and scheduling +@node Deadlines and scheduling, Clocking work time, Creating timestamps, Dates and times @section Deadlines and scheduling A timestamp may be preceded by special keywords to facilitate planning. Both @@ -6337,7 +6337,7 @@ sexp entry matches. * Repeated tasks:: Items that show up again and again @end menu -@node Inserting deadline/schedule +@node Inserting deadline/schedule, Repeated tasks, Deadlines and scheduling, Deadlines and scheduling @subsection Inserting deadlines or schedules The following commands allow you to quickly insert a deadline or to schedule @@ -6384,7 +6384,7 @@ setting the date by indicating a relative time: e.g., +1d will set the date to the next day after today, and --1w will set the date to the previous week before any current timestamp. -@node Repeated tasks +@node Repeated tasks, , Inserting deadline/schedule, Deadlines and scheduling @subsection Repeated tasks @cindex tasks, repeated @cindex repeated tasks @@ -6485,7 +6485,7 @@ subtree, with dates shifted in each copy. The command @kbd{C-c C-x c} was created for this purpose, it is described in @ref{Structure editing}. -@node Clocking work time +@node Clocking work time, Effort estimates, Deadlines and scheduling, Dates and times @section Clocking work time @cindex clocking time @cindex time clocking @@ -6517,7 +6517,7 @@ what to do with it. * Resolving idle time:: Resolving time when you've been idle @end menu -@node Clocking commands +@node Clocking commands, The clock table, Clocking work time, Clocking work time @subsection Clocking commands @table @kbd @@ -6616,7 +6616,7 @@ which tasks have been worked on or closed during a day. @code{org-clock-in-last} can have a global key binding and will not modify the window disposition. -@node The clock table +@node The clock table, Resolving idle time, Clocking commands, Clocking work time @subsection The clock table @cindex clocktable, dynamic block @cindex report, of clocked time @@ -6768,7 +6768,7 @@ would be #+END: clocktable @end example -@node Resolving idle time +@node Resolving idle time, , The clock table, Clocking work time @subsection Resolving idle time and continuous clocking @subsubheading Resolving idle time @@ -6853,7 +6853,7 @@ last clocked entry for this session, and start the new clock from there. If you only want this from time to time, use three universal prefix arguments with @code{org-clock-in} and two @kbd{C-u C-u} with @code{org-clock-in-last}. -@node Effort estimates +@node Effort estimates, Timers, Clocking work time, Dates and times @section Effort estimates @cindex effort estimates @@ -6914,7 +6914,7 @@ with the @kbd{/} key in the agenda (@pxref{Agenda commands}). If you have these estimates defined consistently, two or three key presses will narrow down the list to stuff that fits into an available time slot. -@node Timers +@node Timers, , Effort estimates, Dates and times @section Taking notes with a timer @cindex relative timer @cindex countdown timer @@ -6964,7 +6964,7 @@ Stop the timer. After this, you can only start a new timer, not continue the old one. This command also removes the timer from the mode line. @end table -@node Capture - Refile - Archive +@node Capture - Refile - Archive, Agenda views, Dates and times, Top @chapter Capture - Refile - Archive @cindex capture @@ -6984,7 +6984,7 @@ trees to an archive file keeps the system compact and fast. * Archiving:: What to do with finished projects @end menu -@node Capture +@node Capture, Attachments, Capture - Refile - Archive, Capture - Refile - Archive @section Capture @cindex capture @@ -7011,7 +7011,7 @@ customization. * Capture templates:: Define the outline of different note types @end menu -@node Setting up capture +@node Setting up capture, Using capture, Capture, Capture @subsection Setting up capture The following customization sets a default target file for notes, and defines @@ -7026,7 +7026,7 @@ suggestion.} for capturing new material. @end group @end smalllisp -@node Using capture +@node Using capture, Capture templates, Setting up capture, Capture @subsection Using capture @table @kbd @@ -7083,7 +7083,7 @@ automatically be created unless you set @code{org-capture-bookmark} to To insert the capture at point in an Org buffer, call @code{org-capture} with a @code{C-0} prefix argument. -@node Capture templates +@node Capture templates, , Using capture, Capture @subsection Capture templates @cindex templates, for Capture @@ -7142,7 +7142,7 @@ like this: * Templates in contexts:: Only show a template in a specific context @end menu -@node Template elements +@node Template elements, Template expansion, Capture templates, Capture templates @subsubsection Template elements Now lets look at the elements of a template definition. Each entry in @@ -7307,7 +7307,7 @@ buffer again after capture is completed. @end table @end table -@node Template expansion +@node Template expansion, Templates in contexts, Template elements, Capture templates @subsubsection Template expansion In the template itself, special @kbd{%}-escapes@footnote{If you need one of @@ -7392,7 +7392,7 @@ To place the cursor after template expansion use: %? @r{After completing the template, position cursor here.} @end smallexample -@node Templates in contexts +@node Templates in contexts, , Template expansion, Capture templates @subsubsection Templates in contexts @vindex org-capture-templates-contexts @@ -7416,7 +7416,7 @@ template. In that case, add this command key like this: See the docstring of the variable for more information. -@node Attachments +@node Attachments, RSS feeds, Capture, Capture - Refile - Archive @section Attachments @cindex attachments @@ -7507,7 +7507,7 @@ same directory for attachments as the parent does. @end table @end table -@node RSS feeds +@node RSS feeds, Protocols, Attachments, Capture - Refile - Archive @section RSS feeds @cindex RSS feeds @cindex Atom feeds @@ -7550,7 +7550,7 @@ adding the same item several times. For more information, including how to read atom feeds, see @file{org-feed.el} and the docstring of @code{org-feed-alist}. -@node Protocols +@node Protocols, Refile and copy, RSS feeds, Capture - Refile - Archive @section Protocols for external access @cindex protocols, for external access @@ -7588,7 +7588,7 @@ sections. Configure @code{org-protocol-protocol-alist} to define your own. * @code{open-source} protocol:: Edit published contents. @end menu -@node @code{store-link} protocol +@node @code{store-link} protocol, @code{capture} protocol, Protocols, Protocols @subsection @code{store-link} protocol @cindex store-link protocol @cindex protocol, store-link @@ -7619,7 +7619,7 @@ javascript:location.href='org-protocol://store-link?url='+ encodeURIComponent(location.href); @end example -@node @code{capture} protocol +@node @code{capture} protocol, @code{open-source} protocol, @code{store-link} protocol, Protocols @subsection @code{capture} protocol @cindex capture protocol @cindex protocol, capture @@ -7661,7 +7661,7 @@ The following template placeholders are available: %i The selected text @end example -@node @code{open-source} protocol +@node @code{open-source} protocol, , @code{capture} protocol, Protocols @subsection @code{open-source} protocol @cindex open-source protocol @cindex protocol, open-source @@ -7758,7 +7758,7 @@ valid contents: @code{org-protocol-create} and @code{org-protocol-create-for-org}. The latter is of use if you're editing an Org file that is part of a publishing project. -@node Refile and copy +@node Refile and copy, Archiving, Protocols, Capture - Refile - Archive @section Refile and copy @cindex refiling notes @cindex copying notes @@ -7815,7 +7815,7 @@ setting @code{org-refile-use-cache}. To make the command see new possible targets, you have to clear the cache with this command. @end table -@node Archiving +@node Archiving, , Refile and copy, Capture - Refile - Archive @section Archiving @cindex archiving @@ -7836,7 +7836,7 @@ Archive the current entry using the command specified in the variable * Internal archiving:: Switch off a tree but keep it in the file @end menu -@node Moving subtrees +@node Moving subtrees, Internal archiving, Archiving, Archiving @subsection Moving a tree to the archive file @cindex external archiving @@ -7890,7 +7890,7 @@ outline path the archiving time etc. Configure the variable added. -@node Internal archiving +@node Internal archiving, , Moving subtrees, Archiving @subsection Internal archiving @cindex archive tag @@ -7954,7 +7954,7 @@ outline. @end table -@node Agenda views +@node Agenda views, Markup, Capture - Refile - Archive, Top @chapter Agenda views @cindex agenda views @@ -8021,7 +8021,7 @@ window configuration is restored when the agenda exits: * Agenda column view:: Using column view for collected entries @end menu -@node Agenda files +@node Agenda files, Agenda dispatcher, Agenda views, Agenda views @section Agenda files @cindex agenda files @cindex files for agenda @@ -8098,7 +8098,7 @@ effect immediately. Lift the restriction. @end table -@node Agenda dispatcher +@node Agenda dispatcher, Built-in agenda views, Agenda files, Agenda views @section The agenda dispatcher @cindex agenda dispatcher @cindex dispatching agenda commands @@ -8161,7 +8161,7 @@ possibility to create extended agenda buffers that contain several blocks together, for example the weekly agenda, the global TODO list and a number of special tags matches. @xref{Custom agenda views}. -@node Built-in agenda views +@node Built-in agenda views, Presentation and sorting, Agenda dispatcher, Agenda views @section The built-in agenda views In this section we describe the built-in views. @@ -8174,7 +8174,7 @@ In this section we describe the built-in views. * Stuck projects:: Find projects you need to review @end menu -@node Weekly/daily agenda +@node Weekly/daily agenda, Global TODO list, Built-in agenda views, Built-in agenda views @subsection The weekly/daily agenda @cindex agenda @cindex weekly agenda @@ -8333,7 +8333,7 @@ It also reads a @code{APPT_WARNTIME} property which will then override the value of @code{appt-message-warning-time} for this appointment. See the docstring for details. -@node Global TODO list +@node Global TODO list, Matching tags and properties, Weekly/daily agenda, Built-in agenda views @subsection The global TODO list @cindex global TODO list @cindex TODO list, global @@ -8394,7 +8394,7 @@ and omit the sublevels from the global list. Configure the variable @code{org-agenda-todo-list-sublevels} to get this behavior. @end itemize -@node Matching tags and properties +@node Matching tags and properties, Search view, Global TODO list, Built-in agenda views @subsection Matching tags and properties @cindex matching, of tags @cindex matching, of properties @@ -8567,7 +8567,7 @@ Select @samp{:work:}-tagged TODO lines that are either @samp{WAITING} or @samp{NEXT}. @end table -@node Search view +@node Search view, Stuck projects, Matching tags and properties, Built-in agenda views @subsection Search view @cindex search view @cindex text search @@ -8597,7 +8597,7 @@ the docstring of the command @code{org-search-view}. Note that in addition to the agenda files, this command will also search the files listed in @code{org-agenda-text-search-extra-files}. -@node Stuck projects +@node Stuck projects, , Search view, Built-in agenda views @subsection Stuck projects @pindex GTD, Getting Things Done @@ -8645,7 +8645,7 @@ correct customization for this is Note that if a project is identified as non-stuck, the subtree of this entry will still be searched for stuck projects. -@node Presentation and sorting +@node Presentation and sorting, Agenda commands, Built-in agenda views, Agenda views @section Presentation and sorting @cindex presentation, of agenda items @@ -8667,7 +8667,7 @@ associated with the item. * Filtering/limiting agenda items:: Dynamically narrow the agenda @end menu -@node Categories +@node Categories, Time-of-day specifications, Presentation and sorting, Presentation and sorting @subsection Categories @cindex category @@ -8694,7 +8694,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 +@node Time-of-day specifications, Sorting agenda items, Categories, Presentation and sorting @subsection Time-of-day specifications @cindex time-of-day specification @@ -8745,7 +8745,7 @@ 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 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 @@ -8779,7 +8779,7 @@ 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 +@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 @@ -8965,7 +8965,7 @@ rebuilding the agenda: This prompts for the type of limit to apply and its value. @end table -@node Agenda commands +@node Agenda commands, Custom agenda views, Presentation and sorting, Agenda views @section Commands in the agenda buffer @cindex commands, in agenda buffer @@ -9488,7 +9488,7 @@ visit Org files will not be removed. @end table -@node Custom agenda views +@node Custom agenda views, Exporting agenda views, Agenda commands, Agenda views @section Custom agenda views @cindex custom agenda views @cindex agenda views, custom @@ -9504,7 +9504,7 @@ dispatcher (@pxref{Agenda dispatcher}), just like the default commands. * Setting options:: Changing the rules @end menu -@node Storing searches +@node Storing searches, Block agenda, Custom agenda views, Custom agenda views @subsection Storing searches The first application of custom searches is the definition of keyboard @@ -9596,7 +9596,7 @@ Peter, or Kim) as additional tag to match. Note that the @code{*-tree} agenda views need to be called from an Org buffer as they operate on the current buffer only. -@node Block agenda +@node Block agenda, Setting options, Storing searches, Custom agenda views @subsection Block agenda @cindex block agenda @cindex agenda, with block views @@ -9630,7 +9630,7 @@ your agenda for the current week, all TODO items that carry the tag @samp{home}, and also all lines tagged with @samp{garden}. Finally the command @kbd{C-c a o} provides a similar view for office tasks. -@node Setting options +@node Setting options, , Block agenda, Custom agenda views @subsection Setting options for custom commands @cindex options, for custom agenda views @@ -9722,7 +9722,7 @@ command key @code{"r"}. In that case, add this command key like this: See the docstring of the variable for more information. -@node Exporting agenda views +@node Exporting agenda views, Agenda column view, Custom agenda views, Agenda views @section Exporting agenda views @cindex agenda views, exporting @@ -9862,7 +9862,7 @@ processing by other programs. See @ref{Extracting agenda information}, for more information. -@node Agenda column view +@node Agenda column view, , Exporting agenda views, Agenda views @section Using column view in the agenda @cindex column view, in agenda @cindex agenda, column view @@ -9928,7 +9928,7 @@ spent ---via @code{CLOCKSUM}---and with the planned total effort for it. @end enumerate -@node Markup +@node Markup, Exporting, Agenda views, Top @chapter Markup for rich export When exporting Org mode documents, the exporter tries to reflect the @@ -9948,7 +9948,7 @@ markup rules used in an Org mode buffer. * Embedded @LaTeX{}:: LaTeX can be freely used inside Org documents @end menu -@node Paragraphs +@node Paragraphs, Emphasis and monospace, Markup, Markup @section Paragraphs, line breaks, and quoting @cindex paragraphs, markup rules @@ -9994,7 +9994,7 @@ but not any simpler #+END_CENTER @end example -@node Emphasis and monospace +@node Emphasis and monospace, Horizontal rules, Paragraphs, Markup @section Emphasis and monospace @cindex underlined text, markup rules @@ -10019,13 +10019,13 @@ 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 +@node Horizontal rules, Images and tables, Emphasis and monospace, Markup @section Horizontal rules @cindex horizontal rules, markup rules A line consisting of only dashes, and at least 5 of them, will be exported as a horizontal line. -@node Images and tables +@node Images and tables, Literal examples, Horizontal rules, Markup @section Images and Tables @cindex tables, markup rules @@ -10073,7 +10073,7 @@ the same caption mechanism can apply to many others (e.g., @LaTeX{} equations, source code blocks). Depending on the export back-end, those may or may not be handled. -@node Literal examples +@node Literal examples, Special symbols, Images and tables, Markup @section Literal examples @cindex literal examples, markup rules @cindex code line references, markup rules @@ -10213,7 +10213,7 @@ formatting like @samp{(ref:label)} at the end of the current line. Then the label is stored as a link @samp{(label)}, for retrieval with @kbd{C-c C-l}. @end table -@node Special symbols +@node Special symbols, Subscripts and superscripts, Literal examples, Markup @section Special symbols @cindex Org entities @cindex math symbols @@ -10274,7 +10274,7 @@ way@footnote{This behaviour can be disabled with @code{-} export setting combinations: @samp{\-} is treated as a shy hyphen, @samp{--} and @samp{---} are converted into dashes, and @samp{...} becomes a compact set of dots. -@node Subscripts and superscripts +@node Subscripts and superscripts, Embedded @LaTeX{}, Special symbols, Markup @section Subscripts and superscripts @cindex subscript @cindex superscript @@ -10303,7 +10303,7 @@ In addition to showing entities as UTF-8 characters, this command will also format sub- and superscripts in a WYSIWYM way. @end table -@node Embedded @LaTeX{} +@node Embedded @LaTeX{}, , Subscripts and superscripts, Markup @section Embedded @LaTeX{} @cindex @TeX{} interpretation @cindex @LaTeX{} interpretation @@ -10324,7 +10324,7 @@ readily processed to produce pretty output for a number of export back-ends. * CDLaTeX mode:: Speed up entering of formulas @end menu -@node @LaTeX{} fragments +@node @LaTeX{} fragments, Previewing @LaTeX{} fragments, Embedded @LaTeX{}, Embedded @LaTeX{} @subsection @LaTeX{} fragments @cindex @LaTeX{} fragments @@ -10388,7 +10388,7 @@ lines: #+OPTIONS: tex:verbatim @r{Verbatim export, for jsMath or so} @end example -@node Previewing @LaTeX{} fragments +@node Previewing @LaTeX{} fragments, CDLaTeX mode, @LaTeX{} fragments, Embedded @LaTeX{} @subsection Previewing @LaTeX{} fragments @cindex @LaTeX{} fragments, preview @@ -10436,7 +10436,7 @@ To disable it, simply use #+STARTUP: nolatexpreview @end example -@node CDLaTeX mode +@node CDLaTeX mode, , Previewing @LaTeX{} fragments, Embedded @LaTeX{} @subsection Using CD@LaTeX{} to enter math @cindex CD@LaTeX{} @@ -10497,7 +10497,7 @@ modification will work only inside @LaTeX{} fragments; outside the quote is normal. @end itemize -@node Exporting +@node Exporting, Publishing, Markup, Top @chapter Exporting @cindex exporting @@ -10564,7 +10564,7 @@ library in the Emacs init file like this: * Export in foreign buffers:: Author tables and lists in Org syntax @end menu -@node The export dispatcher +@node The export dispatcher, Export settings, Exporting, Exporting @section The export dispatcher @vindex org-export-dispatch-use-expert-ui @cindex Export, dispatcher @@ -10631,7 +10631,7 @@ Toggle visible-only export. Useful for exporting only visible parts of an Org document by adjusting outline visibility settings. @end table -@node Export settings +@node Export settings, Table of contents, The export dispatcher, Exporting @section Export settings @cindex Export, settings @@ -10903,7 +10903,7 @@ 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 keywords. -@node Table of contents +@node Table of contents, Include files, Export settings, Exporting @section Table of contents @cindex table of contents @cindex list of tables @@ -10980,7 +10980,7 @@ Normally Org uses the headline for its entry in the table of contents. But with @code{ALT_TITLE} property, a different entry can be specified for the table of contents. -@node Include files +@node Include files, Macro replacement, Table of contents, Exporting @section Include files @cindex include files, during export Include other files during export. For example, to include your @file{.emacs} @@ -11054,7 +11054,7 @@ element. Some examples: Visit the include file at point. @end table -@node Macro replacement +@node Macro replacement, Comment lines, Include files, Exporting @section Macro replacement @cindex macro replacement, during export @cindex #+MACRO @@ -11140,7 +11140,7 @@ The surrounding brackets can be made invisible by setting Org expands macros at the very beginning of the export process. -@node Comment lines +@node Comment lines, ASCII/Latin-1/UTF-8 export, Macro replacement, Exporting @section Comment lines @cindex exporting, not @@ -11167,7 +11167,7 @@ comment status of a headline. Toggle the @samp{COMMENT} keyword at the beginning of an entry. @end table -@node ASCII/Latin-1/UTF-8 export +@node ASCII/Latin-1/UTF-8 export, Beamer export, Comment lines, Exporting @section ASCII/Latin-1/UTF-8 export @cindex ASCII export @cindex Latin-1 export @@ -11267,7 +11267,7 @@ It's just a jump to the left... #+END_JUSTIFYRIGHT @end example -@node Beamer export +@node Beamer export, HTML export, ASCII/Latin-1/UTF-8 export, Exporting @section Beamer export @cindex Beamer export @@ -11285,7 +11285,7 @@ popular display formats. * A Beamer example:: A complete presentation. @end menu -@node Beamer export commands +@node Beamer export commands, Beamer specific export settings, Beamer export, Beamer export @subsection Beamer export commands @table @kbd @@ -11301,7 +11301,7 @@ Export as @LaTeX{} file, convert it to PDF format, and then open the PDF file. @end table -@node Beamer specific export settings +@node Beamer specific export settings, Sectioning Frames and Blocks in Beamer, Beamer export commands, Beamer export @subsection Beamer specific export settings Beamer export back-end has several additional keywords for customizing Beamer @@ -11360,7 +11360,7 @@ metadata. Use @code{org-latex-title-command} to configure typesetting of subtitle as part of front matter. @end table -@node Sectioning Frames and Blocks in Beamer +@node Sectioning Frames and Blocks in Beamer, Beamer specific syntax, Beamer specific export settings, Beamer export @subsection Sectioning, Frames and Blocks in Beamer Org transforms heading levels into Beamer's sectioning elements, frames and @@ -11429,7 +11429,7 @@ Beamer export automatically handles @LaTeX{} column separations for contiguous headlines. To manually adjust them for any unique configurations needs, use the @code{BEAMER_ENV} property. -@node Beamer specific syntax +@node Beamer specific syntax, Editing support, Sectioning Frames and Blocks in Beamer, Beamer export @subsection Beamer specific syntax Since Org's Beamer export back-end is an extension of the @LaTeX{} back-end, it recognizes other @LaTeX{} specific syntax---for example, @samp{#+LATEX:} @@ -11493,7 +11493,7 @@ Let $G$ be a finite group, and let $H$ be a subgroup of $G$. Then the order of $H$ divides the order of $G$. @end example -@node Editing support +@node Editing support, A Beamer example, Beamer specific syntax, Beamer export @subsection Editing support @@ -11510,7 +11510,7 @@ The @code{org-beamer-mode} provides this key for quicker selections in Beamer normal environments, and for selecting the @code{BEAMER_COL} property. @end table -@node A Beamer example +@node A Beamer example, , Editing support, Beamer export @subsection A Beamer example Here is an example of an Org document ready for Beamer export. @@ -11549,7 +11549,7 @@ Here is an example of an Org document ready for Beamer export. Please test this stuff! @end example -@node HTML export +@node HTML export, @LaTeX{} export, Beamer export, Exporting @section HTML export @cindex HTML export @@ -11572,7 +11572,7 @@ with XHTML 1.0 strict standard. @end menu -@node HTML Export commands +@node HTML Export commands, HTML Specific export settings, HTML export, HTML export @subsection HTML export commands @table @kbd @@ -11585,7 +11585,7 @@ h o} Exports to HTML and opens it in a web browser. Exports to a temporary buffer. Does not create a file. @end table -@node HTML Specific export settings +@node HTML Specific export settings, HTML doctypes, HTML Export commands, HTML export @subsection HTML Specific export settings HTML export has a number of keywords, similar to the general options settings described in @ref{Export settings}. @@ -11659,7 +11659,7 @@ The document's subtitle. HTML exporter formats subtitle if document type is Some of these keywords are explained in more detail in the following sections of the manual. -@node HTML doctypes +@node HTML doctypes, HTML preamble and postamble, HTML Specific export settings, HTML export @subsection HTML doctypes Org can export to various (X)HTML flavors. @@ -11747,7 +11747,7 @@ Special blocks cannot have headlines. For the HTML exporter to wrap the headline and its contents in @samp{<section>} or @samp{<article>} tags, set the @code{HTML_CONTAINER} property for the headline. -@node HTML preamble and postamble +@node HTML preamble and postamble, Quoting HTML tags, HTML doctypes, HTML export @subsection HTML preamble and postamble @vindex org-html-preamble @vindex org-html-postamble @@ -11775,7 +11775,7 @@ to insert the postamble in the format specified in the @code{org-html-postamble-format} variable. The HTML exporter will not insert a postamble if @code{org-html-postamble} is set to @code{nil}. -@node Quoting HTML tags +@node Quoting HTML tags, Links in HTML export, HTML preamble and postamble, HTML export @subsection Quoting HTML tags The HTML export back-end transforms @samp{<} and @samp{>} to @samp{<} and @@ -11801,7 +11801,7 @@ All lines between these markers are exported literally @end example -@node Links in HTML export +@node Links in HTML export, Tables in HTML export, Quoting HTML tags, HTML export @subsection Links in HTML export @cindex links, in HTML export @@ -11835,7 +11835,7 @@ to @code{<a>} or @code{<img>} tags. This example shows changing the link's [[http://orgmode.org]] @end example -@node Tables in HTML export +@node Tables in HTML export, Images in HTML export, Links in HTML export, HTML export @subsection Tables in HTML export @cindex tables, in HTML @vindex org-html-table-default-attributes @@ -11887,7 +11887,7 @@ Opening and ending tags for table rows. Non-@code{nil} formats column one in tables with header tags. @end table -@node Images in HTML export +@node Images in HTML export, Math formatting in HTML export, Tables in HTML export, HTML export @subsection Images in HTML export @cindex images, inline in HTML @@ -11931,7 +11931,7 @@ standards. The HTML export back-end copies the @code{http} links from the Org file as is. -@node Math formatting in HTML export +@node Math formatting in HTML export, Text areas in HTML export, Images in HTML export, HTML export @subsection Math formatting in HTML export @cindex MathJax @cindex dvipng @@ -11976,7 +11976,7 @@ or: #+OPTIONS: tex:imagemagick @end example -@node Text areas in HTML export +@node Text areas in HTML export, CSS support, Math formatting in HTML export, HTML export @subsection Text areas in HTML export @cindex text areas, in HTML @@ -12005,7 +12005,7 @@ and height just enough to fit the content. Override these defaults with @end example -@node CSS support +@node CSS support, JavaScript support, Text areas in HTML export, HTML export @subsection CSS support @cindex CSS, for HTML export @cindex HTML export, CSS @@ -12096,7 +12096,7 @@ simpler ways of customizing as described above. @c FIXME: More about header and footer styles @c FIXME: Talk about links and targets. -@node JavaScript support +@node JavaScript support, , CSS support, HTML export @subsection JavaScript supported display of web pages @cindex Rose, Sebastian @@ -12158,7 +12158,7 @@ You can choose default values for these options by customizing the variable @code{org-html-infojs-options}. If you want the script to always apply to your pages, configure the variable @code{org-html-use-infojs}. -@node @LaTeX{} export +@node @LaTeX{} export, Markdown export, HTML export, Exporting @section @LaTeX{} export @cindex @LaTeX{} export @cindex PDF export @@ -12193,7 +12193,7 @@ blank lines to tell apart syntactical elements, such as paragraphs. * Horizontal rules in @LaTeX{} export:: Attributes specific to horizontal rules. @end menu -@node @LaTeX{} export commands +@node @LaTeX{} export commands, @LaTeX{} specific export settings, @LaTeX{} export, @LaTeX{} export @subsection @LaTeX{} export commands @table @kbd @@ -12226,7 +12226,7 @@ compilers for different files. However, ``smart'' @LaTeX{} compilation systems, such as @samp{latexmk}, can select the correct bibliography compiler.}. -@node @LaTeX{} specific export settings +@node @LaTeX{} specific export settings, @LaTeX{} header and sectioning, @LaTeX{} export commands, @LaTeX{} export @subsection @LaTeX{} specific export settings The @LaTeX{} export back-end has several additional keywords for customizing @@ -12302,7 +12302,7 @@ document's front matter. The following sections have further details. -@node @LaTeX{} header and sectioning +@node @LaTeX{} header and sectioning, Quoting @LaTeX{} code, @LaTeX{} specific export settings, @LaTeX{} export @subsection @LaTeX{} header and sectioning structure @cindex @LaTeX{} class @cindex @LaTeX{} sectioning structure @@ -12365,7 +12365,7 @@ A sample Org file with the above headers: some more text @end example -@node Quoting @LaTeX{} code +@node Quoting @LaTeX{} code, Tables in @LaTeX{} export, @LaTeX{} header and sectioning, @LaTeX{} export @subsection Quoting @LaTeX{} code The @LaTeX{} export back-end can insert any arbitrary @LaTeX{} code, @@ -12393,7 +12393,7 @@ any arbitrary LaTeX code #+END_EXPORT @end example -@node Tables in @LaTeX{} export +@node Tables in @LaTeX{} export, Images in @LaTeX{} export, Quoting @LaTeX{} code, @LaTeX{} export @subsection Tables in @LaTeX{} export @cindex tables, in @LaTeX{} export @cindex #+ATTR_LATEX, in tables @@ -12496,7 +12496,7 @@ Set the caption with the @LaTeX{} command @end example -@node Images in @LaTeX{} export +@node Images in @LaTeX{} export, Plain lists in @LaTeX{} export, Tables in @LaTeX{} export, @LaTeX{} export @subsection Images in @LaTeX{} export @cindex images, inline in @LaTeX{} @cindex inlining images in @LaTeX{} @@ -12567,7 +12567,7 @@ centering globally, set @code{org-latex-images-centered} to @code{t}. Set the @code{:comment-include} attribute to non-@code{nil} value for the @LaTeX{} export back-end to comment out the @code{\includegraphics} macro. -@node Plain lists in @LaTeX{} export +@node Plain lists in @LaTeX{} export, Source blocks in @LaTeX{} export, Images in @LaTeX{} export, @LaTeX{} export @subsection Plain lists in @LaTeX{} export @cindex plain lists, in @LaTeX{} export @cindex #+ATTR_LATEX, in plain lists @@ -12601,7 +12601,7 @@ four: - Five @end example -@node Source blocks in @LaTeX{} export +@node Source blocks in @LaTeX{} export, Example blocks in @LaTeX{} export, Plain lists in @LaTeX{} export, @LaTeX{} export @subsection Source blocks in @LaTeX{} export @cindex source blocks, in @LaTeX{} export @cindex #+ATTR_LATEX, in source blocks @@ -12647,7 +12647,7 @@ To apply similar configuration options for all source blocks in a file, use the @code{org-latex-listings-options} and @code{org-latex-minted-options} variables. -@node Example blocks in @LaTeX{} export +@node Example blocks in @LaTeX{} export, Special blocks in @LaTeX{} export, Source blocks in @LaTeX{} export, @LaTeX{} export @subsection Example blocks in @LaTeX{} export @cindex example blocks, in @LaTeX{} export @cindex verbatim blocks, in @LaTeX{} export @@ -12666,7 +12666,7 @@ This sentence is false. #+END_EXAMPLE @end example -@node Special blocks in @LaTeX{} export +@node Special blocks in @LaTeX{} export, Horizontal rules in @LaTeX{} export, Example blocks in @LaTeX{} export, @LaTeX{} export @subsection Special blocks in @LaTeX{} export @cindex special blocks, in @LaTeX{} export @cindex abstract, in @LaTeX{} export @@ -12716,7 +12716,7 @@ example: #+END_proof @end example -@node Horizontal rules in @LaTeX{} export +@node Horizontal rules in @LaTeX{} export, , Special blocks in @LaTeX{} export, @LaTeX{} export @subsection Horizontal rules in @LaTeX{} export @cindex horizontal rules, in @LaTeX{} export @cindex #+ATTR_LATEX, in horizontal rules @@ -12729,7 +12729,7 @@ The @LaTeX{} export back-end converts horizontal rules by the specified ----- @end example -@node Markdown export +@node Markdown export, OpenDocument Text export, @LaTeX{} export, Exporting @section Markdown export @cindex Markdown export @@ -12763,7 +12763,7 @@ level before the absolute limit (@pxref{Export settings}). @c begin opendocument -@node OpenDocument Text export +@node OpenDocument Text export, Org export, Markdown export, Exporting @section OpenDocument Text export @cindex ODT @cindex OpenDocument @@ -12791,14 +12791,14 @@ is compatible with LibreOffice 3.4. * Advanced topics in ODT export:: For power users. @end menu -@node Pre-requisites for ODT export +@node Pre-requisites for ODT export, ODT export commands, OpenDocument Text export, OpenDocument Text export @subsection Pre-requisites for ODT export @cindex zip The ODT export back-end relies on the @file{zip} program to create the final compressed ODT output. Check if @file{zip} is locally available and executable. Without @file{zip}, export cannot finish. -@node ODT export commands +@node ODT export commands, ODT specific export settings, Pre-requisites for ODT export, OpenDocument Text export @subsection ODT export commands @anchor{x-export-to-odt} @cindex region, active @@ -12835,7 +12835,7 @@ file instead. @xref{x-export-to-other-formats, , Automatically exporting to other formats}. @end table -@node ODT specific export settings +@node ODT specific export settings, Extending ODT export, ODT export commands, OpenDocument Text export @subsection ODT specific export settings The ODT export back-end has several additional keywords for customizing ODT output. Setting these keywords works similar to the general options @@ -12866,7 +12866,7 @@ The ODT export back-end uses the @code{org-odt-styles-file} by default. See The document subtitle. @end table -@node Extending ODT export +@node Extending ODT export, Applying custom styles, ODT specific export settings, OpenDocument Text export @subsection Extending ODT export The ODT export back-end can produce documents in other formats besides ODT @@ -12909,7 +12909,7 @@ Convert an existing document from one format to another. With a prefix argument, opens the newly produced file. @end table -@node Applying custom styles +@node Applying custom styles, Links in ODT export, Extending ODT export, OpenDocument Text export @subsection Applying custom styles @cindex styles, custom @cindex template, custom @@ -12965,7 +12965,7 @@ The ODT export back-end relies on many templates and style names. Using third-party styles and templates can lead to mismatches. Templates derived from built in ODT templates and styles seem to have fewer problems. -@node Links in ODT export +@node Links in ODT export, Tables in ODT export, Applying custom styles, OpenDocument Text export @subsection Links in ODT export @cindex links, in ODT export @@ -12979,7 +12979,7 @@ A @samp{\ref@{label@}}-style reference to an image, table etc.@: is replaced with a cross-reference and sequence number of the labeled entity. @xref{Labels and captions in ODT export}. -@node Tables in ODT export +@node Tables in ODT export, Images in ODT export, Links in ODT export, OpenDocument Text export @subsection Tables in ODT export @cindex tables, in ODT export @@ -13024,7 +13024,7 @@ For even more customization, create custom table styles and associate them with a table using the @code{#+ATTR_ODT} line. @xref{Customizing tables in ODT export}. -@node Images in ODT export +@node Images in ODT export, Math formatting in ODT export, Tables in ODT export, OpenDocument Text export @subsection Images in ODT export @cindex images, embedding in ODT @cindex embedding images in ODT @@ -13121,7 +13121,7 @@ To create an image that is anchored to a page: [[./img.png]] @end example -@node Math formatting in ODT export +@node Math formatting in ODT export, Labels and captions in ODT export, Images in ODT export, OpenDocument Text export @subsection Math formatting in ODT export The ODT export back-end has special support built-in for handling math. @@ -13131,7 +13131,7 @@ The ODT export back-end has special support built-in for handling math. * Working with MathML or OpenDocument formula files:: Embedding in native format. @end menu -@node Working with @LaTeX{} math snippets +@node Working with @LaTeX{} math snippets, Working with MathML or OpenDocument formula files, Math formatting in ODT export, Math formatting in ODT export @subsubheading Working with @LaTeX{} math snippets @LaTeX{} math snippets (@pxref{@LaTeX{} fragments}) can be embedded in an ODT @@ -13214,7 +13214,7 @@ requires @file{dvipng} program, @file{dvisvgm} or @file{imagemagick} programs. @end enumerate -@node Working with MathML or OpenDocument formula files +@node Working with MathML or OpenDocument formula files, , Working with @LaTeX{} math snippets, Math formatting in ODT export @subsubheading Working with MathML or OpenDocument formula files When embedding @LaTeX{} math snippets in ODT documents is not reliable, there @@ -13232,7 +13232,7 @@ or [[./equation.odf]] @end example -@node Labels and captions in ODT export +@node Labels and captions in ODT export, Literal examples in ODT export, Math formatting in ODT export, OpenDocument Text export @subsection Labels and captions in ODT export ODT format handles labeling and captioning of objects based on their @@ -13270,7 +13270,7 @@ With the above modification, the previous example changes to: Illustration 2: Bell curve @end example -@node Literal examples in ODT export +@node Literal examples in ODT export, Advanced topics in ODT export, Labels and captions in ODT export, OpenDocument Text export @subsection Literal examples in ODT export The ODT export back-end supports literal examples (@pxref{Literal examples}) @@ -13288,7 +13288,7 @@ For custom fontification styles, customize the To turn off fontification of literal examples, customize the @code{org-odt-fontify-srcblocks} option. -@node Advanced topics in ODT export +@node Advanced topics in ODT export, , Literal examples in ODT export, OpenDocument Text export @subsection Advanced topics in ODT export The ODT export back-end has extensive features useful for power users and @@ -13302,7 +13302,7 @@ frequent uses of ODT formats. * Validating OpenDocument XML:: Debugging corrupted OpenDocument files. @end menu -@node Configuring a document converter +@node Configuring a document converter, Working with OpenDocument style files, Advanced topics in ODT export, Advanced topics in ODT export @subsubheading Configuring a document converter @cindex convert @cindex doc, docx, rtf @@ -13335,7 +13335,7 @@ Select the newly added converter as the preferred one by customizing the option @code{org-odt-convert-process}. @end enumerate -@node Working with OpenDocument style files +@node Working with OpenDocument style files, Creating one-off styles, Configuring a document converter, Advanced topics in ODT export @subsubheading Working with OpenDocument style files @cindex styles, custom @cindex template, custom @@ -13438,7 +13438,7 @@ Use this variable to specify the blank @file{content.xml} that will be used in the final output. @end itemize -@node Creating one-off styles +@node Creating one-off styles, Customizing tables in ODT export, Working with OpenDocument style files, Advanced topics in ODT export @subsubheading Creating one-off styles The ODT export back-end can read embedded raw OpenDocument XML from the Org @@ -13504,7 +13504,7 @@ This paragraph is specially formatted and uses bold text. @end enumerate -@node Customizing tables in ODT export +@node Customizing tables in ODT export, Validating OpenDocument XML, Creating one-off styles, Advanced topics in ODT export @subsubheading Customizing tables in ODT export @cindex tables, in ODT export @@ -13666,7 +13666,7 @@ the @code{ATTR_ODT} line as shown below. @end example @end enumerate -@node Validating OpenDocument XML +@node Validating OpenDocument XML, , Customizing tables in ODT export, Advanced topics in ODT export @subsubheading Validating OpenDocument XML Sometimes ODT format files may not open due to @file{.odt} file corruption. @@ -13685,7 +13685,7 @@ back-end takes care of updating the @code{rng-schema-locating-files}. @c end opendocument -@node Org export +@node Org export, Texinfo export, OpenDocument Text export, Exporting @section Org export @cindex Org export @@ -13706,7 +13706,7 @@ Export to a temporary buffer. Does not create a file. Export to an Org file, then open it. @end table -@node Texinfo export +@node Texinfo export, iCalendar export, Org export, Exporting @section Texinfo export @cindex Texinfo export @@ -13718,7 +13718,7 @@ can compile to Info format. * Texinfo specific export settings:: Setting the environment. * Texinfo file header:: Generating the header. * Texinfo title and copyright page:: Creating preamble pages. -* Info directory file:: Installing a manual in Info file hierarchy. +* Info directory file:: Installing a manual in Info file hierarchy. * Headings and sectioning structure:: Building document structure. * Indices:: Creating indices. * Quoting Texinfo code:: Incorporating literal Texinfo code. @@ -13729,7 +13729,7 @@ can compile to Info format. * A Texinfo example:: Processing Org to Texinfo. @end menu -@node Texinfo export commands +@node Texinfo export commands, Texinfo specific export settings, Texinfo export, Texinfo export @subsection Texinfo export commands @vindex org-texinfo-info-process @@ -13743,7 +13743,7 @@ generate other formats, such as DocBook, customize the @code{org-texinfo-info-process} variable. @end table -@node Texinfo specific export settings +@node Texinfo specific export settings, Texinfo file header, Texinfo export commands, Texinfo export @subsection Texinfo specific export settings The Texinfo export back-end has several additional keywords for customizing Texinfo output. Setting these keywords works similar to the general options @@ -13794,7 +13794,7 @@ The directory description of the document. The printed title of the document. @end table -@node Texinfo file header +@node Texinfo file header, Texinfo title and copyright page, Texinfo specific export settings, Texinfo export @subsection Texinfo file header @cindex #+TEXINFO_FILENAME @@ -13817,7 +13817,7 @@ Instead of repeatedly installing the same set of commands, define a class in @code{org-texinfo-classes} once, and then activate it in the document by setting the @code{#+TEXINFO_CLASS} keyword to that class. -@node Texinfo title and copyright page +@node Texinfo title and copyright page, Info directory file, Texinfo file header, Texinfo export @subsection Texinfo title and copyright page @cindex #+TEXINFO_PRINTED_TITLE @@ -13856,7 +13856,7 @@ Copyright information is printed on the back of the title page. Copyright \copy 2016 Free Software Foundation, Inc. @end example -@node Info directory file +@node Info directory file, Headings and sectioning structure, Texinfo title and copyright page, Texinfo export @subsection Info directory file @cindex @samp{dir} file, in Texinfo export @cindex Texinfo export, @samp{dir} file @@ -13882,7 +13882,7 @@ Here is an example that writes to the Info directory file: #+TEXINFO_DIR_DESC: Outline-based notes management and organizer @end example -@node Headings and sectioning structure +@node Headings and sectioning structure, Indices, Info directory file, Texinfo export @subsection Headings and sectioning structure @vindex org-texinfo-classes @@ -13930,7 +13930,7 @@ node in which a reader enters an Info manual. As such, it is expected not to appear in printed output generated from the @file{.texi} file. @inforef{The Top Node,,texinfo}, for more information. -@node Indices +@node Indices, Quoting Texinfo code, Headings and sectioning structure, Texinfo export @subsection Indices @cindex #+CINDEX @@ -13976,7 +13976,7 @@ inserts the index after its contents. :END: @end example -@node Quoting Texinfo code +@node Quoting Texinfo code, Plain lists in Texinfo export, Indices, Texinfo export @subsection Quoting Texinfo code Use any of the following three methods to insert or escape raw Texinfo code: @@ -13995,7 +13995,7 @@ This paragraph is preceded by... #+END_EXPORT @end example -@node Plain lists in Texinfo export +@node Plain lists in Texinfo export, Tables in Texinfo export, Quoting Texinfo code, Texinfo export @subsection Plain lists in Texinfo export @cindex #+ATTR_TEXINFO, in plain lists @cindex Two-column tables, in Texinfo export @@ -14039,7 +14039,7 @@ This is the common text for variables foo and bar. @@end table @end example -@node Tables in Texinfo export +@node Tables in Texinfo export, Images in Texinfo export, Plain lists in Texinfo export, Texinfo export @subsection Tables in Texinfo export @cindex #+ATTR_TEXINFO, in tables @@ -14052,7 +14052,7 @@ length, use the @code{:columns} attribute. See example below. | a cell | another cell | @end example -@node Images in Texinfo export +@node Images in Texinfo export, Special blocks in Texinfo export, Tables in Texinfo export, Texinfo export @subsection Images in Texinfo export @cindex #+ATTR_TEXINFO, in images @@ -14067,7 +14067,7 @@ the text using Texinfo code, as shown in the example: [[ridt.pdf]] @end example -@node Special blocks in Texinfo export +@node Special blocks in Texinfo export, A Texinfo example, Images in Texinfo export, Texinfo export @subsection Special blocks @cindex #+ATTR_TEXINFO, in special blocks @@ -14091,7 +14091,7 @@ A somewhat obsessive function. @@end defun @end example -@node A Texinfo example +@node A Texinfo example, , Special blocks in Texinfo export, Texinfo export @subsection A Texinfo example Here is a more detailed example Org file. See @ref{GNU Sample @@ -14163,7 +14163,7 @@ This manual is for GNU Sample (version @{@{@{version@}@}@}, :END: @end example -@node iCalendar export +@node iCalendar export, Other built-in back-ends, Texinfo export, Exporting @section iCalendar export @cindex iCalendar export @@ -14246,7 +14246,7 @@ Exporting to iCalendar format depends in large part on the capabilities of the destination application. Some are more lenient than others. Consult the Org mode FAQ for advice on specific applications. -@node Other built-in back-ends +@node Other built-in back-ends, Advanced configuration, iCalendar export, Exporting @section Other built-in back-ends @cindex export back-ends, built-in @vindex org-export-backends @@ -14265,7 +14265,7 @@ dispatcher}). Follow the comment section of such files, for example, @file{ox-man.el}, for usage and configuration details. -@node Advanced configuration +@node Advanced configuration, Export in foreign buffers, Other built-in back-ends, Exporting @section Advanced configuration @subheading Hooks @@ -14463,7 +14463,7 @@ To use the newly defined back-end, call the following from an Org buffer: Further steps to consider would be an interactive function, self-installing an item in the export dispatcher menu, and other user-friendly improvements. -@node Export in foreign buffers +@node Export in foreign buffers, , Advanced configuration, Exporting @section Export in foreign buffers The export back-ends in Org often include commands to convert selected @@ -14488,7 +14488,7 @@ commands to create a list, select it, and covert it to HTML with @code{M-x org-html-convert-region-to-html RET}. -@node Publishing +@node Publishing, Working with source code, Exporting, Top @chapter Publishing @cindex publishing @@ -14510,7 +14510,7 @@ Publishing has been contributed to Org by David O'Toole. * Triggering publication:: Publication commands @end menu -@node Configuration +@node Configuration, Uploading files, Publishing, Publishing @section Configuration Publishing needs significant configuration to specify files, destination @@ -14527,7 +14527,7 @@ and many other properties of a project. * Generating an index:: An index that reaches across pages @end menu -@node Project alist +@node Project alist, Sources and destinations, Configuration, Configuration @subsection The variable @code{org-publish-project-alist} @cindex org-publish-project-alist @cindex projects, for publishing @@ -14554,7 +14554,7 @@ together files requiring different publishing options. When you publish such a ``meta-project'', all the components will also be published, in the sequence given. -@node Sources and destinations +@node Sources and destinations, Selecting files, Project alist, Configuration @subsection Sources and destinations for files @cindex directories, for publishing @@ -14583,7 +14583,7 @@ list. @end multitable @noindent -@node Selecting files +@node Selecting files, Publishing action, Sources and destinations, Configuration @subsection Selecting files @cindex files, selecting for publishing @@ -14609,7 +14609,7 @@ and @code{:exclude}. @tab non-@code{nil} means, check base-directory recursively for files to publish. @end multitable -@node Publishing action +@node Publishing action, Publishing options, Selecting files, Configuration @subsection Publishing action @cindex action, for publishing @@ -14648,7 +14648,7 @@ and the path to the publishing directory of the output file. It should take the specified file, make the necessary transformation (if any) and place the result into the destination folder. -@node Publishing options +@node Publishing options, Publishing links, Publishing action, Configuration @subsection Options for the exporters @cindex options, for publishing @@ -14877,7 +14877,7 @@ however, override everything. @item @code{:texinfo-text-markup-alist} @tab @code{org-texinfo-text-markup-alist} @end multitable -@node Publishing links +@node Publishing links, Sitemap, Publishing options, Configuration @subsection Links between published files @cindex links, publishing @@ -14906,7 +14906,7 @@ all point to a dedicated anchor in @file{foo.html}. [[file:foo.org::target]] @end example -@node Sitemap +@node Sitemap, Generating an index, Publishing links, Configuration @subsection Generating a sitemap @cindex sitemap, of published pages @@ -14968,7 +14968,7 @@ a sitemap entry's date is to be formatted. This property bypasses @end multitable -@node Generating an index +@node Generating an index, , Sitemap, Configuration @subsection Generating an index @cindex index, in a publishing project @@ -14995,7 +14995,7 @@ contains an exclamation mark will create a sub item. #+INDEX: Application!CV @end example -@node Uploading files +@node Uploading files, Sample configuration, Configuration, Publishing @section Uploading files @cindex rsync @cindex unison @@ -15028,7 +15028,7 @@ benefit of re-including any changed external files such as source example files you might include with @code{#+INCLUDE:}. The timestamp mechanism in Org is not smart enough to detect if included files have been modified. -@node Sample configuration +@node Sample configuration, Triggering publication, Uploading files, Publishing @section Sample configuration Below we provide two example configurations. The first one is a simple @@ -15040,7 +15040,7 @@ more complex, with a multi-component project. * Complex example:: A multi-component publishing example @end menu -@node Simple example +@node Simple example, Complex example, Sample configuration, Sample configuration @subsection Example: simple publishing configuration This example publishes a set of Org files to the @file{public_html} @@ -15059,7 +15059,7 @@ directory on the local machine. type=\"text/css\"/>"))) @end lisp -@node Complex example +@node Complex example, , Simple example, Sample configuration @subsection Example: complex publishing configuration This more complicated example publishes an entire website, including @@ -15109,7 +15109,7 @@ right place on the web server, and publishing images to it. ("website" :components ("orgfiles" "images" "other")))) @end lisp -@node Triggering publication +@node Triggering publication, , Sample configuration, Publishing @section Triggering publication Once properly configured, Org can publish with the following commands: @@ -15134,7 +15134,7 @@ This may be necessary in particular if files include other files via @code{#+SETUPFILE:} or @code{#+INCLUDE:}. -@node Working with source code +@node Working with source code, Miscellaneous, Publishing, Top @chapter Working with source code @cindex Schulte, Eric @cindex Davison, Dan @@ -15224,7 +15224,7 @@ Details of Org's facilities for working with source code are shown next. @end menu -@node Structure of code blocks +@node Structure of code blocks, Editing source code, Working with source code, Working with source code @section Structure of code blocks @cindex code block, structure @cindex source code, block structure @@ -15243,12 +15243,12 @@ A @samp{src} block conforms to this structure: #+END_SRC @end example -Org mode's templates system (@pxref{Easy templates}) speeds up creating -@samp{src} code blocks with just three keystrokes. Do not be put-off by -having to remember the source block syntax. Org also works with other -completion systems in Emacs, some of which predate Org and have custom -domain-specific languages for defining templates. Regular use of templates -reduces errors, increases accuracy, and maintains consistency. +Do not be put off by having to remember the source block syntax. Org mode +offers a command for wrapping existing text in a block (@pxref{Inserting +structure templates}). Org also works with other completion systems in +Emacs, some of which predate Org and have custom domain-specific languages +for defining templates. Regular use of templates reduces errors, increases +accuracy, and maintains consistency. @cindex source code, inline An inline code block conforms to this structure: @@ -15296,7 +15296,7 @@ specific sub-trees of the Org document. Source code in the dialect of the specified language identifier. @end table -@node Editing source code +@node Editing source code, Exporting code blocks, Structure of code blocks, Working with source code @section Editing source code @cindex code block, editing @cindex source code, editing @@ -15360,7 +15360,7 @@ Emacs-Lisp languages. ("python" (:background "#E5FFB8")))) @end lisp -@node Exporting code blocks +@node Exporting code blocks, Extracting source code, Editing source code, Working with source code @section Exporting code blocks @cindex code block, exporting @cindex source code, exporting @@ -15413,7 +15413,7 @@ Org never evaluates code blocks in commented sub-trees when exporting (@pxref{Comment lines}). On the other hand, Org does evaluate code blocks in sub-trees excluded from export (@pxref{Export settings}). -@node Extracting source code +@node Extracting source code, Evaluating code blocks, Exporting code blocks, Working with source code @section Extracting source code @cindex tangling @cindex source code, extracting @@ -15478,7 +15478,7 @@ block header arguments: One, set @code{padline} (@pxref{padline}) to true (the default setting). Two, set @code{comments} (@pxref{comments}) to @code{link}, which makes Org insert links to the Org file. -@node Evaluating code blocks +@node Evaluating code blocks, Library of Babel, Extracting source code, Working with source code @section Evaluating code blocks @cindex code block, evaluating @cindex source code, evaluating @@ -15555,7 +15555,7 @@ For more examples of header arguments for @code{#+CALL:} lines, @pxref{Arguments in function calls}. @end table -@node Library of Babel +@node Library of Babel, Languages, Evaluating code blocks, Working with source code @section Library of Babel @cindex babel, library of @cindex source code, library @@ -15572,7 +15572,7 @@ For any user to add code to the library, first save the code in regular @samp{src} code blocks of an Org file, and then load the Org file with @code{org-babel-lob-ingest}, which is bound to @kbd{C-c C-v i}. -@node Languages +@node Languages, Header arguments, Library of Babel, Working with source code @section Languages @cindex babel, languages @cindex source code, languages @@ -15632,7 +15632,7 @@ following enables execution of @code{clojure} code blocks: (require 'ob-clojure) @end lisp -@node Header arguments +@node Header arguments, Results of evaluation, Languages, Working with source code @section Header arguments @cindex code block, header arguments @cindex source code, block header arguments @@ -15644,7 +15644,7 @@ Details of configuring header arguments are shown here. * Specific header arguments:: List of header arguments @end menu -@node Using header arguments +@node Using header arguments, Specific header arguments, Header arguments, Header arguments @subsection Using header arguments Since header arguments can be set in several ways, Org prioritizes them in @@ -15661,7 +15661,7 @@ global defaults. @end menu -@node System-wide header arguments +@node System-wide header arguments, Language-specific header arguments, Using header arguments, Using header arguments @subsubheading System-wide header arguments @vindex org-babel-default-header-args System-wide values of header arguments can be specified by adapting the @@ -15689,14 +15689,14 @@ Org expand @code{:noweb} references by default. (assq-delete-all :noweb org-babel-default-header-args))) @end lisp -@node Language-specific header arguments +@node Language-specific header arguments, Header arguments in Org mode properties, System-wide header arguments, Using header arguments @subsubheading Language-specific header arguments Each language can have separate default header arguments by customizing the variable @code{org-babel-default-header-args:<lang>}, where @code{<lang>} is the name of the language. For details, see the language-specific online documentation at @uref{http://orgmode.org/worg/org-contrib/babel}. -@node Header arguments in Org mode properties +@node Header arguments in Org mode properties, Language-specific mode properties, Language-specific header arguments, Using header arguments @subsubheading Header arguments in Org mode properties For header arguments applicable to the buffer, use @code{#+PROPERTY:} lines @@ -15734,7 +15734,7 @@ Properties defined through @code{org-set-property} function, bound to @kbd{C-c C-x p}, apply to all active languages. They override properties set in @code{org-babel-default-header-args}. -@node Language-specific mode properties +@node Language-specific mode properties, Code block specific header arguments, Header arguments in Org mode properties, Using header arguments @subsubheading Language-specific mode properties Language-specific header arguments are also read from properties @@ -15757,7 +15757,7 @@ would force separate sessions for clojure blocks in Heading and Subheading, but use the same session for all @samp{R} blocks. Blocks in Subheading inherit settings from Heading. -@node Code block specific header arguments +@node Code block specific header arguments, Arguments in function calls, Language-specific mode properties, Using header arguments @subsubheading Code block specific header arguments Header arguments are most commonly set at the @samp{src} code block level, on @@ -15815,7 +15815,7 @@ Multi-line header arguments on a named @samp{src} code block: : data:2 @end example -@node Arguments in function calls +@node Arguments in function calls, , Code block specific header arguments, Using header arguments @subsubheading Arguments in function calls Header arguments in function calls are the most specific and override all @@ -15837,7 +15837,7 @@ evaluation of @code{factorial} code block. #+CALL: factorial[:session special](n=5) @end example -@node Specific header arguments +@node Specific header arguments, , Using header arguments, Header arguments @subsection Specific header arguments Org comes with many header arguments common to all languages. New header arguments are added for specific languages as they become available for use @@ -15879,7 +15879,7 @@ are: For language-specific header arguments, see @ref{Languages}. -@node var +@node var, results, Specific header arguments, Specific header arguments @subsubsection @code{:var} @cindex @code{:var}, src header argument Use @code{:var} for passing arguments to @samp{src} code blocks. The @@ -16133,7 +16133,7 @@ as Emacs Lisp code, as illustrated in the following example. : (a b c) @end example -@node results +@node results, file, var, Specific header arguments @subsubsection @code{:results} @cindex @code{:results}, src header argument @@ -16241,7 +16241,7 @@ Prepend results to the Org buffer. Latest results are at the top. Does not remove previous results. Usage example: @code{:results output prepend}. @end itemize -@node file +@node file, file-desc, results, Specific header arguments @subsubsection @code{:file} @cindex @code{:file}, src header argument @@ -16254,7 +16254,7 @@ format}). Some languages, such as @samp{R}, @samp{dot}, @samp{ditaa}, and code. Such code wrapping helps recreate the output, especially graphics output, by executing just the @code{:file} contents. -@node file-desc +@node file-desc, file-ext, file, Specific header arguments @subsubsection @code{:file-desc} A description of the results file. Org uses this description for the link @@ -16262,7 +16262,7 @@ A description of the results file. Org uses this description for the link has no value, Org will use file name for both the ``link'' and the ``description'' portion of the Org mode link. -@node file-ext +@node file-ext, output-dir, file-desc, Specific header arguments @subsubsection @code{:file-ext} @cindex @code{:file-ext}, src header argument @@ -16271,7 +16271,7 @@ name, and extension by combining @code{:file-ext}, @code{#+NAME:} of the source block, and the @ref{output-dir} header argument. To override this auto generated file name, use the @code{:file} header argument. -@node output-dir +@node output-dir, dir, file-ext, Specific header arguments @subsubsection @code{:output-dir} @cindex @code{:output-dir}, src header argument @@ -16280,7 +16280,7 @@ absolute path (beginning with @code{/}) or a relative directory (without @code{/}). The value can be combined with @code{#+NAME:} of the source block and @ref{file} or @ref{file-ext} header arguments. -@node dir +@node dir, exports, output-dir, Specific header arguments @subsubsection @code{:dir} and remote execution @cindex @code{:dir}, src header argument @@ -16339,7 +16339,7 @@ Org does not expand @code{default directory} to avoid some underlying portability issues. @end itemize -@node exports +@node exports, tangle, dir, Specific header arguments @subsubsection @code{:exports} @cindex @code{:exports}, src header argument @@ -16363,7 +16363,7 @@ file. Whether the code is evaluated at all depends on other options. Example: @code{:exports none}. @end itemize -@node tangle +@node tangle, mkdirp, exports, Specific header arguments @subsubsection @code{:tangle} @cindex @code{:tangle}, src header argument @@ -16386,7 +16386,7 @@ the file name as being relative to the directory of the Org file's location. Example: @code{:tangle path}. @end itemize -@node mkdirp +@node mkdirp, comments, tangle, Specific header arguments @subsubsection @code{:mkdirp} @cindex @code{:mkdirp}, src header argument @@ -16394,7 +16394,7 @@ The @code{:mkdirp} header argument creates parent directories for tangled files if the directory does not exist. @code{yes} enables directory creation and @code{no} inhibits directory creation. -@node comments +@node comments, padline, mkdirp, Specific header arguments @subsubsection @code{:comments} @cindex @code{:comments}, src header argument Controls inserting comments into tangled files. These are above and beyond @@ -16418,7 +16418,7 @@ Includes ``link'' comment option, expands noweb references, and wraps them in link comments inside the body of the @samp{src} code block. @end itemize -@node padline +@node padline, no-expand, comments, Specific header arguments @subsubsection @code{:padline} @cindex @code{:padline}, src header argument Control insertion of newlines to pad @samp{src} code blocks in the tangled @@ -16431,7 +16431,7 @@ tangled file. Do not insert newlines to pad the tangled @samp{src} code blocks. @end itemize -@node no-expand +@node no-expand, session, padline, Specific header arguments @subsubsection @code{:no-expand} @cindex @code{:no-expand}, src header argument @@ -16444,7 +16444,7 @@ these expansions may cause premature assignment, hence this option. This option makes a difference only for tangling. It has no effect when exporting since @samp{src} code blocks for execution have to be expanded anyway. -@node session +@node session, noweb, no-expand, Specific header arguments @subsubsection @code{:session} @cindex @code{:session}, src header argument @@ -16467,7 +16467,7 @@ shared. Some interpreted languages support concurrent sessions when subsequent source code language blocks change session names. @end itemize -@node noweb +@node noweb, noweb-ref, session, Specific header arguments @subsubsection @code{:noweb} @cindex @code{:noweb}, src header argument @@ -16575,7 +16575,7 @@ and evaluates to: Do things when True @end example -@node noweb-ref +@node noweb-ref, noweb-sep, noweb, Specific header arguments @subsubsection @code{:noweb-ref} @cindex @code{:noweb-ref}, src header argument @@ -16613,7 +16613,7 @@ when tangled. #+END_SRC @end example -@node noweb-sep +@node noweb-sep, cache, noweb-ref, Specific header arguments @subsubsection @code{:noweb-sep} @cindex @code{:noweb-sep}, src header argument @@ -16621,7 +16621,7 @@ By default a newline separates each noweb reference concatenation. To change this newline separator, edit the @code{:noweb-sep} (@pxref{noweb-sep}) header argument. -@node cache +@node cache, sep, noweb-sep, Specific header arguments @subsubsection @code{:cache} @cindex @code{:cache}, src header argument @@ -16686,7 +16686,7 @@ the result from @code{random} has changed since the last run. 0.254227238707244 @end example -@node sep +@node sep, hlines, cache, Specific header arguments @subsubsection @code{:sep} @cindex @code{:sep}, src header argument @@ -16695,7 +16695,7 @@ to files (@pxref{file}) external to Org mode. Org defaults to tab delimited output. The function, @code{org-open-at-point}, which is bound to @kbd{C-c C-o}, also uses @code{:sep} for opening tabular results. -@node hlines +@node hlines, colnames, sep, Specific header arguments @subsubsection @code{:hlines} @cindex @code{:hlines}, src header argument @@ -16756,7 +16756,7 @@ For @code{:hlines yes}, the example shows hlines unchanged. @end example @end itemize -@node colnames +@node colnames, rownames, hlines, Specific header arguments @subsubsection @code{:colnames} @cindex @code{:colnames}, src header argument @@ -16803,7 +16803,7 @@ value. That is, Org removes the column names, processes the table, puts back the column names, and then writes the table to the results block. @end itemize -@node rownames +@node rownames, shebang, colnames, Specific header arguments @subsubsection @code{:rownames} @cindex @code{:rownames}, src header argument @@ -16842,7 +16842,7 @@ for indexing. @end itemize -@node shebang +@node shebang, tangle-mode, rownames, Specific header arguments @subsubsection @code{:shebang} @cindex @code{:shebang}, src header argument @@ -16852,7 +16852,7 @@ setting the @code{:shebang} header argument to a string value (for example, the tangled file that the @samp{src} code block is extracted to. Org then turns on the tangled file's executable permission. -@node tangle-mode +@node tangle-mode, eval, shebang, Specific header arguments @subsubsection @code{:tangle-mode} @cindex @code{:tangle-mode}, src header argument @@ -16870,7 +16870,7 @@ When multiple @samp{src} code blocks tangle to a single file with different and conflicting @code{tangle-mode} header arguments, Org's behavior is undefined. -@node eval +@node eval, wrap, tangle-mode, Specific header arguments @subsubsection @code{:eval} @cindex @code{:eval}, src header argument The @code{:eval} header argument can limit evaluation of specific code @@ -16894,14 +16894,14 @@ If @code{:eval} header argument is not set for a source block, then Org determines whether to evaluate from the @code{org-confirm-babel-evaluate} variable (@pxref{Code evaluation security}). -@node wrap +@node wrap, post, eval, Specific header arguments @subsubsection @code{:wrap} @cindex @code{:wrap}, src header argument The @code{:wrap} header argument marks the results block by appending strings to @code{#+BEGIN_} and @code{#+END_}. If no string is specified, Org wraps the results in a @code{#+BEGIN/END_RESULTS} block. -@node post +@node post, prologue, wrap, Specific header arguments @subsubsection @code{:post} @cindex @code{:post}, src header argument The @code{:post} header argument is for post-processing results from @@ -16963,7 +16963,7 @@ data.frame(foo=rnorm(1)) | 1.371 | @end example -@node prologue +@node prologue, epilogue, post, Specific header arguments @subsubsection @code{:prologue} @cindex @code{:prologue}, src header argument The @code{prologue} header argument is for appending to the top of the code @@ -16976,13 +16976,13 @@ execution of a @samp{src} code block. A @code{reset} for @samp{gnuplot}: '((:prologue . "reset"))) @end lisp -@node epilogue +@node epilogue, , prologue, Specific header arguments @subsubsection @code{:epilogue} @cindex @code{:epilogue}, src header argument The value of the @code{epilogue} header argument is for appending to the end of the code block for execution. See also @ref{prologue}. -@node Results of evaluation +@node Results of evaluation, Noweb reference syntax, Header arguments, Working with source code @section Results of evaluation @cindex code block, results of evaluation @cindex source code, results of evaluation @@ -17083,7 +17083,7 @@ in results. In the above @code{:session} mode, the interactive interpreter receives and prints ``2''. Results show that. -@node Noweb reference syntax +@node Noweb reference syntax, Key bindings and useful functions, Results of evaluation, Working with source code @section Noweb reference syntax @cindex code block, noweb reference @cindex syntax, noweb @@ -17165,7 +17165,7 @@ Note that now the expansion contains the @emph{results} of the code block @end example -@node Key bindings and useful functions +@node Key bindings and useful functions, Batch execution, Noweb reference syntax, Working with source code @section Key bindings and useful functions @cindex code block, key bindings @@ -17268,7 +17268,7 @@ Active key bindings in Org mode buffer: @c @item @kbd{C-c C-v C-z} @tab @code{org-babel-switch-to-session} @c @end multitable -@node Batch execution +@node Batch execution, , Key bindings and useful functions, Working with source code @section Batch execution @cindex code block, batch execution @cindex source code, batch execution @@ -17294,12 +17294,12 @@ emacs -Q --batch --eval " " "$@@" @end example -@node Miscellaneous +@node Miscellaneous, Hacking, Working with source code, Top @chapter Miscellaneous @menu * Completion:: M-TAB guesses completions -* Easy templates:: Quick insertion of structural elements +* Inserting structure templates:: Wrapping text in code blocks * Speed keys:: Electric commands at the beginning of a headline * Code evaluation security:: Org mode files evaluate inline code * Customization:: Adapting Org to changing tastes @@ -17312,7 +17312,7 @@ emacs -Q --batch --eval " @end menu -@node Completion +@node Completion, Inserting structure templates, Miscellaneous, Miscellaneous @section Completion @cindex completion, of @TeX{} symbols @cindex completion, of TODO keywords @@ -17374,47 +17374,42 @@ If your desktop intercepts the combo @kbd{M-@key{TAB}} to switch windows, use environment. @end table -@node Easy templates -@section Easy templates +@node Inserting structure templates, Speed keys, Completion, Miscellaneous +@section Inserting structure templates @cindex template insertion @cindex insertion, of templates -With just a few keystrokes, Org's easy templates inserts empty pairs of -structural elements, such as @code{#+BEGIN_SRC} and @code{#+END_SRC}. Easy -templates use an expansion mechanism, which is native to Org, in a process -similar to @file{yasnippet} and other Emacs template expansion packages. - -@kbd{<} @kbd{s} @kbd{@key{TAB}} expands to a @samp{src} code block. - -@kbd{<} @kbd{l} @kbd{@key{TAB}} expands to: - -#+BEGIN_EXPORT latex - -#+END_EXPORT +With just a few keystrokes, it's possible to insert empty structural blocks, +such as @code{#+begin_src} and @code{#+end_src}, or to wrap existing text in +such a block. + +@defun org-insert-structure-template +@kindex C-c C-x w +Prompt for a type of block structure, and insert the block at point. If the +region is active, it will be wrapped in the block. First prompts the user +for a key, which is used to look up a structure type from the values below. +If the key is @key{TAB}, the user is prompted to enter a type. Bound to +@kbd{C-c C-x w}. +@end defun -Org comes with these pre-defined easy templates: - -@multitable @columnfractions 0.1 0.9 -@item @kbd{s} @tab @code{#+BEGIN_SRC ... #+END_SRC} -@item @kbd{e} @tab @code{#+BEGIN_EXAMPLE ... #+END_EXAMPLE} -@item @kbd{q} @tab @code{#+BEGIN_QUOTE ... #+END_QUOTE} -@item @kbd{v} @tab @code{#+BEGIN_VERSE ... #+END_VERSE} -@item @kbd{c} @tab @code{#+BEGIN_CENTER ... #+END_CENTER} -@item @kbd{C} @tab @code{#+BEGIN_COMMENT ... #+END_COMMENT} -@item @kbd{l} @tab @code{#+BEGIN_EXPORT latex ... #+END_EXPORT} -@item @kbd{L} @tab @code{#+LATEX:} -@item @kbd{h} @tab @code{#+BEGIN_EXPORT html ... #+END_EXPORT} -@item @kbd{H} @tab @code{#+HTML:} -@item @kbd{a} @tab @code{#+BEGIN_EXPORT ascii ... #+END_EXPORT} -@item @kbd{A} @tab @code{#+ASCII:} -@item @kbd{i} @tab @code{#+INDEX:} line -@item @kbd{I} @tab @code{#+INCLUDE:} line +@vindex org-structure-template-alist +Available structure types are defined in @code{org-structure-template-alist}, +see the docstring for adding or changing values. + +@multitable @columnfractions 0.2 0.8 +@item @kbd{s} @tab @code{src} +@item @kbd{e} @tab @code{example} +@item @kbd{E} @tab @code{export} +@item @kbd{q} @tab @code{quote} +@item @kbd{v} @tab @code{verse} +@item @kbd{c} @tab @code{center} +@item @kbd{C} @tab @code{comment} +@item @kbd{l} @tab @code{export latex} +@item @kbd{h} @tab @code{export html} +@item @kbd{a} @tab @code{export ascii} @end multitable -More templates can added by customizing the variable -@code{org-structure-template-alist}, whose docstring has additional details. - -@node Speed keys +@node Speed keys, Code evaluation security, Inserting structure templates, Miscellaneous @section Speed keys @cindex speed keys @@ -17440,7 +17435,7 @@ org-speed-command-help}, or @kbd{?} when cursor is at the beginning of an Org headline, shows currently active Speed Keys, including the user-defined ones. -@node Code evaluation security +@node Code evaluation security, Customization, Speed keys, Miscellaneous @section Code evaluation and security issues Unlike plain text, running code comes with risk. Each @samp{src} code block, @@ -17501,7 +17496,7 @@ Org executes formulas in tables (@pxref{The spreadsheet}) either through the @emph{calc} or the @emph{Emacs Lisp} interpreters. @end table -@node Customization +@node Customization, In-buffer settings, Code evaluation security, Miscellaneous @section Customization @cindex customization @cindex options, for customization @@ -17512,7 +17507,7 @@ through the usual @kbd{M-x org-customize RET} command. Or through the Org menu, @code{Org->Customization->Browse Org Group}. Org also has per-file settings for some variables (@pxref{In-buffer settings}). -@node In-buffer settings +@node In-buffer settings, The very busy C-c C-c key, Customization, Miscellaneous @section Summary of in-buffer settings @cindex in-buffer settings @cindex special keywords @@ -17799,7 +17794,7 @@ These lines set the TODO keywords and their significance to the current file. The corresponding variable is @code{org-todo-keywords}. @end table -@node The very busy C-c C-c key +@node The very busy C-c C-c key, Clean view, In-buffer settings, Miscellaneous @section The very busy C-c C-c key @kindex C-c C-c @cindex C-c C-c, overview @@ -17851,7 +17846,7 @@ block is updated. If the cursor is at a timestamp, fix the day name in the timestamp. @end itemize -@node Clean view +@node Clean view, TTY keys, The very busy C-c C-c key, Miscellaneous @section A cleaner outline view @cindex hiding leading stars @cindex dynamic indentation @@ -17969,7 +17964,7 @@ To switch between single and double stars layouts, use @kbd{M-x org-convert-to-odd-levels RET} and @kbd{M-x org-convert-to-oddeven-levels}. @end enumerate -@node TTY keys +@node TTY keys, Interaction, Clean view, Miscellaneous @section Using Org on a tty @cindex tty key bindings @@ -18003,7 +17998,7 @@ normal @kbd{S-@key{cursor}} for editing timestamp might be better with @end multitable -@node Interaction +@node Interaction, org-crypt, TTY keys, Miscellaneous @section Interaction with other packages @cindex packages, interaction with other Org's compatibility and the level of interaction with other Emacs packages @@ -18015,7 +18010,7 @@ are documented here. * Conflicts:: Packages that lead to conflicts @end menu -@node Cooperation +@node Cooperation, Conflicts, Interaction, Interaction @subsection Packages that Org cooperates with @table @asis @@ -18084,7 +18079,7 @@ for details. @end table @end table -@node Conflicts +@node Conflicts, , Cooperation, Interaction @subsection Packages that conflict with Org mode @table @asis @@ -18208,7 +18203,7 @@ another key for this command, or override the key in @end table -@node org-crypt +@node org-crypt, , Interaction, Miscellaneous @section org-crypt.el @cindex @file{org-crypt.el} @cindex @code{org-decrypt-entry} @@ -18245,7 +18240,7 @@ Suggested Org crypt settings in Emacs init file: Excluding the crypt tag from inheritance prevents encrypting previously encrypted text. -@node Hacking +@node Hacking, MobileOrg, Miscellaneous, Top @appendix Hacking @cindex hacking @@ -18267,7 +18262,7 @@ Org. * Using the mapping API:: Mapping over all or selected entries @end menu -@node Hooks +@node Hooks, Add-on packages, Hacking, Hacking @section Hooks @cindex hooks @@ -18276,7 +18271,7 @@ appendix illustrates using a few. A complete list of hooks with documentation is maintained by the Worg project at @uref{http://orgmode.org/worg/doc.html#hooks}. -@node Add-on packages +@node Add-on packages, Adding hyperlink types, Hooks, Hacking @section Add-on packages @cindex add-on packages @@ -18288,7 +18283,7 @@ See the @file{contrib/README} file in the source code directory for a list of contributed files. Worg page with more information is at: @uref{http://orgmode.org/worg/org-contrib/}. -@node Adding hyperlink types +@node Adding hyperlink types, Adding export back-ends, Add-on packages, Hacking @section Adding hyperlink types @cindex hyperlinks, adding new types @@ -18383,7 +18378,7 @@ To define new link types, define a function that implements completion support with @kbd{C-c C-l}. This function should not accept any arguments but return the appropriate prefix and complete link string. -@node Adding export back-ends +@node Adding export back-ends, Context-sensitive commands, Adding hyperlink types, Hacking @section Adding export back-ends @cindex Export, writing back-ends @@ -18410,7 +18405,7 @@ For complete documentation, see @url{http://orgmode.org/worg/dev/org-export-reference.html, the Org Export Reference on Worg}. -@node Context-sensitive commands +@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 @@ -18427,7 +18422,7 @@ These context sensitive commands work by providing a function that detects special context for that add-on and executes functionality appropriate for that context. -@node Tables in arbitrary syntax +@node Tables in arbitrary syntax, Dynamic blocks, Context-sensitive commands, Hacking @section Tables and lists in arbitrary syntax @cindex tables, in other modes @cindex lists, in other modes @@ -18460,7 +18455,7 @@ list locally to another format, such as HTML, @LaTeX{} or Texinfo. * Radio lists:: Sending and receiving lists @end menu -@node Radio tables +@node Radio tables, A @LaTeX{} example, Tables in arbitrary syntax, Tables in arbitrary syntax @subsection Radio tables @cindex radio tables @@ -18522,7 +18517,7 @@ Comment and uncomment each line of the table during edits. The @kbd{M-x orgtbl-toggle-comment RET} command makes toggling easy. @end itemize -@node A @LaTeX{} example +@node A @LaTeX{} example, Translator functions, Radio tables, Tables in arbitrary syntax @subsection A @LaTeX{} example of radio tables @cindex @LaTeX{}, and Orgtbl mode @@ -18628,7 +18623,7 @@ Functions with two arguments can be supplied instead of strings. By default, no special formatting is applied. @end table -@node Translator functions +@node Translator functions, Radio lists, A @LaTeX{} example, Tables in arbitrary syntax @subsection Translator functions @cindex HTML, and Orgtbl mode @cindex translator function @@ -18679,7 +18674,7 @@ parameters specified in the @samp{#+ORGTBL: SEND} line. Please share your translator functions by posting them to the Org users mailing list, @email{emacs-orgmode@@gnu.org}. -@node Radio lists +@node Radio lists, , Translator functions, Tables in arbitrary syntax @subsection Radio lists @cindex radio lists @cindex org-list-insert-radio-list @@ -18720,7 +18715,7 @@ parameters for accurate customizations of lists. Here is a @LaTeX{} example: @kbd{C-c C-c} on @samp{a new house} inserts the translated @LaTeX{} list in-between the BEGIN and END marker lines. -@node Dynamic blocks +@node Dynamic blocks, Special agenda views, Tables in arbitrary syntax, Hacking @section Dynamic blocks @cindex dynamic blocks @@ -18784,7 +18779,7 @@ Org mode. Dynamic blocks, like any other block, can be narrowed with @code{org-narrow-to-block}. -@node Special agenda views +@node Special agenda views, Speeding up your agendas, Dynamic blocks, Hacking @section Special agenda views @cindex agenda views, user-defined @@ -18880,7 +18875,7 @@ special function: (org-agenda-overriding-header "Projects waiting for something: ")))) @end lisp -@node Speeding up your agendas +@node Speeding up your agendas, Extracting agenda information, Special agenda views, Hacking @section Speeding up your agendas @cindex agenda views, optimization @@ -18921,7 +18916,7 @@ about generation of agenda views, see the docstrings for the relevant variables, and this @uref{http://orgmode.org/worg/agenda-optimization.html, dedicated Worg page} for agenda optimization. -@node Extracting agenda information +@node Extracting agenda information, Using the property API, Speeding up your agendas, Hacking @section Extracting agenda information @cindex agenda, pipe @cindex Scripts, for agenda processing @@ -19023,7 +19018,7 @@ foreach $line (split(/\n/,$agenda)) @{ @} @end example -@node Using the property API +@node Using the property API, Using the mapping API, Extracting agenda information, Hacking @section Using the property API @cindex API, for properties @cindex properties, API @@ -19103,7 +19098,7 @@ to be entered. The functions must return @code{nil} if they are not responsible for this property. @end defopt -@node Using the mapping API +@node Using the mapping API, , Using the property API, Hacking @section Using the mapping API @cindex API, for mapping @cindex mapping entries, API @@ -19209,7 +19204,7 @@ The following example counts the number of entries with TODO keyword (length (org-map-entries t "/+WAITING" 'agenda)) @end lisp -@node MobileOrg +@node MobileOrg, History and acknowledgments, Hacking, Top @appendix MobileOrg @cindex iPhone @cindex MobileOrg @@ -19243,7 +19238,7 @@ them. Though MobileOrg has in-buffer settings, it understands TODO states * Pulling from MobileOrg:: Integrating captured and flagged items @end menu -@node Setting up the staging area +@node Setting up the staging area, Pushing to MobileOrg, MobileOrg, MobileOrg @section Setting up the staging area MobileOrg needs access to a file directory on a server to interact with @@ -19274,7 +19269,7 @@ follows: Org copies files to the above directory for MobileOrg. Org also uses the same directory for sharing notes between Org and MobileOrg. -@node Pushing to MobileOrg +@node Pushing to MobileOrg, Pulling from MobileOrg, Setting up the staging area, MobileOrg @section Pushing to MobileOrg Org pushes files listed in @code{org-mobile-files} to @@ -19299,7 +19294,7 @@ to download for agendas. For faster downloads, MobileOrg will read only those files whose checksums@footnote{Checksums are stored automatically in the file @file{checksums.dat}.} have changed. -@node Pulling from MobileOrg +@node Pulling from MobileOrg, , Pushing to MobileOrg, MobileOrg @section Pulling from MobileOrg When MobileOrg synchronizes with the server, it pulls the Org files for @@ -19343,7 +19338,7 @@ entries. Note that these entries may not be the most recent since MobileOrg searches files that were last pulled. To get an updated agenda view with changes since the last pull, pull again. -@node History and acknowledgments +@node History and acknowledgments, GNU Free Documentation License, MobileOrg, Top @appendix History and acknowledgments @cindex acknowledgments @cindex history @@ -19720,27 +19715,27 @@ and contributed various ideas and code snippets. @end itemize -@node GNU Free Documentation License +@node GNU Free Documentation License, Main Index, History and acknowledgments, Top @appendix GNU Free Documentation License @include doclicense.texi -@node Main Index +@node Main Index, Key Index, GNU Free Documentation License, Top @unnumbered Concept index @printindex cp -@node Key Index +@node Key Index, Command and Function Index, Main Index, Top @unnumbered Key index @printindex ky -@node Command and Function Index +@node Command and Function Index, Variable Index, Key Index, Top @unnumbered Command and function index @printindex fn -@node Variable Index +@node Variable Index, , Command and Function Index, Top @unnumbered Variable index This is not a complete index of variables and faces, only the ones that are diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS index 391ef94ac..97ccf884b 100644 --- a/etc/ORG-NEWS +++ b/etc/ORG-NEWS @@ -149,6 +149,10 @@ you should expect to see something like: #+END_EXAMPLE ** New functions +*** ~org-insert-structure-template~ + +This function can be used to wrap existing text of Org elements in +a #+BEGIN_FOO/#+END_FOO block. Bound to C-c C-x w by default. *** ~org-export-excluded-from-toc-p~ diff --git a/lisp/org.el b/lisp/org.el index 3b26bfd3d..9ad06ac3b 100644 --- a/lisp/org.el +++ b/lisp/org.el @@ -6740,8 +6740,6 @@ Use `\\[org-edit-special]' to edit table.el tables")) ((run-hook-with-args-until-success 'org-tab-after-check-for-cycling-hook)) - ((org-try-structure-completion)) - ((run-hook-with-args-until-success 'org-tab-before-tab-emulation-hook)) @@ -11859,76 +11857,77 @@ keywords relative to each registered export back-end." "TITLE:" "TODO:" "TYP_TODO:" "SELECT_TAGS:" "EXCLUDE_TAGS:")) (defcustom org-structure-template-alist - '(("s" "#+BEGIN_SRC ?\n\n#+END_SRC") - ("e" "#+BEGIN_EXAMPLE\n?\n#+END_EXAMPLE") - ("q" "#+BEGIN_QUOTE\n?\n#+END_QUOTE") - ("v" "#+BEGIN_VERSE\n?\n#+END_VERSE") - ("V" "#+BEGIN_VERBATIM\n?\n#+END_VERBATIM") - ("c" "#+BEGIN_CENTER\n?\n#+END_CENTER") - ("C" "#+BEGIN_COMMENT\n?\n#+END_COMMENT") - ("l" "#+BEGIN_EXPORT latex\n?\n#+END_EXPORT") - ("L" "#+LaTeX: ") - ("h" "#+BEGIN_EXPORT html\n?\n#+END_EXPORT") - ("H" "#+HTML: ") - ("a" "#+BEGIN_EXPORT ascii\n?\n#+END_EXPORT") - ("A" "#+ASCII: ") - ("i" "#+INDEX: ?") - ("I" "#+INCLUDE: %file ?")) + '((?s . "src") + (?e . "example") + (?E . "export") + (?q . "quote") + (?v . "verse") + (?c . "center") + (?C . "comment") + (?l . "export latex") + (?h . "export html") + (?a . "export ascii")) "Structure completion elements. -This is a list of abbreviation keys and values. The value gets inserted -if you type `<' followed by the key and then press the completion key, -usually `TAB'. %file will be replaced by a file name after prompting -for the file using completion. The cursor will be placed at the position -of the `?' in the template. -There are two templates for each key, the first uses the original Org syntax, -the second uses Emacs Muse-like syntax tags. These Muse-like tags become -the default when the /org-mtags.el/ module has been loaded. See also the -variable `org-mtags-prefer-muse-templates'." +This is an alist of characters and values. When +`org-insert-structure-template' is called, an additional key is +read. The key is first looked up in this alist, and the +corresponding structure is inserted, with \"#+begin\" and +\"#+end\" added automatically." :group 'org-completion :type '(repeat - (list - (string :tag "Key") + (cons + (character :tag "Key") (string :tag "Template"))) - :version "26.1" :package-version '(Org . "8.3")) -(defun org-try-structure-completion () - "Try to complete a structure template before point. -This looks for strings like \"<e\" on an otherwise empty line and -expands them." - (let ((l (buffer-substring (point-at-bol) (point))) - a) - (when (and (looking-at "[ \t]*$") - (string-match "^[ \t]*<\\([a-zA-Z]+\\)$" l) - (setq a (assoc (match-string 1 l) org-structure-template-alist))) - (org-complete-expand-structure-template (+ -1 (point-at-bol) - (match-beginning 1)) a) - t))) - -(defun org-complete-expand-structure-template (start cell) - "Expand a structure template." - (let ((rpl (nth 1 cell)) - (ind "")) - (delete-region start (point)) - (when (string-match "\\`[ \t]*#\\+" rpl) - (cond - ((bolp)) - ((not (string-match "\\S-" (buffer-substring (point-at-bol) (point)))) - (setq ind (buffer-substring (point-at-bol) (point)))) - (t (newline)))) - (setq start (point)) - (when (string-match "%file" rpl) - (setq rpl (replace-match - (concat - "\"" - (save-match-data - (abbreviate-file-name (read-file-name "Include file: "))) - "\"") - t t rpl))) - (setq rpl (mapconcat 'identity (split-string rpl "\n") - (concat "\n" ind))) - (insert rpl) - (when (re-search-backward "\\?" start t) (delete-char 1)))) +(defun org-insert-structure-template (type) + "Insert a block structure of the type #+begin_foo/#+end_foo. +First read a character, which can be one of the keys in +`org-structure-template-alist'. When it is <TAB>, prompt the +user for a string to use. With an active region, wrap the region +in the block. Otherwise, insert an empty block." + (interactive + (list + (let* ((key (read-key "Key: ")) + (struct-string + (or (cdr (assq key org-structure-template-alist)) + (and (= key ?\t) + (read-string "Structure type: ")) + (error "'%c' has no structure definition" key)))) + struct-string))) + (let ((s (if (use-region-p) + (region-beginning) + (point))) + (e (copy-marker (if (use-region-p) + (region-end) + (point)) + t)) + column) + (when (string-match-p + (concat "\\`" + (regexp-opt '("example" "export" "src"))) + type) + (org-escape-code-in-region s e)) + (goto-char s) + (setq column (current-indentation)) + (beginning-of-line) + (indent-to column) + (insert (format "#+begin_%s\n" type)) + (goto-char e) + (if (bolp) + (progn + (skip-chars-backward " \n\t") + (forward-line)) + (end-of-line) + (insert "\n")) + (indent-to column) + (insert (format "#+end_%s\n" + (car (split-string type)))) + (when (or (string-match-p "src\\|\\`export\\'" type) + (null (use-region-p))) + (goto-char s) + (end-of-line)) + (set-marker e nil))) ;;;; TODO, DEADLINE, Comments @@ -19393,6 +19392,7 @@ COMMANDS is a list of alternating OLDDEF NEWDEF command names." (org-defkey org-mode-map "\C-c\C-xE" 'org-inc-effort) (org-defkey org-mode-map "\C-c\C-xo" 'org-toggle-ordered-property) (org-defkey org-mode-map "\C-c\C-xi" 'org-columns-insert-dblock) +(org-defkey org-mode-map "\C-c\C-xw" 'org-insert-structure-template) (org-defkey org-mode-map [(control ?c) (control ?x) ?\;] 'org-timer-set-timer) (org-defkey org-mode-map "\C-c\C-x." 'org-timer) diff --git a/testing/lisp/test-org.el b/testing/lisp/test-org.el index 379ded672..ca1b7f463 100644 --- a/testing/lisp/test-org.el +++ b/testing/lisp/test-org.el @@ -4000,6 +4000,52 @@ Text. (org-next-block 1 nil "^[ \t]*#\\+BEGIN_QUOTE") (looking-at "#\\+begin_quote"))))) +(ert-deftest test-org/insert-template () + "Test `org-insert-structure-template'." + ;; Test in empty buffer. + (should + (string= "#+begin_foo\n#+end_foo\n" + (org-test-with-temp-text "" + (org-insert-structure-template "foo") + (buffer-string)))) + ;; Test with multiple lines in buffer. + (should + (string= "#+begin_foo\nI'm a paragraph\n#+end_foo\n\nI'm a second paragraph" + (org-test-with-temp-text "I'm a paragraph\n\nI'm a second paragraph" + (org-mark-element) + (org-insert-structure-template "foo") + (buffer-string)))) + ;; Test with text in buffer, no region, no final newline. + (should + (string= "#+begin_foo\nI'm a paragraph.\n#+end_foo\n" + (org-test-with-temp-text "I'm a paragraph." + (org-mark-element) + (org-insert-structure-template "foo") + (buffer-string)))) + ;; Test with text in buffer and region set. + (should + (string= "#+begin_foo\nI'm a paragraph\n\nI'm a second paragrah\n#+end_foo\n" + (org-test-with-temp-text "I'm a paragraph\n\nI'm a second paragrah" + (goto-char (point-min)) + (set-mark (point)) + (goto-char (point-max)) + (org-insert-structure-template "foo") + (buffer-string)))) + ;; Test with example escaping. + (should + (string= "#+begin_example\n,* Heading\n#+end_example\n" + (org-test-with-temp-text "* Heading" + (org-mark-element) + (org-insert-structure-template "example") + (buffer-string)))) + ;; Test with indentation. + (should + (string= " #+begin_foo\n This is a paragraph\n #+end_foo\n" + (org-test-with-temp-text " This is a paragraph" + (org-mark-element) + (org-insert-structure-template "foo") + (buffer-string))))) + (ert-deftest test-org/previous-block () "Test `org-previous-block' specifications." ;; Regular test. -- 2.14.3