Re: [O] Custom formatting during export

[Thorsten Jolitz]

Gabe Becker <address@hidden> writes:

> orgmode developers and power-users,
>
> I'd like to be able to declare custom entities (apologies if I'm using
> that term incorrectly) within the text of an orgmode document which I
> can specify custom formatting for when my .org is exported, e.g. to
> PDF or HTML.
>
> I have a background in Docbook, so the analogue there would be
> defining a custom xml tag and then extending the XSL files to handle
> it as desired. Please see the following snippet:
>
> * section title
> Here is some text, but I want [specialthing: this bit here] to be
> formatted differently than [newanddifferent: this other big over
> here].
>
> Where I would have defined specific custom formatting rules for
> "specialthing" and "newanddifferent" type entities.
>
> Is there a way to do this in orgmode? If not, it seems like it would
> be a very useful feature (at least to me:) ). Note: I don't care about
> the syntax as long as the result is the same.

After an org buffer is parsed, the complete document is available as
nested list (parse tree), containing org elements and objects:

,----[ C-h v org-element-all-elements RET ]
| org-element-all-elements is a variable defined in `org-element.el'.
| Its value is (babel-call center-block clock comment comment-block
| diary-sexp drawer dynamic-block example-block fixed-width
| footnote-definition headline horizontal-rule inlinetask item keyword
| latex-environment node-property paragraph plain-list planning
| property-drawer quote-block section special-block src-block table
| table-row verse-block)
| 
| Documentation: Complete list of element types.
`----

,----[ C-h v org-element-all-objects RET ]
| org-element-all-objects is a variable defined in `org-element.el'.
| Its value is (bold code entity export-snippet footnote-reference
| inline-babel-call inline-src-block italic line-break latex-fragment
| link macro radio-target statistics-cookie strike-through subscript
| superscript table-cell target timestamp underline verbatim)
| 
| Documentation:
| Complete list of object types.
`----

The exporters have complete access to these elements, and define
dedicated functions for transforming each of them to the output format
(LATEX, HTML ...). 

So if you want latex output, but special treatment for a few elements,
the way to go is to define a new export backend that derives from latex:

,----[ C-h f org-export-define-derived-backend RET ]
| org-export-define-derived-backend is a compiled Lisp function in
| `ox.el'.
| 
| (org-export-define-derived-backend CHILD PARENT &rest BODY)
| 
| Create a new back-end as a variant of an existing one.
| 
| CHILD is the name of the derived back-end.  PARENT is the name of
| the parent back-end.
| 
| BODY can start with pre-defined keyword arguments.  The following
| keywords are understood:
| 
|   :export-block
| 
|     String, or list of strings, representing block names that
|     will not be parsed.  This is used to specify blocks that will
|     contain raw code specific to the back-end.  These blocks
|     still have to be handled by the `special-block' type
|     translator.
| 
|   :filters-alist
| 
|     Alist of filters that will overwrite or complete filters
|     defined in PARENT back-end.  See `org-export-filters-alist'
|     for a list of allowed filters.
| 
|   :menu-entry
| 
|     Menu entry for the export dispatcher.  See
|     `org-export-define-backend' for more information about the
|     expected value.
| 
|   :options-alist
| 
|     Alist of back-end specific properties that will overwrite or
|     complete those defined in PARENT back-end.  Refer to
|     `org-export-options-alist' for more information about
|     structure of the values.
| 
|   :translate-alist
| 
|     Alist of element and object types and transcoders that will
|     overwrite or complete transcode table from PARENT back-end.
|     Refer to `org-export-define-backend' for detailed information
|     about transcoders.
| 
| As an example, here is how one could define "my-latex" back-end
| as a variant of `latex' back-end with a custom template function:
| 
|   (org-export-define-derived-backend 'my-latex 'latex
|      :translate-alist '((template . my-latex-template-fun)))
| 
| The back-end could then be called with, for example:
| 
|   (org-export-to-buffer 'my-latex "*Test my-latex*")
`----

-- 
cheers,
Thorsten