Task attachments perfected!

[sdondley]

After way too many hours of work, I have developed a very nice system for attaching urls, files, and notes to tasks thanks mostly to the taskopen command. But there's quite a few glue functions and settings necessary to make things work smoothly from within taskwiki.

I'll try to get this all documented into an easy (hopefully) recipe to follow over the coming days and post it up here.

[sdondley]

Below is the recipe used for enhancing the annotation of tasks. The goals of this recipe are:

• make it possible to associate urls with tasks
• make it possible to associate files with tasks
• make it possible to associate fully editable note files with tasks
• provide a visual indication within vimwiki when a task is annotated

Operation:

• To add a new text note or open existing attached notes of any kind, do:
  • <leader>to
• To attach a URL to a task, do:
  • <leader>tau
• To attach a file to a task, do:
  • <leader>taf

That's it! Easy.

Most of the heavy lifting is done by the taskopen command which you'll need to have installed and properly configured to work with taskwarrior. Instructions for getting this command on your machine are below. The rest of the work is accomplished by adding appropriate functions and mappings to your vim file and a couple of external scripts. These are also covered in the recipe.

Note the recipe is more of a proof of concept rather than robust solution. Limitations of the recipe include:

• some features, like fetching a URL from the browser, are macos and/or application specific (sorry)
• is specific to markdown formatting
• assume you have not altered basic key bindings that work with vim out of the box
• some features require external scripts you'll need to install
• functions provide little error/input checking
• designed to work with text-based terminals, not gui (though it can work with some simple changes)
• my vim scripting skills are modest at best and the vim script is not well tested yet; there are probably some bad bugs hidden in here

OK, with those disclaimers out of the way, let's get to the recipe:

Installing and configuring taskopen

As mentioned, the key to getting better annotations working is to install taskopen set up and working which can be a little confusing. Hopefully the notes below make the process a little easier:

• Installing and configuring task open
  • Go to taskopen GitHub homepage: github.com: jschlatow/taskopen: Tool for taking notes and open urls with taskwarrior
  • Clone the repo
  • Follow the install instructions for your os included in the README
  • Note the path to the "addnote" script on you machine that comes with the repo
  • run the taskopen command on a task
    • taskopen
    • the first time it is run, it will prompt you to create an .taskopenrc file in your home directory
    • answer yes to the prompt for installing it
  • Before proceeding further, it's a good idea to play around with taskopen, read the README and run the command to make sure it works as expected
  • configure .taskopenrc:
    • EDITOR setting
      • If you use nvim for vimwiki, be sure to set the EDITOR setting to nvim, not vim
    • TASKBIN
      • should be set to task unless you have customized the name of the taskwarrior command
    • NOTES_FOLDER
      • change to a location where you want to store your notes
    • NO_ANNOATAION_HOOK
      • unncomment and leave set to addnote
  • configure taskwarrior
    • modify your task configuration file, usually ~/.taskrc
      • if you customized the location of this configuration file, you'll need to edit that custom file instead
    • add the following line to the config file:
      • alias.addnote=execute /path/to/addnote
      • make sure addnote is executable
  • Optional: modify the addnote script
    • the addnote script will prompt you for an extension for your notes when you add a new note
    • this is generally just annoying so I recommending editing addnote and commenting out these lines:
      • # echo -n "Type a file extension (or none): "
      • # read ext
      • commenting out these lines will use txt as the default extension for your note files

add in vim functions

• add the following functions to your vim script

• within my vim config folder, I put these in the after/ftplugin/vimwiki.vim

    function! TaskAnnotateWithNote()
        :w!<cr>
        let uuid = GetUUID()
        call AnnotationMarkerInsert()
        let command = printf('vsplit | term taskopen -A %s', uuid)
        execute command
    endfunction
  
  
    " helper function to get task UUID from task on current line
    function! GetUUID()
        " split line into parts
        let parts = split(getline('.'), '#')
  
        " strip whitespace from last portion of line
        let uuid = substitute(parts[-1], '\s\+$', '', '')
  
        return uuid
    endfunction
  
  
    " add a marker to the end of the task to indicate if an annotation is present
    function! AnnotationMarkerInsert()
        " bail if ==ANN=== already exists
        if (stridx(getline('.'), '==ANN==') == -1)
          execute "normal! $F#hi==ANN==\<esc>:w<cr>"
        endif
    endfunction
  
    function! TaskAnnotateWithURL()
        let uuid = GetUUID()
  
        " runs an applescript
        silent !~/bin/copy_safari_url.osa
        let url = getreg('+')
        let url = substitute(url, '#', '%23', '')
        execute '!task' uuid 'annotate' escape(url, '%')
        call AnnotationMarkerInsert()
    endfunction
  
    function! TaskAnnotateWithFile()
        call inputsave()
        let name = input('Enter file path: ', '', 'file')
        call inputrestore()
        if name
            execute printf('!task %s annotate -- %s', GetUUID(), name)
            call AnnotationMarkerInsert()
        endif
    endfunction
  

• add in vim mappings

  • add these to same file you added the functions above to

nnoremap <leader>to :call TaskAnnotateWithNote()<cr>
nnoremap <leader>gua :call TaskAnnotateWithURL()<cr>
nnoremap <leader>taf :call TaskAnnotateWithFile()<cr>
nmap <leader>tau <leader>gua
nmap <leader>tan <leader>to

add in syntax highlighting vim code

• this code will conceal the ==ANN== marker that in embedded at the end of tasks when any kind of annotation is made to a task
• it will also make tasks with annotations white
  • if you want a different color, just change white in the code below to another color
• this code was written for a text-based vim terminal, not a gui
  • you may need to make some changes to get this working
    • at a minimum, you'll need to add a color setting for the gui

" add a marker to the end of the task to indicate if an annotation is present
function! AnnotationMarkerInsert()
    " bail if ==ANN=== already exists
    if (stridx(getline('.'), '==ANN==') == -1)
      execute "normal! $F#hi==ANN==\<esc>:w<cr>"
    endif
endfunction

syntax region TaskWithAnn start=/\]\s\+/rs=e+1,hs=e+1 end=/==ANN==/re=e-8,he=e-8 oneline containedin=TaskWikiTask,VimwikiListTodo
hi TaskWithAnn ctermfg=white

add in vim code to handle :term command better

• the :term command to open text notes
• add these lines to get rid of some annoyances when opening/closing the terminal:

function! OpenTerm()
    set nonumber
    startinsert
endfunction

function! CloseTerm()
    call feedkeys('<cr>')
endfunction

augroup termops
    autocmd TermOpen *taskopen* call OpenTerm()
    autocmd TermClose *taskopen* call CloseTerm()
augroup END

If you use a mac:

• the TaskAnnotateURL() function above has a call to an external applescript for getting the URL from safari
• add the external copy_safari_url.osa script to your ~/bin directory
• make sure the script is executable
• if you don't use Safari, modify the script below so it works with your preferred browser

#!/usr/bin/osascript

tell application "Safari"
	set theURL to URL of current tab of front window
	set the clipboard to theURL
end tell

if you don't use a mac

• modify the TaskAnnotateURL() as necessary to get the url used in the note

Alright, I think that's everything. Hopefully I didn't forget anything but if something doesn't seem to work or if you run into any kinks, I'll do my best to try to help. Enjoy!