emacs-orgmode@gnu.org archives
 help / color / mirror / code / Atom feed
From: Jambunathan K <kjambunathan@gmail.com>
To: Bastien <bzg@altern.org>
Cc: nicholas.dokos@hp.com, emacs-orgmode@gnu.org
Subject: Re: unnumbered subsections in latex export
Date: Fri, 01 Apr 2011 10:04:54 +0530	[thread overview]
Message-ID: <81y63u7fo1.fsf@gmail.com> (raw)
In-Reply-To: <87tyejymto.fsf@gmail.com> (Nicolas's message of "Thu, 31 Mar 2011 23:58:11 +0200")


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 @<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	other threads:[~2011-04-01  4:35 UTC|newest]

Thread overview: 51+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2011-03-22 12:10 unnumbered subsections in latex export Suvayu Ali
2011-03-22 12:20 ` Sébastien Vauban
2011-03-22 12:31   ` Suvayu Ali
2011-03-22 12:56     ` Sébastien Vauban
2011-03-22 14:26       ` [PATCH] Allow mixed export of numbered and unnumbered sections in LaTeX Lawrence Mitchell
2011-03-22 22:52         ` Suvayu Ali
2011-03-23 14:04         ` [Accepted] " Bastien Guerry
2011-03-23 14:17         ` [PATCH] " Bastien
2011-03-22 14:35     ` Re: unnumbered subsections in latex export Nick Dokos
2011-03-22 23:08       ` Suvayu Ali
2011-03-22 23:21         ` Nick Dokos
2011-03-23  9:38           ` [PATCH] Allow mixed export of numbered and unnumbered sections in HTML Lawrence Mitchell
2011-03-23 14:05             ` [Accepted] " Bastien Guerry
2011-03-23 14:57               ` Nick Dokos
2011-03-23 15:50                 ` Suvayu Ali
2011-03-23 14:18           ` Re: unnumbered subsections in latex export Bastien
2011-03-23 15:02             ` Nick Dokos
2011-03-23 16:25               ` Lawrence Mitchell
2011-03-23 16:42                 ` Nick Dokos
2011-03-23 18:17                   ` Jambunathan K
2011-03-23 19:00                     ` Nick Dokos
2011-03-23 19:18                       ` Jambunathan K
2011-03-23 16:29               ` Thomas S. Dye
2011-03-23 17:42           ` Jambunathan K
2011-03-24  7:59             ` Bastien
2011-03-24 18:27               ` Achim Gratz
2011-03-24 19:25               ` Nick Dokos
2011-03-25  1:06                 ` Suvayu Ali
2011-04-04 14:39                 ` Sébastien Vauban
2011-04-04 17:04                   ` Nick Dokos
2011-04-04 20:32                   ` Aankhen
2011-04-05 10:16                     ` Sébastien Vauban
2011-04-05 19:07                       ` Aankhen
2011-04-05 19:27                         ` Eric S Fraga
2011-04-05 21:25                           ` New features for the exporters? Sébastien Vauban
2011-04-05 21:45                           ` Re: unnumbered subsections in latex export Aankhen
2011-04-06 18:49                   ` Matt Lundin
2011-04-06 20:19                     ` Sébastien Vauban
2011-03-27 11:16               ` Jambunathan K
2011-03-27 11:40                 ` Bastien
2011-03-31 21:58               ` Nicolas
2011-04-01  4:34                 ` Jambunathan K [this message]
2011-04-01  4:41                   ` Jambunathan K
2011-04-01  6:29                   ` Nick Dokos
2011-04-01 15:41                   ` Eric S Fraga
2011-04-04 14:00                     ` Matt Lundin
2011-04-04 14:12                       ` Jambunathan K
2011-04-04 16:36                         ` Matt Lundin
2011-04-04 17:09                           ` Nick Dokos
2011-04-01  7:39                 ` Jambunathan K
2011-04-01 18:25                 ` Achim Gratz

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: https://www.orgmode.org/

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=81y63u7fo1.fsf@gmail.com \
    --to=kjambunathan@gmail.com \
    --cc=bzg@altern.org \
    --cc=emacs-orgmode@gnu.org \
    --cc=nicholas.dokos@hp.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).