new html exporter

new html exporter

[henry atting]

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

-- 
http://literaturlatenight.de

Re: new html exporter

[Robert Klein]

[-- 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=.

Re: new html exporter

[henry atting]

Robert Klein <kleinrob@mpip-mainz.mpg.de> writes:

> 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?

Only a single file. I understand that something like this will no work
anymore with the new exporter.

#+SETUPFILE: /home/me/.setup.org

whereby the content of the setup file is:

#+STYLE: <link rel="stylesheet" type="text/css" href="/home/me/.style.css" />
#+INFOJS_OPT: view:info toc:t path:/home/me/.org-info.js

Besides I'm pretty happy with the old exporter and was only curious
because I read that it will be replaced with the new one in a future
stable version. I hope the old one will remain part of contrib (or
antique or whatever) so I can choose to my liking.


> 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

Best regards

henry


-- 
http://literaturlatenight.de

Re: new html exporter

[Nicolas Goaziou]

Hello,

henry atting <nsmp_03@online.de> writes:

> Only a single file. I understand that something like this will no work
> anymore with the new exporter.
>
> #+SETUPFILE: /home/me/.setup.org

It's #+SETUP_FILE: in the new exporter.

> Besides I'm pretty happy with the old exporter and was only curious
> because I read that it will be replaced with the new one in a future
> stable version. I hope the old one will remain part of contrib (or
> antique or whatever) so I can choose to my liking.

It would help to know what the new exporter is missing.


Regards,

-- 
Nicolas Goaziou

Re: new html exporter

[henry atting]

Nicolas Goaziou <n.goaziou@gmail.com> writes:

> Hello,
>
> henry atting <nsmp_03@online.de> writes:
>
>> Only a single file. I understand that something like this will no work
>> anymore with the new exporter.
>>
>> #+SETUPFILE: /home/me/.setup.org
>
> It's #+SETUP_FILE: in the new exporter.

Okay, then it applies the `#+STYLE:' option from the setup file but not
the path to org-info.js set in `#+INFOJS_OPT: path:~/.org-info.js'.

>> Besides I'm pretty happy with the old exporter and was only curious
>> because I read that it will be replaced with the new one in a future
>> stable version. I hope the old one will remain part of contrib (or
>> antique or whatever) so I can choose to my liking.
>
> It would help to know what the new exporter is missing.

Most probably nothing. Orgmode already has so many features, most of
them I will never need I suppose. I am using orgmode for some years now
but I wouldn't call me a heavy user. I jot down notes with org-capture,
keep up a very simple agenda, plot my monthly household expenses and do
some exporting to html.
As to me I am content with e.g. org-export-as-html as I probably will be
with the upcoming switch to the new exporter. I am only a little
disappointed by the fact that these above mentioned tiny changes (like
setupfile to setup_file) for someone like me (who does not want to
take a deeper look into orgmode) are more confusing than they should be. 
Then again this little confusion will of course not discourage me from using
orgmode.  

>
> Regards,

Regards,
henry

-- 
http://literaturlatenight.de

Re: new html exporter

[Nicolas Goaziou]

Hello,

henry atting <nsmp_03@online.de> writes:

> Okay, then it applies the `#+STYLE:' option from the setup file but not
> the path to org-info.js set in `#+INFOJS_OPT: path:~/.org-info.js'.

This is to be expected: org-jsinfo.el doesn't recognize the new exporter
yet.

> As to me I am content with e.g. org-export-as-html as I probably will
> be with the upcoming switch to the new exporter. I am only a little
> disappointed by the fact that these above mentioned tiny changes (like
> setupfile to setup_file) for someone like me (who does not want to
> take a deeper look into orgmode) are more confusing than they should
> be.

Documentation will be updated when the new exporter becomes mainstream.


Regards,

-- 
Nicolas Goaziou