WARNING This documentation is likely to be out of date.
org-info-js (subsequently called the script) implements part of Emacs Org-mode in it’s XHTML-exported files, allowing them to be rendered and browsed in a linuxdoc/texinfo style.
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 and the script is small
and fast, even for large files. It is used on the org-mode site to
display ORGWEBPAGE/Changes.org
which has over 220.
If you don’t mind using it despite the health warnings and adjusting your org export options occaisionally we wish you good luck and hope the fun will outweigh your effort.
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.
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 ’F
’. - presentation mode
- This mode displays sections one by as slides. Still very rustic and experimental. Rick Moynihan embarked and we plan a separat tool for presentations.
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 view, info view and presentation
- 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 `m´) you can switch between info and plain view mode. The presentation mode is very rudimentary and just a quick hack realy. Press ‘x’ to see it.
- 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 and more.
- 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
- Tags index
-
’
C
’ shows a table of contents based on tags. Inherited tags are not supported yet. This was an idea of Rick Moynihan.
- 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. - Startup information
- Show a little message on page load to tell the visitor about the script usage.
- Wrap text before first headline
-
This is a temporary fix for the
missing
<p>
element around the text before the first headline, available since version 0.0.7.3a. If you export withskip:nil
, you may add this to your stylesheet: :#text-before-first-headline {color:red;font-weight:bold;}
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.
Key | Function |
---|---|
? / ¿ | show this help screen |
Moving around | |
n / p | goto the next / previous section |
N / P | goto the next / previous sibling |
t / E | goto the first / last section |
g | goto section… |
u | go one level up (parent section) |
i / C | show table of contents / tags index |
b / B | go back to last / forward to next visited section. |
h / H | go to main index in this directory / link HOME page |
View | |
m / x | toggle the view mode between info and plain / presentation |
f / F | fold current section / whole document (plain view only) |
Searching | |
s / r | search forward / backward.... |
S / R | search again forward / backward |
o | occur-mode |
c | clear search highlights |
Misc | |
l / L | display HTML link / Org link |
v / V | scroll down / up |
Thanks Carsten, for this beautifull table!
This section describes how to setup your org files to use the
script. Export-Setup - the new Way covers setting up org XHTML
export with Org-mode version >= 6.02. For those using an older
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 reasonably recent org version is available for download on orgmode.org whilst the latest version of the script is in the git repo:
:git-clone git://github.com/SebastianRose/org-info-js.git
This script will not work with the XHTML exporter that comes with Org-mode in Emacs 22.x.
The current version of Org-mode was used to produce this XHTML file
with the new exporter which was revised by Carsten Dominik in March
2008 (in Org-mode v5.23a+) to better support XML
. You can use
M-x org-version
to see which version of Org-mode you have
installed.
The new XHTML structure won’t break any of your stylesheets.
org-info-js now supports the standard Org-mode methods for exporting XHTML, and including extra data in the head of the exported 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
To use customize type
:M-x customize-group RET org-export-html RET
scroll to the bottom and click Org Export HTML INFOJS
.
On this page three main options may be configured. Org Export Html Use Infojs is very good documented and Org Infojs Template should be perfect by default. So I’ll concentrate on Org Infojs Options here.
path
-
Absolute or relative URL to the script as used in in XHTML
links. ’
org-info.js
’ will find the file in the current directory. Keep in mind that this will be the directory of the exported file, eventually a directory on a server. view
-
What kind of view mode should the script enter on startup? Possible
values are
info
— info view mode,overview
— plain view mode, only first level headlines visible,content
— plain view mode, all headlines visible,showall
— plain view mode showing the entire document.
toc
-
Show the table of contents?
Possible values:t
— show the toc,nil
— hide the toc (only show when ’i
’ is pressed),Publishing/Export property
— derivate this setting from another property likeorg-export-with-toc
.
localtoc
-
Should the script insert a local table of contents below the headings
of sections containing subsections? The default is no.
Possible values:t
— show the local toc below the first text in a section,nil
— hide the toc (only show when ’i
’ is pressed). This is the default, if this option is omitted.above
— sho the toc directly under the sections heading.
mouse
-
Highlight the headline under the mouse in plain view mode?
underline
— underline the headline under mouse,#dddddd
— or any valid XHTML/CSS color value likered
to draw a colored background for the headline under the mouse.
runs
-
Obsolete.
Number of attempts to scan the document. It’s no risk to set this to a
higher value than the default. The
org_html_manager
will stop as soon as the entire document is scanned. buttons
- Affects plain view mode only.
A single file may overwrite the global options using a line like this:
#+INFOJS_OPT: view:info mouse:underline up:index.html home:http://www.mydomain.tpl toc:t
Possible options are the same as in the previous section. Additional (?) options include:
home
-
An URL to link to the homepage. The text displayed is
HOME
. up
-
An URL pointing to some main page. The text displayed is
Up
.
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.
The second possibility to include the script is to add a special section to the end of your org file (multiple lines possible):
* COMMENT html style specifications
# Local Variables:
# org-export-html-style: "<link rel=\"stylesheet\"
# type=\"text/css\" href=\"styles.css\" />
# <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(\"VIEW_BUTTONS\", \"true\");
# org_html_manager.set(\"MOUSE_HINT\", \"underline\");
# org_html_manager.setup ();
# /* ]]> */
# </script>"
# End:
Ensure to precede all the verbatim double quotes with a backslash and
include the whole value of org-export-html-style
into double quotes
itself.
One could customize the option ’org-export-html-style
’ globaly by
:M-x cuomize-variable RET org-export-html-style RET
and set it there.
<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("VIEW_BUTTONS", "true");
org_html_manager.set("MOUSE_HINT", "underline");
org_html_manager.setup ();
/* ]]> */
</script>
This way all your files will be exported using the script in the future.
Last but not least and very handy is the possibility to setup the usage of the script per project. This is a taylor made passage of the org manual:
(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\" src=\"org-info.js\"></script>
<script type=\"text/javascript\">
/* <![CDATA[ */
org_html_manager.setup ();
/* ]]> */
</script>")))
Don’t forget to add an export target for the script itself ;-)
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 don’t know for
sure. 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.
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.
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>
instead of
<script type="text/javascript" src="org-info.js" />
which is valid XHTML but not understood by all browsers. I’ll use the first version throughout this document where ever the space allows to do so.
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
,org\_html\_manager.PRESENTATION\_VIEW
ororg\_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. Iffalse
, only at the top of the file such a link is displayed when in plain view. Default isfalse
. 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 somesubdir/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 somesubdir/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. HELP
-
Display a little message on page load? Defaults to no message. Set to
1
to display the startup message.
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 Org-mode 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.