EMACS ORG-INFO.JS

The org-info.js JavaScript (subsequently called the script) and its setup are still under development and might change frequently. This documentation might as well be outdated by the time you read this. If you don't mind using it anyway and adjust your org export options at times we wish you good luck and hope the fun will outweigh your effort.

The aim of this little script is to implement a part of emacs Org-mode facilities (folding in the first place) in the XHTML-exported files and to display them in a linuxdoc like way. This documentation is one XHTML file, exported from one *.org file using a single keyboard shortcut. No additional postprocessing was done.

There are no external dependencies. The script is quite small and fast enough for larger files too. I tested it with the file ORGWEBPAGE/Changes.org in the Org-mode package which gave me 225 pages to handle and on my old omnibook it still worked nicely. The current version tries to do so over the net too (see http://orgmode.org/Changes.html).

There are some drawbacks though. It is currently not possible to open internal links in another tab (e.g. using middle click in Firefox) due my poor JavaScript knowledge. This is not very high on my TODO list since the history mechanism of the script is a good alternative to tab usage.

A list of Changes can be found here (separat file).

Go to the next section by pressing 'n'.

Find out about shortcuts in section Shortcuts (and come back here pressing 'b').

'?' will show all shortcuts available.

The visitor of this file (and every XHTML-exported org file that includes the script) may use the mouse or the following keys to navigate. '?' should give you a list of shortcuts too.

The script always tries to keep the last selected section visible. This is somewhat strange when scrolling, but really helpfull for keyboard navigation.

If the keyboard shortcuts work for you, drop me a mail and tell me your browser and its version so we can put it on list of supported browsers.

The TOC is handled specially, when hidden. If you press 'i', the TOC is displayed. Any subsequent key press goes back to where you've been before. The TOC does not show up the history. Same applies to the keyboard help.

Thanks Carsten, for this beautifull table!

This section describes the setup of your org files for the utilisation of the script. Export-Setup - the new Way will guide you to setup your org XHTML export. That section refers to an Org-mode version >= 6.02. For those using an Org-mode version < 6.02 the next section (Export-Setup - the old Way) remains. Using Set() contains a list of all supported options for adjusting the org_html_manager to suit your needs.

A sufficient up to date version is available for download on orgmode.org or in the git repo:

git-clone git://repo.or.cz/org-mode.git

This script will not work with the XHTML export as distributed with the current Org-mode package (and hence emacs 22.x) anymore (??). But I'm afraid there are good chances the new exporter is in emacs before this thing here enters a somewhat stable state :-)

To produce this XHTML file I used the current version of Org-mode and it's XHTML export. The structure of the exported XHTML has changed a bit in beginning of March 2008 to support scripting an other tools that work on XML. Thanks to Carsten Dominik who found the time to modify the current export modul to produce the draft version of the next generation XHTML. The new structure won't break any of your stylesheets though.

The new export made it into git somewhere around version 5.23a+. Try M-x org-version to find out about your Org-mode version.

Just use the ordinary link syntax to link to files that use the script. Append the section to the URL if neccessary:

 http://www.domain.tld/path/to/org.html#sec-3.4

One may overwrite the author's settings using special suffixes appended to the URL of the script. Here are some examples linking to this section and changing the intial view mode. Currently only the 'internal' options are used (see Using set() for a list).

• index.html?TOC=1&VIEW=info#sec-5
• index.html?TOC=0&VIEW=overview#sec-5
• index.html?VIEW=content&TOC_DEPTH=1#sec-5
• index.html?VIEW=showall&MOUSE_HINT=rgb(255,133,0)#sec-5
• index.html?OCCUR=java

Note that it is not possible to change the 'HOME' and 'Up' links.

Note also that everything but [0-9a-zA-Z\.-_] should be URL encoded if used as an options value.

There is currently only one CSS class used in the script. More style classes will follow in the future.

org-info-info-navigation

Style for the navigation table in info view mode. I needed this one to avoid border around that table. You may add lines like these to your stylesheet:

/* Style for org-info.js */

.org-info-js_info-navigation
{
  border-style:none;
}
#org-info-js_console-label
{
  font-size:10px;
  font-weight:bold;
  white-space:nowrap;
}
.org-info-js_search-highlight
{
  background-color:#ffff00;
  color:#000000;
  font-weight:bold;
}

The functionality of the script is based on DOM. This leads to some incompatibility with legacy browsers. But hey, it's 2008, isn't it?

So what browsers are supported then? Well - I do not know for shure. JavaScript™ 1.4 plus DOM should make

• Netscape 6.0 and higher
• Internet Explorer 5.0 and up
• Firefox 1.0 ++ - 2.0.0.12 and 3.0 Beta tested
• Opera 7.0 and higher - v.9.26 tested.
• Safari 1.0

I have written and tested the script only in current Firefox, Opera and IE 6 so far for a lack of spare time, operating systems on my laptop, and installed browsers. IE is not fully supported (position fixed…) but fairly working. Firefox 2 is anyoing slow as with all web pages heavily utilising JavaScript. I recently installed Firefox 3.0 Beta which works much better. For once in my life I have to admit that Opera is the best here.

Currently the script depends on the table of contents in the resulting XHTML. The T.O.C. can be hidden though.

The main reason is the behaviour of browsers. There is no safe way to detect if the entire document is loaded at a certain point in time. Opera for example returns true if we ask it if(document.body). The init() function of the OrgHtmlManager is aware of the possibility, that not even the T.O.C. might be loaded when this function is called. Hence it should work for slow connections too. There should be tons of other bugs though :)

