Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/tty-tourist/org-tracktable

Track your writing progress in an org-table
https://github.com/tty-tourist/org-tracktable

Last synced: 2 months ago
JSON representation

Track your writing progress in an org-table

Awesome Lists containing this project

README 

        
* Org-tracktable



[[http://stable.melpa.org:1337/#/org-tracktable][file:http://stable.melpa.org:1337/packages/org-tracktable-badge.svg]]

[[https://melpa.org/#/org-tracktable][file:https://melpa.org/packages/org-tracktable-badge.svg]]



=org-tracktable= is an emacs/org-mode package for tracking your writing progress in an org-table.



It provides functions for inserting a table for tracking progress, updating that table, and getting status messages with your progress.



In the spirit of org-mode, the package aims to keep everything in plain view and in a single file.



The package is useful when writing the first draft of something, not so much in the editing and rewriting phases where, alas, hard work is seldom reflected in the word count.



=org-tracktable= is inspired by [[https://github.com/dato/org-wc/blob/master/org-wc.el][org-wc.el]] and [[https://github.com/noctuid/chronicler][chronicler.el]].



** Installation

Clone this repo or download =org-tracktable.el= to an appropriate location like =~/.emacs.d/lisp/=.



Add the location to emacs' path and load it: 



#+BEGIN_SRC emacs-lisp

(add-to-list 'load-path "~/.emacs.d/lisp/org-tracktable")

(load "org-tracktable.el")

#+END_SRC



** Functions

When =org-tracktable.el= is loaded, these three functions become available:



- =org-tracktable-insert-table=: insert a table to keep track of word count in an org-mode buffer.



- =org-tracktable-write=: add an entry with the current word count to the table. You only need to do this when you're done writing for the day. If an entry for the current day already exists, this entry will be updated.



- =org-tracktable-status=: message the total word count in the buffer, or region if active. If the table was inserted by =org-tracktable-insert-table=, the count of words written the current day is also shown together with percentage of your daily writing goal.



** Keys

It can be convenient to map =org-tracktable-write= and  =org-tracktable-status= to whatever keys you can spare, for example:



#+BEGIN_SRC emacs-lisp

(global-set-key (kbd "") 'org-tracktable-status)

(global-set-key (kbd "") 'org-tracktable-write)

#+END_SRC



** The table

This is the table inserted by =org-tracktable-insert-table=:



#+BEGIN_SRC org

#+NAME: tracktable

|---+---------------+-----+-----+-------+---------|

| ! | date          | beg | end | total | comment |

|---+---------------+-----+-----+-------+---------|

|   | initial count |   0 |   0 |     0 |         |

|---+---------------+-----+-----+-------+---------|

#+TBLFM: @2$2=initial count::$2='(org-tracktable-stamp)::@2$3=0::$3=(@-1$4)::$4='(org-tracktable-current-count)::$5=$4-$3

#+END_SRC



Starting off, it will only have one line containing a count of the words already in the buffer. Everything is counted except: comments, (folded) drawers, heading lines, and any content of headings with the tags =nowc= or =noexport=.



For that reason it's a good idea to put a =nowc= or =noexport= tag on any heading not containing whatever you consider productive writing, such as research and todo lists – and the heading containing the table itself.



The name of the table can be changed by customizing =org-tracktable-table-name=, for example:



#+BEGIN_SRC emacs-lisp

(setq org-tracktable-table-name "my-table-name")

#+END_SRC



The name set with =org-tracktable-table-name= is used when the other functions try to find the table, so if you want to change the variable it's recommended to do it before calling =org-tracktable-table-name=, to ensure consistency.



** Updating the table

All that the table needs to record the current word count with a time-stamp and a calculation of daily productivity is contained in the formula, so the table could be manually updated by inserting a new row and updating it with =C-c *=.



=org-tracktable-write= makes is easier to update the table. It will jump to the table from anywhere in the buffer, create a new entry and take you to the comment field. =C-c &= will take you back to your writing again.



If an entry from the current day already exist, =org-tracktable-write= will update this entry instead of creating a new one. In that way, =org-tracktable.el= is designed to only keep one entry per day. For testing purposes, you can manually change the time-stamp for the last entry a to insest new entries and get familiar with the behavior.



Note that a new day is considered to start at 5am. This can be altered by changing the variable =org-tracktable-day-delay=.



** Getting status

=org-tracktable-status= will give you a message with:



- Number of words in the org buffer or region, if it's active.

- The number of words written today (this is only shown if the table exist). This value is the difference between the last entry in the table and the total word count. Note that if the last entry is from the current day, =org-tracktable-status= will skip it and look at the second last. If  =org-tracktable-write= was called when you were done writing the preceding day, the count for the current day should be correct.

- The percentage of your daily writing goal achieved so far. The daily writing goal is set to 300 words by default. It can be altered by changing the variable =org-tracktable-daily-goal=. Set this variable to 0 to disable =org-tracktable-status= from displaying daily goal.