EMACS ORG-INFO.JS

I tend to talk about view modes. One may toggle the view mode by pressing 'm' or click the toggle view link. Currently two view modes exist.

info view mode

This mode displays the sections one by one, paged like the typical linuxdoc or texinfo files. This is the view mode you should face when first visiting this documentation.

plain view mode

This mode displays the entire file. In this mode the sections are foldable by clicking the headlines or pressing 'f' (fold). The entire structure of the document my be (un-)folded using 'g'.

T.O.C. is used for the table of contents. The table of contents may be visited using 'i' (index) regardless of its visibility.

A section is everything with a headline.

Toggle plain and info view

One can click the script-generated links in info view mode to read through the whole file page by page. By clicking on 'toggle view' (or pressing `t´) you can switch between info and plain view mode.

Keep place in file when toggling

When changing the view mode via the 'toggle view' links, the reader gets the same part of the document presented after the view change as he saw before.

Cut the TOC

You may cut the table of contents to a certain depth. The splitting of the document is not affected by this option. Hence you might set the level of headlines to 4, but cut the TOC to show only the first two levels.

Optional subindexes

The script optionally creates subindexes under the headline of a section containing subsections not exceeding org-export-headline-levels. This was done to get a more texinfo/linuxdoc kind of feel and a better orientaton.

Startupview customizable

Choose how to display the document on load. Info-like or plain.

Toggle links everywhere / only on top

You may choose to display the 'toggle view' links above every headline or just next the current sections headline.

Numbered pages

In info view mode every page gets a page number starting from one.

Markright alike headings

Info view mode only. Similar to the \markright command in LaTeX the Title of the current sections parent appears on top of each page. In subsections this heading can be use as link up to start of the parent section (see top of this page when you're in info view mode). You can move to the parent section by pressing `u´ (up).

Tooltips

Moving the mouse on the navigation links shows a tooltip with name of next/previous section.

Hide T.O.C.

The T.O.C. can be hidden completly. Hitting 'i' still will show it. When showing the T.O.C. hitting 'i' any navigation command ('n', 'p', 's'…) will trigger an history-back. Thus the T.O.C. will not get in your way when navigating the history later on.

Easy keyboard navigation

See Section Shortcuts for a list of shortcuts.

Customizable features

All features are customizable simply by setting up your export options template (see Usage).

Folding

Emulates the way of folding in emacs Org-mode. Mouse supported.

Full text-search with highlighting

Search forward, backwards, repeated search… This is still experimental.

Occur mode

As experimental as the text-search, but I love this one. You may link to a file using this script like this: index.html?OCCUR=java

Inter-linking

The exported pages can be linked to the homepage and an directory index or some other sort of parent file.

Adjusted internal links

Internal links to section headings are automatically adjusted to work with this script. When following such internal links, one may go back again using 'b'.

Detect the target in the URL

If the URL is suffixed by '#sec-x.y.z' that section will be displayed after startup.

Structure is taken from export preferences

The paging is done according to your setting of org-export-headline-levels. Scanning the T.O.C. is a good way to get around browser detection. An option to hide the T.O.C. exists.

There is no need to do something you don't do occasionally in Org-mode when it comes to XHTML export. Just use one of the ordinary ways to include something into the head of the resulting html file.

The modern way of org export setup provides extra options to include and configure the script, as well as a emacs customize interface for this same purpose. Options set in customize may be overwritten on a per-file basis using one or more special #+INFOJS_OPT: lines in the head of your org file.

As an example, the head of this org file looks like:

#+INFOJS_OPT: path:org-info.js
#+INFOJS_OPT: toc:nil localtoc:t view:info mouse:underline
#+INFOJS_OPT: up:http://www.legito.net/
#+INFOJS_OPT: home:http://orgmode.org buttons:nil

M-x customize-group RET org-export-html RET

#+INFOJS_OPT: view:info mouse:underline up:index.html home:http://www.mydomain.tpl toc:t

This section describes the old way to setup the script using the org-export-html-style configuration. If you own a current version (6.00 ++) of Org-mode you should better use Export-Setup - the new Way of setting up the export for script usage. You might want to read the sections The XHTML for more information. Using Set() contains a list of all supported options recognised by the script.

* COMMENT html style specifications
# Local Variables:
# org-export-html-style: "<link rel=\"stylesheet\"
# type=\"text/css\" href=\"styles.css\" />
# <script type=\"text/javascript\" language=\"JavaScript\" src=\"org-info.js\">
# </script>
# <script type=\"text/javascript\" language=\"JavaScript\">
#  /* <![CDATA[ */
#    org_html_manager.set(\"LOCAL_TOC\", 1);
#    org_html_manager.set(\"VIEW_BUTTONS\", \"true\");
#    org_html_manager.set(\"MOUSE_HINT\", \"underline\");
#    org_html_manager.setup ();
#  /* ]]> */
# </script>"
# End:

M-x cuomize-variable RET org-export-html-style RET

<script type="text/javascript" language="JavaScript" src="org-info.js"></script>
<script type="text/javascript" language="JavaScript">
/* <![CDATA[ */
org_html_manager.set("LOCAL_TOC", 1);
org_html_manager.set("VIEW_BUTTONS", "true");
org_html_manager.set("MOUSE_HINT", "underline");
org_html_manager.setup ();
/* ]]> */
</script>

(setq org-publish-project-alist
      ’(("org"
         :base-directory "~/org/"
         :publishing-directory "~/public_html"
         :section-numbers nil
         :table-of-contents nil
         :style "<link rel=stylesheet href=\"../other/mystyle.css\"
                type=\"text/css\">
                <script type=\"text/javascript\" language=\"JavaScript\"
                        src=\"org-info.js\"></script>
                <script type=\"text/javascript\" language=\"JavaScript\">
                 /* <![CDATA[ */
                    org_html_manager.setup ();
                 /* ]]> */
                </script>")))

So let's gather the tested Browsers here. Problems are only listed, if they are Browser specific. Let me say it again: we don't wont to support legacy browsers, do we?

Browser	Version
Opera	9.26
Firefox/Iceweasel	2.0.0.12
Firefox/Iceweasel	3.0.2 Beta
IE	5.5
IE	6

If you manage to get this thingy working in any browser please let us know, so we can update the above table.

Before calling

org_html_manager.setup ();

one may configure the script by using the org_html_manager's function set(key, val). There is one important rule for all of these options. If you set a string value containing single quotes, do it this way:

org_html_manager.set("key", "value with \\'single quotes\\'");

VIEW

Set to a true value to start in textinfo kind of view. Note: you could also use org_html_manager.INFO_VIEW or org_html_manager.PLAIN_VIEW. Defaults to plain view mode.

HIDE_TOC

If 1, hide the table of contents.

SUB_INDEXES

If set to a true (1 or not empty string) value, create subindexes for sections containing subsections. See sections 1 2, or 3.1 of this document. The index below the headline (under 'Contents:') is generated by the script. This one is off by default.

VIEW_BUTTONS

If true, include the small 'toggle view' link above every headline in plain view too. The visitor can toggle the view every where in the file then. If false, only at the top of the file such a link is displayed when in plain view. Default is false.

MOUSE_HINT

Highlight the heading under the mouse. This can be a background color (like '#ff0000', 'red' or 'rgb(230,230,230)') or the keyword #'underline'.

LINK_UP

May be set, to link to an other file, preferably the main index page of a subdirectory. You might consider using an absolute URL here. This link will be displayed as

<a href="LINK_UP">Up</a>

Command: 'h' - home:: This way we can link files into a tree, if all subdirectories in the project follow the same conventions. Like containing some subdir/index.org and a homepage somwhere else.

LINK_HOME

May be set, to link to an other file, preferably the main home page. You must use an absolute URL here. This link will be displayed as

<a href="LINK_HOME">Up</a>

Command: 'H' - HOME:: This way we can link files into a tree, if all subdirectories in the project follow the same conventions. Like containing some subdir/index.org and a homepage somwhere else.

TOC_DEPTH

Cut the T.O.C. at a certain level. This was done to support big big files and was requested by Carsten Dominik. If '0' or not provided at all the T.O.C. will not be cut. If set to a number greater than '0', the T.O.C. will cut to only show headlines down to that very level.

Any key to proceed

Now it's realy any key that shuts down the minibuffer.

More hardcoded styles

…to avoid a border around the input field in the minibuffer and too much padding in the minibuffers <td> elements.

Divide the script in sections

The script is now roughly devided in sections by form-feeds. Thus we can move section wise using the common emacs commands for this purpos ('M-x ]' and 'M-x ]'). This was done to ease editing of the script.

The sections are:

1. The comment block on top of the file.
2. Everything around OrgNodes.
3. org_html_manager constructor and setup.
4. org_html_manager folding and view related stuff.
5. org_html_manager history related methods.
6. org_html_manager minibuffer handling.
7. org_html_manager user input.
8. org_html_manager search functonality.
9. org_html_manager misc.
10. Global functions.

Missing shortcuts in help

'F' and 'B'.

Use two lines to be more verbose

Since the new read-mode, there are many occasions when you have to press RET to close the minibuffer. Thus we should always have a parenthesis saying 'press X to close'.

Implement the 'standard minibuffer'

A little bit more visible, two lines, a narrow gray border.

Scroll to the very top for sec. 0 in plain view mode

Scrolling the NODE.div into view seemed unnatural.

Standard height for minibuffer

This was done to hide and show the minibuffer quite correct.

Reduce flicker after reading

hideConsole() is only called, if the result of the last read command does not lead to an error. showConsole() looks, wether the the minibuffer is hidden.

• Stop searching empty strings.
• Use the local stylesheet again.

• One out of many ideas from Carsten. This one is cutomizable. Use org_html_manager.set("STARTUP_MESSAGE", "0"); to inhibit.

'L' and 'l' use the new read mode

This means we may use CTRL-c to copy the link. Close the minibuffer using RET.

'L' and 'l' choose link type

If the search string is not empty, the visitor is prompted to choose between a link to the current section or an 'occur' link.

Error in docs

Carsten Dominik schrieb:
> One more:
>
> index.html still says that "l" shows the list of shortcuts.  This is no
> longer the case.
>
> - Carsten

Absolute path to stylesheet

Avoid missing stylesheet. Now this file links to the absolute URL.

RET hides minibuffer

…in every case now.

's RET' does the same as 'S'

One of the many good ideas of Carsten.
Implementation: if the search string has not changed, 's' and 'r' move on to the next/previous section. Else the current section is searched first.

Clear the search highlight

If a new search/occur is started, the search highlight is cleared. It may still be cleared by pressing 'c' (clear).

CSS styles renamed

All the style classes and IDs in use are renamed, to avoid clashing with styles in other packages in Worg.git/code/*. All the styles are now prefixed by org-info-js_ (see CSS).

Position of minibuffer

Typo. Fixed.

Remove nested search highlight

If searching for org and after that for rg, the highlight was not removed when pressing 'c' (clear search highlight). Fixed.

Build regexp from user input

To be able to search for e.g. '>' and '<' these characters are replaced with '>' and '<' respectively. It's now possible to search for the following characters:

< > \ = ? * +

This is still a compromise since syntax highlighting is done using html tags. Thus searching for '<script' will not work for passages wehre the angle bracket has a different color than the word 'script'.

Occur mode

Press 'o' to get prompted for a string to search. The document switches to plain view mode and opens all sections containing the search string. Matches will be highlighted. Neither connected to the navigation history nor any special navigation so far. But you may walk through all the occurences using 'S' and 'R'.

URL suffix for occur

See section Section *Linking to Files using the Script for an example.

Shortcut table

Thanks to Carsten Dominik for the great org radio table trick and the new shortcut table.

This update introduced some changes concerning keyboard shortcuts.

This one is not tested in IE yet!

Search

You may use 's' to search forward and 'r' to search backwards. These two prompt for input. To repeat the last search, use 'S' and 'R' to search forward and backwards respectively. Use 'c' to remove all the match highlights.

Absolutely Beta…

goto-section

Since 's' was the candidate for searching, it could no longer be used for the goto section command. This is now remapped to 'g' (goto).

No more popups

The minibuffer can be switched to read mode. Thus it may be used to read input. No need for popup windows (window.prompt()) anymore.

New Variable org-export-section-number-format

Adjusted the script to detect the IDs correctly for use with the new OrgMode version 6.05 (the section number format can now be adjusted in OrgMode via org-export-section-number-format). This Change is backward compatible.

Display HTML links

'l' now displays a HTML link to the current section whereas 'L' now shows the OrgMode link. Thanks to Carsten for this idea.

• T.O.C. fixed accidentally

If FIXED_TOC is set, 'i' focusses the first link in the T.O.C. TAB may be used to traverse the links.

Docs where wrong

Still some outdated stuff here.

Allow overwrites

Changed the code to explicitly allow a certain URL overwrite. Otherwise visitors could overwrite any variable internally used by the org_html_manger.

URL Parsing

Now the user may call the script and pass options to overwrite the authors settings using this syntax:

 http://localhost/index.html?TOC=0&VIEW=showall&MOUSE_HINT=rgb(255,133,0)

Some links for testing are provided in section Linking to Files using the Script

Focus the T.O.C.

'i' tries to focus the T.O.C. if FIXED_TOC is ="1". This is still very primitive. Just the first step. '=i' simply focusses the first anchor in the T.O.C. Tabindexes empower the user to run through the links in the table of contents using the TAB key.

FIX: Show Start Section

The start section (index.html#sec-X.Y) was not shown in plain view mode. Now this section is always shown regardless of initial folding state and view mode.

FIX: Hitting 'u' several times

Hitting 'u' multiple times made the script focus the root node so that 'n' went to the first section. Fixed.

IE and onclick

Trying a different technique to make IE handle the clicks on headlines. Can't test this now in IE but don't want to forget the trick :)

Org Links

'l' prints an Org link in the minibuffer for copying to an org file. Currently it's only possible to copy the link using the mouse. A change of this is on my TODO list.

New key to go to the first section

Since 'i' now shows the T.O.C. there was a shortcut missing to go to the first section (which might as well be the T.O.C. if #+INFOJS_OPT: toc:t). This key is now 't' or '<'. For toggling the view mode, 'm' is used from now on.

New key for last section

'E' or '>' move to the last section.

&iquest;

To show the help screen one may use the '¿' key. The help-screen got upated using '¿' now to avoid distorted displaying of this character.

org-info-info-navigation

Style class for the navigation bar in info view mode.

Documentation

Documentation reworked. Should be fairly uptodate now.

Removal of Minibuffer

The minibuffer was not removed when unsing the mouse to navigate. Fixed.

First Section

'n' now unfolds the current section if folded when in plain view mode. Thus the first section will be shown after startup in folded view.

Startup in info view mode

This one was broken. Fixed.

OrgHtmlManager class

No more OrgHtmlManager class anymore. Script uses the

var org_html_manager = { property: value, /* ... */ };

syntax now. This was done to avoid inheritance and instantiation of more than one OrgHtmlManager.

Help display

The displaying of Keyboard shortcuts now behaves like the (hidden) TOC. I.e. keyboard shortcuts are displayed when pressing '?' and any hidden again when pressing any key. The old view mode is restored when hiding the help display.

Fixed: external links

External links now work again.

Minibuffer Handling

If the document is neither in info view mode nor displayed with a fixed TOC, the minibuffer will be shown right above the current headline. This is not the final fix for this, but a work around for the wrong IE behaviout concerning position:fixed.

Keyboard Input on keypress

The script now takes the onkeypress function to read user input. This is more compatible then onkeydown or onkeyup. Thus the keys work now in IE too (and the '?' key in Firefox). Holding the 'n' key down for a while can be used for fast searching.

Scrolling in IE

…is fixed. But it is not possible to scroll in IE if FIXED_TOC is on.

RUNS DROPPED

The option 'RUNS' is dropped now. The org_html_manager now tries to scan the document until it's entirely loaded. There is an internal limit now set to some hundred runs which will makes a max. ~2 minute scan phase.

These two changes where ideas of Carsten Dominik.

Local TOC

…shows now subsections only.

Cut the TOC

Now the table of contents may be cutted to a certain depth. Navigation is not affected. The name of the new set() option is 'TOC_DEPTH'.

Overall history

History now records all commands that change the current section.

Hide TOC but show when 'i' is pressed

The TOC is now always shown, when 'i' is pressed, even if hidden from the document. The fun is, that each following navigation command triggers a history-back event. This way the hidden TOC does not show up when moving in the history thereafter. Hence now it's possible to read section 5.1, take a short look in the TOC and the next 'n', 'p' or 'b' command takes you back to the section last visited (5.1 in this case).

Minibuffer fixed for IE

It now appears and hides again. Thanks to Tobias Prinz for the trick with negative margins.

• Adjusted to new Setup Carsten Dominik added the new possibility to configure the script using typical org syntax. Users may even use customize to set up the script now. Names of options passed to the set() functions are now adjusted to the ones we discussed. Internal variable names where changed to reflect this change.
• TODO search my mails to figure out the correct date!!!

Fixed subindexes

…when using HIDE_TOC. First section had no subindex in this case.

Added key q

…to close the window.

Internal links working

Internal links are now converted to work with this script. The user has to go back using the `=s=' key since the history is not updated. Could Browsers understand this? Or is there a possibility to catch the `/back/' button event?

org-file.html#sec-x.y.z

is now working too. That is, http://path/to/org-file.html#sec-x.y.z makes the script displaying that section in the configured view mode.

Folding now on by default.

Scrolling

'v' and 'V' now scroll the window by the visible height of the document window. A little bit less though for better orientation.

Deleted setup section using export options template

This one was not working. I'm not shure it ever was… but I think so. I should look up this one in the documentation again.

Plain view mode is default

FIXED Bugs

• The view mode was dependend on the folding feature.
• When folding was of an error was shown when trying to fold.

Clicking a headline makes it the current section

and thus the candidate for displaying in next info view and the point from where 'next' and 'previous' work.

TOC, title and global folding

The title was doubled in some cases. This should be fixed now. The TOC is now a node as all the other sections to.

Keyboard

Some more work on this. There seems to be some locale related problem concerning the keyboard input of a `?´ (help) in Firefox. Added a workaround for this one, but probably only working here.

• Documentation updated.

Stylesheet

now with indentation. This demonstrates the folding somewhat better.

Hide T.O.C.

The table of contents can now be hidden completely due to the new option HIDE_TOC. Hence the documents have to be exported with T.O.C., but may be displayed without it.

Commands reworked

The 'minibuffer' is now invisible by default. Commands can be entered into the document itself. Still, the chars entered are appended to the minibuffers contents, to keep the possibility to enter more complex commands in the future. The minibuffer is still needed for commands to work in firefox.

Section numbers are now read through window.prompt()

This was done to simplify the command interface code. Now the commands entered are just one char in length.

Global folding now working

There was not much to do left for this one to do.

Added new config options:

LINK_UP

May be set, to link to an other file, preferably the main index page. This link will be displayed as

<a href="LINK_UP">HOME</a>

Command: 'h' - home

LINK_TO_MAIN

May be set, to link to an other file, preferably the main index page. This link will be displayed as

<a href="LINK_TO_MAIN">Up</a>

Command: 'H' - HOME

This way we can link files into a tree, if all subdirectories in the project follow the same conventions. Like containing some subdir/index.org and a homepage somwhere else.

Folding.

First attempt to get the global folding working. Hmm.

New Commands

• '?' - show the little help screen.
• 'n' - go to next section.
• 'p' - go to previous section.
• 'i' - go to Index.
• 'f' - fold current section when in plain view mode.
• 'g' - fold globally when in plain view mode.
• 'u' - up to parent section.
• 't' - toggle view mode.
• 'v' - scroll down.
• 'V' - scroll up.

Radical code cleanup.

Removed unused variables and functions. More secure, less errorprone. This cood be even better.

???

Org mode like toggling of headlines now basically works.

Commands can be input through a little 'minibuffer' on top of the screen.

This needs some special style settings for IE (position fixed). I will append a minimal stylesheet for this purpos the next days in this documentation for copy and paste. This is partially working. Implemented Commands are:

• 'help' - show a little help screen. This done with alert() and thus a TODO.
• 't' - toggle view mode.
• 'k' - kill the minibuffer.
• 'N' - where N is a section number: goto section N. This could be working in both modes very easy, but currently also only in info view mode implemented.

???

Code relies now on next generation XHTML-Export format.

Some kind of rudimentary debugging system.

May be turned on bei seting config options:

org_html_manager.set("WINDOW_BORDER", "true");
org_html_manager.set("DEBUG", org_html_manager.DEBUG_FATAL);

Better way of configuration for the enduser. Fault tolerant. No undefined

variables when scanning starts. The users my use the set(key, value) function of the OrgHtmlManger class like this:

org_html_manager.set ( "LOCAL_TOC",        0);
org_html_manager.set ( "VIEW_BUTTONS", "true");
org_html_manager.set ( "FOLDING",            "true");
org_html_manager.set ( "MOUSE_HINT",         "underline");
org_html_manager.set ( "CONSOLE",            "true");
org_html_manager.setup ();

New configuration accepts these options

SUB_INDEXES

Create subindexes for sections containing sections.

INFO_SWITCH_ALWAYS

Show the small 'toggle view' link next to every Headline to toggle the view easily without scrolling back to top of the page in plain view mode.

FOLDING

This is for the new folding. Turn it on. This will be the default when the moving and toggling has an acceptable form.

MOUSE_HINT

I love this one. Accepts the keyword 'underline' or any other value. But if not 'underline', it should be a valid value to set the background-color in CSS. So preferebly something like '#eeeeee'. In plain view mode with toggle feature turned on the headline with mouse in it will be either hightlighted, if you pass a color, or underlined.

CONSOLE

Display the minibuffer on top of the screen. Turn this one on. It's fun and you can kill it simply by pressing 'k'.

VIEW

Set the initial view mode. Set to org_html_manager.PLAIN_VIEW or org_html_manager.INFO_VIEW.