An attempt to build org-mode for vim orgmode.

Information about the license are found in the file LICENSE

Add the following lines to your .vimrc file to ensure that filetype plugins are loaded properly:

filetype on filetype plugin on filetype indent on

Please install the Universal Text Linking addon, otherwise hyperlinks will not be usable.

If you want to install the vim-orgmode plugin for a single user, this is the preferred way.

Open the file in vim and source it. Restart vim and the plugin is active:

vim orgmode.vba.gz :so %

If you want to install the plugin into a specific directory, e.g. when you are using pathogen, then just add the desired directory to the runtimepath before sourcing the vba-file.

vim orgmode.vba.gz :set rtp=$HOME/.vim/bundle/orgmode,&rtp :so %

If you want to install the vim-orgmode plugin for all users of your computer, this is the preferred way.

Install the plugin by using the Debian Package Manager:

dpkg -i vim-orgmode.deb

The plugin is installed in /usr/lib/vim/addons. Please make sure this directory part of your runtimepath. By default it’s not! Add the following command to your .vimrc to add the path on startup:

:set rtp=/usr/lib/vim/addons,&rtp

This method is mainly used for development purposes. It’s rather a stoney

Copy the directories ftdetect, ftplugin, indent and syntax to your $HOME/.vim directory or the bundle directory in case you are using pathogen.

vim-orgmode aims to be clone of the original orgmode for Emacs. Since Emacs is not vim the clone is not aiming for 100% compatibility. Especially in terms of the keybindings there will be major differences!

You’ll definitively enjoy the modal interface, this where vim’s strength is. Almost all keybindings for orgmode work only in normal and visual mode where as in insert mode just a few are available.

To start vim-orgmode open a file with the extension .org. An additional menu “Org” is shown that gives an overview of the implemented functionality and the keybindings.

Vim offers a mighty feature called text-objects. A text-object is bound to a certain character sequence that can be used in combination with all kinds of editing and selection tasks. vim-orgmode offers the following text-objects:

ih - inner heading, referring to the current heading excluding the heading level characters (*) ah - a heading, referring to the current heading including everything it - inner subtree, starting with the current heading at - a subtree, starting with the current heading Oh - inner outer heading, referring to the parent Ot - inner outer heading, including subtree, referring to the parent OH - a outer heading OT - a outer subtree

Movement commands can also be used for editing like text-objects:

