emacs-orgmode@gnu.org archives
 help / color / mirror / code / Atom feed
* [ANN] Merge export-block type within special-block
@ 2014-07-27 12:37 Nicolas Goaziou
  2014-07-27 22:13 ` Bastien
  2014-08-29 14:02 ` KDr2
  0 siblings, 2 replies; 8+ messages in thread
From: Nicolas Goaziou @ 2014-07-27 12:37 UTC (permalink / raw)
  To: Org Mode List

Hello,

Export blocks are blocks dedicated to export back-ends, e.g.,
"#+BEGIN_LATEX". The way they are currently parsed is flawed.

Export blocks are back-end dependent. At the moment, back-ends register
their own export block in a variable, `org-element-block-name-alist', so
the parser can know if it needs to parse an export block or not. As
a consequence, the same block can be parsed differently if a given
export back-end is loaded or not. E.g.,

  #+BEGIN_HTML
  ...
  #+END_HTML

will be parsed as a `special-block' if "ox-html.el" is not loaded, or an
`export-block' otherwise. This is slightly... ugly. And it gets worse if
we include the cache, which will not update the block if it is not
modified.

I just committed a set of patches that solve the problem: `export-block'
elements do not exist anymore. Instead, such blocks are now parsed as
`special-block', always. This does not depend on the libraries loaded so
far.

Of course, special blocks are not treated exactly as export blocks. The
latter's contents are included as-is in the output whereas the former's
are interpreted. Therefore, special blocks now include another
property, :raw-value, which stores the pristine initial contents of the
block, and "ox.el" provides a new function,
`org-export-raw-special-block-p', which tells the difference between
a former export block and a special block. This makes sense since an
"export-block" is clearly, and only, an export concept. This is not
related to Org syntax.

This is more simple to handle than it sounds, and can be described with
two steps:

  1. `export-block' elements, translators and filters are now ignored.
     These can be removed from export back-ends (unless you want to
     preserve compatibility with Org 8.2, in which case leaving them
     will not hurt: they will be used in Org 8.2 and ignored in Org
     8.3).

  2. Translators for special blocks, e.g. `org-BACKEND-special-block'
     need to be updated and check first if current block is a raw
     special block or not. The following template is a suggestion.

     #+BEGIN_SRC emacs-lisp
     (defun org-latex-special-block (special-block contents info)
       (if (org-export-raw-special-block-p special-block info)
           (org-element-property :raw-value special-block)
         ;; Usual handling for special blocks goes here.
         ))
     #+END_SRC

     Note that if BACKEND is a derived back-end and doesn't implement
     its own special block translator already, there is nothing to
     change. The parent back-end will take care of such blocks.

     All back-ends in core and in contrib have been updated this way
     already.

I included `org-export-raw-special-block-p' in Org 8.2, as
a forward-compatibility measure, so back-end maintainers do not have to
do the `fboundp' dance.

BTW, for those in the back of the room: I didn't remove
"#+BEGIN_LATEX"-like constructs.


Regards,

-- 
Nicolas Goaziou                                                0x80A93738

^ permalink raw reply	[flat|nested] 8+ messages in thread

end of thread, other threads:[~2014-09-28  7:26 UTC | newest]

Thread overview: 8+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2014-07-27 12:37 [ANN] Merge export-block type within special-block Nicolas Goaziou
2014-07-27 22:13 ` Bastien
2014-08-29 14:02 ` KDr2
2014-08-31 12:56   ` Nicolas Goaziou
2014-09-25 15:12     ` KDr2
2014-09-26  9:09       ` Nicolas Goaziou
2014-09-28  6:18     ` Aaron Ecay
2014-09-28  7:26       ` Nicolas Goaziou

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).