diff --git a/README.markdown b/README.markdown index 02192bb..1913c27 100644 --- a/README.markdown +++ b/README.markdown @@ -1,97 +1,136 @@ -# Readme +# Todo.txt-vim -**Note:** Since v0.7.3, `TodoComplete` is `todo#Complete`, you might need to -update your vimrc. + ##### # # + # #### ##### #### ##### # # ##### # # # # # + # # # # # # # # # # # # # # ## ## + # # # # # # # # ## # ### # # # # ## # + # # # # # # # # ## # # # # # # + # # # # # # # ## # # # # # # # # # + # #### ##### #### ## # # # # # # # # -## What is this plugin ? + Efficient Todo.txt management in vim + +## Table of Contents + +1. [Release notes](#release-notes) +2. [Introduction](#introduction) + 1. [Todo.txt rules](#todo.txt-rules) + 2. [Why this Fork ?](#Why-this-fork-?) + 3. [Installation](#installation) +3. [TodoTxt Files](#todotxt-files) +4. [Completion](#completion) +5. [Hierarchical Sort](#hierarchical-sort) +6. [Mappings](#mappings) + 1. [Sort](#sort) + 2. [Priorities](#priorities) + 3. [Dates](#dates) + 4. [Done](#done) + +## Release notes + +Since v0.7.3, `TodoComplete` is replaced by `todo#Complete`, you might need to +update your vimrc (see [completion](#completion)). + +## Introduction + +Todo.txt-vim is a plugin to manage todo.txt files it was initially designed by +[Freitass](https://github.com/freitass/todo.txt-vim) then forked and improved +by David Beniamine. + +### Todo.txt rules + +Todo.txt is a standard human readable todo notes file defined [here](http://todotxt.com): + +"The todo.txt format is a simple set of +[rules](https://github.com/ginatrapani/todo.txt-cli/wiki/The-Todo.txt-Format) +that make todo.txt both human and machine-readable. The format supports +priorities, creation and completion dates, projects and contexts. That's +all you need to be productive. See an example Todo.txt file": + + (A) Call Mom @Phone +Family + (A) Schedule annual checkup +Health + (B) Outline chapter 5 +FamilyNovel @Computer + (C) Add cover sheets @ComputerOffice +FamilyTPSReports + Plan backyard herb garden @ComputerHome + Pick up milk @ComputerGroceryStore + Research self-publishing services +FamilyNovel @ComputerComputer + x Download Todo.txt mobile app @ComputerPhone + +### Why this fork ? This plugin is a fork of [freitass -todo.txt](https://github.com/freitass/todo.txt-vim). It add severals -functionalities including a [hierarchical sort](#sort), a -[complete](#completion) function, some stuff to handle [due -dates](#due-dates), a more [flexible file naming](#flexible-file-naming), and -others stuff see [new features](#new-features). +todo.txt-vim](https://github.com/freitass/todo.txt-vim). It add severals cool +functionalities including: -Freitass announced on october 30th 2014 that he is not going to merge his version. ++ [Hierarchical sort](##hierarchical-sort) ++ [A completion function](#completion) ++ [A proper handling of due dates](#dates) ++ [A Flexible file naming](#todotxt-files). ++ Syntax Highlight for couples key:value. ++ `x` is a toggle which allow you to unmark a task as done. ++ `C` Toggle Mark a task cancelled ++ If the current buffer is a done.txt file, the basic sort sorts on + completion date. ++ ... -## Install +### Installation -### Vizardry +#### Vizardry -If you have [Vizardry](https://github.com/dbeniamine/vizardry) installed, you -can run from vim: +If you have [Vizardry](https://github.com/dbeniamine/vizardry) installed, +you can run from vim: :Invoke -u dbeniamine todo.txt-vim -### Pathogen install +#### Pathogen install git clone https://github.com/dbeniamine/todo.txt-vim.git ~/.vim/bundle/todo.txt-vim Then from vim: `:Helptags` to update the doc -### Quick install +#### Quick install - git clone https://github.com/dbeniamine/todo.txt-vim.git - cd todo.txt-vim - cp -r ./* ~/.vim + git clone https://github.com/dbeniamine/todo.txt-vim.git + cd todo.txt-vim + cp -r ./* ~/.vim If you want the help installed, run `:helptags ~/.vim/doc` inside vim after having copied the files. Then you will be able to get the commands help with: `:h todo.txt` -## Features included in Freitass version +## TodoTxt Files -This plugin gives syntax highlighting to [todo.txt](http://todotxt.com/) files. It also defines a few mappings, to help with editing these files: +This plugin provides a Flexible file naming for todo.txt, all the following +names are recognized as todo: -`s` : Sort the file + YYYY-MM-[Tt]odo.txt + YYYY-MM-DD[Tt]odo.txt + [Tt]odo-YYYY-MM.txt + [Tt]odo-YYYY-MM-DD.txt + [Tt]odo.txt + [Tt]oday.txt -`s+` : Sort the file on +Projects +And obviously the same are recognize as done: -`s@` : Sort the file on @Contexts + YYYY-MM-[Dd]one.txt + YYYY-MM-DD[Dd]one.txt + [Dd]one-YYYY-MM.txt + [Dd]one-YYYY-MM-DD.txt + [Dd]one.txt + [Dd]one-[Tt]oday.txt -`j` : Lower the priority of the current line +Moreover, `D` moves the task under the cursor to the done.txt +file corresponding to the current todo.txt, aka if you are editing +2015-07-07-todo.txt, the done file while be 2015-07-07-done.txt. If you don't +like this behavior, you can set the default done.txt name: -`k` : Increase the priority of the current line + let g:TodoTxtForceDoneName='done.txt' -`a` : Add the priority (A) to the current line +## Completion -`b` : Add the priority (B) to the current line - -`c` : Add the priority (C) to the current line - -`d` : Insert the current date - -`date` : (Insert mode) Insert the current date - -`x` : Toggle mark task as done (inserts current date as completion date) - -`X` : Mark all tasks as completed - -`-D` : Move completed tasks to done.txt - -## New features - -### Sort - -This fork provides a hierarchical sorting function designed to do by project -and/or by context sorts and a priority sort. - -`sc` : Sort the file by context then by priority -`scp` : Sort the file by context, project then by priority -`sp` : Sort the file by project then by priority -`spc` : Sort the file by project, context then by priority - -The user can give argument for the two call to vim sort function by changing -the following variables in its vimrc: -see :help sort - let g:Todo_txt_first_level_sort_mode="! i" - let g:Todo_txt_second_level_sort_mode="i" - -### Completion - -We also provide a nice complete function for project and context, to use it -add the following lines to your vimrc: +This plugin provides a nice complete function for project and context, to use +it add the following lines to your vimrc: " Use todo#complete as the omni complete function for todo files au filetype todo setlocal omnifunc=todo#complete @@ -105,68 +144,80 @@ adding the next lines to your vimrc: " Auto complete contexts au filetype todo imap @ @ -The `todo#complete` function is designed to complete projects (starting by '+') -and context (starting by '@'). If you use it on a regular word, it will do a + +The `todo#complete` function is designed to complete projects (starting by `+`) +and context (starting by `@`). If you use it on a regular word, it will do a normal keyword completion (on all buffers). + If you try to complete a project, it will propose all projects in all open buffers and for each of them, it will show their context and the name of the -buffers in which they appears in the preview window. -TodoCompelte does the same thing for context except that it gives in the -preview the list of projects existing in each existing contexts. +buffers in which they appears in the preview window. It does the same thing +for context except that it gives in the preview the list of projects existing +in each existing contexts. -### Due dates +## Hierarchical sort -I've integrated the [work from -durcheinandr](https://github.com/durcheinandr/todo.txt-vim/) concerning due -dates + some little improvements: +This fork provides a hierarchical sorting function designed to do by project +and/or by context sorts and a priority sort. -Accorrding to the todo.txt rules, one can define due dates using `due:date` or -`DUE:date` or any other `key:value` combination. This plugins handle dates at -the format `YYYY-MM-DD` and the key `due` can be spell using any combination -of lower and upper case letters. The following mappings are provided: +`sc` : Sort the file by context then by priority +`scp` : Sort the file by context, project then by priority +`sp` : Sort the file by project then by priority +`spc` : Sort the file by project, context then by priority -`-sd` : Sort the file by due-date. Entries with a due date appears +The user can give argument for the two calls to vim sort function by changing +the following variables: + + g:Todo_txt_first_level_sort_mode + g:Todo_txt_second_level_sort_mode + +Defaults values are: + + + g:Todo_txt_first_level_sort_mode="i" + g:Todo_txt_second_level_sort_mode="i" + + +For more information on the available flags see `help :sort` + +## Mappings + +`` is \ by default, so ̀`-s` means you type \s + +### Sort + ++ `s` : Sort the file by priority ++ `s+` : Sort the file on `+Projects` ++ `s@` : Sort the file on `@Contexts` ++ `s@` : Sort the file on due dates ++ `sc` : Sort the file by context then by priority ++ `scp` : Sort the file by context, project then by priority ++ `sp` : Sort the file by project then by priority ++ `spc` : Sort the file by project, context then by priority ++ `-sd` : Sort the file by due-date. Entries with a due date appears sorted by at the beginning of the file, the rest of the file is not modified. -`due:` : (Insert mode) Insert `due:` followed by the current date +### Priorities -`DUE:` : (Insert mode) Insert `DUE:` followed by the current date ++ `j` : Lower the priority of the current line ++ `k` : Increase the priority of the current line ++ `a` : Add the priority (A) to the current line ++ `b` : Add the priority (B) to the current line ++ `c` : Add the priority (C) to the current line -### Flexible File naming +### Dates -This plugin provides a Flexible file naming for todo.txt, all the following -names are recognized as todo: ++ `d` : Insert the current date ++ `date` : (Insert mode) Insert the current date ++ `due:` : (Insert mode) Insert `due:` followed by the current date ++ `DUE:` : (Insert mode) Insert `DUE:` followed by the current date - YYYY-MM-[Tt]odo.txt - YYYY-MM-DD[Tt]odo.txt - [Tt]odo-YYYY-MM.txt - [Tt]odo-YYYY-MM-DD.txt - [Tt]odo.txt - [Tt]oday.txt +### Done -And obviously the same are recognize as done: - YYYY-MM-[Dd]one.txt - YYYY-MM-DD[Dd]one.txt - [Dd]one-YYYY-MM.txt - [Dd]one-YYYY-MM-DD.txt - [Dd]one.txt - [Dd]one-[Tt]oday.txt - -Moreover, remove complete tasks `D` moves the task to the -done.txt file corresponding to the current todo.txt, aka if you are editing -2015-07-07-todo.txt, the done file while be 2015-07-07-done.txt. If you don't -like this behavior, you can set the default done.txt name: - - let g:TodoTxtForceDoneName='done.txt' - -### Others - -`x` is a toggle which allow you to unmark a task as done. - -`c` Mark a task cancelled - -Syntax highlighting for couples key:value - -If the current buffer is a done.txt file, the basic sort sorts on completion -date. ++ `x` : Toggle mark task as done (inserts or remove current ++ date as completion date) ++ `C` : Toggle mark task cancelled ++ `X` : Mark all tasks as completed ++ `D` : Move completed tasks to done file, see [TodoTxt +Files](#todotxt-files) diff --git a/doc/todo.txt b/doc/todo.txt index 4f86804..d0e8f6c 100644 --- a/doc/todo.txt +++ b/doc/todo.txt @@ -1,112 +1,111 @@ -*todo.txt* +*Todo.txt-vim* -Note: Since v0.7.3, `TodoComplete` is `todo#Complete`, you might need to -update your vimrc. + ##### # # + # #### ##### #### ##### # # ##### # # # # # + # # # # # # # # # # # # # # ## ## + # # # # # # # # ## # ### # # # # ## # + # # # # # # # # ## # # # # # # + # # # # # # # ## # # # # # # # # # + # #### ##### #### ## # # # # # # # # -============================================================================== -COMMANDS *todo-commands* + Efficient Todo.txt management in vim -`s` : Sort the file by priority - -`s+` : Sort the file on +Projects - -`s@` : Sort the file on @Contexts - -`s@` : Sort the file on due dates - -`sc` : Sort the file by context then by priority - -`scp` : Sort the file by context, project then by priority - -`sp` : Sort the file by project then by priority - -`spc` : Sort the file by project, context then by priority - -`-sd` : Sort the file by due-date. Entries with a due date appears -sorted by at the beginning of the file, the rest of the file is not modified. - -`j` : Lower the priority of the current line - -`k` : Increase the priority of the current line - -`a` : Add the priority (A) to the current line - -`b` : Add the priority (B) to the current line - -`c` : Add the priority (C) to the current line - -`d` : Insert the current date - -`date` : (Insert mode) Insert the current date - -`due:` : (Insert mode) Insert `due:` followed by the current date - -`DUE:` : (Insert mode) Insert `DUE:` followed by the current date - -`x` : Toggle mark task as done (inserts or remove current date as - completion date) - -`X` : Mark all tasks as completed - -`D` : Move completed tasks to done file, see |todo-flexibleFileNaming| - -`` is \ by default, so ̀`-s` means you type \s =============================================================================== -CONFIGURATION *todo-configuration* +Table of Contents *TodoTxt-Contents* ~ -The user can give argument for the two calls to vim sort function by changing -the following variables: - -g:Todo_txt_first_level_sort_mode -g:Todo_txt_second_level_sort_mode - -Defaults values are: - -> - g:Todo_txt_first_level_sort_mode="i" - g:Todo_txt_second_level_sort_mode="i" -< - -For more information on the available flags see help :sort - -We also provide a nice complete function for project and context, to use it -add the following lines to your vimrc: -> - " Use todo#Completete as the omni complete for todo files - au filetype todo setlocal omnifunc=todo#Complete -< - -You can also start automatically the completion when entering '+' or '@' by -adding the next lines to your vimrc: -> - " Auto complete projects - au filetype todo imap + + - - " Auto complete contexts - au filetype todo imap @ @ -< -To force completed task to be moved to a file independently from the current -file name, add the following to your vimrc: -> - let g:TodoTxtForceDoneName='done.txt' -< -For more explanations, see |todo-flexibleFileNaming| + 1. Release notes.................................|TodoTxt-ReleaseNotes| + 2. Introduction..................................|TodoTxt-Introduction| + 2.1 Todo.txt rules...........................|TodoTxt-Rules| + 2.2 Why this Fork............................|TodoTxt-Fork| + 2.3 Installation.............................|TodoTxt-Installation| + 3. TodoTxt Files.................................|TodoTxt-Files| + 4. Completion....................................|TodoTxt-Completion| + 5. Hierarchical Sort.............................|TodoTxt-HierarchicalSort| + 6. Mappings......................................|TodoTxt-Mappings| + 6.1 Sort.....................................|TodoTxt-Sort| + 6.2 Priorities...............................|TodoTxt-Priorities| + 6.3 Dates....................................|TodoTxt-Dates| + 6.4 Done.txt.................................|TodoTxt-Done| =============================================================================== -COMPLETION *todo-complete* +1. Release notes *TodoTxt-ReleaseNotes* ~ -The `todo#Complete`te function is designed to complete projects (starting by '+') -and context (starting by '@'). If you use it on a regular word, it will do a -normal keyword completion (on all buffers). -If you try to complete a project, it will propose all projects in all open -buffers and for each of them, it will show their context and the name of the -buffers in which they appears in the preview window. -TodoCompelte does the same thing for context except that it gives in the -preview the list of projects existing in each existing contexts. +Since v0.7.3, `TodoComplete` is replaced by `todo#Complete`, you might need to +update your vimrc (see |TodoTxt-Completion|). =============================================================================== -FLEXIBLE FILE NAMING *todo-flexibleFileNaming* +2. Introduction *TodoTxt-Introduction* ~ + +Todo.txt-vim is a plugin to manage todo.txt files it was initially designed by +Freitass (https://github.com/freitass/todo.txt-vim) then forked and improved +by David Beniamine. + +2.1 Todo.txt rules *TodoTxt-Rules* + + Todo.txt is a standard human readable todo notes file defined here: + http://todotxt.com + + "The todo.txt format is a simple set of + rules(https://github.com/ginatrapani/todo.txt-cli/wiki/The-Todo.txt-Format) + that make todo.txt both human and machine-readable. The format supports + priorities, creation and completion dates, projects and contexts. That's + all you need to be productive. See an example Todo.txt file": +> + (A) Call Mom @Phone +Family + (A) Schedule annual checkup +Health + (B) Outline chapter 5 +FamilyNovel @Computer + (C) Add cover sheets @ComputerOffice +FamilyTPSReports + Plan backyard herb garden @ComputerHome + Pick up milk @ComputerGroceryStore + Research self-publishing services +FamilyNovel @ComputerComputer + x Download Todo.txt mobile app @ComputerPhone +< +2.2 Why this fork ? *TodoTxt-Fork* + + This plugin is a fork of freitass todo.txt-vim + (https://github.com/freitass/todo.txt-vim). It add severals cool + functionalities including: + + + Hierarchical sort: |TodoTxt-Sort| and |TodoTxt-HierarchicalSort|. + + A completion function: |TodoTxt-Completion|. + + A proper handling of due dates: |TodoTxt-Dates| + + A Flexible file naming: |TodoTxt-Files|. + + Syntax Highlight for couples key:value. + + `x` is a toggle which allow you to unmark a task as done. + + `C` Toggle Mark a task cancelled + + If the current buffer is a done.txt file, the basic sort sorts on + completion date. + + ... + +2.3 Installation *TodoTxt-Installation* + ++ Vizardry + + If you have Vizardry(https://github.com/dbeniamine/vizardry) installed, + you can run from vim: +> + :Invoke -u dbeniamine todo.txt-vim +< ++ Pathogen install +> + git clone https://github.com/dbeniamine/todo.txt-vim.git ~/.vim/bundle/todo.txt-vim +< + Then from vim: `:Helptags` to update the doc + ++ Quick install +> + git clone https://github.com/dbeniamine/todo.txt-vim.git + cd todo.txt-vim + cp -r ./* ~/.vim +< + + If you want the help installed, run `:helptags ~/.vim/doc` inside vim + after having copied the files. Then you will be able to get the commands + help with: `:h todo.txt` + +=============================================================================== +3. TodoTxt Files *TodoTxt-Files* ~ This plugin provides a Flexible file naming for todo.txt, all the following names are recognized as todo: @@ -127,10 +126,124 @@ And obviously the same are recognize as done: [Dd]one.txt [Dd]one-[Tt]oday.txt < -Moreover, remove complete tasks `D` moves the task to the -done.txt file corresponding to the current todo.txt, aka if you are editing +Moreover, `D` moves the task under the cursor to the done.txt +file corresponding to the current todo.txt, aka if you are editing 2015-07-07-todo.txt, the done file while be 2015-07-07-done.txt. If you don't like this behavior, you can set the default done.txt name: > let g:TodoTxtForceDoneName='done.txt' < +=============================================================================== +4. Completion *TodoTxt-Completion* ~ + +This plugin provides a nice complete function for project and context, to use +it add the following lines to your vimrc: +> + " Use todo#complete as the omni complete function for todo files + au filetype todo setlocal omnifunc=todo#complete +< +You can also start automatically the completion when entering '+' or '@' by +adding the next lines to your vimrc: +> + " Auto complete projects + au filetype todo imap + + + + " Auto complete contexts + au filetype todo imap @ @ +< + +The `todo#complete` function is designed to complete projects (starting by `+`) +and context (starting by `@`). If you use it on a regular word, it will do a +normal keyword completion (on all buffers). + +If you try to complete a project, it will propose all projects in all open +buffers and for each of them, it will show their context and the name of the +buffers in which they appears in the preview window. It does the same thing +for context except that it gives in the preview the list of projects existing +in each existing contexts. + +=============================================================================== +5. Hierarchical sort *TodoTxt-HierarchicalSort* ~ + +This fork provides a hierarchical sorting function designed to do by project +and/or by context sorts and a priority sort. + +`sc` : Sort the file by context then by priority +`scp` : Sort the file by context, project then by priority +`sp` : Sort the file by project then by priority +`spc` : Sort the file by project, context then by priority + +The user can give argument for the two calls to vim sort function by changing +the following variables: +> + g:Todo_txt_first_level_sort_mode + g:Todo_txt_second_level_sort_mode +< +Defaults values are: + +> + g:Todo_txt_first_level_sort_mode="i" + g:Todo_txt_second_level_sort_mode="i" +< + +For more information on the available flags see |:sort| + +=============================================================================== +6. Mappings *TodoTxt-Mappings* ~ + +6.1 Sort *TodoTxt-Sort* + + `s` : Sort the file by priority + + `s+` : Sort the file on +Projects + + `s@` : Sort the file on @Contexts + + `s@` : Sort the file on due dates + + `sc` : Sort the file by context then by priority + + `scp` : Sort the file by context, project then by priority + + `sp` : Sort the file by project then by priority + + `spc` : Sort the file by project, context then by priority + + `-sd` : Sort the file by due-date. Entries with a due date appears + sorted by at the beginning of the file, the rest of the file is not modified. + +6.2 Priorities *TodoTxt-Priorities* + + `j` : Lower the priority of the current line + + `k` : Increase the priority of the current line + + `a` : Add the priority (A) to the current line + + `b` : Add the priority (B) to the current line + + `c` : Add the priority (C) to the current line + +6.3 Dates *TodoTxt-Dates* + + `d` : Insert the current date + + `date` : (Insert mode) Insert the current date + + `due:` : (Insert mode) Insert `due:` followed by the current date + + `DUE:` : (Insert mode) Insert `DUE:` followed by the current date + +6.4 Done *TodoTxt-Done* + + + `x` : Toggle mark task as done (inserts or remove current + date as completion date) + + `C` : Toggle mark task cancelled + + `X` : Mark all tasks as completed + + `D` : Move completed tasks to done file, see |TodoTxt-Files| + +`` is \ by default, so ̀`-s` means you type \s