#+TITLE: EMACS ORG-INFO.JS #+AUTHOR: Sebastian Rose #+STARTUP: align fold nodlcheck hidestars oddeven lognotestate #+EMAIL: #+LANGUAGE: en #+OPTIONS: d:nil #+INFOJS_OPT: path:org-info.js #+INFOJS_OPT: toc:nil ltoc:above view:info mouse:underline buttons:nil #+INFOJS_OPT: up:https://orgmode.org/worg/ #+INFOJS_OPT: home:https://orgmode.org #+HTML_HEAD: * The Name of the Game org-info-js (subsequently called /the script/) implements part of Emacs Org-mode in its 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 [[https://orgmode.org/Changes.html][org-mode site]] to display =ORGWEBPAGE/Changes.org= which consists of more than 220 sections. If you don't mind using it despite the /health warnings/ 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. Go to the next section by pressing '=n='. Find out about shortcuts in section [[#shortcuts][Shortcuts]] (and come back here pressing '=b='). In addition, '=?=' will show all shortcuts available. ** <<>> - A list of changes can be found [[file:changes.org][here]] (separate file). - Download the [[file:org-info.js][minified version]] or the [[file:org-info-src.js][source code]]. - Create the minified versions from the sources using the =Makefile= and a little sed script (see within this directory). Development of the script takes place on [[http://github.com/SebastianRose/org-info-js/tree/master][github]], but every working release is published here on Worg synchronously. That said, you can follow the development by tracking the Worg repo as well, available at [[https://git.sr.ht/~bzg/worg]]. ** Terms used throughout this Document :PROPERTIES: :CUSTOM_ID: terms :END: The script knows three different so called /view modes/. One may toggle the view mode by pressing '=m=' or click the /toggle view/ link the script adds to your pages. Currently three 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 may be (un-)folded using '=F='. You may determine what's visible on page load. + *presentation mode* :: This mode displays sections one by one as slides. Still very rustic and experimental. Rick Moynihan embarked and we plan a separate tool for presentations, but... The table of contents (*TOC*) is required, albeit it may be hidden (CSS). The TOC may be visited using '=i=' (index) regardless of its visibility. A *section* is everything with a headline. * Features :PROPERTIES: :CUSTOM_ID: features :END: ** Appearance + *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 TOC* :: The TOC can be hidden completly. Hitting '=i=' still will show it. When showing the TOC hitting '=i=' any navigation command ('=n=', '=p=', '=s='...) will trigger an history-back. Thus the TOC will not get in your way when navigating the history later on. ** Keyboard navigation + *Easy keyboard navigation* :: See Section [[#shortcuts][Shortcuts]] for a list of shortcuts. + Navigation history :: Navigating a file through the keyboard shortcuts is recorded in an internal history. You may go back and forth in this history. Once an end is reached, org-info.js tries to go back/forth in the browsers history. If you move back to a previous visited file that uses the script, you will return to the place you left the file. Thus following links in published files feels like following footnotes. + *Customizable features* :: All features are customizable simply by setting up your export options template (see [[#setup][Setup]]). + *Folding* :: Emulates the way of folding in emacs Org-mode. Mouse supported. ** Searching + *Full text-search with highlighting* :: Search forward, backwards, repeated search... (experimental). Simple regular expressions are supported. Try to search for =a[e-h].*n= for example. All searches are case insensitive. Grouping is not supported. We couldn't search for round brackets otherwise. Supported are wildcards (e.g. =.*=) and ranges (e.g. =[a-g]=). Sometimes only one match is found between two HTML tags. The longer the expression, the better the matches. + *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=. Use regular expressions likewise. + *Tags index* :: '=C=' shows a table of contents based on tags. Inherited tags are not supported yet. This was an [[http://lists.gnu.org/archive/html/emacs-orgmode/2008-07/msg00434.html][idea of Rick Moynihan]]. ** Miscellaneous + *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 TOC is a good way to get around browser detection. An option to hide the TOC 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 =

