* Re: new html exporter
2012-09-29 11:36 new html exporter henry atting
@ 2012-09-29 15:18 ` Robert Klein
2012-09-29 16:19 ` henry atting
0 siblings, 1 reply; 6+ messages in thread
From: Robert Klein @ 2012-09-29 15:18 UTC (permalink / raw)
To: henry atting; +Cc: emacs-orgmode
[-- 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=.
^ permalink raw reply [flat|nested] 6+ messages in thread