Re: new html exporter

[Robert Klein <kleinrob@mpip-mainz.mpg.de>]

[-- Attachment #1: Type: text/plain, Size: 963 bytes --]

On 09/29/2012 01:36 PM, henry atting wrote:
> Hi,
>
> I gave the new html exporter a try (org-e-html-to-file). The export
> obviously ignores my setup file, and so the path to my css and js files.
>
> Maybe with the new exporter everything has changed and I only miss a
> good tutorial?
>
> henry
>


Do you want to export a single file or do you want to publish a complete 
project?

As for projects, the setup is very similar to the old exporter.  I 
noticed however, I used some deprecated options or options not in the 
right way, so I did have my own problems getting  publishing to work.

Until recently you had to require org-e-html in your .emacs for 
publishing to work.  Thanks to Nicolas great help this and some other 
obstacles are removed in recent git versions (master branch, not maint).

I attached a description of an example project using the new exporter. 
The example isn't comprehensive, but it should get you started.

Best regards
Robert


[-- Attachment #2: newexporter.org --]
[-- Type: text/plain, Size: 7912 bytes --]

#+ -*- fill-column:75; coding: utf-8-unix; -*-
#+TITLE: Using the new org exporter

* Setting up org-mode

/Note:/ You'll need a rather current version of the Org mode git master for
everything to work.

See
[[http://orgmode.org/worg/org-faq.html#keeping-current-with-Org-mode-development]]
on how to get a current version.

See [[http://orgmode.org/worg/dev/org-build-system.html]] for more information
about installing Org mode.

To use the new exporter the autoloads for it have to be created.  If
you install Org mode with, e.g. =make= ensure you have something like
the following line in your local.mk:

#+begin_example
ORG_ADD_CONTRIB = org-e-* org-md org-export
#+end_example

* helper function to save this files code as new-exporter.emacs

This is simply a helper function for tangling this file.  The helper
function is included in the tangled file, so I don't have to C-x C-e
it before use.

Adjust file names and path for your own use.
#+begin_src emacs-lisp
  (defun roklein/save-dotemacs ()
    "Save my emacs configuration as new-exporter.emacs"
    (interactive)
    (let* ((source-directory "~/Documents/org/emacs")
           (source-filename "newexporter.org")
           (destination-dir "~/Documents/org/emacs")
           (destination-filename "new-exporter.emacs"))
      (org-babel-tangle-file (expand-file-name source-filename source-directory)
                             (expand-file-name destination-filename destination-dir)
                             "emacs-lisp")))
#+end_src

* load org specific settings

First I'm setting the load-path for org-mode including contrib.
Depending on your Org mode setup you don't need to load-path the contrib
directory.

#+begin_src emacs-lisp
  ;;;
  ;;; org-mode and contrib
  ;;;
  (setq load-path (cons "~/.emacs.d/org-mode/lisp" load-path))
  (setq load-path (cons "~/.emacs.d/org-mode/contrib/lisp" load-path))
  (require 'org-install)
#+end_src

* Initializing the new exporter
First I initialize the alist.  Note, the alist has a different name
than the alist for the old exporter.  
#+begin_src emacs-lisp
  (setq org-e-publish-project-alist nil)
#+end_src


* Configuring a  project

** alist entry for the complete project

The project is made up from two components, the part publishing the
org files (example-html) and the part copying the static files.

#+begin_src emacs-lisp
  (add-to-list 'org-e-publish-project-alist
               '("example"
                 :components ("example-html" "example-extra")))
#+end_src


** alist-entry for .org-files

First I'm configuring setting up the alist entry for html publishing.

#+begin_src emacs-lisp
  (add-to-list 'org-e-publish-project-alist
               '("example-html"
#+end_src

The first for items are necessary for any publishing project.  They
are pretty much the same as for the old exporter.  The publishing
functions name has changed to =org-e-publish-org-to-html=.

The =:base-directory= is where the file to be published are located;
=:base-extension= tells the publishing function which files are to be
published, =:publishing-directory= is the directory where the exported
files are written to, and =:publishing-function= is the function used
be the publisher to export the files as determined by the
=:base-directory= and =:base-extension=.

#+begin_src emacs-lisp
                 :base-directory "~/Documents/org/example"
                 :base-extension "org"
                 :publishing-directory "~/public_html/example.com"
                 :publishing-function org-e-publish-org-to-html
#+end_src


The publisher can invoke a function each before starting the
publishing process and after finishing it.  E.g. you can disable the
confirmation prompt when evaluating babel code and enable it again
after publishing is complete.
#+begin_src emacs-lisp
                 :preparation-function example-prepare
                 :completion-function example-complete
#+end_src


Some information I don't want to have in every .org files header...
#+begin_src emacs-lisp
                 :author "John Doe"
                 :email "john.doe@example.com"
                 :language "en"
                 :section-numbers nil
#+end_src

Some settings for HTML styles and so on.  These options look the same
like in the old exporter.  
#+begin_src emacs-lisp
                 :style "<link rel=\"stylesheet\" type=\"text/css\" href=\"css/example.css\" />"
                 :style-include-default nil
                 :style-include-scripts nil
                 :LaTeX-fragments nil
#+end_src

The =:html-preamble= variable can be set to one
of four settings:
- nil :: no preamble is created by the exporter
- t :: a default preamble is created
- a string :: a custom formatting string. =%t=, =%a=, =%e=, and =%d=
              are replaced by the title, the author's name, the
              author's email, or the date, respectively.
-  a function name :: a function which creates the preamble. The
     function must return a string.


The =:html-postamble= variable can be set to the same four settings.
For the string option =%a=, =%e=, =%d=, =%c=, and =%v= can be used to
be replaced by the author's name, the author's email, the date, the
Org/Emacs- version, or the org-e-html-validation-link, respectively.

Other than the old exporter when you want to use a function, as I do
here, the function itself must accept one option, a plist containing
the export options.

#+begin_src emacs-lisp

                 :html-preamble example-preamble
                 :html-postamble example-postamble
                 ))
#+end_src

** alist entry for any files simply to be copied

This is pretty much the same as above, notice the difference in the
base-extension — all the files I want to be copied verbatim — and the
publishing-function.

I added a recursive option here.  While I tend to accumulate the
org-files in the case-directory, I usually have extra directories for
css files and images.

#+begin_src emacs-lisp
  (add-to-list 'org-e-publish-project-alist
               '("example-extra"
                 :base-directory "~/Documents/org/example"
                 :publishing-directory "~/public_html/example.com"
                 :base-extension "css\\|pdf\\|png\\|jpg\\|gif\\|ksh\\|sh\\|py"
                 :publishing-function org-e-publish-attachment
                 :recursive t
                 ))
#+end_src

** preparation and completion functions

Most of this I took from older projects.  The important stuff is
disabling backup and babel confirmation before publishing and enabling
it again after publishing.

#+begin_src emacs-lisp
  ;; prepare environment before publishing and reset it after
  (defun example-prepare ()
    (setq org-export-html-coding-system 'utf-8)
    (setq make-backup-files nil)
    (setq org-export-html-inline-images t)
    (setq org-export-allow-BIND t)
    (setq org-confirm-babel-evaluate nil))
  (defun example-complete ()
    (setq make-backup-files t)
    (setq org-confirm-babel-evaluate t))
#+end_src


** HTML preamble and postamble functions

Note, the pre- and postamble functions have one argument which
contains a plist of the export options (called so by the exporter).

I noticed, I used a function from the old exporter,
=org-get-file-contents=, so I changed it in the postamble-function to
show another way.  I'm not using the options argument in this example.

#+begin_src emacs-lisp
  ;; pre- and postamble for html export
  (defun example-preamble (options)
    (org-get-file-contents "~/Documents/org/example/html/preamble.html"))
  (defun example-postamble (options)
    (with-temp-buffer
      (insert-file-contents "~/Documents/org/example/html/postamble.html")
      (buffer-string)))
#+end_src  
  
  
  
* Publishing

Press =M-x=, type org-e-publish, press =ENTER=, type the projects name
(=TAB= completes, double =TAB= shows the available completions), e/g
=example= and press =ENTER=.