emacs-orgmode
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

[O] Re: unnumbered subsections in latex export


From: Jambunathan K
Subject: [O] Re: unnumbered subsections in latex export
Date: Fri, 01 Apr 2011 10:04:54 +0530
User-agent: Gnus/5.13 (Gnus v5.13) Emacs/24.0.50 (windows-nt)

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. address@hidden 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 @<tag> @<tag/> 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.



reply via email to

[Prev in Thread] Current Thread [Next in Thread]