An attempt to build org-mode for vim orgmode.

Information about the license are found in the file LICENSE

Installation

Prerequisites

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.

From .vba file

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 %

Installation into a specific directory

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 %

From .deb file

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

From git checkout

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.

Usage

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.

Text objects

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

Suggested plugins

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

Development

Building a Vimball

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.

Building a Debian Package

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.

Source code

Files and folders

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

Structure

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’]

Writing a plugin

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

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

Keybinding

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.

Example

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

Plug

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.

Example

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

ActionEntry

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.

Example

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

Todos

Todo/Done plugin

implement keyboard shortcuts to select todo state

implement switching to next/previous todo state list

implement todo state triggers

implement tests for toggle_todo_state

toggle_todo does not work when the cursor is in text (not heading)

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.

implement multi-state workflows

implement todo items

ShowHide plugin

implement keybindings to in/decrease foldlevel

make fast access keys for different fold levels customizable

implement fast access keys for different fold levels

implement count for toggle folding

implement tests for toggle_folding

implement show/hide plugin

implement TAB to cycle folding

implement |fold-foldtext|

Navigator plugin

implement other paragraph and block text-object operators, e.g. dap, cip, dab, cib

implement tests for ]]

implement mappings for visual and operator mode in a better way

implement count for navigator mappings in visual mode

implement sparse tree. is a special folding needed?

impelement repeat for text-object operators

implement section wise movement (skip children) by ]]

implement omap

change } mapping to ]] - canceled

implement navigator mappings for visual mode

bug in function g{, it places the cursor one character too far to the right

EditStructure plugin

implement tests for move heading

implement tests for indenting a single heading

indentation with C-t,C-d doesn’t work when not on a heading

implement non-relative heading changes

implement a closer behavior of M-RET to orginal orgmode

maybe change keybinding for headings to M-RET

implement promotion/demotion of headings in visual mode, do I really need this? How do I promote/demote a single heading without subheadings?

implement other paragraph motions, e.g. d}, c{, this should also work for a whole heading with subheadings

use vim.current.buffer[x:y] = [a, b, c] functionality

implement M-RET to insert new headings

implement moving of headings

add an additional empty line when adding a new heading

implement promotion and demotion for space indented files

implement promotion/demotion of headings

TagsProperties plugin

implement tests

Tests for tags have been implemented in test_vimbuffer.py

move tags functionaly to global Heading class

make edit tasks update tags position

implement command to realign all tags

issues with the positioning of tags, some include one whitespace too much

orgmode tags column is 77 not 78

multibyte characters in foldtext shorten displayed string

remove empty tags

preserve leading colon (:) at the first character

update tags when editing heading

implement completion

implement plugin

error when only a tag is on a line

error when pressing <Esc> while editing tags

Dates plugin

implement a calendar

implement the agenda view by using the location list

implement active dates

implement intive dates

promt to insert dates

integrate speeddating plugin

Logging/time tracking plugin

implement logging plugin

implement Record DONE time

Hyperlinks plugin

implement Internal-links and Targeted-links

implement mouse interaction for links

implement tests

implement better support for External-links

implement Store a link to the current location

integrate with UTL plugin

fix empty links creation

fix passing of function arguments

implement hyperlinks plugin

integrate with Universal Text Linking plugin

implement edit functionality

liborgmode

add support for related documents

move HeadingList._associate_heading to Heading and Document

add support for easily changing a heading’s level

throw exception when adding a heading to the DOM with a lower level than the parent

throw exception when decreasing a heading’s level below or equal to the parent’s level

add support for specific TODO states/allow no other states

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

add support for detaching a heading from a document

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

add support for unicode

build a general library for parsing orgmode files

build a general library for parsing orgmode files

I think of something general like asciidoc

remove dependency to vim to make the plugin generaly usable

turn Document.heading into a method/property and make it writable

implement a more general object structure

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.

Documentation

add descriptions to settings

the goal is to automatically generate most parts of the documentation

generate documentation from plugin code, add short/long descriptions to keybindings

Misc

autocommand for removing Org menu breaks other plugins

reimplement syntax file (the current version is from hsitz)

implement functionality of Orgmode 5 Minutes Tutorial

implement repeat for text-objects

implement settings as part of the plugin

figure out a way to get the keys the user pressed to activate a mapping so that feedkeys can be used properly

integrate v:operator

make use of maparg() and mapcheck()

make a video about vim-orgmode

orgmode taglist integration doesn’t work with txtfmt plugin: setf org.txtfmt

add support for tagbar plugin

tagbar is a reimplementation of the taglist plugin

in original Org-mode keybindings perform different actions based on the context! This functionality should be integrated in vim-orgmode as well

implement better object structure for Heading.parent and Heading.children. At the moment the already created objects are not reused, especially for iterchildern this is important!

Resolved by the implementation of liborgmode

integrate with YankRing plugin

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

integrate with Narrow Region plugin

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

install -D doesn’t work on BSD based systems; migrate commands to install -d

add support for debian package management

add changelog like in debian

implement commands

write general documentation

multibyte characters in foldtext shorten displayed string

fix issue with exceeded buffer boundaries

extract general text-objects from Navigator plugin and move them to Misc plugin

focus more on building text-objects for all major changes

fix issue in recognizing a heading

change behavior of I and ^ on a heading to jump to the first character of the title

introduce general org_leader variable

fix vba issue with empty files

replace tabs in folded view

Create vimball http://vim.wikia.com/wiki/Using_VimBall_with_%27Make%27

allow the user to customize keybindings

remove indent mode, it’s not need!

make plugin keybindings/commands repeatable by pressing .

implement <plug> for all commands

improve syntax highlighting for light backgrounds

disable menu instead of removing and adding it every time

make plugin work for more than one buffer. register menu end keybindings for each buffer

allow user definied settings

implement implement indentation

implement ctags to make browsing bigger files easy

implement org-menu

implement key registration

bug in indentation function something goes wrong with mixed heading levels

bug in indentation function it appears to be really slow

add tests for indentation and and folding

improve tests for Heading.end_of_last_child

add tests for Heading.end_of_last_child

vi: ft=org:tw=72