Merge branch 'akstrfn-some_refactoring'

Author: Ron89

CHANGELOG.org

@@ -4,6 +4,7 @@
   This log is kept according to the [[http://keepachangelog.com/][Keep a CHANGELOG]] manifesto
 ** 0.6.0                  					 :unreleased:
 *** Added
+    - Introduced sphinx documentation to Python modules. (PR #237)
     - Add =Python3= support. (closes issue #226, merge PR #231)
     - Implementing agenda overview for current buffer. (merges PR #229)
     - =g:org_aggressive_conceal=, if value =1=, will conceal all simple format
@@ -17,6 +18,7 @@
     - Add export as LaTeX beamer slides (merges PR #206)
     - Keybinding to create plainlist item directly. (closes issue #190)
 *** Changed
+    - Revamped TODO keyword cycling rules. (PR #237)
     - In [[syntax/org.vim][syntax/org.vim]], changed `\@<=' with computational faster `\zs'
     - Using =<localleader>c[n/N]= to create new plainlist item following
       current plainlist item. Now these keybindings will unconditionally

README.org

@@ -18,10 +18,10 @@
   [[https://github.com/jceb/vim-orgmode/blob/master/examples/mylife.org][file:examples/mylife.gif]]
 
 ** Features
-   vim-orgmode is still very young but already quite usable. Here is a short
-   list of the already supported features:
+   Currently vim-orgmode does not support all ormode features but is quite
+   usable. Short list of the already supported features:
 
-   - Proper syntax highlighting
+   - Syntax highlighting
    - Cycle visibility of headings (folding)
    - Navigate between headings
    - Edit the structure of the document: add, move, promote, denote headings
@@ -33,8 +33,6 @@
    - Basic date handling
    - Export to other formats (via Emacs' Org-Mode)
 
-   More features are coming...
-
 * Installation and Usage
   Installation and usage instructions are found in the file [[doc/orgguide.txt][doc/orgguide.txt]].
 

doc/orgguide.txt

@@ -75,32 +75,32 @@ line tools*.
 
 ------------------------------------------------------------------------------
 Preface~
-   vim-orgmode is a file type plugin for keeping notes, maintaining TODO
-   lists, and doing project planning with a fast and effective plain-text
-   system. It is also an authoring and publishing system.
+  vim-orgmode is a file type plugin for keeping notes, maintaining TODO
+  lists, and doing project planning with a fast and effective plain-text
+  system. It is also an authoring and publishing system.
 
-   This document is a copy of the orgmode-guide for emacs
-   (http://orgmode.org/) with modifications for vim. It contains all basic
-   features and commands, along with important hints for customization.
+  This document is a copy of the orgmode-guide for emacs
+  (http://orgmode.org/) with modifications for vim. It contains all basic
+  features and commands, along with important hints for customization.
 
-   To start create a new file with the extension ".org".
+  To start create a new file with the extension ".org".
 
 ------------------------------------------------------------------------------
 Features~
-  vim-orgmode is still very young but already quite usable. Here is a short
-  list of the already supported features:
+  Currently vim-orgmode does not support all ormode features but is quite
+  usable. Short list of the already supported features:
 
-  - Cycle visibility of headings
+  - Syntax highlighting
+  - Cycle visibility of headings (folding)
   - Navigate between headings
   - Edit the structure of the document: add, move, promote, denote headings
     and more
   - Hyperlinks within vim-orgmode and outside (files, webpages, etc.)
   - TODO list management
   - Tags for headings
+  - Lists in alphanumeric and bullet item notation and checkbox support
   - Basic date handling
-  - Export (via emacs)
-
-  More features are coming...
+  - Export to other formats (via emacs)
 
 ------------------------------------------------------------------------------
 Default mappings~
@@ -204,7 +204,7 @@ Inline markup~
 
   Note:
   - /italic/ is rendered as reverse in most terms (works fine in gVim, though)
-  - +strike-through+ doesn't work on Vim / gVim
+  - +strike-through+ doesn't work on Vim / GVim
   - the non-standard `code' markup is also supported
   - =code= and ~verbatim~ are also supported as block-level markup, see below.
 
@@ -222,27 +222,24 @@ INSTALLATION AND UPGRADE                                 *orgguide-installation*
 >
     :so %
 <
-
   ATTENTION: All .pyc files of former versions of vim-orgmode need to be
   deleted beforehand!
 
   Add the following line to your .vimrc file to ensure that filetype plugins
   are loaded properly:
 >
-  filetype plugin indent on
+    filetype plugin indent on
 <
+  Installation can also be done with plugin managers that automatically pull
+  dependencies i.e. vim-plug (https://github.com/junegunn/vim-plug), dein.vim
+  (https://github.com/Shougo/dein.vim).
 
-  Please install the Universal Text Linking
-  (http://www.vim.org/scripts/script.php?script_id=293) add-on, otherwise
-  hyperlinks won't work. Other plugins that integrate well with vim orgmode
-  are listed in the following section.
-
-  Note: If you want to insert timestamp by using a calendar, you should
-  install calendar(https://github.com/mattn/calendar-vim) to
-  enable this feature.
+  NOTE: For some functionality vim-orgmode relies on external plugins which
+  are mentioned in suggested plugins.
 
 ------------------------------------------------------------------------------
 Suggested plugins~
+
   Universal Text Linking~
     (http://www.vim.org/scripts/script.php?script_id=293) general support for
     text linking. The hyperlinks feature of vim-orgmode depends on this
@@ -284,7 +281,8 @@ Suggested plugins~
 
   SyntaxRange~
     (http://www.vim.org/scripts/script.php?script_id=4168)
-    Use proper syntax highlighting for code blocks such as: >
+    Use proper syntax highlighting for code blocks such as:
+>
     #+BEGIN_SRC cpp
     int i = 1;
     #+END_SRC
@@ -311,6 +309,7 @@ Outlines~
 
 ------------------------------------------------------------------------------
 Headlines~
+
   Headlines define the structure of an outline tree. The headlines in
   vim-orgmode start with one or more stars, on the left margin. For example:
 >
@@ -333,6 +332,7 @@ Headlines~
 
 ------------------------------------------------------------------------------
 Text objects~
+
   Vim offers a mighty feature called |text-objects|. A text object is bound to
   a certain character sequence that can be used in combination with all kinds
   of editing and selection tasks.
@@ -547,6 +547,7 @@ Internal links~
 
 ------------------------------------------------------------------------------
 External links~
+
   |utl| supports links to files and websites. Others can be added by extending
   utl (see |utl-smartSamples|).  External links are URL-like locators. They
   start with a short identifying string followed by a colon. There can be no
@@ -566,6 +567,7 @@ External links~
 
 ------------------------------------------------------------------------------
 Handling links~
+
   vim-orgmode provides methods to create a link in the correct syntax, to
   insert it into an org file, and to follow the link.
 
@@ -684,7 +686,7 @@ Multi-state workflows~
   of which subsequence should be used for a given entry. The example also
   shows how to define keys for fast access of a particular state, by
   adding a letter in parenthesis after each keyword - you will be prompted
-  for the key after pressing ,d.
+  for the key after pressing <LocalLeader>d.
 
                                                        *orgguide-<LocalLeader>d*
   <LocalLeader>d        prompt for fast access of a todo state
@@ -832,7 +834,7 @@ Timestamps~
   A timestamp is a specification of a date (possibly with a time or a range of
   times) in a special format, either <2003-09-16 Tue> or <2003-09-16 Tue
   09:39> or <2003-09-16 Tue 12:00-12:30>. A timestamp can appear anywhere in
-  the headline or body of an org tree entry.  Its presence causes entries to
+  the headline or body of an org tree entry. Its presence causes entries to
   be shown on specific dates in the agenda (see section |orgguide-agenda|). We
   distinguish:
 
@@ -902,8 +904,11 @@ Creating timestamps~
   When vim-orgmode prompts for a date/time, it will accept any string
   containing some date and/or time information, and intelligently interpret
   the string, deriving defaults for unspecified information from the current
-  date and time. See the manual for more information on how exactly the
-  date/time prompt works.
+  date and time.
+    Example~
+      If the current date is <2016-06-14 Tue>, entering +3 at the prompt will
+      insert the date <2016-06-17 Fri>, entering sat will insert date
+      <2016-06-18 Sat>
 
   You can also select a date in the pop-up calendar.
   NOTE: The plugin 'calendar' should be installed for this feature.

ftplugin/org.vim

@@ -6,7 +6,18 @@
 " @Revision     : 0.4
 " vi: ft=vim:tw=80:sw=4:ts=4:fdm=marker
 
-if ! (has('python3') || has('python')) || v:version < 703
+if v:version > 702
+	if has('python3')
+		let s:py_version = 'python3 '
+		let s:py_env = 'python3 << EOF'
+	elseif has('python')
+		let s:py_version = 'python '
+		let s:py_env = 'python << EOF'
+	else
+		echoerr "Unable to start orgmode. Orgmode depends on Vim >= 7.3 with Python support complied in."
+		finish
+	endif
+else
 	echoerr "Unable to start orgmode. Orgmode depends on Vim >= 7.3 with Python support complied in."
 	finish
 endif
@@ -31,11 +42,7 @@ if ! exists('b:did_ftplugin')
 
 	" register keybindings if they don't have been registered before
 	if exists("g:loaded_org")
-		if has('python3')
-			python3 ORGMODE.register_keybindings()
-		else
-			python ORGMODE.register_keybindings()
-		endif
+		exe s:py_version . 'ORGMODE.register_keybindings()'
 	endif
 endif
 
@@ -71,40 +78,20 @@ endif
 
 " Menu and document handling {{{1
 function! <SID>OrgRegisterMenu()
-	if has('python3')
-		python3 ORGMODE.register_menu()
-	else
-		python ORGMODE.register_menu()
-	endif
+	exe s:py_version . 'ORGMODE.register_menu()'
 endfunction
 
 function! <SID>OrgUnregisterMenu()
-	if has('python3')
-		python3 ORGMODE.unregister_menu()
-	else
-		python ORGMODE.unregister_menu()
-	endif
+	exe s:py_version . 'ORGMODE.unregister_menu()'
 endfunction
 
-if has('python3')
-function! <SID>OrgDeleteUnusedDocument(bufnr)
-python3 << EOF
-b = int(vim.eval('a:bufnr'))
-if b in ORGMODE._documents:
-	del ORGMODE._documents[b]
-EOF
-endfunction
-
-else
-
 function! <SID>OrgDeleteUnusedDocument(bufnr)
-python << EOF
+	exe s:py_env
 b = int(vim.eval('a:bufnr'))
 if b in ORGMODE._documents:
 	del ORGMODE._documents[b]
 EOF
 endfunction
-endif
 
 " show and hide Org menu depending on the filetype
 augroup orgmode
@@ -115,8 +102,7 @@ augroup END
 
 " Start orgmode {{{1
 " Expand our path
-if has('python3')
-python3 << EOF
+exec s:py_env
 import vim, os, sys
 
 for p in vim.eval("&runtimepath").split(','):
@@ -129,30 +115,9 @@ for p in vim.eval("&runtimepath").split(','):
 from orgmode._vim import ORGMODE, insert_at_cursor, get_user_input, date_to_str
 ORGMODE.start()
 
-from Date import Date
 import datetime
 EOF
 
-else
-
-python << EOF
-import vim, os, sys
-
-for p in vim.eval("&runtimepath").split(','):
-	dname = os.path.join(p, "ftplugin")
-	if os.path.exists(os.path.join(dname, "orgmode")):
-		if dname not in sys.path:
-			sys.path.append(dname)
-			break
-
-from orgmode._vim import ORGMODE, insert_at_cursor, get_user_input, date_to_str
-ORGMODE.start()
-
-from Date import Date
-import datetime
-EOF
-endif
-
 " 3rd Party Plugin Integration {{{1
 " * Repeat {{{2
 try
@@ -182,20 +147,20 @@ endif
 fun CalendarAction(day, month, year, week, dir)
 	let g:org_timestamp = printf("%04d-%02d-%02d Fri", a:year, a:month, a:day)
 	let datetime_date = printf("datetime.date(%d, %d, %d)", a:year, a:month, a:day)
-	exe "py selected_date = " . datetime_date
+	exe s:py_version . "selected_date = " . datetime_date
 	" get_user_input
 	let msg = printf("Inserting %s | Modify date", g:org_timestamp)
-	exe "py modifier = get_user_input('" . msg . "')"
+	exe s:py_version . "modifier = get_user_input('" . msg . "')"
 	" change date according to user input
-	exe "py print modifier"
-	exe "py newdate = Date._modify_time(selected_date, modifier)"
-	exe "py newdate = date_to_str(newdate)"
+	exe s:py_version . "print modifier"
+	exe s:py_version . "newdate = Date._modify_time(selected_date, modifier)"
+	exe s:py_version . "newdate = date_to_str(newdate)"
 	" close Calendar
 	exe "q"
 	" goto previous window
 	exe "wincmd p"
-	exe "py timestamp = '" . g:org_timestamp_template . "' % newdate"
-	exe "py insert_at_cursor(timestamp)"
+	exe s:py_version . "timestamp = '" . g:org_timestamp_template . "' % newdate"
+	exe s:py_version . "insert_at_cursor(timestamp)"
 	" restore calendar_action
 	let g:calendar_action = g:org_calendar_action_backup
 endf