= element around the text before the first headline, available since version 0.0.7.3a (fixed in current Org-mode versions). If you export with =skip:nil=, you may add this to your stylesheet: : #text-before-first-headline {color:red;font-weight:bold;} + Hooks :: The OrgHtmlManager object provides hooks (two currently) to add custom actions. * Shortcuts :PROPERTIES: :CUSTOM_ID: shortcuts :END: 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. The script always tries to keep the last selected section visible. This is somewhat strange when scrolling, but really helpful for keyboard navigation. 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 / slides | | 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-highlight | |-----------+---------------------------------------------------------| | | *Misc* | | l / L / U | display HTML link / Org link / Plain-URL | | v / V | scroll down / up | Thanks Carsten, for this beautiful table! * Setup :PROPERTIES: :CUSTOM_ID: setup :END: This section describes how to setup your org files to use the script. [[#the-new-way][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 ([[#the-old-way][Export-Setup - the old Way]]) remains. [[#using-set][Using Set()]] contains a list of all supported options for adjusting the =org\_html\_manager= to suit your needs. See the Download section on how to obtain a version of the script. The first version of this document was created with the new XHTML 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. ** Export-Setup - the new Way :PROPERTIES: :CUSTOM_ID: the-new-way :END: The modern way of org export setup provides extra options to include and configure the script, as well as an emacs customize interface for this very 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: #+BEGIN_SRC org ,#+INFOJS_OPT: path:org-info.js ,#+INFOJS_OPT: toc:nil ltoc:t view:info mouse:underline buttons:nil ,#+INFOJS_OPT: up:https://orgmode.org/worg/ ,#+INFOJS_OPT: home:https://orgmode.org #+END_SRC *** Using customize 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 like =org-export-with-toc=. + =ltoc= :: 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 like =red= 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. If '=t=', display the little /Up|HOME|HELP|Toggle view/ links next to _each_ headline in plain view mode. *** Per File Basis: ~#+INFOJS_OPT~ A single file may overwrite the global options using a line like this: #+BEGIN_SRC org ,#+INFOJS_OPT: view:info mouse:underline up:index.html home:http://www.mydomain.tpl toc:t #+END_SRC 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=. ** Export-Setup - the old Way :PROPERTIES: :CUSTOM_ID: the-old-way :END: 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 [[#the-new-way][Export-Setup - the new Way]] of setting up the export for script usage. You might want to read the sections [[#xhtml][The XHTML]] for more information. [[#using-set][Using Set()]] contains a list of all supported options recognised by the script. *** 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): #+BEGIN_SRC org ,* COMMENT html style specifications ,# Local Variables: ,# org-export-html-style: " ,# ,# " ,# End: #+END_SRC 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. *** 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. #+BEGIN_SRC html #+END_SRC This way all your files will be exported using the script in the future. If you publish entire directories, supply an absolute URI to the =src= attribute of the first script tag above. *** 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: #+BEGIN_SRC emacs-lisp (setq org-publish-project-alist ’(("org" :base-directory "~/org/" :publishing-directory "~/public_html" :section-numbers nil :table-of-contents nil :style " "))) #+END_SRC Don't forget to add an export target for the script itself ;-) * Linking to Files using the Script :PROPERTIES: :CUSTOM_ID: linking :END: 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][Using set()]] for a list). #+BEGIN_HTML

#+END_HTML *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. * CSS :PROPERTIES: :CUSTOM_ID: css :END: Here is an excerpt from the stylesheet for this file. Be carful not to mess things up when trying to position the console. #+BEGIN_SRC css /* Styles for org-info.js */ .org-info-js_info-navigation { border-style:none; } #org-info-js_console { color:#333333; margin:0px; background-color:#ffffff; } #org-info-js_console-input { background-color:#ffffff; border-style:none; color:#333333; padding-left:10px; vertical-align:middle; } #org-info-js_console-label { font-size:11px; font-weight:bold; padding-left:10px; font-family:Verdana,Arial,sans-serif; vertical-align:middle; } .org-info-js_console-label-warning { color:#cc0000; } #org-info-js_console-container { border:1px solid #cccccc; } .org-info-js_search-highlight { background-color:#adefef; /* emacs default */ color:#000000; font-weight:bold; } /* END STYLES FOR org-info.js */ #+END_SRC * Supported Browsers The functionality of the script is based on =DOM=. This leads to some incompatibility with legacy browsers. But hey, it's 2009, 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 try to test the script before each release in Firefox 3.x.x and Opera 10 on Linux, and in FF 3, IE 6 and Safari on windows. Because of the number of features and browsers, some bugs might remain undiscovered. Please report bugs to the emacs-orgmode mailing list. In most cases we manage to fix them within the next 24 hours. ** <> 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. * Why Do I Need a T.O.C? Currently the script depends on the table of contents in the resulting XHTML. The TOC 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 TOC might be loaded when this function is called. Hence it should work for slow connections too. * The XHTML :PROPERTIES: :CUSTOM_ID: xhtml :END: 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][Using Set()]]. This is what the head section should look like: #+BEGIN_SRC html #+END_SRC To just use the script with the defaults put this into the head section of the XHTML files: #+BEGIN_SRC html #+END_SRC I recommend the use of #+BEGIN_SRC html #+END_SRC instead of #+BEGIN_SRC html #+end_src *Make sure to remove hook functions at the end of the hook*. Strange things could happen otherwise (the hook loop will overlook a member. While the hook loop runs in first hook first, the remove loop removes the last hook first). * How it works First of all the script is included in the header as described in [[#setup][Setup]]. The document has to be exported with TOC 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 [[#setup][Setup]]), sets up a timeout function calling its =init()= function after 50ms. After those 50 ms The =init()= function starts its first attempt to scan the document, using the TOC 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 TOC) 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 long ago, but the accesskeys will stay cause there is no reason to remove them. * Presentations with org-info.js 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