[Orgmode] Re: HTML export and heading levels

[Bernt Hansen]

Bastien <address@hidden> 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 ]
| address@hidden: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