g{ - execute command from current position to the beginning of the parent heading { - execute command from current position to the beginning of the current heading } - execute command from current position to the end of the current heading <a href=” - execute command from current position to the beginning of the previous heading sibling “> - execute command from current position to the beginning of the previous heading sibling - execute command from current position to the end of the next heading sibling

For further information please read :h text-objects-changed

• pathogen for an easy management of multiple plugins.
• repeat to repeat some actions that would not be repeatable otherwise.
• taglist to get an structural overview over files.
• speeddating to in-/decrease dates the vim way: (C-a) C-x.
• Narrow Region to have emacs Narrow Region feature.
• Universal Text Linking to have ‘clickable’ links to other resources (files, urls, etc.).

Vimball is an archive format for vim plugins. It’s of use when you want to install vim-orgmode for a single user. To build a Vimball just run the following command in the root folder of this plugin. Please make sure that vim is installed on your computer:

make vba

For installing the plugin form the resulting orgmode.vba.gz file, please refer to the Installation section.

A Debian package is of use when you want to make vim-orgmode available to all users on your computer. Make sure you’ve debhelper and vim installed, than run the following command from the root directory of this plugin to build the package:

fakeroot ./debian/rules clean binary

For installing the plugin form the resulting vim-orgmode.deb file, please refer to the Installation section.

build_vim - Build file for the Vimball ftdetect/ - Filetype detection for orgmode files ftplugin/ - Home of the main part of the plugin ftplugin/orgmode/ - Home for all Python code related to the plugin ftplugin/orgmode/plugins - Home for all orgmode plugins indent/ - Indentation for orgmode files LICENSE - License Information Makefile - Build file for the Vimball README - This file syntax/ - Syntax highlighting test/ - Tests to verify the consistency and correctness of the plugin

The majority of the source code is stored in folder ftplugin/orgmode. This is where the actual functionality of the plugin is located.

I choose to implement vim-orgmode mainly in Python. I hope this will ease the implementation especially with the functionality of the Python standard library at hand.

Right below the directory ftplugin/orgmode the basic implementation of vim-orgmode is found. This basic functionality provides everything for higher level implementations that modify the buffer, provide a menu and keybindings to the user and everything else that is needed.

Below the directory ftplugin/orgmode/plugins the plugins are located. Every plugin must provide a class equal to its filename with the .py-extension. An example for a plugin can be found in file ftplugin/orgmode/plugins/Example.py.

Every plugin must be enabled by the user by setting the g:org_plugins variable. By default all shipped plugins are enabled. Example:

let g:org_plugins = [‘ShowHide’, ‘|’, ‘Navigator’, ‘EditStructure’]

To write a plugin:

1. copy file ftplugin/orgmode/plugins/Example.py to ftplugin/orgmode/plugins/YourPlugin.py
2. Change class name to “YourPlugin”
3. Set the menu name, it doesn’t need to match the filename anymore, e.g. “Your Plugin”
4. Prepare keybindings in function register by defining a proper action and a key this action should be mapped to. For further information refer to section Keybindings.
5. Register your plugin: let g:org_plugins = [‘ShowHide’, ‘|’, ‘Navigator’, ‘EditStructure’, ‘YourPlugin’]
6. Implement YourPlugin

Keybindings alias mappings are described very well in the vim documentation, see |map-modes|. vim-orgmode tries to make it easy for the developer to register new keybindings, make them customizable and provide menu entries so that the user can access the functionality like in original orgmode.

This is done by providing three classes: Keybinding, Plug and ActionEntry

This is the basic class that encapsulates a single keybinding consisting of a key/mapping and an action. Several options can be set when creating the object to specify the mode and all kinds of other things.

If a Plug is given instead of an action string the Plug is bound to the key. All relevant data is read from the Plug, e.g. name, mode aso.

Map g{ to moving to parent heading in normal mode:

Keybinding(‘g{‘, ‘:py ORGMODE.plugins[“Navigator”].parent(mode=”normal”)<CR>’, mode=MODE_NORMAL) vim -> :nmap g{ :py ORGMODE.plugins[“Navigator”].parent(mode=”normal”)<CR>

Map g{ to moving to parent heading in normal mode by using a Plug:

Keybinding(‘g{‘, Plug(‘OrgJumpToParentNormal’, ‘:py ORGMODE.plugins[“Navigator”].parent(mode=”normal”)<CR>’)) vim -> :nnoremap <Plug>OrgJumpToParentNormal :py ORGMODE.plugins[“Navigator”].parent(mode=”normal”)<CR> vim -> :nmap g{ <Plug>OrgJumpToParentNormal

A Plug is a unique keybinding that can not be executed by pressing any key. This makes it a special Keybinding that takes a name and an action to create an object. A plug normally goes together with a regular Keybinding to bind the Plug to a key.

This special behavior is needed to ensure that keybindings are customizable by the user. If the user creates a keybinding to a Plug the Keybinding object makes sure that the users keybinding is used and the keybinding specified by the plugin is not used.

Map g{ to moving to parent heading in normal mode by using a Plug:

Keybinding(‘g{‘, Plug(‘OrgJumpToParentNormal’, ‘:py ORGMODE.plugins[“Navigator”].parent(mode=”normal”)<CR>’)) vim -> :nnoremap <Plug>OrgJumpToParentNormal :py ORGMODE.plugins[“Navigator”].parent(mode=”normal”)<CR> vim -> :nmap g{ <Plug>OrgJumpToParentNormal

An ActionEntry makes Keybindings accessible by the vim menu. It takes a description and a Keybinding object and builds a menu entry from this. The resulting object can be added to a Submenu object by using the + operator.

Map g{ to moving to parent heading in normal mode by using a Plug:

k = Keybinding(‘g{‘, Plug(‘OrgJumpToParentNormal’, ‘:py ORGMODE.plugins[“Navigator”].parent(mode=”normal”)<CR>’)) vim -> :nnoremap <Plug>OrgJumpToParentNormal :py ORGMODE.plugins[“Navigator”].parent(mode=”normal”)<CR> vim -> :nmap g{ <Plug>OrgJumpToParentNormal

menu + ActionEntry(‘&Up’, k) vim -> :nmenu &Org.&Naviagte Headings.&Up<Tab>g{ <Plug>OrgJumpToParentNormal

Emacs toggles the todo state for the corresponding heading when the cursor is in the description text of the heading. vim-orgmode does not do that yet.

Tests for tags have been implemented in test_vimbuffer.py

I’m not quite sure whether this is actually need in liborgmode or should be part of a specific plugin

This is strongly linked to the changing of a heading’s level. There needs to be an easy way to do that

I think of something general like asciidoc

It should consist of a Document class implementing access to the current vim buffer or just a normal file. The Document also contains subdocuments and Headings. This would loosen the dependency to vim.

the goal is to automatically generate most parts of the documentation

tagbar is a reimplementation of the taglist plugin

Resolved by the implementation of liborgmode

actually I think there is not very much that needs to be integrated - it just works

actually I think there is not very much that needs to be integrated - it just works

vi: ft=org:tw=72