JIe
2bb7059579
Some checks failed
Detach Plugins / check (FlyGrep.vim) (push) Has been cancelled
Detach Plugins / check (GitHub.vim) (push) Has been cancelled
Detach Plugins / check (JavaUnit.vim) (push) Has been cancelled
Detach Plugins / check (SourceCounter.vim) (push) Has been cancelled
Detach Plugins / check (cpicker.nvim) (push) Has been cancelled
Detach Plugins / check (dein-ui.vim) (push) Has been cancelled
Detach Plugins / check (git.vim) (push) Has been cancelled
Detach Plugins / check (iedit.vim) (push) Has been cancelled
Detach Plugins / check (scrollbar.vim) (push) Has been cancelled
Detach Plugins / check (vim-chat) (push) Has been cancelled
Detach Plugins / check (vim-cheat) (push) Has been cancelled
Detach Plugins / check (vim-todo) (push) Has been cancelled
Detach Plugins / check (xmake.vim) (push) Has been cancelled
test / Linux (nvim, nightly) (push) Has been cancelled
test / Linux (nvim, v0.3.8) (push) Has been cancelled
test / Linux (nvim, v0.4.0) (push) Has been cancelled
test / Linux (nvim, v0.4.2) (push) Has been cancelled
test / Linux (nvim, v0.4.3) (push) Has been cancelled
test / Linux (nvim, v0.4.4) (push) Has been cancelled
test / Linux (nvim, v0.5.0) (push) Has been cancelled
test / Linux (nvim, v0.5.1) (push) Has been cancelled
test / Linux (nvim, v0.6.0) (push) Has been cancelled
test / Linux (nvim, v0.6.1) (push) Has been cancelled
test / Linux (nvim, v0.7.0) (push) Has been cancelled
test / Linux (nvim, v0.7.2) (push) Has been cancelled
test / Linux (nvim, v0.8.0) (push) Has been cancelled
test / Linux (nvim, v0.8.1) (push) Has been cancelled
test / Linux (nvim, v0.8.2) (push) Has been cancelled
test / Linux (nvim, v0.8.3) (push) Has been cancelled
test / Linux (nvim, v0.9.0) (push) Has been cancelled
test / Linux (nvim, v0.9.1) (push) Has been cancelled
test / Linux (true, vim, v7.4.052) (push) Has been cancelled
test / Linux (true, vim, v7.4.1689) (push) Has been cancelled
test / Linux (true, vim, v7.4.629) (push) Has been cancelled
test / Linux (true, vim, v8.0.0027) (push) Has been cancelled
test / Linux (true, vim, v8.0.0183) (push) Has been cancelled
test / Linux (vim, nightly) (push) Has been cancelled
test / Linux (vim, v8.0.0184) (push) Has been cancelled
test / Linux (vim, v8.0.1453) (push) Has been cancelled
test / Linux (vim, v8.1.2269) (push) Has been cancelled
test / Linux (vim, v8.2.2434) (push) Has been cancelled
test / Linux (vim, v8.2.3995) (push) Has been cancelled
test / Windows (nvim, nightly) (push) Has been cancelled
test / Windows (nvim, v0.3.8) (push) Has been cancelled
test / Windows (nvim, v0.4.2) (push) Has been cancelled
test / Windows (nvim, v0.4.3) (push) Has been cancelled
test / Windows (nvim, v0.4.4) (push) Has been cancelled
test / Windows (nvim, v0.5.0) (push) Has been cancelled
test / Windows (nvim, v0.5.1) (push) Has been cancelled
test / Windows (nvim, v0.6.0) (push) Has been cancelled
test / Windows (nvim, v0.6.1) (push) Has been cancelled
test / Windows (nvim, v0.7.0) (push) Has been cancelled
test / Windows (nvim, v0.7.2) (push) Has been cancelled
test / Windows (nvim, v0.8.0) (push) Has been cancelled
test / Windows (nvim, v0.8.1) (push) Has been cancelled
test / Windows (nvim, v0.8.2) (push) Has been cancelled
test / Windows (nvim, v0.8.3) (push) Has been cancelled
test / Windows (nvim, v0.9.0) (push) Has been cancelled
test / Windows (nvim, v0.9.1) (push) Has been cancelled
test / Windows (vim, nightly) (push) Has been cancelled
test / Windows (vim, v7.4.1185) (push) Has been cancelled
test / Windows (vim, v7.4.1689) (push) Has been cancelled
test / Windows (vim, v8.0.0027) (push) Has been cancelled
test / Windows (vim, v8.0.1453) (push) Has been cancelled
test / Windows (vim, v8.1.2269) (push) Has been cancelled
test / Windows (vim, v8.2.2434) (push) Has been cancelled
test / Windows (vim, v8.2.3995) (push) Has been cancelled
docker / docker (push) Has been cancelled
mirror / check (coding) (push) Has been cancelled
mirror / check (gitee) (push) Has been cancelled
mirror / check (gitlab) (push) Has been cancelled
1834 lines
85 KiB
Plaintext
1834 lines
85 KiB
Plaintext
*VimOrganizer.txt* for Vim versions with folding and tabs
|
||
A clone of Emacs' Org-mode for Vim
|
||
|
||
Author: Herbert Sitz <hesitz@gmail.com>
|
||
Version: 0.30, 2011 Nov 02
|
||
|
||
Copyright: (c) 2010, 2011 by Herbert Sitz
|
||
The VIM LICENSE applies to code in the VimOrganizer project,
|
||
unless otherwise indicated.
|
||
(See Vim's |copyright| and substitute 'VimOrganizer' for 'Vim'.)
|
||
NO WARRANTY, EXPRESS OR IMPLIED. USE AT-YOUR-OWN-RISK.
|
||
==============================================================================
|
||
CONTENTS *VimOrganizer* *vimorg*
|
||
|
||
Contents.....................................: |VimOrganizer|
|
||
VimOrganizer Overview........................: |vimorg-overview|
|
||
Document Structure...........................: |vimorg-document-structure|
|
||
File compatibility with Org-mode.............: |vimorg-org-compatibility|
|
||
Vimorg / Emacs Interaction ..................: |vimorg-emacs-interaction|
|
||
Vimorg / Org-mode Conversion.................: |vimorg-org-conversion|
|
||
Vimorg Metadata .............................: |vimorg-metadata|
|
||
|vimorg-tag-metadata|
|
||
|vimorg-todo-metadata|
|
||
|vimorg-property-metadata|
|
||
|vimorg-date-metadata|
|
||
|vimorg-categories|
|
||
|
||
Vimorg Commands .............................: |vimorg-commands|
|
||
|
||
Modifying view of the outline structure |vimorg-view-commands|
|
||
Adding new headings |vimorg-new-headings|
|
||
Heading Navigation |vimorg-navigation|
|
||
Editing Document Structure |vimorg-structure-editing|
|
||
Character formatting |vimorg-character-formatting|
|
||
Footnotes |vimorg-footnotes|
|
||
Capture |vimorg-capture-buffer|
|
||
Refiling |vimorg-refile-heading|
|
||
Mark |vimorg-mark|
|
||
Gather |vimorg-gather|
|
||
Hyperlinks |vimorg-hyperlinks|
|
||
Narrowing Regions |vimorg-narrowing|
|
||
Tables in VimOrganizer |vimorg-tables-editing|
|
||
Clocking |vimorg-clocking|
|
||
|
||
Colorschemes and highlighting |vimorg-colors|
|
||
Code and spreadsheet evaluation in Emacs.....: |vimorg-code-eval|
|
||
|vimorg-spreadsheet-eval|
|
||
|
||
Searches and the Agenda .....................: |vimorg-agenda|
|
||
agenda
|
||
Setting the agenda files
|
||
sparse tree
|
||
custom searches |vimorg-agenda-custom-searches|
|
||
block agendas |vimorg-agenda-blocks|
|
||
agenda window position |vimorg-agenda-window-position|
|
||
clocktables in agenda |vimorg-agenda-include-clocktable|
|
||
|
||
Navigating agenda files |vimorg-files-navigating|
|
||
|
||
Column view..................................: |vimorg-column-view|
|
||
Exporting and Printing.......................: |vimorg-export|
|
||
|
||
Feedback.....................................: |vimorg-feedback|
|
||
|
||
==============================================================================
|
||
VIMORGANIZER OVERVIEW *vimorg-overview*
|
||
|
||
VimOrganizer is a Vim filetype plugin that attempts to clone Emacs' Org-mode.
|
||
It is currently (September 2011) in an alpha-stage, both in terms of (1) the
|
||
breadth and depth of Org-mode features it clones and (2) its level of polish
|
||
and presence of bugs. It's nevertheless very usable in its current state.
|
||
|
||
Org-mode, and thus VimOrganizer, is a text-editor add-on/application that can
|
||
be used for (1) keeping notes, (2) maintaining TODO lists, (3) planning
|
||
projects, and/or (4) authoring and publishing documents, including support for
|
||
literate programming. Like Org-mode, VimOrganizer does this by implementing a
|
||
flexible plain-text system using a lightly structured document format.
|
||
Org-mode has been in constant development for seven or eight years, and
|
||
continues to be developed. Work on VimOrganizer is likewise ongoing, but
|
||
VimOrganizer is at present a much smaller and less ambitious project than
|
||
Org-mode.
|
||
|
||
VimOrganizer also allows Vim users to make use of Org-babel, a subproject of
|
||
Org-mode that allows execution of source-code blocks in org-format
|
||
documents. Uses for Org-babel range from writing technical research papers to
|
||
simply using a VimOrganizer document as a "language-scratchpad". Over
|
||
twenty languages are supported, including C, R, Lisp, Python, Perl, Ruby,
|
||
and others. VimOrganizer calls out to a running Emacs server for Org-babel
|
||
processing; functionality and speed are basically the same as
|
||
when editing with Org-mode in Emacs.
|
||
|
||
VimOrganizer doesn't have much documentation yet. The best way to learn how
|
||
to use VimOrganizer is to learn the basics of Emacs' Org-mode. VimOrganizer
|
||
uses the same basic concepts but implements them within the context of Vim
|
||
and with a reduced feature set. (Parts of this help file were
|
||
copied from Org-mode's documentation.) Org-mode's main documentation and
|
||
support newsgroup are found here:
|
||
Org-mode Main Manual: http://orgmode.org/manual/index.html
|
||
Org-mode Compact Guide: http://orgmode.org/guide/index.html
|
||
Org-mode support newsgroup: http://news.gmane.org/gmane.emacs.orgmode
|
||
Org-babel information: http://orgmode.org/worg/org-contrib/babel/
|
||
|
||
File formats and basic workflows for VimOrganizer and Org-mode are very
|
||
similar, and VimOrganizer actually calls out to an Emacs' Org-mode server to
|
||
implement important features, e.g., exporting to html and pdf formats.
|
||
Thus, to make full use of VimOrganizer you will often want to have an Emacs'
|
||
server running alongside. In most cases this requires little knowledge of
|
||
Emacs other than how to start it up and add a few lines to the '.emacs' file,
|
||
Emacs' counterpart to Vim's '.vimrc'. (You can even edit the .emacs file in
|
||
Vim.)
|
||
|
||
===============================================================================
|
||
VIMORGANIZER DOCUMENT STRUCTURE *vimorg-document-structure*
|
||
|
||
VimOrganizer documents (an "Org document") are organized around a basic
|
||
outline structure. Headlines define the structure of an outline tree. The
|
||
headlines in an Org document start with one or more stars, which must start on
|
||
the leftmost column. For example:
|
||
|
||
------ sample Org-format outline below --------------------------------
|
||
>
|
||
* Top level headline
|
||
** Second level
|
||
*** 3rd level
|
||
some text
|
||
*** 3rd level
|
||
more text
|
||
* Another top level headline
|
||
more text
|
||
------ sample Org-format outline above --------------------------------
|
||
|
||
An overview of this structure is achieved by folding (hiding) large parts of
|
||
the document to show only the general document structure and the parts
|
||
currently being worked on. VimOrganizer simplifies the use of outlines by
|
||
compressing the entire show/hide functionality of a heading and its subtree
|
||
into a simple "cycle" operation, which is bound to the <TAB> key. A user can
|
||
cycle through several views, from fully folded to unfolded, by repeated
|
||
presses of <TAB>. While <TAB> operates on the structure of a single heading,
|
||
<shift-TAB> performs an analogous cycle operation on the document as a whole.
|
||
|
||
Because all of the folds in VimOrganizer are ordinary Vim folds, users can
|
||
also manipulate folds with the usual array of Vim fold commands: zc, zv, zo,
|
||
etc. (see |fold.txt|)
|
||
|
||
===============================================================================
|
||
VIMORGANIZER FILE COMPATIBILITY WITH ORG-MODE *vimorg-org-compatiblity*
|
||
|
||
VimOrganizer's file format is nearly identical to Org-mode. There are
|
||
currently a couple of differences:
|
||
|
||
-------------------------------------------------------------------------------
|
||
METADATA-BLOCKS *vimorg-metadata-format*
|
||
|
||
In VimOrganizer lines in a heading's metadata must (1) immediately follow
|
||
the heading line, and (2) all begin with a colon followed by a
|
||
non-whitespace character.
|
||
|
||
Blocks of metadata typically follow a heading in Org-mode documents, but
|
||
Org-mode doesn't require this. That is, the metadata can be anywhere in the
|
||
text block of a heading. Also, in Org-mode some, but not all (e.g., dates),
|
||
metadata lines are preceded by a colon (:) character. E.g.,
|
||
|
||
------ sample Org-format outline below ----------
|
||
>
|
||
* Top level headline
|
||
DEADLINE:<2011-11-13 Thu>
|
||
:PROPERTIES:
|
||
:SOMEPROP:SomePropValue
|
||
:END:
|
||
One or more lines of text for heading here. . . .
|
||
SCHEDULED:<2011-11-12 Wed>
|
||
One or more lines of text for heading here. . . .
|
||
** subheading
|
||
** another subheading
|
||
------ sample Org-format outline above ---------
|
||
|
||
The sample above should be formatted like this in
|
||
VimOrganizer, with the SCHEDULED date moved above
|
||
PROPERTIES and colons preceding the date lines:
|
||
|
||
------ sample VimOrganizer-format outline below -----
|
||
>
|
||
* Top level headline
|
||
:DEADLINE:<2011-11-13 Thu>
|
||
:SCHEDULED:<2011-11-12 Wed>
|
||
:PROPERTIES:
|
||
:SOMEPROP:SomePropValue
|
||
:END:
|
||
One or more lines of text for heading here. . . .
|
||
** subheading
|
||
** another subheading
|
||
------ sample VimOrganizer-format outline above ----
|
||
|
||
------------------------------------------------------------------------------
|
||
TAG FORMAT IN VIMORGANIZER *vimorg-tag-format*
|
||
|
||
The second major difference between VimOrganizer and Org-mode is in the
|
||
format of tag data. In Org-mode tags are included on heading lines as
|
||
following the end of the heading. In VimOrganizer tags are included as part
|
||
of the metadata block and must be on the first line following a heading.
|
||
|
||
For example, tags in Org-mode look like this:
|
||
|
||
------ sample Org-format tags below ----------
|
||
>
|
||
* Top level headline :tagone:tagtwo:tagthree:
|
||
:PROPERTIES:
|
||
:SOMEPROP:SomePropValue
|
||
:END:
|
||
One or more lines of text for heading here. . . .
|
||
------ sample Org-format tags above ---------
|
||
|
||
The same tags in VimOrganizer would look like this:
|
||
|
||
------ sample VimOrganizer-format tags below ----------
|
||
>
|
||
* Top level headline
|
||
:tagone:tagtwo:tagthree:
|
||
:PROPERTIES:
|
||
:SOMEPROP: SomePropValue
|
||
:END:
|
||
One or more lines of text for heading here. . . .
|
||
------ sample VimOrganizer-format tags above ---------
|
||
|
||
In practice the difference is less visible, since for folded headings the
|
||
default settings in VimOrganizer can show the tags on the same line as the
|
||
heading text. (See |vimorg-column-view|)
|
||
|
||
==============================================================================
|
||
|
||
VIMORGANIZER AND EMACS INTERACTION *vimorg-emacs-interaction*
|
||
*vimorg-emacs-setup*
|
||
|
||
CALLING AN EMACS CLIENT FROM VIMORGANIZER *vimorg-invoking-emacs*
|
||
|
||
For features where Vim/VimOrganizer call out to an Emacs client, setup
|
||
must be configured to properly invoke the Emacs client. This differs depending
|
||
on whether the user is running Windows or a Linux/OS X OS.
|
||
|
||
First, of course, Emacs must be installed and Org-mode must be set up
|
||
properly. Recent Emacs installs include Org-mode and should work without any
|
||
more configuration than a basic install. A '.org' file should be opened in
|
||
Emacs to confirm this. Emacs can be obtained from a link at
|
||
http://www.gnu.org/software/emacs.
|
||
|
||
a. On WINDOWS. The variable, g:org_command_for_emacsclient, must be
|
||
assigned in your vimrc file with a command that will open an emacs client
|
||
on your system. On Windows the associated exe file is emacsclientw.exe
|
||
in Emacs' bin directory. By default Emacs is installed with
|
||
a path that includes spaces in a directory name (viz., '/program files/).
|
||
The complex command that VimOrganizer constructs to call
|
||
Emacs won't work if the command invoking Emacs itself
|
||
includes a space. There are two ways to work around this: 1. Create a
|
||
"symbolic link" to the Emacs client executable that doesn't have a space and
|
||
include that link as value of g:org_command_for_emacs, e.g.,
|
||
>
|
||
let g:org_command_for_emacsclient = c:\users\george\emacsclientw
|
||
|
||
On Windows7 or Vista, the link can be created with Windows' MKLINK command line utility:
|
||
>
|
||
mklink c:\users\george\emacsclientw c:\program files(x86)\Emacs\emacs\bin\emacsclientw.exe
|
||
|
||
Alternatively, rather than create a symbolic link having a path with no
|
||
spaces, a user can add the directory to the environment's path variable, so
|
||
that the emacsclient can be invoked simply by issuing the command
|
||
'emacsclientw', without including any element of its path. In that case you
|
||
would include this assignment in your vimrc:
|
||
>
|
||
let g:org_command_for_emacsclient = emacsclientw.exe
|
||
|
||
|
||
b. ON LINUX/OS X. On Linux the executable to start an Emacs client is
|
||
named emacsclient. In general all you need to do is put this line
|
||
in your vimrc:
|
||
>
|
||
let g:org_command_for_emacsclient = emacsclient
|
||
|
||
NOTE: Unlike the Emacs client on Windows, emacsclient on Linux will NOT start
|
||
up an Emacs server if one is not running, the emacsclient command will simply
|
||
fail.
|
||
Thus, at least for the time being, the user must manually start Emacs before
|
||
using Emacs features from VimOrganizer, and in the running Emacs instance must
|
||
issue the server-start command, either by putting it in the .emacs file or by
|
||
issuing the command manually within Emacs (alt-x server-start).
|
||
|
||
----------------------------------------------------------------------------
|
||
|
||
CONVERSION BETWEEN ORG-MODE AND VIMORGANIZER *vimorg-orgmode-conversion*
|
||
|
||
In practice nothing may go drastically wrong if you don't have perfect
|
||
formatting, either in VimOrganizer or Org-mode, but VimOrganizer by default is
|
||
set to convert Org-mode documents to its own format upon opening. Also, it is
|
||
recommended to put a "hook" function in your .emacs file to convert
|
||
VimOrganizer-format documents to Org-mode format upon opening. Once set up in
|
||
this way you shouldn't need to worry about formatting differences. The
|
||
code to add to your .emacs file is below:
|
||
|
||
--------- elisp code for .emacs ---------------------
|
||
>
|
||
(defun vimorg-tag-adjust ()
|
||
(interactive)
|
||
(while (re-search-forward "^*.*?\n[ \t]+:[^ \t]+:" nil t)
|
||
(if (not (string-match "\\(PROPERTIES\\|LOGBOOK\\)" (thing-at-point 'line)))
|
||
(join-line))))
|
||
|
||
(defun vimorg-set-unmodified ()
|
||
(interactive)
|
||
(set-buffer-modified-p nil))
|
||
|
||
(add-hook 'org-mode-hook
|
||
(lambda () (interactive)(replace-regexp "\\(\\s-*\\):\\(DEADLINE\\|CLOSED\\|SCHEDULED\\|CLOCK\\|<[0-9]\\{4\\}-[0-9]\\{2\\}-[0-9]\\{2\\} \\)" "\\1\\2")
|
||
(beginning-of-buffer)(vimorg-tag-adjust)
|
||
(beginning-of-buffer) ))
|
||
-----------------------------------------------------
|
||
|
||
==============================================================================
|
||
METADATA *vimorg-metadata*
|
||
|
||
Org-mode has different kinds of metadata: tags, todos, properties, dates, and
|
||
categories. Here is how to set up and edit them.
|
||
------------------------------------------------------------------------
|
||
TODOS *vimorg-todo-metadata*
|
||
|
||
*Todos* are single_words that can appear in a heading after the last asterisk
|
||
and immediately before the first word of the heading. By default the todos
|
||
are: (1) TODO and (2) DONE, to identify headings that are tasks that need to
|
||
be done, and headlines that are done tasks.
|
||
|
||
A user can cycle between todo states by pressing <s-enter> in Normal mode
|
||
with the cursor on a headline. Here is how the todos would cycle with the
|
||
default setup of TODO and DONE todos:
|
||
>
|
||
* Work on final report
|
||
* TODO Work on final report (after user presses <s-enter>)
|
||
* DONE Work on final report (after second press of <s-enter>)
|
||
* Work on final report (after third press of <s-enter>)
|
||
|
||
The global default for todos setup is in g:org_todo_setup. If you want to
|
||
change the todo states you can reassign g:org_todo_setup in your vimrc. For
|
||
example, the line below would add a 'STARTED' state to indicate todos that
|
||
had been started but were not yet finished:
|
||
>
|
||
let g:org_todo_setup='TODO STARTED | DONE'
|
||
|
||
Per-file defaults can be set by including a config line in a particular .org
|
||
file. For example, the config line below would add a CANCELLED keyword to
|
||
the todo cycle in a specific document:
|
||
>
|
||
#+TODO: TODO STARTED | DONE CANCELLED
|
||
|
||
Please see the Org-mode documentation for more info on todos. It should be
|
||
helpful, even though not all Org-mode todo features are implemented yet in
|
||
VimOrganizer: http://orgmode.org/manual/TODO-Items.html.
|
||
-------------------------------------------------------------------------
|
||
TAGS *vimorg-tag-metadata*
|
||
|
||
Tags offer a way of attaching multiple labels or contexts to a single heading.
|
||
Tags are added to a heading by putting them on the line immediately after
|
||
the heading, with each tag preceded and followed by a single colon. E.g.,
|
||
here is a heading with two tags:
|
||
>
|
||
* Example heading
|
||
:work:urgent:
|
||
|
||
You can add whatever tags you wish by editing the tag line directly, however
|
||
it's usually preferable to use VimOrganizer's system for setting up and
|
||
editing tags. Global tags setup is held in the variable, g:org_tag_setup,
|
||
which by default holds the setup string '{home(h) work(w)}'. You can override
|
||
the global setup by including a config line in a particular file. E.g.,:
|
||
>
|
||
#+TAGS: { work(w) home(h) tennisclub(t) } laptop(l) pc(p)
|
||
|
||
The braces in the example above indicate that the tags inside are mutually
|
||
exclusive, so choosing one will automatically delete any other. The letters
|
||
in parentheses provide single-key selection when using VimOrganizer's
|
||
tag editing menu. (Single-key letters will be assigned automatically if
|
||
not explicitly assigned in the tag setup string.
|
||
|
||
The tag editing menu can be opened by choosing 'Edit Tags' from the Org
|
||
menu, or by pressing ',et' in Normal mode.
|
||
|
||
Although not all Org-mode tag functionality is present in VimOrganizer, it
|
||
may be helpful to review the Org-mode tag docs at:
|
||
http://orgmode.org/manual/Tags.html#Tags
|
||
|
||
-------------------------------------------------------------------------
|
||
PROPERTIES *vimorg-property-metadata*
|
||
|
||
Properties offer a way to attach key/value pairs to headings in a document.
|
||
These pairs must be included, one per line, in between a :PROPERTIES: and
|
||
an :END: marker beneath a heading. For example:
|
||
>
|
||
* Example heading
|
||
:PROPERTIES:
|
||
:Title: Goldberg Variations
|
||
:Composer: J.S. Bach
|
||
:Artist: Glen Gould
|
||
:Publisher: Deutsche Grammophon
|
||
:NDisks: 1
|
||
:END:
|
||
|
||
For more information on how properties work, please refer to the Org-mode
|
||
documentation:
|
||
http://orgmode.org/manual/Properties-and-Columns.html#Properties-and-Columns
|
||
|
||
-------------------------------------------------------------------------
|
||
DATES *vimorg-date-metadata*
|
||
|
||
Dates are another form of metadata that can be associated with a heading.
|
||
The following commands may be issued anywhere within a headline and will
|
||
enter or edit the corresponding date for the headline. One date of
|
||
each type may be defined per headline (i.e, 'DEADLINE', 'SCHEDULED',
|
||
'CLOSED', and 'timestamp'). You can enter more dates anywhere you want, but
|
||
this editing mechanism is currently restricted to dealing with only these
|
||
"primary" dates.
|
||
|
||
Command Result
|
||
,dd enter DEADLINE date for headline
|
||
,ds enter SCHEDULED date for headline
|
||
,dc enter CLOSED date for headline
|
||
,dt enter timestamp date (i.e., no indicator) for headline
|
||
,dg set date at cursor
|
||
|
||
The command-line prompt and calendar that appear when you execute a ',d_'
|
||
command operate nearly the same as the date-time prompt in Emacs'
|
||
Org-mode. Some options are not yet implemented (e.g., the 'w'eek
|
||
options), but most should work just the same. For documentation
|
||
on Org-mode's date-time prompt see:
|
||
http://orgmode.org/manual/The-date_002ftime-prompt.html#The-date_002ftime-prompt
|
||
|
||
Except when using the 'set date at cursor' option, the date will be located
|
||
beneath the heading, immediately after any tag line, and immediately before
|
||
any PROPERTIES block. Dates added in other locations will be searched
|
||
when using VimOrganizer's searches, but they aren't strictly speaking part
|
||
of the 'metadata block' that immediately follows a heading.
|
||
-------------------------------------------------------------------------
|
||
CATEGORIES *vimorg-categories*
|
||
|
||
Categories are yet another form of metadata in Org files. Categories
|
||
are useful because a heading's 'Category' is displayed as the first column
|
||
of data in a heading line in Agenda results. (Remember that there
|
||
is limited space for display, try to keep category names less than
|
||
10 characters.) By default a heading's Category will be its file name.
|
||
However you can change this in several ways.
|
||
|
||
First, you can establish a new category for an entire document by
|
||
placing a category config line at the top of the document. All
|
||
headings in the document will inherit it as their default. Like
|
||
all config lines, it must begin in the leftmost column of the buffer,
|
||
e.g.,:
|
||
>
|
||
#+CATEGORY: MyCategory
|
||
|
||
All headings in the document would now display that as the first column
|
||
when they are part of an agenda result.
|
||
|
||
Second, you can override a document's default category by giving a
|
||
heading a category property, like this:
|
||
------------------------
|
||
>
|
||
* Heading One
|
||
:PROPERTIES:
|
||
:CATEGORY: NewCategory
|
||
:END:
|
||
** Subheading One
|
||
** Subheading TWo
|
||
* Heading Two
|
||
------------------------
|
||
In the snippet above, Heading One's category would be 'NewCategory'.
|
||
Categories are inherited by subheadings, so Subheading One and Sub-
|
||
heading Two would also be 'NewCategory'. Heading Two, on the other
|
||
hand, would inherit the category from a config line, if any, or its
|
||
category would be the file name (excluding the . and extension).
|
||
|
||
You can read more about how categories work here:
|
||
http://orgmode.org/manual/Categories.html#Categories
|
||
NOTE: Although Org-mode still supports multiple category config
|
||
lines in a document, each affecting text occurring after it (and
|
||
before another category config line), VimOrganizer does not
|
||
support this. You can put one CATEGORY config line in a document and
|
||
it will be inherited by any heading that does not have a CATEGORY
|
||
property (or inherit a CATEGORY property from an ancestor heading).
|
||
|
||
=============================================================================
|
||
VIMORGANIZER COMMANDS *vimorg-commands*
|
||
|
||
VimOrganizer commands are listed below, along with the normal-mode
|
||
keystrokes to invoke them. (<localleader> in VimOrganizer documents
|
||
is by default the comma (",") character, which accounts for the commas
|
||
in the commands below):
|
||
|
||
---------------------------------------------------------------------
|
||
MODIFYING VIEW OF THE OUTLINE STRUCTURE *vimorg-view-commands*
|
||
|
||
View Document Structure Show entire document with headings
|
||
,,N expanded to outline level N.
|
||
where N is for level 1-9
|
||
|
||
View Subtree Structure Show current subtree with headings
|
||
,N expanded to outline level N.
|
||
where N is for level 1-9
|
||
---------------------------------------------------------------------
|
||
ADDING NEW HEADINGS *vimorg-new-headings*
|
||
|
||
New headings can of course be added by normal Vim text editing. Create
|
||
a new line and put one or more asterisks starting flush with the left
|
||
column. Normal mode commands below are shortcuts to do the same thing.
|
||
|
||
|
||
new heading same level Insert a new heading of current level
|
||
<CR> in normal mode after current heading's subtree.
|
||
<S-CR> in insert mode
|
||
|
||
new subhead Insert a new heading that is a
|
||
<C-CR> sub-heading of the current heading
|
||
|
||
new parent head Insert a new heading that is at
|
||
<S-C-CR> the level of current subhead's parent
|
||
|
||
-----------------------------------------------------------------------
|
||
HEADING NAVIGATION *vimorg-navigation*
|
||
|
||
VimOrganizer has commands that let you navigate a document by outline
|
||
node. Some outline navigation commands are not mapped to keys but are
|
||
available on the menu.
|
||
|
||
Up to parent Move cursor to parent heading.
|
||
<a-left-arrow>
|
||
|
||
Previous sibling Move cursor to previous heading
|
||
<a-up-arrow> of same level in current subtree.
|
||
|
||
Next sibling Move cursor to next heading of
|
||
<a-down-arrow> same level in current subtree
|
||
|
||
First child Move cursor to first child heading
|
||
<a-right-arrow> of current heading.
|
||
|
||
Last child Move cursor to last child heading
|
||
of current heading.
|
||
|
||
Next heading . . . to next heading of any kind
|
||
|
||
Previous heading . . . to previous heading of any kind
|
||
|
||
Next heading same level . . . to next heading of same level
|
||
regardless of whether it is in
|
||
current subtree
|
||
|
||
Previous heading same level . . . to next heading of same level
|
||
regardless of whether it is in
|
||
current subtree
|
||
----------------------------------------------------------------------
|
||
EDITING DOCUMENT STRUCTURE *vimorg-structure-editing*
|
||
|
||
These commands let you move entire sections of a document based on its
|
||
outline structure.
|
||
|
||
Move subtree up Move current subtree to position
|
||
<c-a-uparrow> before previous subtree.
|
||
|
||
Move subtree down Move current subtree to position
|
||
<c-a-downarrow> after next subtree.
|
||
|
||
Promote subtree Move entire subtree to be at parent
|
||
<c-a-leftarrow> heading's level and position after
|
||
parent subtree.
|
||
|
||
Demote subtree Move entire subtree to be child
|
||
<c-a-rightarrow> of previous heading of same level.
|
||
--------------------------------------------------------------
|
||
CHARACTER FORMATTING *vimorg-character-formatting*
|
||
|
||
These commands automatically add the markup Org-mode uses to print
|
||
documents with specially formatted text. Text can be selected
|
||
prior to issuing command to wrap text in markup or just issue
|
||
the command then add text between the markup delimiters.
|
||
|
||
NOTE: these delimiters do NOT format phrases that span
|
||
over a line break, they are for the same line only. If you
|
||
want to format over two or more lines you need to apply
|
||
to each word in the lines (for safety when reformatting)
|
||
or to the begin and end of each line (which will pose
|
||
problems upon reformatting).
|
||
|
||
Bold text uses * delimiters
|
||
,cb
|
||
|
||
Italic text uses / delimiters
|
||
,ci
|
||
|
||
Underline text uses _ delimiters
|
||
,cu
|
||
|
||
Code text uses = delimiters to specify
|
||
,cc monospaced unformatted text
|
||
|
||
----------------------------------------------------
|
||
FOOTNOTES *vimorg-footnotes*
|
||
|
||
VimOrganizer has no special support for footnotes yet. However footnotes can
|
||
still be easily included, and upon export will be properly positioned
|
||
formatted (and linked, depending on the output format). The special support
|
||
that will be added consists mostly of automatically assembling footnote text
|
||
in a separate portion of the document.
|
||
|
||
You can add footnotes in any of the following ways:
|
||
|
||
[fn::text of footnote here] This inline method will make the
|
||
text into a footnote and add a
|
||
proper footnote reference at the
|
||
position of the reference.
|
||
|
||
[fn:name:text of footnote here] This inline method allows the same
|
||
note to be referenced by another
|
||
note reference of this form:
|
||
[fn:name]
|
||
|
||
[fn:name] This creates a reference point in
|
||
the document that will be numbered
|
||
and linked to the footnote text with
|
||
the same name. The text of the foot-,
|
||
note is entered in a separate
|
||
paragraph of its own, located
|
||
anywhere in the document but always
|
||
beginning in column 0, like this:
|
||
|
||
[fn:name] This paragraph (text to next blank line) is the note
|
||
for the footnote reference: name. Upon export numbers will be
|
||
substituted for all of the footnote names in the document.
|
||
|
||
See the Org-mode documentation for more complete information
|
||
on footnotes. Remember, you can use them in VimOrganizer, the
|
||
main thing missing is automatic gathering of all the note
|
||
text at a common point in the document:
|
||
http://orgmode.org/manual/Footnotes.html#Footnotes
|
||
|
||
----------------------------------------------------
|
||
CAPTURE BUFFER *vimorg-capture-buffer*
|
||
*OrgCapture*
|
||
*g:org_capture_file*
|
||
|
||
The "capture buffer" is a buffer that can be opened
|
||
wherever you are in Vim. It provides a quick and
|
||
simple way to "capture" a note in a "capture file"
|
||
that you can review later and refile items to
|
||
whatever end location is appropriate. "Capturing"
|
||
in essence lets you quickly save a note without having
|
||
to worry about identifying or opening the file it
|
||
will eventually end up in. Later you can open your
|
||
capture file and focus on refiling all of your notes
|
||
to the appropriate spot in one of your .org files.
|
||
|
||
The capture buffer opens with a simple
|
||
Org template of a single level 1 heading with no text
|
||
and a generic datetime marking the date of creation.
|
||
E.g., >
|
||
|
||
*
|
||
:<2012-01-08 Sun 16:00>
|
||
|
||
The buffer is opened in insert mode with the cursor positioned
|
||
one space to the right of the asterisk, where you can
|
||
enter the heading text, then enter the content of the note
|
||
below the timestamp.
|
||
|
||
When in the capture buffer the write command (:w) will
|
||
(1) save the contents of the capture buffer to the capture file,
|
||
then (2) close the capture buffer.
|
||
|
||
When in a capture buffer the quit command (:q) will abandon any changes
|
||
and close the buffer without confirmation.
|
||
|
||
A "capture buffer" can be opened by choosing "Open
|
||
Capture Buffer" from the menu in gvim or with with the command
|
||
:OrgCapture. The :OrgCapture command should be defined in
|
||
your vimrc and is part of the sample vimrc of the VimOrganizer
|
||
project. This ensures that the command is enabled regardless
|
||
of whether you have opened a .org file in your Vim session.
|
||
|
||
The command :OpenCaptureFile will open your capture file
|
||
into a Vim buffer, so you can then refile each of the items
|
||
in it to the appropriate location.
|
||
|
||
----------------------------------------------------
|
||
REFILING *vimorg-refile-heading*
|
||
*vimorg-jump-to-headng*
|
||
|
||
Refiling involves moving a subtree structure
|
||
to a new location, either in the current document or
|
||
another document. (The user interface for
|
||
this is currently barebones and not optimal, like many other
|
||
things it will be revised. . . .)
|
||
|
||
Open refile dashboard
|
||
,r Open the refiling dashboard. Type an action's
|
||
character to perform it, or <Esc> to cancel and
|
||
close the menu.
|
||
|
||
Refile to point
|
||
,rr Move current subtree to be subchild
|
||
of heading at a different location.
|
||
Invoking this command first presents
|
||
you with a 'Target file:' prompt, at
|
||
which you can use <Tab> to choose the
|
||
file target. Then press <Enter> to
|
||
get a list of top-level headings in
|
||
the selected file. If you want to
|
||
select a lower-level heading then add
|
||
a '/' and press <Tab> to get list of
|
||
direct subheadings of the heading, or
|
||
'*' and <Tab> to get list of all levels
|
||
of subheads of selected heading. Finally,
|
||
<Enter> to choose the heading to refile to,
|
||
or <Esc> to cancel the refile.
|
||
|
||
Refile, jump to point
|
||
,rj Uses same prompt as 'Refile to point' command,
|
||
but instead of moving subtree there simply
|
||
moves cursor to that point (which may involve
|
||
moving to a different buffer if chosen point
|
||
is not in current buffer).
|
||
|
||
Refile, set persistent
|
||
refile point
|
||
,rs Same prompt as for 'Refile to point' command,
|
||
but instead of refiling it saves the
|
||
chosen file and heading to be used as
|
||
target of subsequent 'Refile to Persistent
|
||
Point' command.
|
||
|
||
Refile to persistent
|
||
refile point
|
||
,rp Move current subtree to location defined
|
||
by the persistent refile point.
|
||
|
||
Refile, jump to
|
||
persistent point
|
||
,rx Move cursor to file/heading that is persistent
|
||
refile point.
|
||
|
||
Refile to last
|
||
refile point
|
||
,rl Refile the current subtree to the previously
|
||
used location
|
||
|
||
Refile, jump to last
|
||
refile point
|
||
,rz Move cursor to the previously used refile
|
||
location
|
||
|
||
Items may be refiled to an archive file. The archive has the same path
|
||
and name as the originating file with '_archive' appended. Archived
|
||
subtrees are appended to the end. Additional properties are added like
|
||
the archival date and time.
|
||
|
||
Refile to archive
|
||
,ra Refile to the end of the archive file
|
||
associated with the current org file
|
||
|
||
Jump to archive
|
||
,rv Open the archive file in a new tab.
|
||
|
||
|
||
------------------------------------------------------------------------
|
||
MARK *vimorg-mark*
|
||
|
||
Headings may be toggled to a "marked" state in either an .org buffer
|
||
or in the agenda.
|
||
Note that the keymap to mark a heading is different depending on
|
||
whether you're in an .org buffer or in the Agenda:
|
||
|
||
In an .org buffer: ,<space>
|
||
In the Agenda: <space>
|
||
|
||
In the Agenda certain operations will work on all marked headings --
|
||
if any are marked -- otherwise only on current heading:
|
||
|
||
Date edits
|
||
Todo edits
|
||
Refiling
|
||
|
||
In an .org buffer these operations will operate on all marked
|
||
headings:
|
||
|
||
Refiling
|
||
Gathering
|
||
|
||
When operating on multiple marked headlines, the above operations will
|
||
operate on all marks in any open .org buffer. I.e., they are not restricted
|
||
to marks in the current .org buffer.
|
||
|
||
Also, when the operation is complete the headlines will all be toggled
|
||
to an 'unmarked' state.
|
||
|
||
All 'marked' headlines may be toggled to 'unmarked' by choosing
|
||
'Unmark all' from the 'Mark/Gather/Sort' menu in gvim, or with
|
||
key combination of:
|
||
,<c-space> in an .org buffer, or
|
||
<c-space> in Agenda
|
||
|
||
'gathered' headings are normally placed after the last subhead of
|
||
the heading from where 'gather' command is issued, but they will
|
||
always be placed at top of subheads if g:org_reverse_note_order = 1
|
||
|
||
------------------------------------------------------------------------
|
||
GATHERING *vimorg-gather*
|
||
*vimorg-gather-sort*
|
||
|
||
'Gathering' refers to a process whereby all 'marked' headings are
|
||
moved to be subheads of the current heading in an .org buffer.
|
||
(Gather is not available from or to the Agenda buffer.)
|
||
|
||
A simple gather dashboard is accessed by pressing: ,g
|
||
|
||
'gather' can be thought of as a different way of doing 'refiling'.
|
||
In refiling you mark all headings to be refiled to the same spot,
|
||
then choose a refile operation to select a target heading to move them to.
|
||
With 'gather' you mark all the headings, then simply move to the target
|
||
heading and issue the 'gather' command.
|
||
|
||
The 'gather' operation can be accessed from the 'Mark/Gather/Sort'
|
||
menu in gvim or by the key command: ,gh
|
||
|
||
------------------------------------------------------------------------
|
||
GATHER AND SORT *vimorg-sort*
|
||
|
||
The 'sort' operation reorders subheadings of the current heading to
|
||
be in alphabetical or reverse-alphabetical order. Normal order
|
||
is (case-sensitive) alphabetical, reverse is used if the variable,
|
||
g:org_reverse_note_order is equal to 1.
|
||
|
||
|
||
------------------------------------------------------------------------
|
||
KEYBINDINGS *vimorg-keybindings*
|
||
|
||
Keybindings are still a moving target. I'm happy to hear from people
|
||
who think they've found better command bindings. You can look up bindings
|
||
(1) in this help file, (2) in the menu in g(raphical)vim, which lists
|
||
binding next to command you choose, and/or in the vimorg-main-mappings.vim
|
||
and vimorg-agenda-mappings.vim scripts in the ftplugin directory. A few
|
||
mappings, mostly agenda stuff, are also made in the main org.vim ftplugin
|
||
file. The keybindings are messy and will be cleaned up at some point.
|
||
|
||
*vimorg-keybindings-terminal*
|
||
TERMINAL KEYBINDINGS. It's important to understand that many of the
|
||
default bindings are NOT available in many or all versions of vim running
|
||
on terminals. This is the fault of the terminal for not handling the
|
||
particular key combination. Here's a link to an Org-mode webpage listing
|
||
common key combinations that are not available in terminals, with suggested
|
||
Emacs alternatives. Vim keybindings are of course different (no crazy
|
||
chord combinations), but the suggestions there might give you ideas for
|
||
mappings you want to do for yourself:
|
||
http://orgmode.org/manual/TTY-keys.html#TTY-keys
|
||
|
||
Below are the alternate mappings already in VimOrganizer for the most
|
||
commonly-used key combinations that aren't available in terminals. They
|
||
are found at the bottom of the file, vimorg-main-mappings.vim in the
|
||
ftplugin folder:
|
||
|
||
,<tab> GlobalCycle (same as <shift-TAB> in gvim)
|
||
(note default for ,<tab> is now to toggle between org buffer/Agenda buffer)
|
||
gk Node navigate up (same as <alt-up>... )
|
||
gj Node Navigate down (same as <alt-down>... )
|
||
gh Node navigate left (same as <alt-left>... )
|
||
gl Node navigate right (same as <alt-right>... )
|
||
<< Promote heading tree (same as <ctrl-alt-left>... )
|
||
>> Demote headng tree (same as <ctrl-alt-right>...)
|
||
<, Move heading tree up (same as <ctrl-alt-up>... )
|
||
>. Move headng tree down (same as <ctrl-alt-down>... )
|
||
<localleader>np Add new heading node below at parent's level (<c-s-enter>)
|
||
<localleader>ns Add new heading node below at subhead level (<c-enter>)
|
||
|
||
|
||
------------------------------------------------------------------------
|
||
HYPERLINKS *vimorg-hyperlinks* *vimorg-links*
|
||
|
||
VimOrganizer uses the same hyperlink markup style as Org-mode, but doesn't
|
||
support as many types of links. You can read about the Org-mode link
|
||
format here: http://orgmode.org/manual/Hyperlinks.html#Hyperlinks .
|
||
|
||
While you can add and edit links with VimOrganizer without it, to follow
|
||
external links you must have the "Universal Text Linking" Vim plugin (UTL)
|
||
installed. You can find it here:
|
||
http://www.vim.org/scripts/script.php?script_id=293 .
|
||
UTL itself does not use Org-mode compatible links, but it is used by
|
||
VimOrganizer behind the scenes to follow links.
|
||
|
||
In general, an Org-mode formatted link looks like this:
|
||
>
|
||
[[link_specification][descriptive_link_name]
|
||
|
||
You can also use a link with no descriptive name:
|
||
>
|
||
[[link_specification]]
|
||
|
||
Here is an example that links to the Yahoo home page:
|
||
>
|
||
[[http://www.yahoo.com][Yahoo home page]]
|
||
|
||
If using a Vim version that has the 'conceal' feature, VimOrganizer allows
|
||
you to set your display so that the brackets and the link specification
|
||
are hidden, and you see only the highlighted *descriptive_link_name* .
|
||
(If the link has a link-specification only, no descriptive name, then
|
||
just the brackets will be hidden in conceal mode.)
|
||
|
||
|
||
Add/edit link Allows you to edit a link in the command line.
|
||
,le You are first prompted for the link
|
||
specification, then press <Enter> and you
|
||
will be prompted for a link name.
|
||
|
||
Follow link Will "follow" a link. With web URLs this
|
||
,lf will open a browser, with files it will
|
||
(or just press <Enter> open the file in an appropriate app if a
|
||
cursor on the link) handler app has been defined. (UTL setup
|
||
has default set of handlers and can be
|
||
changed.) Internal links will move to
|
||
associated spot within a vimorg document.
|
||
|
||
NOTE: The Org-mode format requires that
|
||
the 'http://' prefix be included when specifying
|
||
web urls. Links will fail if you don't
|
||
include 'http://'.
|
||
|
||
Next link Moves to next link in the document.
|
||
,ln
|
||
|
||
Previous link Moves to previous link in the document.
|
||
,lp
|
||
|
||
Perma-compress links There are three types of link "compression".
|
||
,lc All work only in Vim version 7.3 or later
|
||
Auto-compress links that is compiled with the conceal feature.
|
||
,la Perma-compress will keep the link com-
|
||
Do not compress links pressed using Vim's conceal feature unless
|
||
,lx you are Insert mode. (You can always edit
|
||
a link directly in Insert mode as well as
|
||
using the 'Add/edit link' function.)
|
||
Auto-compress keeps link ends concealed
|
||
in Normal mode except it automatically expands
|
||
all links on the same line as the cursor.
|
||
'Do not compress' option sets things to always
|
||
show the entire link text (and is the only
|
||
option that works in Vim versions prior to 7.3).
|
||
|
||
------------------------------------------------------------------------
|
||
NARROWING REGIONS *vimorg-narrowing*
|
||
|
||
VimOrganizer uses Christian Brabandt's NrwRgn plugin to edit subsections
|
||
of an outline in separate window. For outline sections this function is
|
||
sometimes called "hoisting". There are two different kinds of narrowing: (1)
|
||
narrowing of a subtree, and (2) narrowing of a code block.
|
||
|
||
Narrow heading tree ,na is the keysequence to narrow a region.
|
||
,na If within a code block then the code block
|
||
-- or -- will be chosen as the region to be narrowed.
|
||
Narrow code block If not in a code block, then the current
|
||
,na heading will be used to determine the
|
||
narrowed region, with the heading and its
|
||
entire subtree opened in the new window.
|
||
If region is a code block, in most cases
|
||
the language of the code block will be recognized
|
||
and the new window will treat it as the
|
||
appropriate filetype, with correct syntax
|
||
highlighting and indenting.
|
||
|
||
When editing a narrowed region in a separate window, the main buffer will
|
||
be uneditable and the region that was narrowed will be highlighted within it.
|
||
The narrowed region in the separate window is in a buffer that is different
|
||
from the buffer from the main document, so changes made in it are not
|
||
immediately reflected in the original buffer. To save changes use the *write*
|
||
command, *wq* to write and quit, or just *q* to abandon unsaved changes and
|
||
return to original buffer. See help for |NarrowRegion| for more information.
|
||
|
||
|
||
------------------------------------------------------------------------
|
||
TABLES IN VIMORGANIZER *vimorg-tables-editing*
|
||
|
||
Tables in VimOrganizer work very much like they work in Org-mode.
|
||
VimOrganizer uses some of the table code from the excellent VimWiki project.
|
||
Other major parts of the table functionality come from calling directly
|
||
to Org-mode in Emacs to evaluate or manipulate a table.
|
||
|
||
Regardless of the editing functionality available in VimOrganizer,
|
||
the behavior of tables in export will be identical to what it is
|
||
in Org-mode, since exports are in fact done by Org-mode.
|
||
|
||
Table operations are accessed through the Table Dashboard. You can open
|
||
the dashboard with the command :OrgTableDashboard or the key sequence
|
||
,b. The table dashboard is context-sensitive. Operations accessible
|
||
on the table dashboard are as follows:
|
||
|
||
1. When cursor is on a blank line You are prompted to create
|
||
a new table, which you can do
|
||
by specifying rows and columns.
|
||
|
||
2. When cursor is on non-table text You will be prompted to create a
|
||
table from the block of text you
|
||
are on. The block is defined as
|
||
the area between the previous
|
||
blank line and the next blank
|
||
line. This operation calls out
|
||
to Org-mode and processes the
|
||
text block with the elisp
|
||
function 'org-convert-table-region'.
|
||
The text will be split into a
|
||
table based on the following rules:
|
||
|
||
a. If every line contains at least
|
||
one TAB character, the function
|
||
assumes that the material is tab
|
||
separated.
|
||
b. If every line contains a comma,
|
||
comma-separated values (CSV) are
|
||
assumed.
|
||
c. If neither of above apply, lines
|
||
are split at whitespace into fields.
|
||
|
||
3. When cursor is on a table. In this case a full dashboard is shown.
|
||
All user options call out to Org-mode
|
||
in Emacs to process the table. This is
|
||
done even for relatively simple options,
|
||
since the #+TBLFM line may change. See
|
||
Org-mode documenation regading these
|
||
options and how tables and spreadsheet
|
||
functionality works:
|
||
http://orgmode.org/manual/Tables.html#Tables
|
||
|
||
Dashboard operations: All of these operations depend on the
|
||
position of the cusor within the table.
|
||
|
||
'COLUMN' operatons: l -- move column left
|
||
r -- move column right
|
||
e -- delete column
|
||
o -- insert column
|
||
|
||
'ROW' operations d -- move row down
|
||
u -- move row up
|
||
x -- delete row
|
||
i -- insert row
|
||
|
||
Insert horiontal line h -- insert a line below cursor
|
||
|
||
'RowSort' operations: All of the row sort operations operate
|
||
on the current 'row-region' of the table.
|
||
A row region is the range of rows
|
||
including the cursor row up to (1)
|
||
beginning-of-table or a horizontal line
|
||
above, and down to (2) the end-of-table
|
||
or a horizontal line below.
|
||
|
||
Available sorts are
|
||
a -- alphabetical, a to z
|
||
A -- reverse alphabetical, z-a
|
||
n -- numeric, low to high
|
||
N -- numeric, high to low
|
||
|
||
------------------------------------------------------------------------
|
||
TABLE EVALUATION *vimorg-table-evaluation*
|
||
|
||
Spreadsheet functionality is supported by calling out to Org-mode
|
||
in Emacs. You cause this by putting the cursor in a table and
|
||
choosing '(T)able, E(v)aluate Table' from the menu in gvim, or
|
||
by pressing |,v|. Evaluation will do two things:
|
||
|
||
(1) If cursor is in a table cell with a valid row/col
|
||
formula, it will be moved into the #+TBLFM string.
|
||
(2) Formulas defined in the TBLFM string will be
|
||
evaluated and results will be placed in appropriate
|
||
cells in the table.
|
||
|
||
Since the table is evaluated in Emacs, all of the spreadsheet
|
||
formulas are evaluated as specified in the Org-mode manual:
|
||
http://orgmode.org/manual/The-spreadsheet.html#The-spreadsheet
|
||
|
||
NOTE: Be sure to note that the default evaluation does _NOT_
|
||
follow the rule of equal precedence of multiplication
|
||
and division. Instead, division has lower precedence
|
||
than multiplication:
|
||
|
||
2/3*4 == 2 / (3 * 4)
|
||
|
||
See: http://orgmode.org/manual/Formula-syntax-for-Calc.html#Formula-syntax-for-Calc
|
||
|
||
------------------------------------------------------------------------
|
||
CLOCKING *vimorg-clocking*
|
||
|
||
Clocking means to record the amount time you spend on tasks.
|
||
|
||
,ci Clock in *vimorg-clock-in*
|
||
|
||
When you start work on an item, position the cursor on its headline and
|
||
press ,ci. A property :CLOCK: with the current timestamp is added, to
|
||
record the start time and to mark it as "open".
|
||
|
||
,co Clock out *vimorg-clock-out*
|
||
|
||
When you stop working on the current task, press ,co. You don't have to
|
||
be positioned on the item. The currently open task will be searched in
|
||
the current file or in all Agenda files (see |vimorg-agenda-files|). The
|
||
end time will be recorded. The start time, end time and duration will be
|
||
recorded in a :LOGBOOK: drawer like this:
|
||
|
||
:LOGBOOK:
|
||
:CLOCK: [2010-07-11 Sun 20:30]--[2010-07-11 Sun 22:26] -> 1:56
|
||
:END:
|
||
|
||
You can clock the same task multiple times and multiple :CLOCK: lines
|
||
will accumulate in the logbook.
|
||
|
||
|
||
========================================================================
|
||
COLORS AND HIGHLIGHTING IN VIMORGANIZER *vimorg-colors*
|
||
*vimorg-colorschemes*
|
||
*vimorg-highlighting*
|
||
|
||
VimOrganizer works well with many different Vim colorschemes. It will
|
||
automatically adjust highlighting for major items when a new
|
||
colorscheme is loaded. Colors for heading lines are mapped to
|
||
the colors a colorscheme sets for the following syntax items:
|
||
>
|
||
Outline Level 1 - Statement
|
||
Outline Level 2 - Identifier
|
||
Outline Level 3 - Constant
|
||
Outline Level 4 - Comment
|
||
Outline Level 5 - Special
|
||
|
||
Many elements in VimOrganizer documents have highlighting that is not
|
||
affected by generic colorschemes. These include items like TODO
|
||
keywords, tags, properties, configuration lines, etc.
|
||
-------------------------------------------------------------------
|
||
*vimorg-customizing-colors*
|
||
The main way to change highlighting is to add a special function to your
|
||
vimrc. This function is called when a VimOrganizer file is loaded
|
||
and whenever a colorscheme is changed. It provides a spot to write
|
||
your own highlight statements (see |highlight| ) to override the
|
||
default settings.
|
||
>
|
||
function! OrgCustomColors()
|
||
" various Org syntax item highlighting statements below
|
||
" are the current defaults. Uncomment and edit a line if you
|
||
" want different highlighting for the element.
|
||
|
||
" Below are defaults for any TODOS you define. TODOS that
|
||
" come before the | in a definition will use 'NOTDONETODO'
|
||
" and those that come after are DONETODO
|
||
"hi! DONETODO guifg=green ctermfg=green
|
||
"hi! NOTDONETODO guifg=red ctermfg=lightred
|
||
|
||
" Heading level highlighting is done in pairs, one for the
|
||
" heading when unfolded and one for folded. Default is to make
|
||
" them the same except for the folded version being bold:
|
||
" assign OL1 pair for level 1, OL2 pair for level 2, etc.
|
||
"hi! OL1 guifg=somecolor guibg=somecolor
|
||
"hi! OL1Folded guifg=somecolor guibg=somecolor gui=bold
|
||
|
||
|
||
" Tags are lines below headings that have :colon:separated:tags:
|
||
"hi! Org_Tag guifg=lightgreen ctermfg=blue
|
||
|
||
" Lines that begin with '#+' in column 0 are config lines
|
||
"hi! Org_Config_Line guifg=darkgray ctermfg=magenta
|
||
|
||
" Drawers are :PROPERTIES: and :LOGBOOK: lines and their associated
|
||
" :END: lines
|
||
"hi! Org_Drawer guifg=pink ctermfg=magenta
|
||
"hi! Org_Drawer_Folded guifg=pink ctermfg=magenta gui=bold cterm=bold
|
||
|
||
" This applies to value names in :PROPERTIES: blocks
|
||
"hi! Org_Property_Value guifg=pink ctermfg=magenta
|
||
|
||
" Three lines below apply to different kinds of blocks
|
||
"hi! Org_Block guifg=#555555 ctermfg=magenta
|
||
"hi! Org_Src_Block guifg=#555555 ctermfg=magenta
|
||
"hi! Org_Table guifg=#888888 guibg=#333333 ctermfg=magenta
|
||
|
||
" Dates are date specs between angle brackets (<>) or square brackets ([])
|
||
"hi! Org_Date guifg=magenta ctermfg=magenta gui=underline cterm=underline
|
||
|
||
" Org_Star is used to "hide" initial asterisks in a heading
|
||
"hi! Org_Star guifg=#444444 ctermfg=darkgray
|
||
|
||
"hi! Props guifg=#ffa0a0 ctermfg=gray
|
||
|
||
" Bold, italics, underline, and code are highlights applied
|
||
" to character formatting
|
||
"hi! Org_Code guifg=darkgray gui=bold ctermfg=14
|
||
"hi! Org_Itals gui=italic guifg=#aaaaaa ctermfg=lightgray
|
||
"hi! Org_Bold gui=bold guifg=#aaaaaa ctermfg=lightgray
|
||
"hi! Org_Underline gui=underline guifg=#aaaaaa ctermfg=lightgray
|
||
"hi! Org_Lnumber guifg=#999999 ctermfg=gray
|
||
|
||
" These lines apply to links: [[link]], and [[link][link desc]]
|
||
"if has("conceal")
|
||
" hi! default linkends guifg=blue ctermfg=blue
|
||
"endif
|
||
"hi! Org_Full_Link guifg=cyan gui=underline ctermfg=lightblue cterm=underline
|
||
"hi! Org_Half_Link guifg=cyan gui=underline ctermfg=lightblue cterm=underline
|
||
|
||
" Applies to the Heading line that can be displayed in column view
|
||
"highlight OrgColumnHeadings guibg=#444444 guifg=#aaaaaa gui=underline
|
||
|
||
endfunction
|
||
----------------------------------------------------------------------
|
||
CUSTOM TODO HIGHLIGHTING *vimorg-custom-todo-highlights*
|
||
|
||
VimOrganizer will automatically highlight DONETODOs and NOTDONETODOs with
|
||
a default color, or color you assign in OrgCustomColors(). If you
|
||
want to assign custom highlighting for one or more TODOs then
|
||
you need to create a dictionary with appropriate values.
|
||
Below is an illustration:
|
||
|
||
|
||
Problem: You want to create custom highlights for the NEXT
|
||
and WAITING todos in the todo setup of: >
|
||
'TODO NEXT WAITING | DONE CANCELED'
|
||
<
|
||
Solution: put statement like the one below in OrgCustomColors()
|
||
function in your vimrc, (or somewhere in vimrc below
|
||
the OrgCustomColors() func, if any):
|
||
>
|
||
let g:org_todo_custom_highlights =
|
||
\ { 'NEXT': { 'guifg':'#888888', 'guibg':'#222222',
|
||
\ 'ctermfg':'gray', 'ctermbg':'darkgray'}
|
||
\ 'WAITING': { 'guifg':'red',
|
||
\ 'ctermfg':'red' } }
|
||
|
||
NOTE: (1) Vim has specific punctuation in its dictionary assignments.
|
||
Each of the keys in the statement above is a string,
|
||
and keys are separated from their values by a colon.
|
||
(2) You can override one or more of the highlight items:
|
||
guifg, guibg, ctermfg, ctermbg
|
||
|
||
========================================================================
|
||
SEARCHES AND THE AGENDA *vimorg-agenda* *vimorg-searches*
|
||
|
||
The agenda is a buffer where VimOrganizer gathers heading lines from
|
||
one or more buffers in response to various kinds of searches. The content
|
||
of the agenda doesn't just show you the results of your search, it also
|
||
gives you the means to quickly view or jump to any of the "found" headings,
|
||
as well as providing a means to remotely edit them, i.e., effect changes in
|
||
the original buffer by making changes in the agenda.
|
||
|
||
Here is how the Org-mode manual introduces the agenda:
|
||
-----------------------------------------
|
||
"Due to the way Org works, TODO items, time-stamped items,
|
||
and tagged headlines can be scattered throughout a file or
|
||
even a number of files. To get an overview of open action
|
||
items, or of events that are important for a particular
|
||
date, this information must be collected, sorted and
|
||
displayed in an organized way."
|
||
|
||
"Org can select items based on various criteria and display
|
||
them in a separate buffer. Seven different view types
|
||
are provided:"
|
||
|
||
"- an agenda that is like a calendar and shows
|
||
information for specific dates,
|
||
- a TODO list that covers all unfinished action items,
|
||
- a match view, showings headlines based on the tags,
|
||
properties, and TODO state associated with them,
|
||
- a timeline view that shows all events in a single
|
||
Org file, in time-sorted view,
|
||
[. . .]
|
||
- custom views that are special searches and
|
||
combinations of different views."
|
||
from http://orgmode.org/manual/Agenda-Views.html#Agenda-Views
|
||
------------------------------------------
|
||
|
||
VimOrganizer currently supports versions of the
|
||
above-mentioned agenda views, doesn't yet support the
|
||
'text search view' or the 'stuck projects view'.
|
||
|
||
---------------------------------------------------------------------------
|
||
AGENDA FILES *vimorg-agenda-files*
|
||
|
||
When VimOrganizer runs a search to generate an agenda view, it searches
|
||
files that are included in the 'agenda files' list. If a file in agenda
|
||
files list has not yet been loaded, it will be loaded as part of the
|
||
search.
|
||
|
||
The variable, g:agenda_files holds the list of agenda files.
|
||
You can enter values for g:agenda_files in your vimrc, e.g.,
|
||
>
|
||
:let g:agenda_files = ['c:/path/myfile1.org','c:/path/myfile2.org']
|
||
|
||
There is a bare-bones agenda-editing mechanism that works like this:
|
||
|
||
(1) Put your .org working directories in list g:agenda_dirs. Mine is in my
|
||
vimrc and includes a single directory:
|
||
>
|
||
:let g:agenda_dirs=["c:/users/herbert/documents/org-files"]
|
||
|
||
(2) Then to edit your agenda files issue this command
|
||
>
|
||
:EditAgendaFiles
|
||
<
|
||
This will open a new tab and show your current agenda files along with a list
|
||
of all org files in your agenda dirs. Simply copy or move files from the
|
||
agenda dirs list to the top and when done press :W (that's a capital 'W').
|
||
|
||
You can also use Vimscript to add files to g:agenda_files. For
|
||
example, putting something like the following lines in your vimrc would
|
||
always fill g:agenda_files upon startup:
|
||
>
|
||
let g:org_agenda_files = split(glob("~/documents/org_files/*.org"),"\n")
|
||
|
||
HINT: use the '+=' operator if you want to append these entries to those
|
||
already in g:org_agenda_files. E.g.,
|
||
>
|
||
let g:org_agenda_files += split(glob("~/documents/org_files/*.org"),"\n")
|
||
|
||
The 'agenda files dashboard' includes more commands that let you add,
|
||
remove, or rearrange files in the list of agenda files. You can bring
|
||
up this dashboard with the ',af' keymap, which will present these options:
|
||
|
||
e Edit agenda files
|
||
t Current file to top of agenda file list
|
||
b Current file to bottom of agenda file list
|
||
r Remove Current file from agenda file list
|
||
|
||
The 'agenda files dashboard' also has commands that let you navigate
|
||
among org buffers, see: |vimorg-files-navigating|
|
||
----------------------------------------------------------------------
|
||
THE AGENDA DASHBOARD *vimorg-agenda-dashboard*
|
||
|
||
The agenda_dashboard provides a user-interface for issuing different
|
||
kinds of agenda searches. Below is a list of the different commands
|
||
you can issue from the dashboard:
|
||
|
||
a This will search agenda files for headings with dates
|
||
that fall in the current week. The resulting agenda allows
|
||
you to issue more commands to change the view:
|
||
|
||
vd, vw, vm, vy -- Sets view period. The 'a'
|
||
command always starts with
|
||
a week view, but you can change
|
||
it to show single day (vd),
|
||
single month (vm), or year (vy).
|
||
[<num>]f, [<num>]b -- forward and backward to next
|
||
or previous view period. Optional
|
||
number prefix to specify number
|
||
of periods to jump. E.g., issuing
|
||
3f when view is a month view
|
||
of August 2011 would jump forward
|
||
three months and show month view
|
||
of November 2011.
|
||
|
||
t Assembles a list of headings marked as todo items. Top line
|
||
of agenda provides menu that allows you to press a number
|
||
to rerun the search limiting results to certain todo items.
|
||
UNFINISHED_TODOS will match whichever tags are before the '|'
|
||
in a buffer's todo spec, so may match multiple TODO items.
|
||
Likewise, FINISHED_TODOS will match whichever todos occur
|
||
_after_ the '|' in a buffer's todo setup.
|
||
|
||
m Tags/TODO/Property match. Prompts you for a search
|
||
specification in command line and retrieves headings
|
||
with matching metadata. See |vimorg-tags-search| .
|
||
|
||
c Show the 'custom searches' menu.
|
||
See |vimorg-agenda-custom-searches|
|
||
|
||
--------------------------------------------------------------------
|
||
AGENDA WINDOW POSITION *vimorg-agenda-window-position*
|
||
|
||
Location of the agenda window can be controlled by setting the
|
||
g:org_agenda_window_position variable. Possible values are
|
||
'top', 'bottom', 'left', 'right'. The default position is
|
||
'bottom'.
|
||
-------------------------------------------------------------------
|
||
INCLUDING CLOCKTABLE IN AGENDA *vimorg-agenda-include-clocktable*
|
||
|
||
You can have a clocktable included in agendas by setting the
|
||
variable below to 1 (default is 0). When set, agenda searches
|
||
that are of 'agenda' type (i.e., not just todo/tags/properties)
|
||
will include a clocktable after the regular view. The clocktable
|
||
will be for a period equal to the period of time shown
|
||
in the agenda view:
|
||
>
|
||
Include clocktable: g:org_agenda_include_clocktable = 1
|
||
Don't include: g:org_agenda_include_clocktable = 0
|
||
|
||
--------------------------------------------------------------------
|
||
KEYMAPPINGS IN THE AGENDA *vimorg-agenda-keys*
|
||
|
||
Some keys have special operation in the Agenda:
|
||
|
||
<enter> - pressing <enter> on a heading in agenda
|
||
will (1) switch (if necessary) to show
|
||
the chosen heading's buffer in window
|
||
above the agenda, (2) fully fold the
|
||
heading's entire buffer, and (3) position
|
||
buffer at heading and unfold the chosen
|
||
heading. The cursor remains in the agenda
|
||
but you can see the synched heading in
|
||
window above.
|
||
<ctl-enter> - Will stay in the Agenda's window and
|
||
switch to the chosen heading's buffer
|
||
with cursor positioned at heading.
|
||
<tab> - will toggle heading's text in its
|
||
original buffer (different from previous
|
||
versions where <tab> would toggle text
|
||
into the agenda buffer itself. . .)
|
||
<shift-tab> - Will cycle through the heading's todo
|
||
items, simultaneously also changing the
|
||
heading in its original buffer. The
|
||
cycling is smart enough to use the todo
|
||
setup of each original buffer, so
|
||
different headings in agenda may cycle
|
||
different todo items.
|
||
q - close agenda window
|
||
r - rerun the search, in case you have
|
||
changed data and want to get new
|
||
view. Will use dates and view of the
|
||
results currently showing in the fifth
|
||
line of the agenda, including a filter
|
||
specification, which may be changed
|
||
before refreshing. For example, to
|
||
refresh agenda to show only unfinished
|
||
todo items, change text after 'FILTER:'
|
||
to be +UNFINISHED_TODOS.
|
||
,d Invokes the date dashboard, allowing you
|
||
to remotely edit or add to the heading's dates
|
||
in the original buffer.
|
||
---------------------------------------------------------------
|
||
TAGS-TODO-PROPERTY SEARCH *vimorg-tags-search*
|
||
|
||
You can enter a tags/todo search that will search
|
||
various various parts of each heading's metadata
|
||
and return the results in the agenda.
|
||
Here are some examples that
|
||
illustrate the syntax:
|
||
>
|
||
Enter search string: +work
|
||
selects headlines tagged ':work:'
|
||
>
|
||
Enter search string: +work-boss
|
||
< selects headlines tagged ':work:', but
|
||
excludes those also tagged ':boss:'.
|
||
>
|
||
Enter search string: +work|+boss (or just work|boss)
|
||
< selects headlines tagged ':work:' or ':boss:'
|
||
>
|
||
Enter search string: +work|+laptop+night
|
||
< selects headlines tagged ':work:' or
|
||
both ':laptop:' and ':night:'
|
||
|
||
The examples above are search tags, but you can include
|
||
searches for todo items in the same way:
|
||
>
|
||
Enter search string: +work+TODO
|
||
< selects headlines tagged ':work:' that
|
||
are marked with 'TODO' status.
|
||
(e.g., * TODO My work item
|
||
:work: )
|
||
>
|
||
Enter search string: +work+DONE
|
||
< selects headlines tagged ':work:' that
|
||
are marked with 'DONE' status.
|
||
(e.g., * DONE My work item
|
||
:work: )
|
||
|
||
Instead of a tag, you may also specify a regular expression enclosed
|
||
in curly braces. For example:
|
||
>
|
||
Enter search string: +work+{boss.*}
|
||
< selects headlines that contain the tag ':work:'
|
||
and any tag starting with <20>:boss<73>. (Note: unlike
|
||
the similar search in Org-mode, there should be
|
||
_no_ initial '^'.)
|
||
|
||
You may also search for properties at the search string. Properties
|
||
may be ones you have entered yourself ( see |vimorg-properties| ) or
|
||
one of a set of special properties that all headings have. E.g.,
|
||
'LEVEL' is a built-in property that indicates the outline level of a
|
||
heading, so you could do this:
|
||
>
|
||
Enter search string: +work+LEVEL=2
|
||
< selects headlines at level 2 that are
|
||
also tagged ':work:'
|
||
|
||
Here is an example of a complex search string, which assumes
|
||
the user has entered a 'WITH' property and an 'EFFORT'
|
||
property for some headings:
|
||
>
|
||
+work-boss+EFFORT<2+WITH={Sarah\|George}+DEADLINE>="2011-11-13"
|
||
<
|
||
The type of comparison done depends on how the comparison value is written:
|
||
|
||
- If the comparison value is a plain number, a numerical comparison is
|
||
done, and the allowed operators are <20><<3C>, <20>=<3D>, <20>><3E>, <20><=<3D>, <20>>=<3D>, and
|
||
<20>!=<3D>.
|
||
- If the comparison value is enclosed in double-quotes, a string
|
||
comparison is done, and the same operators are allowed.
|
||
- If the comparison value is enclosed in double-quotes and angular
|
||
brackets (like <20>DEADLINE<="<2008-12-24 18:30>"<22>), both values are
|
||
assumed to be date/time specifications in the standard way,
|
||
and the comparison will be done accordingly.
|
||
- If the comparison value is enclosed in curly braces, a regexp match
|
||
is performed, with <20>=<3D> meaning that the regexp matches the property
|
||
value, and <20>!=<3D> meaning that it does not match.
|
||
|
||
---------------------------------------------------------------
|
||
CUSTOM SEARCHES *vimorg-agenda-custom-searches*
|
||
|
||
Any number of custom searches can be defined and accessed from the
|
||
'custom searches' menu, which can be accessed from the agenda
|
||
dashboard, from the Org menu in gvim, or directly via the ,ac
|
||
keymapping.
|
||
|
||
Custom searches are stored in a list variable:
|
||
'g:org_custom_searches'. You create new custom searches
|
||
by adding them to that list. Here is an example an assigment
|
||
that could be put in your vimrc to define a number of custom
|
||
searches, which I will explain below:
|
||
>
|
||
let g:org_custom_searches = [
|
||
\ { 'name':"Next week's agenda", 'type':'agenda',
|
||
\ 'agenda_date':'+1w', 'agenda_duration':'w' }
|
||
\ ,{ 'name':"Next week's TODOS", 'type':'agenda',
|
||
\ 'agenda_date':'+1w', 'agenda_duration':'w',
|
||
\ 'spec':'+UNFINISHED_TODOS' }
|
||
\ ,{ 'name':'Home tags', 'type':'tags', 'spec':'+HOME' }
|
||
\ ,{ 'name':'Home tags', 'type':'sparse_tree', 'spec':'+HOME' }
|
||
\ ,[ { 'name':"Next week's agenda", 'type':'agenda',
|
||
\ 'agenda_date':'+1w', 'agenda_duration':'w' }
|
||
\ ,{ 'name':'Home tags', 'type':'tags', 'spec':'+HOME' }
|
||
\ ]
|
||
\ ]
|
||
<
|
||
The assignment above creates five different custom searches.
|
||
Basic searches are dictionaries containing key/value items that
|
||
specify the search. Each search must be given a name and a type.
|
||
|
||
AGENDA-TYPE CUSTOM SEARCHES *vimorg-custom-agenda*
|
||
----------------------------
|
||
The first two searches are 'agenda' type searches, which means their
|
||
results are shown in the agenda organized by date with same
|
||
functionality as the usual agenda view. You have to assign a
|
||
name and specify their 'type' as 'agenda'; their other values
|
||
described below ('agenda-date', 'agenda-duration', and 'spec')
|
||
are optional.
|
||
|
||
The 'agenda-date' value defines the starting date. This date may be
|
||
specified explicitly, (e.g., '2012-01-13') or you can use any cue
|
||
that works on the date-time prompt command line (e.g., '+1w' for
|
||
starting date of 1 week from today, '+36d', '-1y', '+24m', etc.
|
||
-- most of the cues here are supported:
|
||
http://orgmode.org/manual/The-date_002ftime-prompt.html#The-date_002ftime-prompt
|
||
|
||
The agenda-duration value defaults to a week ('w') if not specified,
|
||
but you can otherwise assign a number to represent the number of days
|
||
that should be displayed in the agenda view.
|
||
|
||
The 'spec' in an agenda-type search allows you to specify additonal
|
||
restrictions on headings that will be included in the agenda view.
|
||
This 'spec' works identically to the specification for ad-hoc
|
||
searches that you can enter from the agenda-dashboard, see:
|
||
|vimorg-tags-search|.
|
||
|
||
TAGS-TYPE CUSTOM SEARCHES *vimorg-custom-tags*
|
||
-------------------------
|
||
These searches are like the 'TAGS/PROPS/TODO' queries that you can
|
||
specify on the fly from the agenda dashboard. You have to
|
||
specify a name, the 'type' of 'tags', and then the 'spec' for the
|
||
search. 'Spec' works just as described here:
|
||
|vimorg-tags-search|.
|
||
|
||
SPARSETREE TYPE CUSTOM SEARCHES *vimorg-custom-sparse_tree*
|
||
--------------------------------
|
||
The fourth search in the above assignment to g:org_custom_searches is
|
||
has the 'name' of 'Home tags' and is a search of 'type' 'sparse_tree'.
|
||
This search is a pre-defined version of a search that can be run as a
|
||
'Freeform . . . sparse tree search' from the agenda dashboard. 'Spec'
|
||
works the same as it does for other searches.
|
||
|
||
BLOCK SEARCHES *vimorg-agenda-block-search*
|
||
--------------
|
||
The first four searches assigned to g:org_custom_searches, above, are
|
||
"simple" searches, in that they pre-define searches that correspond to
|
||
one of the agenda views accessible from the agenda dashboard.
|
||
Pre-defined block searches allow you to include the results of two or
|
||
more "simple" searches in a single agenda view. These searches are
|
||
defined by adding a list item in square brackes '[]' to
|
||
g:org_custom_searches, which contains two or more dictionaries
|
||
specifying agenda-type or tags-type simple searches.
|
||
|
||
==============================================================================
|
||
NAVIGATING AMONG ORG FILES *vimorg-files-navigating*
|
||
|
||
VimOrganizer provides several ways of moving directly between org files,
|
||
which are often preferable to using built-in Vim commands. This is
|
||
largely because VimOrganizer works best when all org files are open
|
||
on separate tabs (see Note 2 below). Most of these
|
||
VimOrganizer commands work between files included in the list of 'agenda
|
||
files'. The commands are listed on the 'agenda files' dashboard:
|
||
|
||
Key mapping Operation
|
||
,af Show 'agenda files' dashboard
|
||
|
||
Here is the 'agenda files' dashboard:
|
||
>
|
||
Press key for an agenda files command:
|
||
--------------------------------------
|
||
e Edit agenda files
|
||
t Current file to top of agenda file list
|
||
b Current file to bottom of agenda file list
|
||
r Remove Current file from agenda file list
|
||
n or f Cycle to next file in agenda files
|
||
p or b Cycle to previous file in agenda files
|
||
c or g Choose agenda file or org file to goto
|
||
|
||
Note 1: The 'c or g' choice above provides a list of open org buffers; it is
|
||
_not_ limited to the list of agenda files.
|
||
|
||
Note 2: You can of course use any means Vim provides to navigate among
|
||
Org buffers. Because of the way VimOrganizer works, however, you may want
|
||
to keep org files open on different tabs rather than switching to different
|
||
buffers within the current window. VimOrganizer depends on folding that
|
||
must be recalculated whenever a buffer is loaded into a window. For large
|
||
files these recalculations can take several seconds, thus making quick
|
||
navigation between buffers in the same window impossible. This problem
|
||
is avoided if you keep org files open on different tabs, where switching
|
||
between them is instantaneous. Many Vim plugins are available to
|
||
make file/buffer navigation faster and easier (e.g., Fuzzy Finder,
|
||
BufExplorer, etc.). If you use a plugin you will probably want to configure it
|
||
so that the default method of switching to a buffer is to move to a tab
|
||
with the desired buffer (rather than moving to new buffer while staying
|
||
in current window).
|
||
|
||
==============================================================================
|
||
COLUMN VIEW *vimorg-column-view*
|
||
|
||
Column view in VimOrganizer is similar to the feature having the same name
|
||
in Org-mode, but different in important ways. At its core it simply offers
|
||
a way to reveal data about a heading when it is displayed as a fold.
|
||
Folded heading lines in Vim are not directly editable. (A user interface
|
||
to allow easy editing of columns/properties is on VimOrganizer's todo list.)
|
||
|
||
The default display in VimOrganizer (i.e., colmns off) merely shows the
|
||
number of lines in a fold along the right margin. Column view can be turned
|
||
on or off in each buffer, but to make each buffer default to on you can place
|
||
this line in your vimrc:
|
||
>
|
||
let g:global_column_view = 1
|
||
|
||
Specification of COLUMNS is similar to Org-mode, except that ITEM is
|
||
always included, although length settings for ITEM are always ignored.
|
||
This is because the ITEM display is automatically truncated to make
|
||
space for the other columns, and ITEM will automatically expand or
|
||
contract if you resize the Vim window. The column definition string
|
||
format is identical to that used by Org-mode, although the optional
|
||
'summary-type' attribute is currently ignored in VimOrganizer. See:
|
||
http://orgmode.org/manual/Defining-columns.html#Defining-columns
|
||
|
||
The built-in global default for column view is to show any TAGS flush
|
||
left in a 35 character column. You can modify that be setting a global
|
||
default in your vimrc. The built-in default would look like this:
|
||
>
|
||
let g:global_column_defaults = '%ITEM %35TAGS'
|
||
|
||
A default that would show the DEADLINE value in addition to TAGS might
|
||
look like this:
|
||
>
|
||
let g:global_column_defaults = '%ITEM %15DEADLINE %30TAGS'
|
||
|
||
--------------------------------------------------------------------------
|
||
COLUMNS DASHBOARD *vimorg-columns-dashboard*
|
||
|
||
You can access the column dashboard by pressing ,m or by entering the command
|
||
:OrgColumns. The dashboard shows you the current relevant settings and
|
||
allows you to change them:
|
||
|
||
buffer default columns -- These defaults are taken either
|
||
from the global defaults, or from the
|
||
settings in a columns configuration
|
||
line in a document.
|
||
current default columns -- The current settings, which may reflect
|
||
custom default settings
|
||
column view on -- Will be ON/OFF
|
||
Show column headers -- Will be ON/OFF
|
||
heading line count -- Will be ON/OFF, refers to whether the
|
||
count of heading lines shows at right
|
||
margin for a folded heading. Can be
|
||
ON even if column view is OFF.
|
||
>
|
||
Operations on Columns dashboard
|
||
-----------------------
|
||
f -- Force all of buffer to use settings. If
|
||
not chosen then (1) only the current subtree will be
|
||
placed into column, or (2) entire buffer
|
||
will be in column view if cursor is in
|
||
front of the first heading in the document.
|
||
r -- Revert to buffer defaults, if defaults have
|
||
been changed
|
||
t -- Toggle column view ON/OFF
|
||
h -- Toggle column headings ON/OFF
|
||
l -- Toggle line count ON/OFF
|
||
<
|
||
*org_columns_custom_list*
|
||
Custom column options will then be listed. If no custom options have
|
||
been assigned in the vimrc, then built-in behavior is to have two
|
||
options as if the user had the line below in their vimrc. This line
|
||
defines a list of two custom column strings, one having a
|
||
DEADLINE and a TAGS column, the second having just a DEADLINE column:
|
||
>
|
||
let *g:org_custom_column_options* = ['%ITEM %14DEADLINE %30TAGS',
|
||
\ '%ITEM %14DEADLINE']
|
||
<
|
||
g:org_custom_column_options is a list containing column format
|
||
strings. Each format string will be listed on the dashboard
|
||
with a number in front of it, and can be accessed by pressing
|
||
the key for that number (0-9). The format strings are constructed of
|
||
pairs of 'metadata field,format for field' with additional pairs
|
||
also separated by commas. The format options used are the same as those
|
||
of the |printf| function, which is used to format the columns internally.
|
||
--------------------------------------------------------------------------
|
||
COLUMNS CONFIG LINE *vimorg-columns-config-line*
|
||
|
||
Any document may have a line that sets the default column settings
|
||
for the document. This will override any global default that has been
|
||
set. The format allows for a single string, with settings like
|
||
those described above for g:org_custom_column_options. An example
|
||
COLUMNS config would look like this. Note that the '#' must be in the
|
||
leftmost column of the text:
|
||
>
|
||
#+COLUMNS: DEADLINE,%-14s,TAGS,%-30s
|
||
|
||
---------------------------------------------------------------------
|
||
COLUMNS PROPERTY *vimorg-columns-property*
|
||
|
||
Columns properties work like how they work in Org-mode. You can set
|
||
a COLUMNS property in the property block of a heading. That setting
|
||
will (1) override any default or custom settings for the buffer (unless
|
||
you enter a buffer-wide columns mode with cursor not on the heading), and
|
||
(2) be inherited by subheadings of of that heading. (Also, you
|
||
can force entire buffer to use a headings COLUMNS property by
|
||
choosing 'f' on columns dashboard.) For example, entering columns
|
||
mode withe the cursor on 'Heading One' below below would display
|
||
folded lines with just a DEADLINE column, regardless of what the
|
||
settings were in the rest of the document:
|
||
>
|
||
* Heading One
|
||
:PROPERTIES:
|
||
:COLUMNS: %ITEM %14DEADLINE
|
||
:END:
|
||
** Subhead One
|
||
Text for Subhead One
|
||
** Subhead Two
|
||
Some text for Subhead Two
|
||
|
||
==============================================================================
|
||
VIMORGANIZER EXPORT *vimorg-export*
|
||
*vimorg-print*
|
||
*vimorg-export-to-html*
|
||
*vimorg-export-to-pdf*
|
||
|
||
VimOrganizer calls out to Org-mode in Emacs for all exports. To print
|
||
a VimOrganizer file the recommended method is to export to a format that
|
||
is better for printing.
|
||
|
||
The Export Dashboard can be opened from the menu in gvim ('Export/Publish')
|
||
or with the key mapping |,x| .
|
||
The VimOrganizer Export Dashboard is similar to Org-mode's export
|
||
dispatcher, and the best way to learn about it is to read the Org-mode
|
||
documentation:
|
||
http://orgmode.org/manual/Exporting.html#Exporting
|
||
|
||
*vimorg-export-microsoft-word*
|
||
*vimorg-export-opendocument*
|
||
*vimorg-export-openoffice*
|
||
*vimorg-export-docx*
|
||
The Export Dashboard includes an option for export to OpenDocument
|
||
format. This option creates an odt document that can then be
|
||
edited by (recent version) of Microsoft Word or OpenOffice.
|
||
Once into Word, OpenOffice, or LibreOffice the document can
|
||
be saved as a .doc or .docx file.
|
||
Export of items into odt supports objects like images, tables,
|
||
and footnotes in addition to highlighting and other simple formatting.
|
||
The odt export currently (November 2011) requires special configuration
|
||
of your Emacs install. Instructions are here:
|
||
http://orgmode.org/manual/OpenDocumentText-export.html#OpenDocumentText-export
|
||
|
||
*vimorg-publishing*
|
||
As in Org-mode, VimOrganizer's Export Dashboard also includes
|
||
options for "publishing" a project. A "project" is a set of
|
||
related documents that you set up to be automatically exported
|
||
together, which is called "publishing" the project. The
|
||
publishing options on the VimOrganizer's Export Dashboard
|
||
simply call Emacs to process files so the Org-mode documentation for
|
||
publishing is best way to learn about them. Setting up a project
|
||
requires some fairly simple configuration using lisp statements
|
||
added to the .emacs file, which is Emacs' counterpart to Vim's vimrc:
|
||
http://orgmode.org/manual/Publishing.html#Publishing
|
||
|
||
*vimorg-tangling*
|
||
*vimorg-literate-programming*
|
||
Another option on the Export Dashboard is 'tangle'. This operation
|
||
extracts source code blocks from an org document and saves them so
|
||
they're in a format that can be (1) executed by an interpreter or
|
||
(2) compiled, depending on the source block language. This provides
|
||
a way to use VimOrganizer as an editor for 'literate programming'.
|
||
See: http://en.wikipedia.org/wiki/Literate_programming
|
||
Documentation for tangling can be found in Org-mode's manual:
|
||
http://orgmode.org/manual/Extracting-source-code.html#Extracting-source-code
|
||
|
||
*vimorg-export-options*
|
||
Finally, one option on the Export Dashboard simply inserts a template
|
||
of option lines into your document. This template can be inserted anywhere
|
||
in your document, but is typically placed at the very beginning. It
|
||
provides a default set of export-related options that you can modify
|
||
as you wish. For more information on all the options see this page:
|
||
http://orgmode.org/manual/Export-options.html#Export-options
|
||
|
||
|
||
==============================================================================
|
||
VIMORGANIZER FEEDBACK *vimorg-feedback*
|
||
|
||
Feedback is always welcome. If you like the plugin, please rate it at the
|
||
vim-page:
|
||
http://www.vim.org/scripts/script.php?script_id=3075
|
||
|
||
You can also follow the development of the plugin at github:
|
||
http://github.com/hsitz/VimOrganizer
|
||
|
||
Please don't hesitate to report any bugs to the maintainer, mentioned in the
|
||
third line of this document.
|
||
|
||
==============================================================================
|
||
Modeline:
|
||
vim:tw=78:ts=8:ft=help:nowrap:et
|