HTML export and heading levels

HTML export and heading levels

[Bernt Hansen]

Hi Carsten and list,

I started playing with HTML export this week and since I'm lazy I don't
want to have to remember to export.  I created a few simple functions
that export my org file to HTML and copies the resulting HTML file to my
webserver when I save my org file using C-x C-s.

This works great for sharing my ToDo list and other documents with other
people.

-----8<-----

(defvar bth-publish-command "/home/bernt/bin/publish"
  "Command used to publish a document")

(defun bth-publish-buffer ()
  "Publish the document associated with the current buffer."
  (interactive)
  (cond
   ((not (buffer-file-name))
    (error "This buffer is not associated with a file"))
   ((buffer-modified-p)
    (error "Save buffer prior to publishing this document"))
   (t
    (message "Updating document..")
    (if (/= 0 (call-process bth-publish-command
			    nil nil nil
			    (buffer-file-name)))
	(error "Failed to update document")
      (message "Done.")))))

(defun bth-export-save-then-publish ()
  "Save the current buffer, export to HTML, and publish on the website"
  (interactive)
  (save-buffer)
  (org-export-as-html 2)
  (bth-publish-buffer)
  (message "Published."))

(defun bth-org-define-keys ()
  "Define C-x C-s for buffer whose filename ends with .org"
  (when (and (buffer-file-name)
	     (string= (substring (buffer-file-name) -4) ".org"))
    (local-set-key "\C-x\C-s" 'bth-export-save-then-publish)))

(add-hook 'text-mode-hook 'bth-org-define-keys)

----->8-----

Now I have multiple org-mode files and they don't all have the same
structure.  I've hardcoded the HTML export to level 2 in
bth-export-save-then-publish but it would be much better to have the
export honour the org-mode file option instead.

I have the following at the top of my org files:

#+TITLE: ToDo List
#+OPTIONS: H:2 ^:nil f:nil author:nil toc:t

I tried various things but if I change the H:2 to something else (H:3,
etc) it always exports with level 2 in the table of contents when I save
the file with C-x C-s.  If I export manually with the C-c C-e h
sequences then the #+OPTIONS: heading level is used.  All of the other
#+OPTIONS seem to work fine it's just the heading level from my
(org-export-as-html 2) seems to override the file level setting.

Is there an easy fix for this?  I'm still a lisp novice.

One other thing that would be handy is a way to skip tasks in the
export.  I'm not sure if anything like that exists yet or not.  I
normally have a 

* Timelog

entry at the top of every org file which has the clock table format that
is appropriate for that file.  I really don't want that included in my
export to HTML so it would be great if there was a way to say 'skip this
heading and all sublevel headings' on export - maybe as a property or
something.

For now I've delete the Timelog tasks from the files I'm exporting to
keep the time log tables off the published version.

Thanks,
Bernt

Re: HTML export and heading levels

[Bastien]

Hi Bernt,

thanks for sharing this -- I add some (hopefully useful) comments.

Bernt Hansen <bernt@norang.ca> writes:

> I started playing with HTML export this week and since I'm lazy I don't
> want to have to remember to export.  I created a few simple functions
> that export my org file to HTML and copies the resulting HTML file to my
> webserver when I save my org file using C-x C-s.

I guess we need the /home/bernt/bin/publish file for this to be really
reusable, no?

Another way to do a similar think

(add-hook 'org-mode-hook
	  (lambda() (add-hook 'before-save-hook 
			      'org-publish-current-file t t)))

This will run the `org-publish-current-file' function each time you try
to save an org-mode buffer.  For this to take effect, the file has to be
part of a project -- see the manual (info "(org)Configuration") on how
to configure a project.  

> (add-hook 'text-mode-hook 'bth-org-define-keys)

I guess this should be:

(add-hook 'org-mode-hook 'bth-org-define-keys)

> Now I have multiple org-mode files and they don't all have the same
> structure.  I've hardcoded the HTML export to level 2 in
> bth-export-save-then-publish but it would be much better to have the
> export honour the org-mode file option instead.

You can configure this through the org-publish project parameters.  
See the manual: (info "(org)Publishing options") and look for the
:headline-levels parameter.

> One other thing that would be handy is a way to skip tasks in the
> export.  I'm not sure if anything like that exists yet or not.  

(I wish we could set complex filters when exporting, but that may be
another story...)

> I normally have a
>
> * Timelog
>
> entry at the top of every org file which has the clock table format that
> is appropriate for that file.  I really don't want that included in my
> export to HTML so it would be great if there was a way to say 'skip this
> heading and all sublevel headings' on export - maybe as a property or
> something.

For this you can use this workaround:

* COMMENT Timelog

HTH,

-- 
Bastien

Re: HTML export and heading levels

[Bernt Hansen]

Bastien <bzg@altern.org> writes:

> I guess we need the /home/bernt/bin/publish file for this to be really
> reusable, no?

I use SSH keys with the ssh-add command once every morning to load my
keys in the key agent.  After that my ssh/scp commands to remote systems
just work without password prompts.

The publish file is just a simple shell script that takes the filename
source as the only argument and converts it to an HTML file and copies
it to the appropriate place.  For org-mode the conversion is already
done and all it really needs to do is copy the file.

The following bare-bones publish script should work but it's untested.
I've included the script I really use below.

,----[ simple org-mode only ~/bin/publish -- untested ]
| #!/bin/sh
| # If no HTDOCS file then don't publish anything
| if ! [ -e HTDOCS ]; then exit 0; fi
|
| SRCNAM=$1
| DSTSYS=$(cat HTDOCS)
| DSTNAM=$(basename ${SRCNAM/.org/.html})
|
| # Copy the HTML document to the target system
| if [ -e $DSTNAM ]; then
|   scp $SRCNAM $DSTNAM $DSTSYS
| fi
`----

My publish script actually handles a few different tools:
  - crock ( a wiki like text to HTML translater) http://crock.tuxee.net/crock
  - asciidoc (another text to HTML translater) http://www.methods.co.nz/asciidoc/
  - exported org-mode files

The source files live in some directory in my account (~/org for org
files, ~/crock/ for crock sources, ~/asciidoc/ for asciidoc files.  The
crock and asciidoc files have subfolders so I can organize documents
into different groups and publish them to different locations.

Each directory with documents to publish has a HTDOCS file which states
what directory on the target system the .html file is to be copied to.

Crock and AsciiDoc documents have a CROCK and ASCIIDOC file which is
used to tell the publish script what type of document it's working
with.  Both crock and AsciiDoc source files end in .txt

e.g. my ~/org directory has ~/org/HTDOCS with the single line 

,----[ ~/org/HTDOCS ]
| www-data@www:org/
`----

Here's the publish script.  I just hacked the exported org file
functionality into the existing script that handled crock and asciidoc
so it's ugly but it works.

,----[ ~/bin/publish ]
| #!/bin/sh
| # If no HTDOCS file then don't publish anything
| if ! [ -e HTDOCS ]; then exit 0; fi
|
| SRCNAM=$1
| DSTSYS=$(cat HTDOCS)
| DSTNAM=$(basename ${SRCNAM/.txt/.html})
|
| # Publish a crock file 
| if [ -e CROCK ]; then
|   crock $SRCNAM >$DSTNAM
| # Publish an asciidoc file
| elif [ -e ASCIIDOC ]; then
|   ASCIIDOCARGS=$(cat ASCIIDOC)
|   asciidoc $ASCIIDOCARGS $SRCNAM
| fi
| 
| # If the source file isn't *.txt assume it's an org file
| if [ "$SRCNAM" == "$DSTNAM" ]; then
|   DSTNAM=$(basename ${SRCNAM/.org/.html})
| fi
| 
| # Copy the HTML document to the target system
| if [ -e $DSTNAM ]; then
|   scp $SRCNAM $DSTNAM $DSTSYS
| fi
`----

This gets my exported *.html files and their sources to my webserver in
~www-data/org and I just create symlinks to them from websites that need
to show that content.  I can safely publish all my org files to the /org
directory knowing that only the specific documents I linked to end up
being served by apache.

The HTDOCS file in the crock and asciidoc source folders send documents
directly to website locations served by apache.

I've been using crock and asciidoc for years.  If org-mode can do
everything I want I'll probably just start using it instead.

>
> Another way to do a similar think
>
> (add-hook 'org-mode-hook
> 	  (lambda() (add-hook 'before-save-hook 
> 			      'org-publish-current-file t t)))
>
> This will run the `org-publish-current-file' function each time you try
> to save an org-mode buffer.  For this to take effect, the file has to be
> part of a project -- see the manual (info "(org)Configuration") on how
> to configure a project.  

Thanks!  I'll look into this.

>
>> (add-hook 'text-mode-hook 'bth-org-define-keys)
>
> I guess this should be:
>
> (add-hook 'org-mode-hook 'bth-org-define-keys)

Yes it should.  I blatantly cloned my crock setup which works in
text-mode and forgot to change the hook to be org-specific.  It is
working for me with the text-mode-hook though.

>
>> Now I have multiple org-mode files and they don't all have the same
>> structure.  I've hardcoded the HTML export to level 2 in
>> bth-export-save-then-publish but it would be much better to have the
>> export honour the org-mode file option instead.
>
> You can configure this through the org-publish project parameters.  
> See the manual: (info "(org)Publishing options") and look for the
> :headline-levels parameter.
>

I'll put investigate org-publish on my todo list :)

>> One other thing that would be handy is a way to skip tasks in the
>> export.  I'm not sure if anything like that exists yet or not.  
>
> (I wish we could set complex filters when exporting, but that may be
> another story...)
>
>> I normally have a
>>
>> * Timelog
>>
>> entry at the top of every org file which has the clock table format that
>> is appropriate for that file.  I really don't want that included in my
>> export to HTML so it would be great if there was a way to say 'skip this
>> heading and all sublevel headings' on export - maybe as a property or
>> something.
>
> For this you can use this workaround:
>
> * COMMENT Timelog
>
> HTH,

I'll try that.

---

At the time I did this publish tool I needed something I could throw
together in a few minutes and I already had the publish script in place
for other document sources.  I'd completely forgotten about org-publish.
I'll look into cleaning up this process with org-publish instead when I
have some free time.

Thanks for the pointers.  :-)

Bernt

Re: HTML export and heading levels

[Bernt Hansen]

Bernt Hansen <bernt@norang.ca> writes:

> I started playing with HTML export this week and since I'm lazy I don't
> want to have to remember to export.  I created a few simple functions
> that export my org file to HTML and copies the resulting HTML file to my
> webserver when I save my org file using C-x C-s.
>
> This works great for sharing my ToDo list and other documents with other
> people.

And maybe this isn't such a great idea after all.  After I've saved my
document and auto-exported I can't undo things anymore...  Time to look
at org-publish...

-Bernt

Re: Re: HTML export and heading levels

[William Henney]

Hi Bernt

On Jan 17, 2008 7:49 AM, Bernt Hansen <bernt@norang.ca> wrote:
> Bernt Hansen <bernt@norang.ca> writes:
>
> > I started playing with HTML export this week and since I'm lazy I don't
> > want to have to remember to export.  I created a few simple functions
> > that export my org file to HTML and copies the resulting HTML file to my
> > webserver when I save my org file using C-x C-s.
> >
> > This works great for sharing my ToDo list and other documents with other
> > people.
>
> And maybe this isn't such a great idea after all.  After I've saved my
> document and auto-exported I can't undo things anymore...  Time to look
> at org-publish...
>

I have been using org-publish a lot lately and it works pretty well.
One thing that you might want to consider is to publish to a directory
on your local disk and then use an external utility (e.g., your
script) to synchronize with the web server.

The problem I have found with directly setting :publishing-directory
to a remote machine in org-publish-project-alist is that when there
are several files the publishing process becomes very slow (several
minutes) and emacs completely locks up for that time :(

Perhaps Bastien has some advice on how this can be improved. I think
the problem is with tramp rather than org-mode. I currently work
around the problem by publishing to a local directory and then using
"make" and "rsync" to synchronize with the web server.

Cheers

Will

-- 

  Dr William Henney, Centro de Radioastronomía y Astrofísica,
  Universidad Nacional Autónoma de México, Campus Morelia