Where notebooks and calendars and computers meet is ... well, lots of different places. But one place they meet is at work. Thus it did come to pass that I felt the need to take a daily notebook calendaring exercise and turn it into something that could be replicated on my computer. Which brings us to a thing I wrote, entitled "todotxt.vim", a "plugin" for the Vim text editor, which promises little and delivers less.
As it says in the help file I wrote (lol):
When I start work each day, it makes sense for me to:This plugin creates a digital version of that page of my notebook, with a new file for each day.
- Start a new page in my work notebook for that day
- List my meetings for the day (at the top of the page, in order)
- List my tasks for the day (to use the page efficiently, I populate the tasks starting at the bottom of the page, but I don't generally order them or worry about grouping or managing them)
The premise of the plugin is that a list of the things you have to do is a good thing to have. The list might as well be in plain text, so you can look at it on pretty much any device, and if it's in plain text, I might as well be able to use the fancy special features of my favorite text editing program, Vim to edit it. I find it helpful to be able to look back and see what I did on a given day, so a big piece of the "functionality" involves knowing what day it is and making a special file for that day. Since I don't always finish everything I want to do on a given day (lol), another big piece of the "functionality" involves looking at a specified previous day and pulling the un-done tasks from that day to the current day. There's also a tiny bit of attention paid to making it look quasi-nice (using Vim's syntax formatting).
Anyway, if you want to try this, there's a link to the files here:
And while the file itself is more or less definitive, and can be read in a text editor by clicking here, the help file may be more illustrative, so I have pasted it in below. Sorry about the formatting below. If you hate it, click the link, I guess. NOTE: where it says something like \tadd you should replace \ with leader in angle brackets.
*todotxt.txt* for Vim version 7.4 and greater Last change: 2020 Nov 4
Adds limited functionality and syntax highlighting for plain-text to-do files
accessed in Vim.
CONTENTS *todotxtcontents*
1. Introduction ................ |todotxt-introduction|
2. Installation ................ |todotxt-installation|
3. Usage ....................... |todotxt-usage|
4. Mappings .................... |todotxt-mappings|
5. Configuration ............... |todotxt-config|
6. License ..................... |todotxt-license|
7. Bugs, Version, and To-Dos ... |todotxt-bugs|
8. Contributing ................ |todotxt-contributing|
9. Changelog ................... |todotxt-changelog|
10. Credits .................... |todotxt-credits|
================================================================================
Section 1: Introduction *todotxt-introduction*
This is a very simple plugin for creating, using, updating, and (very very
lightly) tracking to-do files in plain text. Syntax highlighting and a few
mappings make the to-do list easier to look at and easier to use.
The basic idea is to start your workday with a file that has the following in
it:
By default, when the empty file is loaded at the beginning of the day, the
plugin will ask if there is a previous file to check for tasks that are not
marked as done. This will usually be the previous workday's file. If the
current day's file, along the lines of the following.
+--------------------------------------------------------------------+
| # Today's Date |
| # Meetings |
| |
| --- |
| |
| # Tasks |
| |
| - [ ] McDonalds 2020-11-04 |
+--------------------------------------------------------------------+
To add a task, use
\tadd to enter a date-stamped task on the line under the cursor along the following lines.
+--------------------------------------------------------------------+
| # Today's Date |
| # Meetings |
| |
| --- |
| |
| # Tasks |
| |
| - [ ] McDonalds 2020-11-04 |
| - [ ] Eat Hot Chip 2020-11-05 |
+--------------------------------------------------------------------+
More tasks can be added to the line under the cursor.
+--------------------------------------------------------------------+
| # Today's Date |
| # Meetings |
| |
| --- |
| |
| # Tasks |
| |
| - [ ] McDonalds 2020-11-04 |
| - [ ] Eat Hot Chip 2020-11-05 |
| - [ ] Charge Phone 2020-11-05 |
| - [ ] Lie 2020-11-05 |
+--------------------------------------------------------------------+
Meetings work similarly, but instead of a datestamp that is added
automatically, meetings ask you to enter a time. Once added, it looks
something like the following. The command for this is
\madd. 
+--------------------------------------------------------------------+
| # Today's Date |
| # Meetings |
| - [ ] Twerk Noonish? |
| |
| --- |
| |
| # Tasks |
| |
| - [ ] McDonalds 2020-11-05 |
| - [ ] Eat Hot Chip 2020-11-05 |
| - [ ] Charge Phone 2020-11-05 |
| - [ ] Lie 2020-11-05 |
+--------------------------------------------------------------------+
Adding tasks and meetings manually can be done throughout the day.
To make a file for the day,
\logit is used. This will create a file with a datestamp in the filename for easy sorting, and to make it simple to
pull the undone tasks from earlier files.
To mark a meeting or task as done, put the cursor on the line of the meeting
or task and enter
\done. This will have an effect like the following. +--------------------------------------------------------------------+
| # Today's Date |
| # Meetings |
| - [ ] Twerk Noonish? |
| |
| --- |
| |
| # Tasks |
| |
| - [X] McDonalds 2020-11-05 |
| - [ ] Eat Hot Chip 2020-11-05 |
| - [X] Charge Phone 2020-11-05 |
| - [X] Lie 2020-11-05 |
+--------------------------------------------------------------------+
Sometimes a meeting will be cancelled or you will decide to not do a task in a
way you want to document (and not carry the task forward to future days). To
do this, enter the command
\skip, which will have an effect like the following.
+--------------------------------------------------------------------+
| # Today's Date |
| # Meetings |
| |
| |
| --- |
| |
| # Tasks |
| |
| - [X] McDonalds 2020-11-05 |
| - [ ] Eat Hot Chip 2020-11-05 |
| - [X] Charge Phone 2020-11-05 |
| - [X] Lie 2020-11-05 |
+--------------------------------------------------------------------+
This doesn't look very interesting in a help file, but the plugin uses
Markdown formatting to make list items and HTML comments -- like the skipped
meeting above -- visually distinctive. Since the meetings and tasks are added
on the line under the cursor, the line the cursor is on is also highlighted.
To-do-specific functions are mostly handled with mappings. Everything else
about the file is meant to be handled using Vim's built-in capabilities. For
more details, see the credits section.
================================================================================
Section 2: Installation *todotxt-installation*
I think this will work with Pathogen? I'm not sure: I don't use Pathogen.
What I would do is:
1. Put the todotxt.vim file somewhere in your plugins folder
2. Make a todo directory somewhere that makes sense to you
3. Add the following to your .vimrc file. >
augroup filetype_todo
autocmd!
autocmd BufNewFile */todotxt/*todo*.txt :source path/to/todotxt.vim
autocmd BufNewFile */todotxt/*todo*.txt :Todotxtstartup
augroup END
<
Or you could just dump the whole todotxt.vim file into your .vimrc...
================================================================================
Section 3: Usage *todotxt-usage*
This is an opinionated little plugin. It is based on a small set of (my)
practices and makes certain assumptions. If those practices and assumptions
don't work for you, this plugin is almost certainly not going to work for you
either (whether or not I've actually made it functional).
Practices: When I start work each day, it makes sense for me to:
1. Start a new page in my work notebook for that day
2. List my meetings for the day (at the top of the page, in order)
3. List my tasks for the day (to use the page efficiently, I populate the
tasks starting at the bottom of the page, but I don't generally order them or
worry about grouping or managing them)
This plugin creates a digital version of that page of my notebook, with a new
file for each day.
Assumptions:
1. You want to do something (very) like the practices above
2. You want to use Vim to edit to-do files
3. You're okay managing your own files
The way todotxt.txt expects you to use it is:
1. Each day, use the command line to tell Vim to create a file with "todo"
(without the quotes) in its filename and the extension .txt in a folder with
"todo" (without the quotes) in its path
2. Tell todotxt.txt to import undone tasks from a specified previous day (or,
in a very special situation, a lot of days)
3. Add your meetings and tasks over the course of the day
4. Mark meetings and tasks done over the course of the day
5. Save a copy of the list for reference later
6. Repeat 1-5 the next day
7. Every so often (once a month would make a lot of sense) move all the old
daily files into a sub-folder
To make 2, 3, 4, and 5 easier, there are mappings. To make the file easier to
look at, it uses syntax highlighting. That's it. That's all it does. It
should save you some typing of items from day-to-day if on Day 2, you have
some tasks you didn't complete on Day 1, and it should look better than a raw
text file. Otherwise, you're on your own.
================================================================================
Section 4: Mappings *todotxt-mappings*
This is kind of the meat of the plugin, in a weird way. Of course, if you're
a Vim user looking for plugins, you probably have a ton of your own mappings,
which is a problem, because I cannot for the life of me figure out all the
things I'm supposed to do to make sure this plugin's mappings aren't going to
clobber yours. Sorry. To make things easier, I've listed them all below. To
make things less dangerous, I've made them all pretty long.
Type: To: ~
\tadd Add a new task \madd Add a new meeting \done Mark a task or meeting accomplished \skip Mark a meeting or task skipped \logit Write a file with the current date in the filename \grabit Pull in undone things from a specified file \graball Pull in undone things from all files in the folder graball is meant for big clean-up jobs and should rarely be used. All others are meant for use daily (
logit) or more often (tadd, madd, done, skip). grabit fires automatically when you open the file, but can be used to add days one at
a time, if needed.
================================================================================
Section 5: Configuration *todotxt-config*
There aren't configuration options at this time. If you want a different path
or a different filename or a different type of syntax highlighting, you can
edit the todotxt.vim file to suit your preferences (but don't blame me if
something goes wrong).
================================================================================
Section 6: License *todotxt-license*
This file is placed in the public domain. But you shouldn't use it if you
aren't literally me.
================================================================================
Section 7: Bugs *todotxt-bugs*
God, there are probably a million bugs. If you find one, shoot me an email at
cfcollision@gmail.com, please! If you fix it, that's even better.
I am having enormous trouble with the apparently important "avoid loading the
file multiple times per buffer" issue, so frequently you may need to manually
set filetype to markdown, and I have no idea why. It loads other shit, but
not the filetype setting and I cannot figure out why that might be. For now,
I just have the entire "1. Filetype Protections from usr_41.txt" section
commented out because I can't make it work properly.
Tasks and meetings are added under the cursor. This is a little clunky, but
since Vim makes it easy to put the cursor where we want it, we can accept this mild inconvenience.
Not a bug, but a behavior: "
logit" will (a) overwrite any previous version of the file you made that day and (b) silently enter the current day if you start
up todotxt.vim on one day but use "
logitlogit" on a different day. "
skip" marks things done, so they do not carry over into following days. This is deliberate, but may not be what you want. My usage is to use "
skipskip" only for meetings that were cancelled, not for tasks I have chosen to leave undone;
those, I would usually allow to carry forward to the next day (and the next
day's file) and simply delete if need be, or use "
skipskip" and add a comment about why I had left the task undone.
This is tested on my home laptop, running Ubuntu 16.4, and my work MacBook.
It has NOT been tested on any Windows machine and probably won't work on one.
This works on Vim version 7.4 on Ubuntu 16.4 and should work on newer
versions. I think it works on Vim version 8.0 on my work MacBook.
Todo:
1. Sorting tasks by datestamp would be pretty cool
2. Auto-sorting meetings by time would also be pretty cool
3. Getting gVim to work would also be sweet (setting pwd on BufNew or
something?)
4. Add menus?
5. Sweet README.md file?
6. Smart enough to check more than one file?
7. Sweep done tasks (but not meetings) to the bottom of the file and hide them
(comment them out or fold them?)
8. Cleverly fold the todotxt.vim file using blank lines?
9. Shortening everything so I could have a cal in there
10. Making long lines work better and not just let them scroll off
endlessly?
================================================================================
Section 8: Contributing *todotxt-contributing*
It is unlikely that this will be useful enough to any other human to merit any
contributions. If you tweak it to your liking, feel free to shoot me an
email about your tweak. If you are okay with me adopting your tweak, please
say so.
================================================================================
Section 9: Changelog *todotxt-changelog*
This document is for plugin version 0.2.1, first even potentially shareable
version, with broken stuff commented out.
================================================================================
Section 10: Credits *todotxt-credits*
This is inspired by three things:
1. Bullet journal practice
2. Hipster PDA practice (documentation here:
http://www.43folders.com/2004/09/03/introducing-the-hipster-pda_ )
3. Steve Losh's program t: "a command-line todo list manager for people who
want to FINISH tasks, not organize them" ... "it does the simplest thing that
could possibly work" ... "hacked together in a couple nights to fit my needs"
with more documentation available here:
https://stevelosh.com/projects/t/
The idea is to mirror in plain text files my particular implementation of
ideas adopted from bullet journaling and the hipster PDA. In particular:
1. Treating a day as a container for the stuff I have to do that day, not
distinguishing between tasks and meetings, because they are both things I have
to do on a given day
2. Devoting a page in a notebook to that day, so everything is available at a
glance
3. Marking things done when done
4. Carrying over things to the next day if they are not done
Losh's program did a lot of things I found interesting, especially with very
short commands to do useful things, but had certain features that didn't work
well for my needs, including a dependency on Python and a need to make
command-line aliases for things. His repeated comment "need to do something?
open it in a text editor" inspired me to harness Vim's capacities and make Vim
the home for the whole thing. Also I have one need his program does not allow
for, which is an occasional but very important need to document what I did on
a given day or set of days: this implies a daily log of some kind. Finally,
hell, sometimes I do want to organize my tasks, not finish them. (And a lot
of his functionality is built around preventing multiple users or computers
clobbering one file, which is not a need I have.)
So, I hacked something together over the course of a couple days, test-drove
it and amended it.
His way -- t -- is almost certainly better, and I encourage you to try it out
rather than muck around with this.
vim:tw=78:ts=8:ft=help:norl:
Previous entries in Vim (for non-programmers):
- Vim (for non-programmers) Chapter O (NOT 0), recipes which are quick and dirty, example six: Let's Make a Time-Stamped Log of Stuff We Read Online and Want to Have a List Of; Hey, Guess What? I Got a Lot of This from Chris Toomey (heart-eyes emoji)
- Vim (for non-programmers) Part Three: Refactoring my _vimrc File; Chapter Five: Correct Easy Link Addition (Correcting My Misreading of Steve Losh)
- Vim (for non-programmers) Part Three: Refactoring my .vimrc File, Chapter Five; Correct Easy Markup of Markdown Headlines (Building on Chris Toomey's "Your First Vim Plugin")
- Vim (for non-programmers) Chapter O (NOT 0), recipes which are quick and dirty, example two: Dumping Out the Recommendations from IDEOTVPod into One File
No comments:
Post a Comment