End users may consider this section obsolete as of org version 6.00-pre-3, since there is a new configuration interface in org now to setup the script without dealing with JavaScript. It is still here to show the desired look of the head section of the XHTML. Also someone might be interested to use the script for XHTML files not exported from org.

The script has to be included in the header of the resulting XHTML files. The document structure has to be exactly the one produced by the current XHTML export of emacs Org-mode. You may pass options to the org_html_manager by utilising its set() method. For a list of options see section Using Set(). This is what the head section should look like:

<script type="text/javascript" src="org-info.js"></script>
<script type="text/javascript">
/* <![CDATA[ */
org_html_manager.set("LOCAL_TOC", 1);
org_html_manager.set("TOC", 1);
org_html_manager.set("VIEW_BUTTONS", "1");
org_html_manager.set("MOUSE_HINT", "underline"); // or background-color like '#eeeeee'
org_html_manager.setup ();
/* ]]> */
</script>

To just use the script with the defaults put this into the head section of the XHTML files:

<script type="text/javascript" src="org-info.js"></script>
<script type="text/javascript">
/* <![CDATA[ */
org_html_manager.setup ();
/* ]]> */
</script>

I recommend the use of

<script type="text/javascript" src="org-info.js"></script>

<script type="text/javascript" src="org-info.js" />

First of all the script is included in the header as described in Usage. The document has to be exported with T.O.C. since the script depends on it (See Why Do I Need a T.O.C?).

When included, it creates a global JavaScript™ variable named org_html_manager.

The org_html_manager::setup() function, that you will have to call yourself (see examples in Usage), sets up a timeout function calling it's init() function after 50ms. After those 50 ms The init() function starts it's first attempt to scan the document, using the T.O.C. as a guide. During this scan the org_html_manager builds a tree of nodes, each caching some data for later use. Once an element of the document is scanned it is marked by setting a property scanned_for_org to 1. This way it will not be scanned a second time in subsquent runs (it will be checked though, but no work will be done for it).

If the document (or the T.O.C.) is not entirely loaded, org_html_manager stops scanning, sets the timeout again to start an other scan 50 ms later. Once the entire document is loaded and scanned no new timeout will be set, and the document is displayed in the desired way (hopefully).

Once the number of attempts to scan the the document was configurable. This was dropped, since we can not know in advance how fast the document will be loaded on the client side.

The org_html_manager also changes the document a bit to make it react on certain input events and follow your wishes. The old 'event handling' was entirely based on the normal link functions using so called accesskeys. This has changed a little, but is still only in experimental state. The accesskeys will stay cause there is no reason to remove them.

There is still the idea of a new emacs like keyboard handling to implement complex commands (which is still in the far future).

The script can handle all the sections as single slides. Press 'x' to switch to the presentation mode. In this mode you may navigate the sections using the mouse. Currently a single click moves forward and a doubleclick backwards (will change this to right mouse button for backwards movement).

The first plain list (i.e. an <ul> element) in a section is special. The items will be shown one by one when moving forward.

If you're at the end of the presentation, a click does not trigger a warning. Same applies to a doubleclick when in the first section.

There is no plan to extend this feature very much. We plan to write a separate tool to handle slides.

The aim of this little script is to implement a part of emacs Org-mode facilities of folding. Oh, no - not originaly.

My first idea was to view some of my larger org files without scrolling. I wanted to have them paged just like texinfo or linuxdoc files. In February 2008 I came across Carsten Dominiks ideas page http://orgmode.org/todo.html. And I could not resist to write him some of my thoughts about this great emacs mode including some little ideas and drawbacks. I don't know how, but it somehow these guys made me, lazy bone that I am, write this little script as an apetizer of web 3.0 in Org-mode (Phil Jackson).

I did and since some people really liked it, worked a bit more on it and added features. Bastien Guerry was so kind to publish it on http://www.legito.net/org-info-js/ the first months. Thanks Bastien.

In the first days of April Carsten Dominik added code to Org-mode to support the usage of this script. Hence the script may now be configured in a similar way to the other export options. Since then it is even possible to configure this script through customize.

Very special thanks to Carsten Dominik, Bastien Guerry and Phil Jackson who have encouraged me to write and publish this little piece of (unfinished) work and all the hundrets of hours they spent on this fantastic emacs mode called Org-mode and the export modules.

Org is a new working experience for me and there is nothing comparable to working with emacs AND Org-mode.

An other big kiss to Gabi (www.emma-stil.de) for being so patient while I was not working on our projects but playing with emacs.

Thanks to Tobias Prinz for listening to my stupid JavaScript questions and all the usefull tips. Espacially the negative margin trick and key input.

And again big thanks to Carsten Dominik for making the inclusion and configuration of the script so easy for the users, all the inspired ideas and the great org radio table trick. A lot of the power of the final make up is your merit! We all love to read the best of all mailing lists because of the kind and relaxed tone that is yours.

Thanks a lot for OrgMode!

What I think about licenses? Well - I think licences and patents are not far from each other. Poor people (and poor countries!!!) stay poor because of both of them. But since I know where I live, in a world made of licenses and patents, I have to apply some license to my work to protect it and stay unprotected.

Hence the script itself is provided under the GPL version 2. This document is subject to GFDL.

This document in emacs23 with Org-mode v. 5.22a+. The visibilty of the contents of a individual section or subsection can be toggled by clicking the stars in front of the headlines or moving there and hitting TAB. The visibility of the entire document structure can be changed by pressing SHIFT+TAB anywhere. When on a headline, pressing ALT+UP/DOWN moves the entire subtree to different location in the tree, keeping it's level of indentation. ALT+LEFT/RIGHT promotes and demotes the subtree.