diff options
| author | Carsten Dominik <dominik@nb-dominik2.science.uva.nl> | 2008-01-31 11:33:51 +0100 |
|---|---|---|
| committer | Carsten Dominik <dominik@nb-dominik2.science.uva.nl> | 2008-01-31 11:33:51 +0100 |
| commit | 5e48ea5630e5787fba98941ea6932966b524b70b (patch) | |
| tree | eab4b04565d69fdfa2fa0bdba75c459c913abe05 | |
| parent | 2c16f092e64915a7e3d0b2dda82f3978a0f42dea (diff) | |
Release 4.65release_4.65
| -rw-r--r-- | org | 699 | ||||
| -rw-r--r-- | org.el | 545 | ||||
| -rw-r--r-- | org.pdf | bin | 672587 -> 690098 bytes | |||
| -rw-r--r-- | org.texi | 294 | ||||
| -rw-r--r-- | orgcard.pdf | bin | 58128 -> 58430 bytes | |||
| -rw-r--r-- | orgcard.tex | 2 |
6 files changed, 1236 insertions, 304 deletions
@@ -5,7 +5,7 @@ START-INFO-DIR-ENTRY * Org Mode: (org). Outline-based notes management and organizer END-INFO-DIR-ENTRY - This manual is for Org-mode (version 4.64). + This manual is for Org-mode (version 4.65). Copyright (C) 2004, 2005, 2006, 2007 Free Software Foundation @@ -27,7 +27,7 @@ File: org, Node: Top, Next: Introduction, Prev: (dir), Up: (dir) Org Mode Manual *************** -This manual is for Org-mode (version 4.64). +This manual is for Org-mode (version 4.65). Copyright (C) 2004, 2005, 2006, 2007 Free Software Foundation @@ -265,8 +265,15 @@ Interaction with other packages Extensions, Hooks and Hacking * Extensions:: Existing 3rd-part extensions +* Tables in arbitrary syntax:: Orgtbl for LaTeX and other programs * Dynamic blocks:: Automatically filled blocks -* Special agenda views:: +* Special agenda views:: Customized views + +Tables in arbitrary syntax + +* Radio tables:: Sending and receiving +* A LaTeX example:: Step by step, almost a tutorial +* Translator functions:: Copy and modify File: org, Node: Introduction, Next: Document structure, Prev: Top, Up: Top @@ -331,7 +338,8 @@ example as: Org-mode's automatic, context sensitive table editor with spreadsheet capabilities can be integrated into any major mode by activating the -minor Orgtbl-mode. +minor Orgtbl-mode. Using a translation step, it can be used to maintain +tables in arbitray file types, for example in LaTeX. There is a website for Org-mode which provides links to the newest version of Org-mode, as well as additional information, frequently asked @@ -1193,6 +1201,12 @@ in mail mode, use (add-hook 'mail-mode-hook 'turn-on-orgtbl) + Furthermore, with some special setup, it is possible to maintain +tables in arbitrary syntax with Orgtbl-mode. For example, it is +possible to construct LaTeX tables with the underlying ease and power of +Orgtbl-mode, including spreadsheet capabulities. For details, see +*Note Tables in arbitrary syntax::. + File: org, Node: The spreadsheet, Prev: orgtbl-mode, Up: Tables @@ -1458,6 +1472,16 @@ formulas of a table. `C-c C-q' Exit the buffer without installing changes. + `<TAB>' + Pretty-print or indent lisp formula at point. When in a line + containing a lisp formula, format the formula according to + Emacs Lisp rules. Another <TAB> collapses the formula back + again. In the open formula, <TAB> re-indents just like in + Emacs-lisp-mode. + + `M-<TAB>' + Complete Lisp symbols, just like in Emacs-lisp-mode. + `S-<up>/<down>' Move the reference line in the Org-mode buffer up and down. This is important for highlighting the references of column @@ -1593,6 +1617,10 @@ column formulas are not applied in rows with empty first field. All lines that should be recalculated should be marked with `#' or `*'. +`/' + Do not export this line. Useful for lines that contain the + narrowing `<N>' markers. + Finally, just to whet your appetite on what can be done with the fantastic `calc' package, here is a table that computes the Taylor series of degree `n' at location `x' for a couple of functions @@ -5413,11 +5441,12 @@ Org-mode. * Menu: * Extensions:: Existing 3rd-part extensions +* Tables in arbitrary syntax:: Orgtbl for LaTeX and other programs * Dynamic blocks:: Automatically filled blocks -* Special agenda views:: +* Special agenda views:: Customized views -File: org, Node: Extensions, Next: Dynamic blocks, Prev: Extensions and Hacking, Up: Extensions and Hacking +File: org, Node: Extensions, Next: Tables in arbitrary syntax, Prev: Extensions and Hacking, Up: Extensions and Hacking A.1 Third-party extensions for Org-mode ======================================= @@ -5426,14 +5455,13 @@ The following extensions for Org-mode have been written by other people: `org-publish.el' by David O'Toole This package provides facilities for publishing related sets of - Org-mode files together with linked files like images as a - webpages. It is highly configurable and can be used for other - publishing purposes as well. As of Org-mode version 4.30, - `org-publish.el' is part of the Org-mode distribution. It is not - yet part of Emacs, however, a delay caused by the preparations for - the 22.1 release. In the mean time, `org-publish.el' can be - downloaded from David's site: - `http://dto.freeshell.org/e/org-publish.el'. + Org-mode files together with linked files like images as webpages. + It is highly configurable and can be used for other publishing + purposes as well. As of Org-mode version 4.30, `org-publish.el' + is part of the Org-mode distribution. It is not yet part of + Emacs, however, a delay caused by the preparations for the 22.1 + release. In the mean time, `org-publish.el' can be downloaded + from David's site: `http://dto.freeshell.org/e/org-publish.el'. `org-mouse.el' by Piotr Zielinski This package implements extended mouse functionality for Org-mode. @@ -5460,9 +5488,219 @@ The following extensions for Org-mode have been written by other people: `http://www.cognition.ens.fr/~guerry/u/org2rem.el'. -File: org, Node: Dynamic blocks, Next: Special agenda views, Prev: Extensions, Up: Extensions and Hacking +File: org, Node: Tables in arbitrary syntax, Next: Dynamic blocks, Prev: Extensions, Up: Extensions and Hacking + +A.2 Tables in arbitrary syntax +============================== + +Since Orgtbl-mode can be used as a minor mode in arbitrary buffers, a +frequent feature request has been to make it work with native tables in +specific languages, for example LaTeX. However, this is extremely hard +to do in a general way, would lead to a customization nightmare, and +would take away much of the simplicity of the Orgtbl-mode table editor. + + This appendix describes different approach. We keep the Orgtbl-mode +table in its native format (the source table), and use a custom +function to translate the table to the correct syntax, and to install +it in the right location (the target table). This puts the burden of +writing conversion functions on the user, but it allows for a very +flexible system. + +* Menu: -A.2 Dynamic blocks +* Radio tables:: Sending and receiving +* A LaTeX example:: Step by step, almost a tutorial +* Translator functions:: Copy and modify + + +File: org, Node: Radio tables, Next: A LaTeX example, Prev: Tables in arbitrary syntax, Up: Tables in arbitrary syntax + +A.2.1 Radio tables +------------------ + +To define the location of the target table, you first need to create two +lines that are comments in the current mode, but contain magic words for +Orgtbl-mode to find. Orgtbl-mode will insert the translated table +between these lines, replacing whatever was there before. For example: + + /* BEGIN RECEIVE ORGTBL table_name */ + /* END RECEIVE ORGTBL table_name */ + +Just above the source table, we put a special line that tells +Orgtbl-mode how to translate this table and where to install it. For +example: + #+ORGTBL: SEND table_name translation_function arguments.... + +`table_name' is the reference name for the table that is also used in +the receiver lines. `translation_function' is the Lisp function that +does the translation. Furthermore, the line can contain a list of +arguments (alternating key and value) at the end. The arguments will be +passed as a property list to the translation function for +interpretation. However, a few standard parameters are already +recognized and acted upon before the translation function is called: + +`:skip N' + Skip the first N lines of the table. Hlines do count! + +`:skipcols (n1 n2 ...)' + List of columns that should be skipped. If the table has a column + with calculation marks, that column is automatically discarded as + well. Please note that the translator function sees the table + _after_ the removal of these columns, the function never knows + that there have been additional columns. + +The one problem remaining is how to keep the source table in the buffer +without disturbing the normal workings of the file, for example during +compilation of a C file or processing of a LaTeX file. There are a +number of different solutions: + + * The table could be placed in a block comment if that is supported + by the language. For example, in C-mode you could wrap the table + between `/*' and `*/' lines. + + * Sometimes it is possible to put the table after some kind of END + statement, for example `\bye' in TeX and `\end{document}' in LaTeX. + + * If all else fails(1), you can just comment the table line by line + whenever you want to process the file, and uncomment it whenever + you need to edit the table. The command `M-x + orgtbl-toggle-comment' does make this a viable option, in + particular if you bind it to a key. + + ---------- Footnotes ---------- + + (1) In principle the source table could also be in a separate file, +but so far this is not implemented. + + +File: org, Node: A LaTeX example, Next: Translator functions, Prev: Radio tables, Up: Tables in arbitrary syntax + +A.2.2 A LaTeX example +--------------------- + +The best way to wrap the source table in LaTeX is to use the `comment' +environment provided by `comment.sty'. It has to be activated by +placing `\usepackage{comment}' into the document header. Orgtbl-mode +can insert a radio table skeleton(1) with the command `M-x +orgtbl-insert-radio-table'. You will be prompted for a table name, +lets say we use `salesfigures'. You will then get the following +template: + + % BEGIN RECEIVE ORGTBL salesfigures + % END RECEIVE ORGTBL salesfigures + \begin{comment} + #+ORGTBL: SEND salesfigures orgtbl-to-latex + | | | + \end{comment} + +The `#+ORGTBL: SEND' line tells orgtbl-mode to use the function +`orgtbl-to-latex' to convert the table into LaTeX and to put it into +the receiver location with name `salesfigures'. You may now fill in +the table, feel free to use the spreadsheet features(2): + + % BEGIN RECEIVE ORGTBL salesfigures + % END RECEIVE ORGTBL salesfigures + \begin{comment} + #+ORGTBL: SEND salesfigures orgtbl-to-latex + | Month | Days | Nr sold | per day | + |-------+------+---------+---------| + | Jan | 23 | 55 | 2.4 | + | Feb | 21 | 16 | 0.8 | + | March | 22 | 278 | 12.6 | + #+TBLFM: $4=$3/$2;%.1f + % $ (optional extra dollar to keep font-lock happy, see footnote) + \end{comment} + +When you are done, press `C-c C-c' in the table to get the converted +table inserted between the two marker lines. + + Now lets assume you want to make the table header by hand, because +you want to control how columns are aligned etc. In this case we make +sure that the table translator does skip the first 2 lines, and tell the +command to work as a splice, i.e. to not produce header and footer +commands of the table: + + \begin{tabular}{lrrr} + Month & \multicolumn{1}{c}{Days} & Nr.\ sold & per day\\ + % BEGIN RECEIVE ORGTBL salesfigures + % END RECEIVE ORGTBL salesfigures + \end{tabular} + % + \begin{comment} + #+ORGTBL: SEND salesfigures orgtbl-to-latex :splice t :skip 2 + | Month | Days | Nr sold | per day | + |-------+------+---------+---------| + | Jan | 23 | 55 | 2.4 | + | Feb | 21 | 16 | 0.8 | + | March | 22 | 278 | 12.6 | + #+TBLFM: $4=$3/$2;%.1f + \end{comment} + + The LaTeX translator function `orgtbl-to-latex' is already part of +Orgtbl-mode. It uses a `tabular' environment to typeset the table and +marks horizontal lines with `\hline'. Furthermore, it interprets the +following parameters: + +`:splice nil/t' + When set to t, return only table body lines, don't wrap them into a + tabular environment. Default is nil. + +`:fmt fmt' + A format to be used to wrap the field, should contain `%s' for the + original field value. For example, to wrap each field value in + dollars, you could use `:fmt "$%s$"'. This may also be a property + list with column numbers and formats. for example `:fmt (2 "$%s$" + 4 "%s%%")'. + +`:efmt efmt' + Use this format to print numbers with exponentials. The format + should have `%s' twice for inserting mantissa and exponent, for + example `"%s\\times10^{%s}"'. The default is `"%s\\,(%s)"'. This + may also be a property list with column numbers and formats, for + example `:efmt (2 "$%s\\times10^{%s}$" 4 "$%s\\cdot10^{%s}$")'. + After `efmt' has been applied to a value, `fmt' will also be + applied. + + ---------- Footnotes ---------- + + (1) By default this works only for LaTeX, HTML, and TeXInfo. +Configure the variable `orgtbl-radio-tables' to install templates for +other modes. + + (2) If the `#+TBLFM' line contains an odd number of dollar +characters, this may cause problems with font-lock in latex-mode. As +shown in the example you can fix this by adding an extra line inside the +`comment' environment that is used to balance the dollar expressions. +If you are using AUCTeX with the font-latex library, a much better +solution is to add the `comment' environment to the variable +`LaTeX-verbatim-environments'. + + +File: org, Node: Translator functions, Prev: A LaTeX example, Up: Tables in arbitrary syntax + +A.2.3 Translator functions +-------------------------- + +Orgtbl-mode has several translator functions built-in: +`orgtbl-to-latex', `orgtbl-to-html', and `orgtbl-to-texinfo'. For +deatils on each of them, please check the corresponding documentation +strings. + + In order to write your own translator function, start by looking at +`orgtbl-to-latex' which is well documented. Basically you have to +write a function that takes two arguments. The first argument is the +table, a list of lines, each line either the symbol `hline' or a list +of fields. The second argument is a property list that will contain +all parameters specified in the `#+ORGTBL: SEND' line. Orgtbl-mode +always handles the `:skip' and `:skipcols' parameters, but your +translator function may use any number of additional parameters. If +you write a generally useful translator, please post it on +`emacs-orgmode@gnu.org' so that others can benefit from your work. + + +File: org, Node: Dynamic blocks, Next: Special agenda views, Prev: Tables in arbitrary syntax, Up: Extensions and Hacking + +A.3 Dynamic blocks ================== Org-mode documents can contain _dynamic blocks_. These are specially @@ -5514,7 +5752,7 @@ Org-mode. File: org, Node: Special agenda views, Prev: Dynamic blocks, Up: Extensions and Hacking -A.3 Special Agenda Views +A.4 Special Agenda Views ======================== Org-mode provides a special hook that can be used to narrow down the @@ -5572,17 +5810,21 @@ Appendix B History and Acknowledgments ************************************** Org-mode was borne in 2003, out of frustration over the user interface -of the Emacs outline-mode. All I initially wanted was to make working -with an outline tree possible without having to remember more than 10 -commands just for hiding and unhiding parts of the outline tree, and to -allow to restructure a tree easily. Visibility cycling and structure -editing were originally implemented in the package `outline-magic.el', -but quickly moved to the more general `org.el'. TODO entries, basic -time stamps, and table support were added next, and highlight the two -main goals that Org-mode still has today: To create a new, -outline-based, plain text mode with innovative and intuitive editing -features, and to incorporate project planning functionality directly -into a notes file. +of the Emacs outline-mode. I was trying to organize my notes and +projects, and using Emacs seemed to be the natural way to go. However, +having to remember eleven different commands with two or three keys per +command, only to hide and unhide parts of the outline tree, that seemed +entirely unacceptable to me. Also, when using outlines to take notes, I +constantly want to restructure the tree, organizing it parallel to my +thoughts and plans. _Visibility cycling_ and _structure editing_ were +originally implemented in the package `outline-magic.el', but quickly +moved to the more general `org.el'. As this environment became +comfortable for project planning, the next step was adding _TODO +entries_, basic _time stamps_, and _table support_. These areas +highlight the two main goals that Org-mode still has today: To create a +new, outline-based, plain text mode with innovative and intuitive +editing features, and to incorporate project planning functionality +directly into a notes file. Since the first release, hundreds of emails to me or on `emacs-orgmode@gnu.org' have provided a constant stream of bug reports, @@ -5734,6 +5976,8 @@ Index * agenda files, removing buffers: Agenda commands. (line 230) * agenda views: Agenda views. (line 6) * agenda views, custom: Custom agenda views. (line 6) +* agenda views, user-defined: Special agenda views. + (line 6) * agenda, batch production: Batch processing. (line 6) * agenda, with block views: Block agenda. (line 6) * align, STARTUP keyword: In-buffer settings. (line 29) @@ -5747,7 +5991,7 @@ Index * backtrace of an error: Feedback. (line 27) * BBDB links: External links. (line 6) * block agenda: Block agenda. (line 6) -* blorg.el: Extensions. (line 33) +* blorg.el: Extensions. (line 32) * bold text: Enhancing text. (line 15) * Boolean logic, for tag searches: Tag searches. (line 23) * bug reports: Feedback. (line 6) @@ -5785,8 +6029,8 @@ Index * completion, of link abbreviations: Completion. (line 6) * completion, of links: Handling links. (line 27) * completion, of option keywords <1>: Completion. (line 6) -* completion, of option keywords: Export options. (line 6) -* Completion, of option keywords: Per file keywords. (line 17) +* completion, of option keywords <2>: Export options. (line 6) +* completion, of option keywords: Per file keywords. (line 17) * completion, of tags <1>: Completion. (line 6) * completion, of tags: Setting tags. (line 11) * completion, of TeX symbols: Completion. (line 6) @@ -5815,9 +6059,9 @@ Index (line 6) * DEADLINE keyword: Time stamps. (line 53) * deadlines: Time stamps. (line 6) -* Deadlines, repeating: Repeating items. (line 6) +* deadlines, repeating: Repeating items. (line 6) * debugging, of table formulas: Editing and debugging formulas. - (line 60) + (line 70) * demotion, of subtrees: Structure editing. (line 6) * diary entries, creating from agenda: Agenda commands. (line 198) * diary integration: Weekly/Daily agenda. (line 24) @@ -5828,6 +6072,7 @@ Index * display changing, in agenda: Agenda commands. (line 65) * document structure: Document structure. (line 6) * DONE, final TODO keyword: Per file keywords. (line 20) +* dynamic blocks: Dynamic blocks. (line 6) * editing tables: Tables. (line 6) * editing, of table formulas: Editing and debugging formulas. (line 6) @@ -5839,10 +6084,11 @@ Index * exporting: Exporting. (line 6) * exporting, not: Comment lines. (line 6) * extended TODO keywords: TODO extensions. (line 6) +* extension, third-party: Extensions. (line 6) * external archiving: Moving subtrees. (line 6) * external links: External links. (line 6) * external links, in HTML export: Links. (line 6) -* FAQ: Summary. (line 52) +* FAQ: Summary. (line 53) * feedback: Feedback. (line 6) * field formula: Field formulas. (line 6) * field references: References. (line 14) @@ -5861,7 +6107,7 @@ Index (line 15) * format, of links: Link format. (line 6) * formula debugging: Editing and debugging formulas. - (line 60) + (line 70) * formula editing: Editing and debugging formulas. (line 6) * formula syntax, Calc: Formula syntax for Calc. @@ -5890,6 +6136,8 @@ Index (line 6) * horizontal rules, in exported files: Enhancing text. (line 18) * HTML export: HTML export. (line 6) +* HTML, and orgtbl-mode: Translator functions. + (line 6) * hyperlinks: Hyperlinks. (line 6) * iCalendar export: iCalendar export. (line 6) * images, inline in HTML: Images. (line 6) @@ -5915,6 +6163,7 @@ Index * LaTeX fragments, preview: Processing LaTeX fragments. (line 6) * LaTeX interpretation: Embedded LaTeX. (line 6) +* LaTeX, and orgtbl-mode: A LaTeX example. (line 6) * level, require for tags match: Tag searches. (line 68) * linebreak preservation: Export options. (line 25) * linebreak, forced: Enhancing text. (line 35) @@ -5968,12 +6217,14 @@ Index * options, for publishing: Publishing options. (line 6) * ordered lists: Plain lists. (line 6) * org-agenda, command: Weekly/Daily agenda. (line 9) -* org-blog.el: Extensions. (line 29) +* org-blog.el: Extensions. (line 28) * org-mode, turning on: Activation. (line 22) -* org-mouse.el: Extensions. (line 17) +* org-mouse.el: Extensions. (line 16) * org-publish-project-alist: Project alist. (line 6) * org-publish.el: Extensions. (line 8) -* org2rem.el: Extensions. (line 37) +* org2rem.el: Extensions. (line 36) +* orgtbl-mode <1>: Tables in arbitrary syntax. + (line 6) * orgtbl-mode: orgtbl-mode. (line 6) * outline tree: Headlines. (line 6) * outline-mode: Outlines. (line 6) @@ -5996,6 +6247,7 @@ Index * promotion, of subtrees: Structure editing. (line 6) * publishing: Publishing. (line 6) * quoted HTML tags: Export options. (line 25) +* radio tables: Radio tables. (line 6) * radio targets: Radio targets. (line 6) * range references: References. (line 44) * ranges, time: Time stamps. (line 6) @@ -6018,7 +6270,7 @@ Index * RMAIL links: External links. (line 6) * SCHEDULED keyword: Time stamps. (line 40) * scheduling: Time stamps. (line 6) -* Scheduling, repeating: Repeating items. (line 6) +* scheduling, repeating: Repeating items. (line 6) * search option in file links: Search options. (line 6) * search strings, custom: Custom searches. (line 6) * searching for tags: Tag searches. (line 6) @@ -6064,6 +6316,8 @@ Index * tables <1>: Export options. (line 25) * tables: Tables. (line 6) * tables, export: Enhancing text. (line 24) +* tables, in other modes: Tables in arbitrary syntax. + (line 6) * tag completion: Completion. (line 6) * tag searches: Tag searches. (line 6) * tags: Tags. (line 6) @@ -6110,6 +6364,8 @@ Index * transient-mark-mode <3>: Built-in table editor. (line 141) * transient-mark-mode: Structure editing. (line 64) +* translator function: Translator functions. + (line 6) * trees, sparse: Sparse trees. (line 6) * trees, visibility: Visibility cycling. (line 6) * tty keybindings: TTY keys. (line 6) @@ -6163,9 +6419,11 @@ Key Index * <TAB> <1>: CDLaTeX mode. (line 23) * <TAB> <2>: Agenda commands. (line 35) * <TAB> <3>: Setting tags. (line 68) -* <TAB> <4>: Built-in table editor. +* <TAB> <4>: Editing and debugging formulas. + (line 37) +* <TAB> <5>: Built-in table editor. (line 57) -* <TAB> <5>: Plain lists. (line 37) +* <TAB> <6>: Plain lists. (line 37) * <TAB>: Visibility cycling. (line 10) * > <1>: Agenda commands. (line 173) * >: The date/time prompt. @@ -6337,7 +6595,7 @@ Key Index * L: Agenda commands. (line 32) * M: Agenda commands. (line 204) * M-<down> <1>: Editing and debugging formulas. - (line 42) + (line 52) * M-<down>: Built-in table editor. (line 82) * M-<left> <1>: Built-in table editor. @@ -6350,9 +6608,11 @@ Key Index * M-<right>: Structure editing. (line 24) * M-<TAB> <1>: Completion. (line 10) * M-<TAB> <2>: Setting tags. (line 6) -* M-<TAB>: Per file keywords. (line 17) +* M-<TAB> <3>: Per file keywords. (line 17) +* M-<TAB>: Editing and debugging formulas. + (line 44) * M-<up> <1>: Editing and debugging formulas. - (line 42) + (line 52) * M-<up>: Built-in table editor. (line 82) * M-S-<down> <1>: Built-in table editor. @@ -6402,7 +6662,7 @@ Key Index * S-<down> <3>: Creating timestamps. (line 58) * S-<down> <4>: Priorities. (line 25) * S-<down> <5>: Editing and debugging formulas. - (line 37) + (line 47) * S-<down>: Plain lists. (line 55) * S-<left> <1>: Agenda commands. (line 169) * S-<left> <2>: The date/time prompt. @@ -6425,7 +6685,7 @@ Key Index * S-<up> <3>: Creating timestamps. (line 58) * S-<up> <4>: Priorities. (line 25) * S-<up> <5>: Editing and debugging formulas. - (line 37) + (line 47) * S-<up>: Plain lists. (line 55) * T: Agenda commands. (line 126) * t: Agenda commands. (line 113) @@ -6437,175 +6697,182 @@ Key Index Tag Table: Node: Top970 -Node: Introduction11179 -Node: Summary11594 -Node: Installation14495 -Node: Activation15873 -Node: Feedback17122 -Node: Document structure19198 -Node: Outlines19972 -Node: Headlines20632 -Node: Visibility cycling21255 -Ref: Visibility cycling-Footnote-123346 -Ref: Visibility cycling-Footnote-223404 -Ref: Visibility cycling-Footnote-323454 -Node: Motion23723 -Node: Structure editing24507 -Node: Archiving27333 -Node: ARCHIVE tag27891 -Node: Moving subtrees29684 -Node: Sparse trees30995 -Ref: Sparse trees-Footnote-133127 -Ref: Sparse trees-Footnote-233309 -Node: Plain lists33424 -Ref: Plain lists-Footnote-136949 -Ref: Plain lists-Footnote-237306 -Node: Tables37490 -Node: Built-in table editor38004 -Node: Narrow columns45000 -Ref: Narrow columns-Footnote-146932 -Node: orgtbl-mode46978 -Node: The spreadsheet47472 -Node: References48290 -Node: Formula syntax for Calc51547 -Node: Formula syntax for Lisp53864 -Node: Field formulas55092 -Node: Column formulas56403 -Node: Editing and debugging formulas57826 -Node: Updating the table60534 -Node: Advanced features61565 -Node: Hyperlinks65990 -Node: Link format66763 -Node: Internal links68056 -Ref: Internal links-Footnote-170045 -Node: Radio targets70177 -Node: CamelCase links70892 -Node: External links71486 -Node: Handling links73890 -Ref: Handling links-Footnote-178982 -Ref: Handling links-Footnote-279219 -Node: Link abbreviations79293 -Node: Search options80972 -Ref: Search options-Footnote-182752 -Node: Custom searches82833 -Node: Remember83881 -Node: Setting up remember84868 -Node: Remember templates85450 -Ref: Remember templates-Footnote-188765 -Node: Storing notes88863 -Node: TODO items90671 -Node: TODO basics91653 -Node: TODO extensions93180 -Node: Workflow states93975 -Node: TODO types94960 -Ref: TODO types-Footnote-196618 -Node: Per file keywords96700 -Ref: Per file keywords-Footnote-198154 -Node: Priorities98355 -Node: Breaking down tasks99599 -Ref: Breaking down tasks-Footnote-1100118 -Node: Checkboxes100214 -Node: Timestamps102969 -Node: Time stamps103503 -Ref: Time stamps-Footnote-1106997 -Ref: Time stamps-Footnote-2107113 -Node: Creating timestamps107268 -Node: The date/time prompt109894 -Ref: The date/time prompt-Footnote-1111660 -Node: Custom time format111766 -Node: Repeating items113324 -Node: Progress logging115134 -Node: Closing items115780 -Ref: Closing items-Footnote-1116714 -Ref: Closing items-Footnote-2116783 -Node: Tracking TODO state changes116856 -Node: Clocking work time117712 -Ref: Clocking work time-Footnote-1121358 -Ref: Clocking work time-Footnote-2121436 -Node: Tags121562 -Node: Tag inheritance122324 -Node: Setting tags123261 -Ref: Setting tags-Footnote-1127460 -Ref: Setting tags-Footnote-2127572 -Node: Tag searches127655 -Node: Agenda views130366 -Node: Agenda files132311 -Ref: Agenda files-Footnote-1133277 -Ref: Agenda files-Footnote-2133426 -Node: Agenda dispatcher133619 -Node: Built-in agenda views135310 -Node: Weekly/Daily agenda135888 -Node: Global TODO list138017 -Node: Matching headline tags140190 -Node: Timeline141261 -Node: Stuck projects141927 -Node: Presentation and sorting143626 -Node: Categories144417 -Node: Time-of-day specifications145081 -Node: Sorting of agenda items147052 -Node: Agenda commands148334 -Node: Custom agenda views154987 -Node: Storing searches155662 -Node: Block agenda157574 -Node: Setting Options158804 -Node: Batch processing161516 -Node: Embedded LaTeX162646 -Ref: Embedded LaTeX-Footnote-1163738 -Node: Math symbols163928 -Node: Subscripts and Superscripts164693 -Node: LaTeX fragments165537 -Ref: LaTeX fragments-Footnote-1167645 -Node: Processing LaTeX fragments167907 -Node: CDLaTeX mode168853 -Ref: CDLaTeX mode-Footnote-1171337 -Node: Exporting171485 -Node: ASCII export172799 -Node: HTML export174089 -Node: Export commands174708 -Node: Quoting HTML tags175432 -Node: Links175895 -Node: Images176592 -Ref: Images-Footnote-1177463 -Node: CSS support177524 -Ref: CSS support-Footnote-1178843 -Node: XOXO export178956 -Node: iCalendar export179395 -Node: Text interpretation180498 -Node: Comment lines180977 -Node: Enhancing text181448 -Node: Export options183266 -Node: Publishing184933 -Ref: Publishing-Footnote-1185729 -Node: Configuration185925 -Node: Project alist186643 -Node: Sources and destinations187709 -Node: Selecting files188439 -Node: Publishing action189187 -Node: Publishing options190420 -Node: Publishing links192572 -Node: Project page index194085 -Node: Sample configuration194863 -Node: Simple example195355 -Node: Complex example196028 -Node: Triggering publication198104 -Node: Miscellaneous198789 -Node: Completion199423 -Node: Customization200894 -Node: In-buffer settings201477 -Node: The very busy C-c C-c key205717 -Node: Clean view207361 -Node: TTY keys209938 -Node: Interaction211547 -Node: Cooperation211944 -Node: Conflicts214684 -Node: Bugs216276 -Node: Extensions and Hacking217772 -Node: Extensions218276 -Node: Dynamic blocks220219 -Node: Special agenda views222175 -Ref: Special agenda views-Footnote-1224454 -Node: History and Acknowledgments224714 -Node: Index230218 -Node: Key Index260293 +Node: Introduction11466 +Node: Summary11881 +Node: Installation14889 +Node: Activation16267 +Node: Feedback17516 +Node: Document structure19592 +Node: Outlines20366 +Node: Headlines21026 +Node: Visibility cycling21649 +Ref: Visibility cycling-Footnote-123740 +Ref: Visibility cycling-Footnote-223798 +Ref: Visibility cycling-Footnote-323848 +Node: Motion24117 +Node: Structure editing24901 +Node: Archiving27727 +Node: ARCHIVE tag28285 +Node: Moving subtrees30078 +Node: Sparse trees31389 +Ref: Sparse trees-Footnote-133521 +Ref: Sparse trees-Footnote-233703 +Node: Plain lists33818 +Ref: Plain lists-Footnote-137343 +Ref: Plain lists-Footnote-237700 +Node: Tables37884 +Node: Built-in table editor38398 +Node: Narrow columns45394 +Ref: Narrow columns-Footnote-147326 +Node: orgtbl-mode47372 +Node: The spreadsheet48176 +Node: References48994 +Node: Formula syntax for Calc52251 +Node: Formula syntax for Lisp54568 +Node: Field formulas55796 +Node: Column formulas57107 +Node: Editing and debugging formulas58530 +Node: Updating the table61640 +Node: Advanced features62671 +Node: Hyperlinks67196 +Node: Link format67969 +Node: Internal links69262 +Ref: Internal links-Footnote-171251 +Node: Radio targets71383 +Node: CamelCase links72098 +Node: External links72692 +Node: Handling links75096 +Ref: Handling links-Footnote-180188 +Ref: Handling links-Footnote-280425 +Node: Link abbreviations80499 +Node: Search options82178 +Ref: Search options-Footnote-183958 +Node: Custom searches84039 +Node: Remember85087 +Node: Setting up remember86074 +Node: Remember templates86656 +Ref: Remember templates-Footnote-189971 +Node: Storing notes90069 +Node: TODO items91877 +Node: TODO basics92859 +Node: TODO extensions94386 +Node: Workflow states95181 +Node: TODO types96166 +Ref: TODO types-Footnote-197824 +Node: Per file keywords97906 +Ref: Per file keywords-Footnote-199360 +Node: Priorities99561 +Node: Breaking down tasks100805 +Ref: Breaking down tasks-Footnote-1101324 +Node: Checkboxes101420 +Node: Timestamps104175 +Node: Time stamps104709 +Ref: Time stamps-Footnote-1108203 +Ref: Time stamps-Footnote-2108319 +Node: Creating timestamps108474 +Node: The date/time prompt111100 +Ref: The date/time prompt-Footnote-1112866 +Node: Custom time format112972 +Node: Repeating items114530 +Node: Progress logging116340 +Node: Closing items116986 +Ref: Closing items-Footnote-1117920 +Ref: Closing items-Footnote-2117989 +Node: Tracking TODO state changes118062 +Node: Clocking work time118918 +Ref: Clocking work time-Footnote-1122564 +Ref: Clocking work time-Footnote-2122642 +Node: Tags122768 +Node: Tag inheritance123530 +Node: Setting tags124467 +Ref: Setting tags-Footnote-1128666 +Ref: Setting tags-Footnote-2128778 +Node: Tag searches128861 +Node: Agenda views131572 +Node: Agenda files133517 +Ref: Agenda files-Footnote-1134483 +Ref: Agenda files-Footnote-2134632 +Node: Agenda dispatcher134825 +Node: Built-in agenda views136516 +Node: Weekly/Daily agenda137094 +Node: Global TODO list139223 +Node: Matching headline tags141396 +Node: Timeline142467 +Node: Stuck projects143133 +Node: Presentation and sorting144832 +Node: Categories145623 +Node: Time-of-day specifications146287 +Node: Sorting of agenda items148258 +Node: Agenda commands149540 +Node: Custom agenda views156193 +Node: Storing searches156868 +Node: Block agenda158780 +Node: Setting Options160010 +Node: Batch processing162722 +Node: Embedded LaTeX163852 +Ref: Embedded LaTeX-Footnote-1164944 +Node: Math symbols165134 +Node: Subscripts and Superscripts165899 +Node: LaTeX fragments166743 +Ref: LaTeX fragments-Footnote-1168851 +Node: Processing LaTeX fragments169113 +Node: CDLaTeX mode170059 +Ref: CDLaTeX mode-Footnote-1172543 +Node: Exporting172691 +Node: ASCII export174005 +Node: HTML export175295 +Node: Export commands175914 +Node: Quoting HTML tags176638 +Node: Links177101 +Node: Images177798 +Ref: Images-Footnote-1178669 +Node: CSS support178730 +Ref: CSS support-Footnote-1180049 +Node: XOXO export180162 +Node: iCalendar export180601 +Node: Text interpretation181704 +Node: Comment lines182183 +Node: Enhancing text182654 +Node: Export options184472 +Node: Publishing186139 +Ref: Publishing-Footnote-1186935 +Node: Configuration187131 +Node: Project alist187849 +Node: Sources and destinations188915 +Node: Selecting files189645 +Node: Publishing action190393 +Node: Publishing options191626 +Node: Publishing links193778 +Node: Project page index195291 +Node: Sample configuration196069 +Node: Simple example196561 +Node: Complex example197234 +Node: Triggering publication199310 +Node: Miscellaneous199995 +Node: Completion200629 +Node: Customization202100 +Node: In-buffer settings202683 +Node: The very busy C-c C-c key206923 +Node: Clean view208567 +Node: TTY keys211144 +Node: Interaction212753 +Node: Cooperation213150 +Node: Conflicts215890 +Node: Bugs217482 +Node: Extensions and Hacking218978 +Node: Extensions219574 +Node: Tables in arbitrary syntax221521 +Node: Radio tables222596 +Ref: Radio tables-Footnote-1225128 +Node: A LaTeX example225236 +Ref: A LaTeX example-Footnote-1228852 +Ref: A LaTeX example-Footnote-2229000 +Node: Translator functions229435 +Node: Dynamic blocks230466 +Node: Special agenda views232438 +Ref: Special agenda views-Footnote-1234717 +Node: History and Acknowledgments234977 +Node: Index240766 +Node: Key Index271825 End Tag Table @@ -5,7 +5,7 @@ ;; Author: Carsten Dominik <dominik at science dot uva dot nl> ;; Keywords: outlines, hypermedia, calendar, wp ;; Homepage: http://www.astro.uva.nl/~dominik/Tools/org/ -;; Version: 4.64a +;; Version: 4.65 ;; ;; This file is part of GNU Emacs. ;; @@ -83,7 +83,7 @@ ;;; Version -(defvar org-version "4.64a" +(defvar org-version "4.65" "The version number of the file org.el.") (defun org-version () (interactive) @@ -679,6 +679,33 @@ this variable requires a restart of Emacs to become effective." :group 'org-table :type 'boolean) +(defcustom orgtbl-radio-table-templates + '((latex-mode "% BEGIN RECEIVE ORGTBL %n +% END RECEIVE ORGTBL %n +\\begin{comment} +#+ORGTBL: SEND %n orgtbl-to-latex :splice nil :skip 0 +| | | +\\end{comment}\n") + (texinfo-mode "@c BEGIN RECEIVE ORGTBL %n +@c END RECEIVE ORGTBL %n +@ignore +#+ORGTBL: SEND %n orgtbl-to-html :splice nil :skip 0 +| | | +@end ignore\n") + (html-mode "<!-- BEGIN RECEIVE ORGTBL %n --> +<!-- END RECEIVE ORGTBL %n --> +<!-- +#+ORGTBL: SEND %n orgtbl-to-html :splice nil :skip 0 +| | | +-->\n")) + "Templates for radio tables in different major modes. +All occurrences of %n in a template will be replaced with the name of the +table, obtained by prompting the user." + :group 'org-table + :type '(repeat + (list (symbol :tag "Major mode") + (string :tag "Format")))) + (defgroup org-table-settings nil "Settings for tables in Org-mode." :tag "Org Table Settings" @@ -2540,7 +2567,7 @@ Otherwise the buffer will just be saved to a file and stay hidden." table { border-collapse: collapse; } td, th { vertical-align: top; - border: 1pt solid #ADB9CC; + <!--border: 1pt solid #ADB9CC;--> } </style>" "The default style specification for exported HTML files. @@ -2610,7 +2637,7 @@ This option can also be set with the +OPTIONS line, e.g. \"@:nil\"." :type 'boolean) (defcustom org-export-html-table-tag - "<table border=\"1\" cellspacing=\"0\" cellpadding=\"6\">" + "<table border=\"2\" cellspacing=\"0\" cellpadding=\"6\" rules=\"groups\" frame=\"hsides\">" "The HTML tag used to start a table. This must be a <table> tag, but you may change the options like borders and spacing." @@ -7945,6 +7972,10 @@ Parameters get priority." (define-key org-edit-formulas-map [(shift right)] 'org-table-edit-next-field) (define-key org-edit-formulas-map [(meta up)] 'org-table-edit-scroll-down) (define-key org-edit-formulas-map [(meta down)] 'org-table-edit-scroll) +(define-key org-edit-formulas-map [(meta tab)] 'lisp-complete-symbol) +(define-key org-edit-formulas-map "\M-\C-i" 'lisp-complete-symbol) +(define-key org-edit-formulas-map [(tab)] 'org-edit-formula-lisp-indent) +(define-key org-edit-formulas-map "\C-i" 'org-edit-formula-lisp-indent) (defvar org-pos) @@ -7965,39 +7996,45 @@ Parameters get priority." (use-local-map org-edit-formulas-map) (org-add-hook 'post-command-hook 'org-table-edit-formulas-post-command t t) (setq s "# `C-c C-c' to finish, `C-u C-c C-c' to also apply, `C-c C-q' to abort. -# `M-up/down' to scroll table, `S-up/down' to change line for column formulas\n") +# `TAB' to pretty-print Lisp expressions, `M-TAB' to complete List symbols +# `M-up/down' to scroll table, `S-up/down' to change line for column formulas\n\n") (put-text-property 0 (length s) 'face 'font-lock-comment-face s) (insert s) (while (setq entry (pop eql)) (setq s (concat (if (equal (string-to-char (car entry)) ?@) "" "$") - (car entry) "=" (cdr entry) "\n")) + (car entry) " = " (cdr entry) "\n")) (remove-text-properties 0 (length s) '(face nil) s) (insert s)) (goto-char (point-min)) (message "Edit formulas and finish with `C-c C-c'."))) (defun org-table-edit-formulas-post-command () - (let ((win (selected-window))) - (save-excursion - (condition-case nil - (org-show-reference) - (error nil)) - (select-window win)))) + (when (not (memq this-command '(lisp-complete-symbol))) + (let ((win (selected-window))) + (save-excursion + (condition-case nil + (org-show-reference) + (error nil)) + (select-window win))))) (defun org-finish-edit-formulas (&optional arg) "Parse the buffer for formula definitions and install them. With prefix ARG, apply the new formulas to the table." (interactive "P") (org-table-remove-rectangle-highlight) - (let ((pos org-pos) eql) + (let ((pos org-pos) eql var form) (setq org-pos nil) (goto-char (point-min)) (while (re-search-forward - "^\\(@[0-9]+\\$[0-9]+\\|\\$\\([a-zA-Z0-9]+\\)\\) *= *\\(.*?\\) *$" + "^\\(@[0-9]+\\$[0-9]+\\|\\$\\([a-zA-Z0-9]+\\)\\) *= *\\(.*\\(\n[ \t]+.*$\\)*\\)" nil t) - (push (cons (if (match-end 2) (match-string 2) (match-string 1)) - (match-string 3)) eql)) + (setq var (if (match-end 2) (match-string 2) (match-string 1)) + form (match-string 3)) + (setq form (org-trim form)) + (while (string-match "[ \t]*\n[ \t]*" form) + (setq form (replace-match " " t t form))) + (push (cons var form) eql)) (set-window-configuration org-window-configuration) (select-window (get-buffer-window (marker-buffer pos))) (goto-char pos) @@ -8021,6 +8058,45 @@ With prefix ARG, apply the new formulas to the table." (move-marker pos nil) (message "Formula editing aborted without installing changes"))) +(defun org-edit-formula-lisp-indent () + "Pretty-print and re-indent Lisp expressions in the Formula Editor." + (interactive) + (let ((pos (point)) beg end ind) + (beginning-of-line 1) + (cond + ((looking-at "[ \t]") + (goto-char pos) + (call-interactively 'lisp-indent-line)) + ((looking-at "[$@0-9a-zA-Z]+ *= *[^ \t\n']") (goto-char pos)) + ((not (fboundp 'pp-buffer)) + (error "Cannot pretty-print. Command `pp-buffer' is not available.")) + ((looking-at "[$@0-9a-zA-Z]+ *= *'(") + (goto-char (- (match-end 0) 2)) + (setq beg (point)) + (setq ind (make-string (current-column) ?\ )) + (condition-case nil (forward-sexp 1) + (error + (error "Cannot pretty-print Lisp expression: Unbalanced parenthesis"))) + (setq end (point)) + (save-restriction + (narrow-to-region beg end) + (if (eq last-command this-command) + (progn + (goto-char (point-min)) + (setq this-command nil) + (while (re-search-forward "[ \t]*\n[ \t]*" nil t) + (replace-match " "))) + (pp-buffer) + (untabify (point-min) (point-max)) + (goto-char (1+ (point-min))) + (while (re-search-forward "^." nil t) + (beginning-of-line 1) + (insert ind)) + (goto-char (point-max)) + (backward-delete-char 1))) + (goto-char beg)) + (t nil)))) + (defvar org-show-positions nil) (defun org-show-reference (&optional local) @@ -8132,7 +8208,7 @@ With prefix ARG, apply the new formulas to the table." (let ((min (apply 'min org-show-positions)) (max (apply 'max org-show-positions))) (when (or (not (pos-visible-in-window-p min)) - (no t(pos-visible-in-window-p max))) + (not (pos-visible-in-window-p max))) (goto-char min) (set-window-start (selected-window) (point-at-bol)) (goto-char pos)))) @@ -8283,6 +8359,14 @@ table editor in arbitrary modes.") (defvar org-old-auto-fill-inhibit-regexp nil "Local variable used by `orgtbl-mode'") +(defconst orgtbl-line-start-regexp "[ \t]*\\(|\\|#\\+\\(TBLFM\\|ORGTBL\\):\\)" + "Matches a line belonging to an orgtbl.") + +(defconst orgtbl-extra-font-lock-keywords + (list (list (concat "^" orgtbl-line-start-regexp ".*") + 0 (quote 'org-table) 'prepend)) + "Extra font-lock-keywords to be added when orgtbl-mode is active.") + ;;;###autoload (defun orgtbl-mode (&optional arg) "The `org-mode' table editor as a minor mode for use in other modes." @@ -8307,15 +8391,22 @@ table editor in arbitrary modes.") auto-fill-inhibit-regexp) (org-set-local 'auto-fill-inhibit-regexp (if auto-fill-inhibit-regexp - (concat "\\([ \t]*|\\|" auto-fill-inhibit-regexp) - "[ \t]*|")) + (concat orgtbl-line-start-regexp "\\|" + auto-fill-inhibit-regexp) + orgtbl-line-start-regexp)) (org-add-to-invisibility-spec '(org-cwidth)) + (when (fboundp 'font-lock-add-keywords) + (font-lock-add-keywords nil orgtbl-extra-font-lock-keywords) + (org-restart-font-lock)) (easy-menu-add orgtbl-mode-menu) (run-hooks 'orgtbl-mode-hook)) (setq auto-fill-inhibit-regexp org-old-auto-fill-inhibit-regexp) (org-cleanup-narrow-column-properties) (org-remove-from-invisibility-spec '(org-cwidth)) (remove-hook 'before-change-functions 'org-before-change-function t) + (when (fboundp 'font-lock-remove-keywords) + (font-lock-remove-keywords nil orgtbl-extra-font-lock-keywords) + (org-restart-font-lock)) (easy-menu-remove orgtbl-mode-menu) (force-mode-line-update 'all)))) @@ -8418,7 +8509,7 @@ to execute outside of tables." (define-key orgtbl-mode-map "\C-i" (orgtbl-make-binding 'orgtbl-tab 104 [(shift tab)])) (define-key orgtbl-mode-map "\C-c\C-c" - (orgtbl-make-binding 'org-ctrl-c-ctrl-c 105 "\C-c\C-c")) + (orgtbl-make-binding 'orgtbl-ctrl-c-ctrl-c 105 "\C-c\C-c")) (when orgtbl-optimized ;; If the user wants maximum table support, we need to hijack ;; some standard editing functions @@ -8429,6 +8520,11 @@ to execute outside of tables." (define-key orgtbl-mode-map "|" 'org-force-self-insert)) (easy-menu-define orgtbl-mode-menu orgtbl-mode-map "OrgTbl menu" '("OrgTbl" + ("Radio tables" + ["Insert radio table" orgtbl-insert-radio-table + (assq major-mode orgtbl-radio-table-templates)] + ["Comment/uncomment table" orgtbl-toggle-comment t]) ;; FIXME: only at a table + "--" ["Align" org-ctrl-c-ctrl-c :active (org-at-table-p) :keys "C-c C-c"] ["Next Field" org-cycle :active (org-at-table-p) :keys "TAB"] ["Previous Field" org-shifttab :active (org-at-table-p) :keys "S-TAB"] @@ -8476,6 +8572,18 @@ to execute outside of tables." )) t) +(defun orgtbl-ctrl-c-ctrl-c (arg) + "If the cursor is inside a table, realign the table. +It it is a table to be sent away to a receiver, do it. +With prefix arg, also recompute table." + (interactive "P") + (org-table-maybe-eval-formula) + (if arg + (call-interactively 'org-table-recalculate) + (org-table-maybe-recalculate-line)) + (call-interactively 'org-table-align) + (orgtbl-send-table 'maybe)) + (defun orgtbl-tab (arg) "Justification and field motion for `orgtbl-mode'." (interactive "P") @@ -8522,6 +8630,272 @@ overwritten, and the table is not marked as requiring realignment." (interactive "p") (self-insert-command N)) +(defvar orgtbl-exp-regexp "^\\([-+]?[0-9][0-9.]*\\)[eE]\\([-+]?[0-9]+\\)$" + "Regula expression matching exponentials as produced by calc.") + +(defvar org-table-clean-did-remove-column-1 nil) + +(defun orgtbl-send-table (&optional maybe) + "Send a tranformed version of this table to the receiver position. +With argument MAYBE, fail quietly if no transformation is defined for +this table." + (interactive) + (catch 'exit + (unless (org-at-table-p) (error "Not at a table")) + ;; when non-interactive, we assume align has just happened. + (when (interactive-p) (org-table-align)) + (save-excursion + (goto-char (org-table-begin)) + (beginning-of-line 0) + (unless (looking-at "#\\+ORGTBL: *SEND +\\([a-zA-Z0-9_]+\\) +\\([^ \t\r\n]+\\)\\( +.*\\)?") + (if maybe + (throw 'exit nil) + (error "Don't know how to transform this table.")))) + (let* ((name (match-string 1)) + i line beg + (transform (intern (match-string 2))) + (params (if (match-end 3) (read (concat "(" (match-string 3) ")")))) + (skip (plist-get params :skip)) + (skipcols (plist-get params :skipcols)) + (txt (buffer-substring-no-properties + (org-table-begin) (org-table-end))) + (lines (nthcdr (or skip 0) (org-split-string txt "[ \t]*\n[ \t]*"))) + (lines (org-table-clean-before-export lines)) + (table (mapcar + (lambda (x) + (if (string-match org-table-hline-regexp x) + 'hline + (setq line (org-split-string (org-trim x) "\\s-*|\\s-*")) + (when skipcols + ;; Remove columns that should be skipped + (setq i (if org-table-clean-did-remove-column-1 1 0) + line + (delq nil + (mapcar (lambda (x) + (if (member (setq i (1+ i)) + skipcols) nil x)) + line)))) + line)) + lines))) + + (unless (fboundp transform) + (error "No such transformation function %s" transform)) + (setq txt (funcall transform table params)) + ;; Find the insertion place + (save-excursion + (goto-char (point-min)) + (unless (re-search-forward + (concat "BEGIN RECEIVE ORGTBL +" name "\\([ \t]\\|$\\)") nil t) + (error "Don't know where to insert translated table")) + (goto-char (match-beginning 0)) + (beginning-of-line 2) + (setq beg (point)) + (unless (re-search-forward (concat "END RECEIVE ORGTBL +" name) nil t) + (error "Cannot find end of insertion region")) + (beginning-of-line 1) + (delete-region beg (point)) + (goto-char beg) + (insert txt "\n")) + (message "Table converted and installed at receiver location")))) + +(defun orgtbl-toggle-comment () + "Comment or uncomment the orgtbl at point." + (interactive) + (let* ((re1 (concat "^" (regexp-quote comment-start) orgtbl-line-start-regexp)) + (re2 (concat "^" orgtbl-line-start-regexp)) + (commented (save-excursion (beginning-of-line 1) + (cond ((looking-at re1) t) + ((looking-at re2) nil) + (t (error "Not at an org table"))))) + (re (if commented re1 re2)) + beg end) + (save-excursion + (beginning-of-line 1) + (while (looking-at re) (beginning-of-line 0)) + (beginning-of-line 2) + (setq beg (point)) + (while (looking-at re) (beginning-of-line 2)) + (setq end (point))) + (comment-region beg end (if commented '(4) nil)))) + +(defun orgtbl-insert-radio-table () + "Insert a radio table template appropriate for this major mode." + (interactive) + (let* ((e (assq major-mode orgtbl-radio-table-templates)) + (txt (nth 1 e)) + name pos) + (unless e (error "No radio table setup defined for %s" major-mode)) + (setq name (read-string "Table name: ")) + (while (string-match "%n" txt) + (setq txt (replace-match name t t txt))) + (or (bolp) (insert "\n")) + (setq pos (point)) + (insert txt) + (goto-char pos))) + +(defun orgtbl-to-latex (table params) + "Convert the orgtbl-mode TABLE to LaTeX. +TABLE is a list, each entry either the symbol `hline' for a horizontal +separator line, or a list of fields for that line. +PARAMS is a property list of parameters that can influence the conversion. +Valid parameters are + +:splice nil/t When set to t, return only table body lines, don't wrap + them into a tabular environment. Default is nil. + +:fmt fmt A format to be used to wrap the field, should contain + %s for the original field value. For example, to wrap + everything in dollars, you could use :fmt \"$%s$\". + This may also be a property list with column numbers and + formats. for example :fmt (2 \"$%s$\" 4 \"%s%%\") + +:efmt efmt Use this format to print numbers with exponentials. + The format should have %s twice for inserting mantissa + and exponent, for example \"%s\\\\times10^{%s}\". Default + is \"%s\\\\,(%s)\". This may also be a property list + with column numbers and formats. + +In addition to this, a number of standard parameters are always handled +directly by `orgtbl-send-table'. See manual." + (interactive) + (let* ((splicep (plist-get params :splice)) ; do we need table header? + (fmt (plist-get params :fmt)) ; General format + (efmt (plist-get params :efmt)) ; Format for numbers with exp + rtn ; list collecting converted lines + alignment line i fm efm) + + ;; First check if we need to put the tabular environment ourselves + (unless splicep + ;; yes, we do + (setq alignment (mapconcat (lambda (x) (if x "r" "l")) + org-table-last-alignment "")) + (push (concat "\\begin{tabular}{" alignment "}") rtn)) + + ;; Now loop over all lines + (while (setq line (pop table)) + (if (eq line 'hline) + ;; A horizontal separator line + (push "\\hline" rtn) + ;; A normal line. Convert the fields, push line onto the result list + (setq i 0) ; counter for column, to access column-specific settings + (push + (concat + (mapconcat + (lambda (f) + ;; First get the settings that apply here. + (setq i (1+ i) + fm (if (stringp fmt) fmt (or (plist-get fmt i) "%s")) + efm (if (stringp efmt) efmt (or (plist-get efmt i) + "%s\\,(%s)"))) + (if (string-match orgtbl-exp-regexp f) + ;; exponential, format accordingly + (setq f (format efm (match-string 1 f) (match-string 2 f)))) + ;; Apply standard format + (format fm f)) + line + " & ") ; Field separator + "\\\\") ; Line separator + rtn))) + + ;; Close the tabular environment? + (unless splicep (push "\\end{tabular}" rtn)) + + ;; Concatenate the lines, to return a single block of text + (mapconcat 'identity (nreverse rtn) "\n"))) + +(defun orgtbl-to-html (table params) + "Convert the orgtbl-mode TABLE to LaTeX. +TABLE is a list, each entry either the symbol `hline' for a horizontal +separator line, or a list of fields for that line. +PARAMS is a property list of parameters that can influence the conversion. +Currently this function recognizes the following parameters: + +:splice nil/t When set to t, return only table body lines, don't wrap + them into a <table> environment. Default is nil. + +A number of standard parameters are always handled directly by +`orgtbl-send-table'. See manual." + (interactive) + (let* ((splicep (plist-get params :splice)) + html) + ;; Just call the formatter we already have + ;; We need to make text lines for it, so put the fields back together. + (setq html (org-format-org-table-html + (mapcar + (lambda (x) + (if (eq x 'hline) + "|----+----|" + (concat "| " (mapconcat 'identity x " | ") " |"))) + table) + splicep)) + (if (string-match "\n+\\'" html) + (setq html (replace-match "" t t html))) + html)) + +(defun orgtbl-to-texinfo (table params) + "Convert the orgtbl-mode TABLE to TeXInfo. +TABLE is a list, each entry either the symbol `hline' for a horizontal +separator line, or a list of fields for that line. +PARAMS is a property list of parameters that can influence the conversion. +Valid parameters are + +:splice nil/t When set to t, return only table body lines, don't wrap + them into a multitable environment. Default is nil. + +:fmt fmt A format to be used to wrap the field, should contain + %s for the original field value. For example, to wrap + everything in @kbd{}, you could use :fmt \"@kbd{%s}\". + This may also be a property list with column numbers and + formats. for example :fmt (2 \"@kbd{%s}\" 4 \"@code{%s}\"). + +:cf \"f1 f2..\" The column fractions for the table. Bye default these + are computed automatically from the width of the columns + under org-mode. + +Furthermore, a number of standard parameters are always handled directly +by `orgtbl-send-table'. See manual." + (interactive) + (let* ((splicep (plist-get params :splice)) ; do we need table header? + (fmt (plist-get params :fmt)) ; General format + (colfrac (plist-get params :cf)) ; Column fractions + rtn ; list collecting converted lines + total line head i fm) + + (if (and (not splicep) (listp (car table)) (eq 'hline (nth 1 table))) + (setq head t)) + + ;; First check if we need to put the multitable environment ourselves + (unless splicep + (unless colfrac + (setq total (float (apply '+ org-table-last-column-widths)) + colfrac (mapconcat + (lambda (x) (format "%.3f" (/ (float x) total))) + org-table-last-column-widths " "))) + (push (concat "@multitable @columnfractions " colfrac) rtn)) + + ;; Loop over all lines + (while (setq line (pop table)) + (if (eq line 'hline) + ;; A horizontal separator line - TeXinfo cannot handle this + nil + ;; A normal line. Convert the fields, push line onto the result list + (setq i 0) ; counter for column, to access column-specific settings + (push + (concat + (if head (progn (setq head nil) "@headitem ") "@item ") + (mapconcat + (lambda (f) + ;; First get the settings that apply here. + (setq i (1+ i) + fm (if (stringp fmt) fmt (or (plist-get fmt i) "%s"))) + (format fm f)) + line + " @tab ") ; Field separator + "") + rtn))) + (unless splicep (push "@end multitable" rtn)) + (mapconcat 'identity (nreverse rtn) "\n"))) + ;;;; Link Stuff ;;; Link abbreviations @@ -10047,7 +10421,7 @@ to be run from that hook to fucntion properly." (or headline "")))) (insert tpl) (goto-char (point-min)) ;; Simple %-escapes - (while (re-search-forward "%\\([tTuTai]\\)" nil t) + (while (re-search-forward "%\\([tTuUai]\\)" nil t) (when (and initial (equal (match-string 0) "%i")) (save-match-data (let* ((lead (buffer-substring @@ -10098,7 +10472,7 @@ to be run from that hook to fucntion properly." ;;;###autoload (defun org-remember () "Call `remember'. If this is already a remember buffer, re-apply template. -If there is an active region, amke sure remember uses it as initial content +If there is an active region, make sure remember uses it as initial content of the remember buffer." (interactive) (if (eq org-finish-function 'remember-buffer) @@ -11028,7 +11402,7 @@ are included in the output." (goto-char lspos) (setq marker (org-agenda-new-marker)) (org-add-props txt props - 'org-marker marker 'org-hd-marker marker 'category category) + 'org-marker marker 'org-hd-marker marker 'org-category category) (push txt rtn)) ;; if we are to skip sublevels, jump to end of subtree (or org-tags-match-list-sublevels (org-end-of-subtree t)))))) @@ -12487,7 +12861,8 @@ The following commands are available: ;; Make sure properties are removed when copying text (when (boundp 'buffer-substring-filters) (org-set-local 'buffer-substring-filters - (cons (lambda (x) (set-text-properties 0 (length x) nil x) x) + (cons (lambda (x) + (set-text-properties 0 (length x) nil x) x) buffer-substring-filters))) (unless org-agenda-keep-modes (setq org-agenda-follow-mode org-agenda-start-with-follow-mode @@ -14022,7 +14397,7 @@ the documentation of `org-diary'." 1))) (org-add-props txt props 'org-marker marker 'org-hd-marker marker - 'priority priority 'category category) + 'priority priority 'org-category category) (push txt ee) (if org-agenda-todo-list-sublevels (goto-char (match-end 1)) @@ -14091,13 +14466,13 @@ the documentation of `org-diary'." (org-add-props txt nil 'face (if donep 'org-done 'org-warning) 'undone-face 'org-warning 'done-face 'org-done - 'category category 'priority (+ 100 priority)) + 'org-category category 'priority (+ 100 priority)) (if scheduledp (org-add-props txt nil 'face 'org-scheduled-today 'undone-face 'org-scheduled-today 'done-face 'org-done - 'category category 'priority (+ 99 priority)) - (org-add-props txt nil 'priority priority 'category category))) + 'org-category category 'priority (+ 99 priority)) + (org-add-props txt nil 'priority priority 'org-category category))) (push txt ee)) (outline-next-heading))) (nreverse ee))) @@ -14148,7 +14523,7 @@ the documentation of `org-diary'." (setq priority 100000) (org-add-props txt props 'org-marker marker 'org-hd-marker hdmarker 'face 'org-done - 'priority priority 'category category + 'priority priority 'org-category category 'undone-face 'org-warning 'done-face 'org-done) (push txt ee)) (outline-next-heading))) @@ -14204,7 +14579,7 @@ the documentation of `org-diary'." 'org-marker (org-agenda-new-marker pos) 'org-hd-marker (org-agenda-new-marker pos1) 'priority (+ (- 10 diff) (org-get-priority txt)) - 'category category + 'org-category category 'face face 'undone-face face 'done-face 'org-done) (push txt ee)))))) ee)) @@ -14257,7 +14632,7 @@ the documentation of `org-diary'." 'org-marker (org-agenda-new-marker pos) 'org-hd-marker (org-agenda-new-marker pos1) 'priority (+ (- 5 diff) (org-get-priority txt)) - 'category category) + 'org-category category) (push txt ee)))))) ee)) @@ -14303,7 +14678,7 @@ the documentation of `org-diary'." (setq txt org-agenda-no-heading-message)) (org-add-props txt props 'org-marker marker 'org-hd-marker hdmarker - 'priority (org-get-priority txt) 'category category) + 'priority (org-get-priority txt) 'org-category category) (push txt ee))) (goto-char pos))) ;; Sort the entries by expiration date. @@ -14420,7 +14795,7 @@ only the correctly processes TXT should be returned - this is used by ;; And finally add the text properties (org-add-props rtn nil - 'category (downcase category) 'tags tags + 'org-category (downcase category) 'tags tags 'prefix-length (- (length rtn) (length txt)) 'time-of-day time-of-day 'dotime dotime)))) @@ -15084,7 +15459,7 @@ the new TODO state." (equal m hdmarker)) (setq props (text-properties-at (point)) dotime (get-text-property (point) 'dotime) - cat (get-text-property (point) 'category) + cat (get-text-property (point) 'org-category) tags (get-text-property (point) 'tags) new (org-format-agenda-item "x" newhead cat tags dotime 'noprefix) pl (get-text-property (point) 'prefix-length) @@ -15111,6 +15486,8 @@ the new TODO state." (beginning-of-line 0))) (org-finalize-agenda))) +;; FIXME: allow negative value for org-agenda-align-tags-to-column +;; See the code in set-tags for the way to do this. (defun org-agenda-align-tags (&optional line) "Align all tags in agenda items to `org-agenda-align-tags-to-column'." (let ((buffer-read-only)) @@ -17415,8 +17792,9 @@ lang=\"%s\" xml:lang=\"%s\"> ;; Need to use the code generator in table.el, with the original text. (org-format-table-table-html-using-table-generate-source olines))))) -(defun org-format-org-table-html (lines) +(defun org-format-org-table-html (lines &optional splice) "Format a table into HTML." + ;; Get rid of hlines at beginning and end (if (string-match "^[ \t]*|-" (car lines)) (setq lines (cdr lines))) (setq lines (nreverse lines)) (if (string-match "^[ \t]*|-" (car lines)) (setq lines (cdr lines))) @@ -17424,52 +17802,84 @@ lang=\"%s\" xml:lang=\"%s\"> (when org-export-table-remove-special-lines ;; Check if the table has a marking column. If yes remove the ;; column and the special lines - (let* ((special - (not - (memq nil - (mapcar - (lambda (x) - (or (string-match "^[ \t]*|-" x) - (string-match "^[ \t]*| *\\([#!$*_^ ]\\) *|" x))) - lines))))) - (if special - (setq lines - (delq nil - (mapcar - (lambda (x) - (if (string-match "^[ \t]*| *[!_^] *|" x) - nil ; ignore this line - (and (or (string-match "^[ \t]*|-+\\+" x) - (string-match "^[ \t]*|[^|]*|" x)) - (replace-match "|" t t x)))) - lines)))))) + (setq lines (org-table-clean-before-export lines))) (let ((head (and org-export-highlight-first-table-line (delq nil (mapcar (lambda (x) (string-match "^[ \t]*|-" x)) (cdr lines))))) - line fields html) - (setq html (concat org-export-html-table-tag "\n")) + (nlines 0) fnum i align al2 + tbopen line fields html) + (if splice (setq head nil)) + (unless splice (push (if head "<thead>" "<tbody>") html)) + (setq tbopen t) (while (setq line (pop lines)) (catch 'next-line (if (string-match "^[ \t]*|-" line) (progn + (unless splice + (push (if head "</thead>" "</tbody>") html) + (if lines (push "<tbody>" html) (setq tbopen nil))) (setq head nil) ;; head ends here, first time around ;; ignore this line (throw 'next-line t))) ;; Break the line into fields (setq fields (org-split-string line "[ \t]*|[ \t]*")) - (setq html (concat - html - "<tr>" - (mapconcat (lambda (x) - (if head - (concat "<th>" x "</th>") - (concat "<td>" x "</td>"))) - fields "") - "</tr>\n")))) - (setq html (concat html "</table>\n")) - html)) + (unless fnum (setq fnum (make-vector (length fields) 0))) + (setq nlines (1+ nlines) i -1) + (push (concat "<tr>" + (mapconcat + (lambda (x) + (setq i (1+ i)) + (if (and (< i nlines) + (string-match org-table-number-regexp x)) + (incf (aref fnum i))) + (if head + (concat "<th>" x "</th>") + (concat "<td>" x "</td>"))) + fields "") + "</tr>") + html))) + (unless splice (if tbopen (push "</tbody>" html))) + (unless splice (push "</table>\n" html)) + (setq html (nreverse html)) + (unless splice + (setq align (mapcar + (lambda (x) + (if (> (/ (float x) nlines) org-table-number-fraction) + "right" "left")) + fnum)) + ;; Put in COL tags with the alignment (unfortuntely often ignored...) + (push (mapconcat + (lambda (x) + (format "<COL align=\"%s\">" + (if (> (/ (float x) nlines) org-table-number-fraction) + "right" "left"))) + fnum "") + html) + (push org-export-html-table-tag html)) + (concat (mapconcat 'identity html "\n") "\n"))) + +(defun org-table-clean-before-export (lines) + "Check if the table has a marking column. +If yes remove the column and the special lines." + (if (memq nil + (mapcar + (lambda (x) (or (string-match "^[ \t]*|-" x) + (string-match "^[ \t]*| *\\([#!$*_^ /]\\) *|" x))) + lines)) + (progn + (setq org-table-clean-did-remove-column-1 nil) + lines) + (setq org-table-clean-did-remove-column-1 t) + (delq nil + (mapcar + (lambda (x) (if (string-match "^[ \t]*| *[!_^/] *|" x) + nil ; ignore this line + (and (or (string-match "^[ \t]*|-+\\+" x) + (string-match "^[ \t]*|[^|]*|" x)) + (replace-match "|" t t x)))) + lines)))) (defun org-fake-empty-table-line (line) "Replace everything except \"|\" with spaces." @@ -19314,6 +19724,7 @@ This function should be run in the `org-after-todo-state-change-hook'." (setq org-log-post-message msg) (message msg)))) + ;;;; Finish up (provide 'org) Binary files differ@@ -3,7 +3,7 @@ @setfilename ../info/org @settitle Org Mode Manual -@set VERSION 4.64 +@set VERSION 4.65 @set DATE February 2007 @dircategory Emacs @@ -296,8 +296,15 @@ Interaction with other packages Extensions, Hooks and Hacking * Extensions:: Existing 3rd-part extensions +* Tables in arbitrary syntax:: Orgtbl for LaTeX and other programs * Dynamic blocks:: Automatically filled blocks -* Special agenda views:: +* Special agenda views:: Customized views + +Tables in arbitrary syntax + +* Radio tables:: Sending and receiving +* A LaTeX example:: Step by step, almost a tutorial +* Translator functions:: Copy and modify @end detailmenu @end menu @@ -363,7 +370,8 @@ example as: Org-mode's automatic, context sensitive table editor with spreadsheet capabilities can be integrated into any major mode by activating the -minor Orgtbl-mode. +minor Orgtbl-mode. Using a translation step, it can be used to maintain +tables in arbitray file types, for example in LaTeX. @cindex FAQ There is a website for Org-mode which provides links to the newest @@ -373,6 +381,7 @@ questions (FAQ), links to tutorials etc. This page is located at @page + @node Installation, Activation, Summary, Introduction @section Installation @cindex installation @@ -1342,6 +1351,12 @@ example in mail mode, use (add-hook 'mail-mode-hook 'turn-on-orgtbl) @end lisp +Furthermore, with some special setup, it is possible to maintain tables +in arbitrary syntax with Orgtbl-mode. For example, it is possible to +construct LaTeX tables with the underlying ease and power of +Orgtbl-mode, including spreadsheet capabulities. For details, see +@ref{Tables in arbitrary syntax}. + @node The spreadsheet, , orgtbl-mode, Tables @section The spreadsheet @cindex calculations, in tables @@ -1634,6 +1649,15 @@ also apply the new formulas to the entire table. @kindex C-c C-q @item C-c C-q Exit the buffer without installing changes. +@kindex @key{TAB} +@item @key{TAB} +Pretty-print or indent lisp formula at point. When in a line containing +a lisp formula, format the formula according to Emacs Lisp rules. +Another @key{TAB} collapses the formula back again. In the open +formula, @key{TAB} re-indents just like in Emacs-lisp-mode. +@kindex M-@key{TAB} +@item M-@key{TAB} +Complete Lisp symbols, just like in Emacs-lisp-mode. @kindex S-@key{up} @kindex S-@key{down} @item S-@key{up}/@key{down} @@ -1779,6 +1803,9 @@ recalculation slows down editing too much. Unmarked lines are exempt from recalculation with @kbd{C-u C-c *}. All lines that should be recalculated should be marked with @samp{#} or @samp{*}. +@item / +Do not export this line. Useful for lines that contain the narrowing +@samp{<N>} markers. @end table Finally, just to whet your appetite on what can be done with the @@ -2590,7 +2617,7 @@ anywhere in the file: #+TYP_TODO: Fred Sara Lucy Mike DONE @end example -@cindex Completion, of option keywords +@cindex completion, of option keywords @kindex M-@key{TAB} @noindent To make sure you are using the correct keyword, type @samp{#+} into the buffer and then use @kbd{M-@key{TAB}} completion. @@ -3059,8 +3086,8 @@ format is shorter, things do work as expected. @node Repeating items, Progress logging, Custom time format, Timestamps @section Repeating items @cindex TODO items, repeating -@cindex Deadlines, repeating -@cindex Scheduling, repeating +@cindex deadlines, repeating +@cindex scheduling, repeating Org-mode integrates with the Emacs calendar and diary to display cyclic appointments, anniversaries and other special entries in the agenda @@ -5935,12 +5962,14 @@ Org-mode. @menu * Extensions:: Existing 3rd-part extensions +* Tables in arbitrary syntax:: Orgtbl for LaTeX and other programs * Dynamic blocks:: Automatically filled blocks -* Special agenda views:: +* Special agenda views:: Customized views @end menu -@node Extensions, Dynamic blocks, Extensions and Hacking, Extensions and Hacking +@node Extensions, Tables in arbitrary syntax, Extensions and Hacking, Extensions and Hacking @section Third-party extensions for Org-mode +@cindex extension, third-party The following extensions for Org-mode have been written by other people: @@ -5948,7 +5977,7 @@ The following extensions for Org-mode have been written by other people: @cindex @file{org-publish.el} @item @file{org-publish.el} by David O'Toole This package provides facilities for publishing related sets of Org-mode -files together with linked files like images as a webpages. It is +files together with linked files like images as webpages. It is highly configurable and can be used for other publishing purposes as well. As of Org-mode version 4.30, @file{org-publish.el} is part of the Org-mode distribution. It is not yet part of Emacs, however, a delay @@ -5980,8 +6009,228 @@ Translates Org-mode files into something readable by Remind. @url{http://www.cognition.ens.fr/~guerry/u/org2rem.el}. @end table -@node Dynamic blocks, Special agenda views, Extensions, Extensions and Hacking +@page + +@node Tables in arbitrary syntax, Dynamic blocks, Extensions, Extensions and Hacking +@section Tables in arbitrary syntax +@cindex tables, in other modes +@cindex orgtbl-mode + +Since Orgtbl-mode can be used as a minor mode in arbitrary buffers, a +frequent feature request has been to make it work with native tables in +specific languages, for example LaTeX. However, this is extremely hard +to do in a general way, would lead to a customization nightmare, and +would take away much of the simplicity of the Orgtbl-mode table editor. + +This appendix describes different approach. We keep the Orgtbl-mode +table in its native format (the @i{source table}), and use a custom +function to @i{translate} the table to the correct syntax, and to +@i{install} it in the right location (the @i{target table}). This puts +the burden of writing conversion functions on the user, but it allows +for a very flexible system. + +@menu +* Radio tables:: Sending and receiving +* A LaTeX example:: Step by step, almost a tutorial +* Translator functions:: Copy and modify +@end menu + +@node Radio tables, A LaTeX example, Tables in arbitrary syntax, Tables in arbitrary syntax +@subsection Radio tables +@cindex radio tables + +To define the location of the target table, you first need to create two +lines that are comments in the current mode, but contain magic words for +Orgtbl-mode to find. Orgtbl-mode will insert the translated table +between these lines, replacing whatever was there before. For example: + +@example +/* BEGIN RECEIVE ORGTBL table_name */ +/* END RECEIVE ORGTBL table_name */ +@end example + +@noindent +Just above the source table, we put a special line that tells +Orgtbl-mode how to translate this table and where to install it. For +example: +@example +#+ORGTBL: SEND table_name translation_function arguments.... +@end example + +@noindent +@code{table_name} is the reference name for the table that is also used +in the receiver lines. @code{translation_function} is the Lisp function +that does the translation. Furthermore, the line can contain a list of +arguments (alternating key and value) at the end. The arguments will be +passed as a property list to the translation function for +interpretation. However, a few standard parameters are already +recognized and acted upon before the translation function is called: + +@table @code +@item :skip N +Skip the first N lines of the table. Hlines do count! +@item :skipcols (n1 n2 ...) +List of columns that should be skipped. If the table has a column with +calculation marks, that column is automatically discarded as well. +Please note that the translator function sees the table @emph{after} the +removal of these columns, the function never knows that there have been +additional columns. +@end table + +@noindent +The one problem remaining is how to keep the source table in the buffer +without disturbing the normal workings of the file, for example during +compilation of a C file or processing of a LaTeX file. There are a +number of different solutions: + +@itemize @bullet +@item +The table could be placed in a block comment if that is supported by the +language. For example, in C-mode you could wrap the table between +@samp{/*} and @samp{*/} lines. +@item +Sometimes it is possible to put the table after some kind of @i{END} +statement, for example @samp{\bye} in TeX and @samp{\end@{document@}} +in LaTeX. +@item +If all else fails@footnote{In principle the source table could also be +in a separate file, but so far this is not implemented.}, you can just +comment the table line by line whenever you want to process the file, +and uncomment it whenever you need to edit the table. The command +@kbd{M-x orgtbl-toggle-comment} does make this a viable option, in +particular if you bind it to a key. +@end itemize + +@node A LaTeX example, Translator functions, Radio tables, Tables in arbitrary syntax +@subsection A LaTeX example +@cindex LaTeX, and orgtbl-mode + +The best way to wrap the source table in LaTeX is to use the +@code{comment} environment provided by @file{comment.sty}. It has to be +activated by placing @code{\usepackage@{comment@}} into the document +header. Orgtbl-mode can insert a radio table skeleton@footnote{By +default this works only for LaTeX, HTML, and TeXInfo. Configure the +variable @code{orgtbl-radio-tables} to install templates for other +modes.} with the command @kbd{M-x orgtbl-insert-radio-table}. You will +be prompted for a table name, lets say we use @samp{salesfigures}. You +will then get the following template: + +@example +% BEGIN RECEIVE ORGTBL salesfigures +% END RECEIVE ORGTBL salesfigures +\begin@{comment@} +#+ORGTBL: SEND salesfigures orgtbl-to-latex +| | | +\end@{comment@} +@end example + +@noindent +The @code{#+ORGTBL: SEND} line tells orgtbl-mode to use the function +@code{orgtbl-to-latex} to convert the table into LaTeX and to put it +into the receiver location with name @code{salesfigures}. You may now +fill in the table, feel free to use the spreadsheet features@footnote{If +the @samp{#+TBLFM} line contains an odd number of dollar characters, +this may cause problems with font-lock in latex-mode. As shown in the +example you can fix this by adding an extra line inside the +@code{comment} environment that is used to balance the dollar +expressions. If you are using AUCTeX with the font-latex library, a +much better solution is to add the @code{comment} environment to the +variable @code{LaTeX-verbatim-environments}.}: + +@example +% BEGIN RECEIVE ORGTBL salesfigures +% END RECEIVE ORGTBL salesfigures +\begin@{comment@} +#+ORGTBL: SEND salesfigures orgtbl-to-latex +| Month | Days | Nr sold | per day | +|-------+------+---------+---------| +| Jan | 23 | 55 | 2.4 | +| Feb | 21 | 16 | 0.8 | +| March | 22 | 278 | 12.6 | +#+TBLFM: $4=$3/$2;%.1f +% $ (optional extra dollar to keep font-lock happy, see footnote) +\end@{comment@} +@end example + +@noindent +When you are done, press @kbd{C-c C-c} in the table to get the converted +table inserted between the two marker lines. + +Now lets assume you want to make the table header by hand, because you +want to control how columns are aligned etc. In this case we make sure +that the table translator does skip the first 2 lines, and tell the +command to work as a @i{splice}, i.e. to not produce header and footer +commands of the table: + +@example +\begin@{tabular@}@{lrrr@} +Month & \multicolumn@{1@}@{c@}@{Days@} & Nr.\ sold & per day\\ +% BEGIN RECEIVE ORGTBL salesfigures +% END RECEIVE ORGTBL salesfigures +\end@{tabular@} +% +\begin@{comment@} +#+ORGTBL: SEND salesfigures orgtbl-to-latex :splice t :skip 2 +| Month | Days | Nr sold | per day | +|-------+------+---------+---------| +| Jan | 23 | 55 | 2.4 | +| Feb | 21 | 16 | 0.8 | +| March | 22 | 278 | 12.6 | +#+TBLFM: $4=$3/$2;%.1f +\end@{comment@} +@end example + +The LaTeX translator function @code{orgtbl-to-latex} is already part of +Orgtbl-mode. It uses a @code{tabular} environment to typeset the table +and marks horizontal lines with @code{\hline}. Furthermore, it +interprets the following parameters: + +@table @code +@item :splice nil/t +When set to t, return only table body lines, don't wrap them into a +tabular environment. Default is nil. + +@item :fmt fmt +A format to be used to wrap the field, should contain @code{%s} for the +original field value. For example, to wrap each field value in dollars, +you could use @code{:fmt "$%s$"}. This may also be a property list with +column numbers and formats. for example @code{:fmt (2 "$%s$" 4 "%s%%")}. + +@item :efmt efmt +Use this format to print numbers with exponentials. The format should +have @code{%s} twice for inserting mantissa and exponent, for example +@code{"%s\\times10^@{%s@}"}. The default is @code{"%s\\,(%s)"}. This +may also be a property list with column numbers and formats, for example +@code{:efmt (2 "$%s\\times10^@{%s@}$" 4 "$%s\\cdot10^@{%s@}$")}. After +@code{efmt} has been applied to a value, @code{fmt} will also be +applied. +@end table + +@node Translator functions, , A LaTeX example, Tables in arbitrary syntax +@subsection Translator functions +@cindex HTML, and orgtbl-mode +@cindex translator function + +Orgtbl-mode has several translator functions built-in: +@code{orgtbl-to-latex}, @code{orgtbl-to-html}, and +@code{orgtbl-to-texinfo}. For deatils on each of them, please check +the corresponding documentation strings. + +In order to write your own translator function, start by looking at +@code{orgtbl-to-latex} which is well documented. Basically you have to +write a function that takes two arguments. The first argument is the +table, a list of lines, each line either the symbol @code{hline} or a +list of fields. The second argument is a property list that will +contain all parameters specified in the @samp{#+ORGTBL: SEND} line. +Orgtbl-mode always handles the @code{:skip} and @code{:skipcols} +parameters, but your translator function may use any number of +additional parameters. If you write a generally useful translator, +please post it on @code{emacs-orgmode@@gnu.org} so that others can +benefit from your work. + +@node Dynamic blocks, Special agenda views, Tables in arbitrary syntax, Extensions and Hacking @section Dynamic blocks +@cindex dynamic blocks Org-mode documents can contain @emph{dynamic blocks}. These are specially marked regions that are updated by some user-written @@ -6041,6 +6290,7 @@ written in a way that is does nothing in buffers that are not in Org-mode. @node Special agenda views, , Dynamic blocks, Extensions and Hacking @section Special Agenda Views +@cindex agenda views, user-defined Org-mode provides a special hook that can be used to narrow down the selection made by any of the agenda views. You may specify a function @@ -6099,17 +6349,21 @@ MATCH is being ignored." @cindex thanks Org-mode was borne in 2003, out of frustration over the user interface -of the Emacs outline-mode. All I initially wanted was to make working -with an outline tree possible without having to remember more than 10 -commands just for hiding and unhiding parts of the outline tree, and to -allow to restructure a tree easily. Visibility cycling and structure -editing were originally implemented in the package +of the Emacs outline-mode. I was trying to organize my notes and +projects, and using Emacs seemed to be the natural way to go. However, +having to remember eleven different commands with two or three keys per +command, only to hide and unhide parts of the outline tree, that seemed +entirely unacceptable to me. Also, when using outlines to take notes, I +constantly want to restructure the tree, organizing it parallel to my +thoughts and plans. @emph{Visibility cycling} and @emph{structure +editing} were originally implemented in the package @file{outline-magic.el}, but quickly moved to the more general -@file{org.el}. TODO entries, basic time stamps, and table support were -added next, and highlight the two main goals that Org-mode still has -today: To create a new, outline-based, plain text mode with innovative -and intuitive editing features, and to incorporate project planning -functionality directly into a notes file. +@file{org.el}. As this environment became comfortable for project +planning, the next step was adding @emph{TODO entries}, basic @emph{time +stamps}, and @emph{table support}. These areas highlight the two main +goals that Org-mode still has today: To create a new, outline-based, +plain text mode with innovative and intuitive editing features, and to +incorporate project planning functionality directly into a notes file. Since the first release, hundreds of emails to me or on @code{emacs-orgmode@@gnu.org} have provided a constant stream of bug diff --git a/orgcard.pdf b/orgcard.pdf Binary files differindex 95f5448bb..5f5121286 100644 --- a/orgcard.pdf +++ b/orgcard.pdf diff --git a/orgcard.tex b/orgcard.tex index 38dd77303..a64c226e0 100644 --- a/orgcard.tex +++ b/orgcard.tex @@ -1,5 +1,5 @@ % Reference Card for Org Mode -\def\orgversionnumber{4.64} +\def\orgversionnumber{4.65} \def\year{2007} % %**start of header |