EMACS ORG-INFO.JS

Table of Contents

1 The Name of the Game

First of all: Press `?´ for a list of available shortcuts.

The aim of this little script is to implement a part of emacs facilities of folding in the HTML-exported files.

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. Two or three weeks ago 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) . It will for shure not work in all browsers. Espacially elder ones since it relies entierly on DOM. There is no browser selector included and no sofisticated event handling due to my small JavaScript™ knowledge. But I already love it and use it locally for all of my notes and documentations written with org-mode.

There are no external dependencies though. 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.

Just in case you see this document split into section with a navigation bar on top:

Try it. Click on the small 'toggle view' link on the top right of the headline. A lot to scroll, right? But still seeing this section after clicking the link? Click the same link againg please. Still here and navigation bar back again? If so, drop me a mail and tell me your browser and its version so we can put it on list of supported browsers (sorry - internal links are on the TODO list).

BTW: you can activate the links using accesskeys. 'n' for 'next', 'p' for previous section, 't' to toggle the view, and 'i' to go to the index.

1.1 The HTML File

To produce this HTML file I used a new version of the org HTML export. The structure of the exported XHTML will change a little bit in the future to support scripting an other tools that work on XML. Carsten Dominik found the time to modify the current export modul to produce the draft version of the next generation XHTML.

To use this script and the new XHTML structure check out the git head from this location:

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

The current version of this script will not work with the XHTML export as delivered with the current org-mode package anymore. I'm afraid there are good chances the new exporter is done before this thing here enters a usefull state :-)

2 How it works

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?). This could change in the future because of the better structured export.

When included, it creates a global JavaScript™ variable named org_html_manager, which is an instance of the class OrgHtmlManager. The class is meant as a singleton but there are no precautions for avoiding the creation of an other instance. No one would need to create a new instance anyway.

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).

The number of attempts to scan the the document is limited to 5 runs. You can change that value by editing the script or, better, adding this line to your header before calling setup(): 

org_html_manager.set("MAX_RUNS", 10);
But 5 runs will do for realy big files and a medium fast connection.

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).

2.1 Features so far

  • Toggle plain and info view
    One can klick 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.
  • Easy keyboard navigation
    See Section Visitor's Navigation for a list of shortcuts.
  • Accesskeys
    The navigation links can be activated by the accesskey feature of current browsers. In Opera you have to press SHIFT+ESC before pressing the actual accesskey, in Firefox the Prefix is ???…. Icedove version 2.0.0.12 does not react on accesskeys. This is a known bug and fixed in the new version. Refer to the documentation of your browser for information on how to use accesskeys. The keys are
    • n next page
    • p previous page
    • t toggle view mode
    • i return to the index (T.O.C)
  • Structure is taken from export preferences
    This is currently only true when exporting with a table of contents. When exported with T.O.C., 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. by script will be added soon.
  • 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 fell and a better orientaton. Can be turned of (see Usage).
  • 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 at the beginning of the document when in plain view mode. The info view mode displays the link on every page.
  • Numbered pages
    In info view mode every page gets a page number starting from one which is the T.O.C.'s page.
  • Markright alike headings
    Also 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).
  • Customizable features
    All features are customizable simply by setting up your export options template (see Usage – an internal link that does not work).
  • Tooltips
    Moving the mouse on the navigation links show a tooltip with name of next/previous section.
  • Folding
    Emulates the way of folding in emacs org-mode.
  • Inter-linking
    The exported pages can be linked to the homepage and an directory index or some other sort of parent file.
  • Hide T.O.C.
    The T.O.C. can be hidden completly.

3 Why Do I Need a T.O.C?

Currently the script depends on the table of contents in the resulting HTML. 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 :)

4 Usage

The script has to be included in the header of the resulting HTML files. The document has to be export with T.O.C. since the script depends on it. You may pass options to the org_html_manager by utilising it's set() method. This is the code I used to set up this file: 

<script type="text/javascript" language="JavaScript" src="org-info.js"></script>
<script type="text/javascript" language="JavaScript">
/* <![CDATA[ */
org_html_manager.set("SUB_INDEXES", 1);
org_html_manager.set("HIDE_TOC", 1);
org_html_manager.set("INFO_SWITCH_ALWAYS", "true");
org_html_manager.set("FOLDING", "true");
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" language="JavaScript" src="org-info.js"></script>
<script type="text/javascript" language="JavaScript">
/* <![CDATA[ */
org_html_manager.setup ();
/* ]]> */
</script>

I recommend the use of 

<script type="text/javascript" language="JavaScript" src="org-info.js"></script>
instead of 
<script type="text/javascript" language="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.

4.1 Using Set()

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.
  • 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.
  • INFO_SWITCH_ALWAYS
    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.
  • MOUSE_HINT
    Highlight the heading under the mouse. This can be a background color (like '#ff0000' or 'red') or the keyword 'underline'.
  • LINK_UP
    May be set, to link to an other file, preferably the main index page of a subdirectory. You must use 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_TO_MAIN
    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_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.
  • MAX_RUNS
    Maximum attempts to scan the file. Defaults to 5 which more than enough usually.
  • DEBUG
    Turn on debugging. This will pop up annoying alerts all over the place.

4.2 Export-Setup

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

4.2.1 Using org-insert-export-options-template

M-x org-insert-export-options-template
at the start of your org-file will insert, bet you know, this text: 
#+TITLE:     fancy-file.org
#+AUTHOR:    Your Name
#+EMAIL:     author@thinktank.tld
#+LANGUAGE:  de
#+TEXT:      Some descriptive text to be emitted.  Several lines OK.
#+OPTIONS:   H:3 num:t toc:t \n:nil @:t ::t |:t ...
Add this (in one line??): 
#+STYLE: <script type=\"text/javascript\" language=\"JavaScript\" src="org-info.js\" />
<script type="text/javascript" language="JavaScript">/* <![CDATA[ */
org_html_manager.setup ();/* ]]> */</script>
In this case I just include the script and drop the options to keep this line short. The next section will show how to pass startup options to script.

4.2.2 Using a special * COMMENT Section

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\" language=\"JavaScript\" src=\"org-info.js\">
# </script>
# <script type=\"text/javascript\" language=\"JavaScript\">
#  /* <![CDATA[ */
#    org_html_manager.set(\"SUB_INDEXES\", 1);
#    org_html_manager.set(\"INFO_SWITCH_ALWAYS\", \"true\");
#    org_html_manager.set(\"FOLDING\", \"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.

4.2.3 Using customize

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 =\"text/javascript\" language=\"JavaScript\" src=\"org-info.js\"></script>
<script type=\"text/javascript\" language=\"JavaScript\">
/* <![CDATA[ */
org_html_manager.set(\"SUB_INDEXES\", 1);
org_html_manager.set(\"INFO_SWITCH_ALWAYS\", \"true\");
org_html_manager.set(\"FOLDING\", \"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.

4.2.4 Export-Setup per Project

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\" language=\"JavaScript\"
                        src=\"org-info.js\"></script>
                <script type=\"text/javascript\" language=\"JavaScript\">
                 /* <![CDATA[ */
                    org_html_manager.setup ();
                 /* ]]> */
                </script>")))

Don't forget to add an export target for the script itself ;-)

5 Visitor's Navigation

Once the script is included, the visitor of the resulting HTML file may use the mouse or the following keys to navigate the page:

KeyActionInfoPlain
nnext sectionyy
pprevious sectionyy
igoto T.O.C.yy
uone level up (parent section)yy
sprompt for section numberyy
ttoggle view modeyy
vscroll by 200 pxyy
Vscroll back 200 pxyy
?show shortcutsyy
hfollow the link 'UP'yy
Hfollow the link 'HOME'yy
ffold current sectiony
gfold globalyy

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

6 Supported Browsers

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

I have written and tested the script only in current Firefox and Opera so far (lack of spare time, operation systems on my laptop, and installed browsers). The test results will go in the next section.

6.1 People reported it works in

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?

BrowserVersion✔Problems
Opera9.26✔-
Iceweasel2.0.0.12✔-

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

7 Bugs and TODOs

7.1 TODO 'toggle view' and Opera

The 'toggle view' link next to the title does not work after toggling from info view mode to plain view mode. The link has to be hidden and shown again to make this work.

The link disappears when folding.

7.2 DONE Previous/Next instead of Next/Previous

CLOSED: 2008-03-22 Sa 19:07

7.3 DONE Parse URLs vor 'HOME' 'Up', and more

CLOSED: 2008-03-21 Fr 23:53

Done for absolute URLs. I think it rarely makes sense to compare the URL of the current page with relative ones, since every subdirectory might contain a file named index.html.

TODO was:

The script needs to parse the URL of the current page itself to detect, if the 'Up' or 'HOME' lins point to the page itself. This is neccessary to avoid linking.

7.4 DONE Goto Section 4.2.1 is broken

Fixed.

7.5 TODO Move the Footnots into own <div>

Footnotes are in the last container element. This is syntactically wrong, since Footnotes for all Sections go into the last parargraps container.

7.6 DONE [#A] Use Precompiled Regexps for getKey()

CLOSED: 2008-03-21 Fr 17:11

Moved regular expressions for triming of commands to the constructor.

TODO was:

Currently the regular expressions in OrgHtmlManager::getKey() have to be evaluated for each and every keypress. We should precompile them by defining in the constructor or, better, setup if CONSOLE is requested.

7.7 DONE [#A] Scroll to View when Changing the View Mode

Console is not visible by default anymore.

TODO was:

When changing the view mode from info to plain and the console is on, the current item is not visible. Hence we must scroll by 40px or so. The title is only half visible either. Maybe put the console to the bottom of the window. We could use a <div> element with 100% height and verticle align bottom to work around differences of browsers. It wont overlap other clickable things if only 1px wide ;-)

7.8 TODO Bug when sections use h1 headlines (??)

Script will not start properly, when sections use h1 headline.

Please test. Could be solved by code cleanup on 2008-03-11 Di.

7.9 TODO Remove subindexes in plain view mode

…to get a really plain view.

7.10 TODO Document without T.O.C

See section Why Do I Need a T.O.C? for the reasons.

So why not depend on TOC and add an option to hide it, show it or append it.

  • Hide TOC
    Would not show the T.O.C. at all.
  • Show T.O.C.
    would show the T.O.C. at the beginning of the document.
  • Append T.O.C.
    Start the document with contents of section 1 (which should be text before first headline if present) and append the T.O.C. at the end.

7.11 TODO [#B] Text before first Headline

Text before first headline will show up on all pages above the navigation (not visible in info view though since we scroll the window to the navigation bar when in info view mode). Some will like that, most will say what I say: it's a bug. Pardon me.

The best solution for this IMHO would be:

  1. Turn the index into a normal OrgNode
  2. Put the text before first headline into an OrgNode too.
  3. Display text before firste headline as the first page in 'info view mode' and append the TOC at the end of the document.

7.12 TODO Internal Links

Internal links are not converted. So they do not work while in info view mode. Even worth: the document could become invisible when activating internal links while in info view mode.

This will force the parser to scan all links inside the document. But - so what? It just HAS to be done.

Actually they are not working in plain view mode either. The new toggling feature is working. What about that?

7.13 TODO [#B] Assign Style Classes to navigational Elements

The navigation elements used should have distinct style class names so their appearance can be customized by the user. Currently they have no style classes but hard coded properties.

7.14 TODO [#B] Add NEVER option to org_js_infoswitch

Add the possibility to NEVER show a toggeling link. The document would then be viewable either in info view mode XOR in plain view mode. This would also disable the 't' command.

7.15 TODO Create Testfiles for all Combinations of relevant Options

A nice thing to have. We need tests for the different settings of export options concerning scripts like this one usable for other scripts too. Here is a list of options in question and theire shorthands in the #+OPTIONS: line. Some of them are not tested at all:

ShorthandWhat it does
H:Level of headslines
toc:T.O.C.
@:Turn on HTML-Tags (think of headlines containing HTML)
f:Footnotes
skip:Text before first headline

Text before first headline is currently displayed on each and every page in info view mode. Footnotes are not tested at all. HTML-Tags should be no problem.

7.16 DONE Add global Folding

CLOSED: 2008-03-21 Fr 22:32

7.17 DONE Add an Debug Option

CLOSED: 2008-03-11 Di 23:01
See Changelog of 2008-03-11.

TODO was:

Currently I still use comments to turn debugging output on/off :)

7.18 DONE Add the Folding Feature

CLOSED: 2008-03-11 Di 20:02
See Changelog of 2008-03-11.

TODO was:

This is not done yet. Maybe create a second script implementing folding only? One will have to decide between folding and toggling between these two view modes anyway.

7.19 DONE Enhance the Startup

CLOSED: 2008-03-09 So 17:23

Fixed for export with T.O.C.:

No try / catch / finaly any more. The OrgHtmlManager now simply stops scanning when it can not find a element mentioned in table of contents. Scanned elements are marked to avoid scanning them a second time. The next scan starts 50 milliseconds later. If all elements mentioned in TOC are successfully scanned, the interval function is removed from the window object and the view gets initialised.

TODO was:

Currently the org_html_manager stops scanning when finding an item that is null by throwing an exeption. Then the it get's destroyed and is created again. The new object starts, after 50 ms timeout, to scan the document allover again. This is risky and could be optimized.

  • It's risky, because any one who does not know that could introduce bugs that are not easy to find. It's risky, because the OrgHtmlManager instance changes the T.O.C. and the new created object would not find the expected content there.
  • It could be optimized by stopping the existing OrgHtmlManager instance and wake it up again after the timeout instead. The instance would save the last valid state while being idle and waiting for the documents contents to be created. This could speed up everythink even more (for really big files).

The repeated scanning is neccessary to avoid browser detection. As an example Opera says that if(window.document) is true, even if not the whole thing is loaded yet (but we ask this question anyway. Firefox handles this point as expected, as so some other browsers, thus scanning only once).

8 ChangeLog

8.1 2008-03-22 Sa

  • 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.

8.2 2008-03-21 Fr

  • 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.

8.3 2008-03-13 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.

8.4 2008-03-12 Mi

  • 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.

8.5 2008-03-11 Di

  • 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 HTML-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 ( "SUB_INDEXES",        0);
org_html_manager.set ( "INFO_SWITCH_ALWAYS", "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.

    Note: not all options are documented here. These are the ones for endusers. Developers! Look in the constructor function OrgHtmlManger () and OrgHtmlManager.set(). It's really stupid and easy to understand.

9 Related Ideas

9.1 Ajax and Paging of huge Articles

Write a similar script that strips all the surrounding body and puts all the contents in one big <div>. The document would be pageable like it is now. Links in the content could be loaded dynamically into the same <div> (Ajax). That way org files could serve as in-page website content and the paging feature would be realy nice for big articles. No reload of sidebars or header.

This way an article or tutorial could be spread over several files even. The deployment of those files is easy manageble through the already existing export infrastructure.

10 Ideas

Ideas concerning org-mode in general.

10.1 Automatically Change the Content of TODO items

1.) When switching a TODO item to the state STARTED automatically add an 'assigned to' entry to the entry. In the example below I added a tag ':USERNAME:' to accomplish this but I could think of better ways. Maybe an extra line like
ASSIGNED: USER TIMESTAMP
So no fiddling with the tags code.

2.) When switching a TODO item to the state DONE automatically insert a paragraph FIXES to be filled with some ChangeLog message (something for CONTRIB?).

This is what I mean:

  • Before:
    • TODO Adding ChangeLogs to TODOs    FEATURE

      Adding ChangeLog-like entries to TODO items when setting them to DONE.

  • After changing the state to STARTED
    • STARTED Adding ChangeLogs to TODOs    FEATURE USER_NAME
      CLOCK: 2008-03-09 So 15:13--

      Adding ChangeLog-like entries to TODO items when setting them to DONE.

  • After changing the state to DONE
    • DONE Adding ChangeLogs to TODOs    FEATURE USER_NAME
      CLOSED: 2008-03-09 So 17:50
      CLOCK: 2008-03-09 So 15:13– 2008-03-09 So 17:23 => 2:10
      • ChangeLog
        Done by adding to Headlines inside the TODO entry. The headlines are directly below the headline-level of the TODO item itself or below the level of org-export-headline-levels if higher.

        If org-ask-for-changelog-other-window is not nil offer input in other window.

      • Description
        Adding ChangeLog-like entries to TODO items when setting them to DONE.

10.2 Sparse Tree from ChangeLog

If we had the feature from the previous section we could have a function org-sparse-tree-changelog to just show the ChangeLog. We could also have a function org-write-changelog to prepend the current ChangeLog entry (or all if prefix) to a file (_MTN/log, ChangeLog or what ever).

10.3 Export-Option to Export CLOCK:

When trying to create the example in last section I found it difficult to include the :CLOCK line. Why can't I export it?

11 Thanks

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.

12 License

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.

13 END

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.

Author: Sebastian Rose <sebastian_rose@gmx.de>

Date: 2008/03/23 01:21:40