From mboxrd@z Thu Jan 1 00:00:00 1970 From: Carsten Dominik Subject: Release 6.17 Date: Sun, 4 Jan 2009 09:13:56 +0100 Message-ID: Mime-Version: 1.0 (Apple Message framework v929.2) Content-Type: text/plain; charset=US-ASCII; format=flowed; delsp=yes Content-Transfer-Encoding: 7bit Return-path: Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1LJO7a-000172-9i for emacs-orgmode@gnu.org; Sun, 04 Jan 2009 03:14:06 -0500 Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1LJO7X-00016q-Hx for emacs-orgmode@gnu.org; Sun, 04 Jan 2009 03:14:05 -0500 Received: from [199.232.76.173] (port=59891 helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1LJO7X-00016n-Dx for emacs-orgmode@gnu.org; Sun, 04 Jan 2009 03:14:03 -0500 Received: from mx20.gnu.org ([199.232.41.8]:11221) by monty-python.gnu.org with esmtps (TLS-1.0:RSA_AES_256_CBC_SHA1:32) (Exim 4.60) (envelope-from ) id 1LJO7W-0004rR-UQ for emacs-orgmode@gnu.org; Sun, 04 Jan 2009 03:14:03 -0500 Received: from mail-ew0-f13.google.com ([209.85.219.13]) by mx20.gnu.org with esmtp (Exim 4.60) (envelope-from ) id 1LJO7V-0001Fn-WE for emacs-orgmode@gnu.org; Sun, 04 Jan 2009 03:14:02 -0500 Received: by ewy6 with SMTP id 6so7683414ewy.18 for ; Sun, 04 Jan 2009 00:13:59 -0800 (PST) List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org Errors-To: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org To: emacs-orgmode list Hi, I am releasing version 6.17 of Org-mode. Besides the footnote support discussed already extensively here, this release also contains a new feature to make Org-mode more usable for writing tutorials and similar documents with code examples. Lines in code examples can now be numbered, and you can link to specific lines with magical highlighting of the line when hovering the moue over the link. Enjoy. - Carsten Changes in Version 6.17 ======================= Overview ========= - Footnote support - Line numbers and references in literal examples - New hooks for export preprocessing - Capture column view into a different file Details ======== Footnote support ----------------- Org-mode now directly supports the creation of footnotes. In contrast to the /footnote.el/ package, Org-mode's footnotes are designed for work on a larger document, not only for one-off documents like emails. The basic syntax is similar to the one used by /footnote.el/, i.e. a footnote is defined in a paragraph that is started by a footnote marker in square brackets in column 0, no indentation allowed. The footnote reference is simply the marker in square brackets inside text. For example: The Org homepage[fn:1] now looks a lot better than it used to. ... [fn:1] The link is: http://orgmode.org Org-mode extends the number-based syntax to /named/ footnotes and optional inline definition. Using plain numbers as markers is supported for backward compatibility, but not encouraged because of possible conflicts with LaTeX syntax. Here are the valid references: - [1] :: A plain numeric footnote marker. - [fn:name] :: A named footnote reference, where `name' is a unique label word or, for simplicity of automatic creation, a number. - [fn:: This is the inline definition of this footnote] :: A LaTeX-like anonymous footnote where the definition is given directly at the reference point. - [fn:name: a definition] :: An inline definition of a footnote, which also specifies a name for the note. Since Org allows multiple references to the same note, you can then use use `[fn:name]' to create additional references. Footnote labels can be created automatically, or you create names yourself. This is handled by the variable `org-footnote-auto-label' and its corresponding `#+STARTUP' keywords, see the docstring of that variable for details. The following command handles footnotes: - C-c C-x f :: The footnote action command. When the cursor is on a footnote reference, jump to the definition. When it is at a definition, jump to the (first) reference. Otherwise, create a new footnote. Depending on the variable `org-footnote-define-inline' (with associated `#+STARTUP' options `fninline' and `nofninline'), the definitions will be placed right into the text as part of the reference, or separately into the location determined by the variable `org-footnote-section'. When this command is called with a prefix argument, a menu of additional options is offered: - s :: Sort the footnote definitions by reference sequence. During editing, Org makes no effort to sort footnote definitions into a particular sequence. If you want them sorted, use this command, which will also move entries according to `org-footnote-section'. - n :: Normalize the footnotes by collecting all definitions (including inline definitions) into a special section, and then numbering them in sequence. The references will then also be numbers. This is meant to be the final step before finishing a document (e.g. sending off an email). The exporters do this automatically, and so could something like `message-send-hook'. - d :: Delete the footnote at point, and all references to it. - C-c C-c :: If the cursor is on a footnote reference, jump to the definition. If it is a the definition, jump back to the reference. When called with a prefix argument at either location, offer the same menu as `C-u C-c C-x f'. - C-c C-o or mouse-1/2 :: Footnote labels are also links to the corresponding definition/reference, and you can use the usual commands to follow these links. Org-mode's footnote support is designed so that it should also work in buffers that are not in Org-mode, for example in email messages. Just bind `org-footnote-action' to a global key like `C-c f'. The main trigger for this development came from a hook function written by Paul Rivier, to implement named footnotes and to convert them to numbered ones before export. Thanks, Paul! Thanks also to Scot Becker for a thoughtful post bringing this subject back onto the discussion table, and to Matt Lundin for the idea of named footnotes and his prompt testing of the new features. Line numbers and references in literal examples ------------------------------------------------ Literal examples introduced with `#+BEGIN_EXAMPLE' or `#+BEGIN_SRC' do now allow optional line numbering in the example. Furthermore, links to specific code lines are supported, greatly increasing Org-mode's utility for writing tutorials and other similar documents. Code references use special labels embedded directly into the source code. Such labels look like "((name))" and must be unique within a document. Org-mode links with the coderef cookie in the link part will be correctly interpreted, both while working with an Org file (internal links), and while exporting to the different backends. Line numbering and code references are supported for all three major backends, HTML, LaTeX, and ASCII. In the HTML backend, hovering the mouse over a link to a source line will remote-highlight the referenced code line. The options for the BEGIN lines are: - -n :: Number the lines in the example - +n :: Like -n, but continue numbering from where the previous example left off. - -r :: Remove the coderef cookies from the example, and replace links to this reference with line numbers. This option takes only effect if either -n or +n are given as well. If -r is not given, coderefs simply use the label name. Here is an example: #+begin_src emacs-lisp -n -r (defmacro org-unmodified (&rest body) ((def)) "Execute body without changing `buffer-modified-p'." `(set-buffer-modified-p ((back)) (prog1 (buffer-modified-p) ,@body))) #+end_src [[Line ((def))]] contains the macro name. Later at line [[((back))]], backquoting is used. When exported, this is translated to the following. Make sure to check this out in the HTML version of this document, at http://orgmode.org/Changes.html#sec-1.2.2 it looks much better there. 1: (defmacro org-unmodified (&rest body) 2: "Execute body without changing `buffer-modified-p'." 3: `(set-buffer-modified-p 4: (prog1 (buffer-modified-p) ,@body))) Line 1 contains the macro name. Later at line 3, backquoting is used. Thanks to Ilya Shlyakhter for proposing this feature set. Thanks to Sebastian Rose for the key Javascript element that made the remote highlighting possible. New hooks for export preprocessing ----------------------------------- The export preprocessor now runs more hooks, to allow better-timed tweaking by user functions: - `org-export-preprocess-hook' :: Pretty much the first thing in the preprocessor. But org-mode is already active in the preprocessing buffer. - `org-export-preprocess-after-include-files-hook' :: This is run after the contents of included files have been inserted. - `org-export-preprocess-after-tree-selection-hook' :: This is run after selection of trees to be exported has happened. This selection includes tags-based selection, as well as removal of commented and archived trees. - `org-export-preprocess-before-backend-specifics-hook' :: Hook run before backend-specific functions are called during preprocessing. - `org-export-preprocess-final-hook' :: Hook for preprocessing an export buffer. This is run as the last thing in the preprocessing buffer, just before returning the buffer string to the backend. Capture column view into a different file ------------------------------------------ The :id parameter for the dynamic block capturing column view can now truly be an ID that will also be found in a different file. Also, it can be like =[file:path/to/file=], to capture the global column view from a different file. Thanks to Francois Lagarde for his report that IDs outside the current file would not work.