Gaze/SpaceVim
1
0
Fork 0
mirror of https://github.com/SpaceVim/SpaceVim.git synced 2025-01-24 02:50:03 +08:00
Code Issues Projects Releases Wiki Activity
0d66e31934
SpaceVim/bundle/org-mode/doc/vimorg.txt
wsdjeg 1470aa788a refactor(org): use bundle org plugin
2022-01-15 22:22:23 +08:00

1834 lines
85 KiB
Plaintext
Raw Blame History

*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
Reference in New Issue View Git Blame Copy Permalink