From mboxrd@z Thu Jan 1 00:00:00 1970 From: Jambunathan K Subject: Re: unnumbered subsections in latex export Date: Fri, 01 Apr 2011 10:04:54 +0530 Message-ID: <81y63u7fo1.fsf@gmail.com> References: <20110322051038.21655c80@kuru.homelinux.net> <80d3lj9wj6.fsf@somewhere.org> <20110322053134.669127e9@kuru.homelinux.net> <8999.1300804510@alphaville.dokosmarshall.org> <20110322160814.227fc53f@bhishma.homelinux.net> <27844.1300836065@alphaville.usa.hp.com> <8162r9hgxm.fsf@gmail.com> <87bp11dk4h.fsf@gnu.org> <87tyejymto.fsf@gmail.com> Mime-Version: 1.0 Content-Type: text/plain Return-path: Received: from [140.186.70.92] (port=41580 helo=eggs.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1Q5W4m-0008TB-UR for emacs-orgmode@gnu.org; Fri, 01 Apr 2011 00:35:14 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1Q5W4l-0004Ps-FF for emacs-orgmode@gnu.org; Fri, 01 Apr 2011 00:35:12 -0400 Received: from mail-iy0-f169.google.com ([209.85.210.169]:45138) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Q5W4l-0004Pf-8W for emacs-orgmode@gnu.org; Fri, 01 Apr 2011 00:35:11 -0400 Received: by iyf13 with SMTP id 13so4016053iyf.0 for ; Thu, 31 Mar 2011 21:35:10 -0700 (PDT) In-Reply-To: <87tyejymto.fsf@gmail.com> (Nicolas's message of "Thu, 31 Mar 2011 23:58:11 +0200") 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: Bastien Cc: nicholas.dokos@hp.com, emacs-orgmode@gnu.org Backward compatibility is a real issue. The real challenge is how to move forward while also not breaking anything that the users have come to rely on. > Thus, Org documentation should provide an exhaustive list of > environments and objects it offers with their associated format during > export. Then, creating an exporter should be as simple as providing > functions to change every one of them into meaningful strings, which > would then be collected by org-exp.el. The immediate benefit is that > only those among us patching org-exp.el will have to know the > intermediate format it creates, and those creating or patching backends > will work on a well-defined format. > > I'll show two examples to illustrate my point: lists and tables. Taken > from a docstring, > > 1. first item > + sub-item one > + [X] sub-item two > more text in first item > 2. [@3] last item > > will be parsed as: > > (ordered (nil \"first item\" > (unordered (nil "sub-item one") > (nil "[CBON] sub-item two")) > "more text in first item"") > (3 "last item")) > > This allows to easily (see org-list-to-latex, org-list-to-html, > org-list-to-texinfo, and so on) transform an Org list in many different > formats. Alas, it cannot be used in org-html.el and org-docbook.el, as > those, again, parse buffer line-wise. >From a refactoring perspective, it is not necessary that a XML-like list structure be offered to the html backend. In principle, it would suffice as long as the html exporter is provided with enough information so that it can "deduce" the above structure while still continuing to be line-oriented. > > The same could be said about tables: > > | Row 1 | 1 | 2 | > |-------+---+---| > | Row 2 | 3 | 4 | > > can be parsed as: > > (("Row 1" "1" "2") > 'hline > ("Row 2" "3" "4")) > > and from that, such functions as orgtbl-to-html, or orgtbl-to-latex were > easy to create. > > So, basically, what I suggest here is: > > 1. list all possible environments and objects offered by the Org format > (table, lists, inlinetasks, center, verbatim, paragraph, headlines, > time-stamps, LaTeX snippets, footnotes, links, source); > 2. define an explicit export format for each of them; > 3. determine options that should be know by org-exp, by the backend; > 4. create a parser, in org-exp, that will output Org buffer in the > chosen format; > 5. create (many are readily available) functions for each backend to > interpret them. Do look at my new html exporter. I have been very conservative in making the changes. Some observations from my side ... > It isn't documented enough because some of those properties are not > exactly defined, and their meaning, or their differences, aren't > always explicit (org-protected, org-example, org-verbatim-emph are > coming to my mind). I agree that text properties are problematic. I see that they are also used inconsistently. Consider org-example. A source block is transformed by org-exp.el in to a html block and is enclosed in #+begin_html...#+end_html. On the otherhand the #+begin_html and #+end_html given by the user isn't marked up with this property. [Context Switch] Protection this seems to me to happen at three levels. Protection at block level happens in example/source blocks, Protection at phrase level happens in verbatim LaTeX equations (fragments?) and Protection at tag level as implied in @ @ convention. [Context Switch] When I see backend specific code in org-exp.el something in my gut says that it is not OK. For example, source blocks are transformed in org-exp.el to html-specific markup and get inserted between #+begin_html and #+end_html with org-indentation, org-protected properties. org-html.el just inserts it. I believe, it would be all the more better if the above "transform & propertize in org-exp.el and just insert in org-html.el" is done as "propertize in org-exp.el and transform & insert in org-html.el". [Context Switch] Html exporter is not only line-oriented it is also a transformation pipeline. The latter part means that if lines are slightly arranged (that is the order of the transformation is changed) then things will break in unexpected ways. This is the root cause of all the recent regressions concerning images and timestamps in the HTML exporter. [Context Switch] org-html.el opens paragraph in anticipation rather than when it is actually needed. As a result previous context just diffuses in to a latter context. If this were not so deleting of empty paragraphs wouldn't be necessary. [Context Switch] HTML exporter occasionally emit things temporarily and goes back and fixes it. Table's colalign and colgroup markers come to mind here. In some sense convenience features like "right align if a column is predominantly numeric" also complicated things. I think one of the reasons Org is so popular it is that it is a common-man's swiss army knife and not a elitist samurai sword. Jambunathan K.