From mboxrd@z Thu Jan 1 00:00:00 1970 From: Nicolas Goaziou Subject: Re: [ANN] Org Export in contrib Date: Fri, 25 Nov 2011 19:57:46 +0100 Message-ID: <878vn4vxlh.fsf@gmail.com> References: <87ipm8w1jz.fsf@gmail.com> Mime-Version: 1.0 Content-Type: text/plain Return-path: Received: from eggs.gnu.org ([140.186.70.92]:40518) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1RU0ze-0005zR-6O for emacs-orgmode@gnu.org; Fri, 25 Nov 2011 13:59:27 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1RU0zb-0006Xz-Vi for emacs-orgmode@gnu.org; Fri, 25 Nov 2011 13:59:26 -0500 Received: from mail-bw0-f41.google.com ([209.85.214.41]:63570) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1RU0zb-0006Xk-Mf for emacs-orgmode@gnu.org; Fri, 25 Nov 2011 13:59:23 -0500 Received: by bke17 with SMTP id 17so5436861bke.0 for ; Fri, 25 Nov 2011 10:59:22 -0800 (PST) In-Reply-To: <87ipm8w1jz.fsf@gmail.com> (Nicolas Goaziou's message of "Fri, 25 Nov 2011 18:32:16 +0100") List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org Sender: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org To: Org Mode List Completing myself, I'll add a few notes about the differences between the current exporter and this one. While it tries to mimic most of the behaviours of its ancestor, some points just couldn't fit in the new scheme, would it be for a technical reason or by design. Here follows a rough list stating how the new engine stands with regards to the older one. When possible, the reasons justifying that the difference remains are given. 1. It's slower. Indeed, it has to first parse completely the area to transcode, even if it doesn't transcode it after (i.e. archive trees). It's the job of the exporter to decide what should or shouldn't be exported. Anticipating filtering would be disastrous for some exporters (i.e. the Org one) and wouldn't fit the modular design. 2. The document title cannot be obtained anymore from the first line of text. It's either explicitely defined with the =TITLE= keyword, or derived from buffer's name. 3. =TEXT= keywords at the beginning of the document are unneeded, and, as such, no longer have an effect. 4. "[TABLE OF CONTENTS]" as a placeholder for the table of contents has been removed. Though, a new keyword, =TOC=, achieves the same effect, and can even take more values, like "contents", "tables", "figures" and "listings". Tools are provided to make them available to any exporter to come. 5. "-t" option at a src or example block isn't supported anymore. This is an HTML only option that could fit in =attr_html= affiliated keyword instead, with a "textarea" value. A new HTML back-end isn't available yet, but should develop in that direction anyway. 6. Macros have been under powered a little. They cannot live anymore in comments, example blocks, or even src blocks. In fact, one cannot find a macro where the text isn't parsed. Macros are Org syntax. Using such syntax where there is, by definition, none is just nonsensical. 7. For the same reason, invisible targets in comments have been deprecated. For the same result, one can now use a =TARGET= keyword instead. 8. =INCLUDE= keyword :prefix, :prefix1 and :minlevel properties support has been dropped. Though, the keyword, which doesn't have to be at column 0 anymore, is aware about its environment. If it belongs to a list, the whole file will be in the current item. Also, including a file from within a sub-tree will always make the top-level headline of the included file is a direct child of that sub-tree. One technical drawback is that no Babel block is executed in the included file. 9. Table.el tables will always use their own export back-end. In other words, no Org syntax will be recognized in such table anymore. A table.el is an extraneous element while the parser is meant to parse Org syntax. Now, an interesting idea from /Jambunathan K./, namely his "list-tables", might fill the gap between the Org spreadsheet and the table.el table. Nothing is implemented about it right now, but we're talking about a modular and extensible parser, after all. 10. Calling an export function with a numeric argument doesn't change headline maximum level, by default. There are enough ways to change this export property already and the argument may be required for something more important in the future. 11. =org-export-with-TeX-macros= has been replaced with the more appropriate =org-export-with-entities=, and the associated =OPTIONS= keyword's symbol changed from =TeX:nil= to =e:nil=. 12. About variables changes, =org-export-author-info=, =org-export-creator-info= and =org-export-email-info= have been replaced with, respectively, =org-export-with-author=, =org-export-with-creator= ad =org-export-with-email=, for the sake of consistency with other opt-in variables. Regards, -- Nicolas Goaziou