chronicler.el is an emacs package primarily for tracking writing statistics for org files.
DISCLAIMER: This package is in an early stage of development and may change drastically or break. I will put it on MELPA after I’ve added more features and it has become relatively stable.
A goal of the project is to be able to quickly and accurately analyze very large files with many headings (even up to 300k+ words). For files not even close to this size, I’ve found emacs lisp to be too slow, so the chronicler command line program is required for this package to function. The fact that the work is offloaded to an external program also means that a similar plugin could also be written fairly easily for vim (e.g. for use with vim-dotoo) or another programmable text editor.
If you have any suggestions for additional functionality, please make an issue.
Comments and org syntax (property drawers, blocks, etc.) will always be ignored.
This package also gives full control over which headings are taken into consideration. By default, all headings are counted. To ignore all headings by default, chronicler-ignore-headings-by-default can be altered:
(setq chronicler-ignore-headings-by-default t)This default can be overridden by changing the properties (in an org property drawer) for a specific heading:
:count: will count text directly under a heading but won’t affect any sub-headings.
:no-count: will prevent text directly under a heading from being counted but won’t affect any subheadings.
:count-recursive: will change the default setting to count the current heading as well as all sub-headings.
:no-count-recursive: will change the default setting to ignore the current heading as well as all sub-headings.
Count settings will override ignore settings if you happen to have a heading with both properties. If a heading is tagged with both :no-count: and :count-recursive:, the text directly under the heading will be ignored, but all sub-headings will be counted by default (assuming there are not additional count or ignore properties added to them). An example use case of this is where there is some description text under a heading that you do not wish to count, but the text under all the sub-headings does actually correspond to writing.
Also note that all sub-headings will be checked, so even when a heading has :no-count-recursive: in its properties, the property drawers of sub-headings will be checked.
Since this may be confusing, I have created a table. The first value corresponds to whether the text directly under a heading (before sub-headings if there are any) will be counted. The second value corresponds to the (possibly new) default behaviour for sub-headings.
| count | no-count | count-recursive | no-count-recursive | |
|---|---|---|---|---|
| count | - | - | - | - |
| no-count | count, default | - | - | - |
| count-recursive | count, count | ignore, count | - | - |
| no-count-recursive | count, ignore | ignore, ignore | default, count | - |
chronicler-store-dir is a string that determines where information should be stored. It defaults to .chronicler/ but can also be an absolute path (if you only want one storage directory).
chronicler-day-start-time is the time (0-23) at which counts should be reset and stored for a new day. Setting this to 0 will ensure that daily counts actually correspond to the day they are written on. However, the default value is 4 (4am) since it seems more likely that a user will want each day to correspond to a period of being awake, and a writing session can easily last past midnight.
chronicler-daily-wc-goal is the goal word count for comparison.
chronicler-update-word-counts will calculate and store counts for all non-ignored headings for the current day. Each day’s progress will be stored separately, and chronicler will automatically reset progress after the chronicler-day-start-time.
chronicler-message-day-progress will message how many words have been written for the current day and what percent of the word count goal has been completed. It should be run after updating with chronicler-update-word-counts.
- Add configurable mode line section
- Add counting functions for sentences (ignoring abbreviations if one-spaced) and paragraphs
- Add word usage analysis (words ordered by times used per section, ignoring common words)
- Add functionality to chart progress over a period of time
- Etc.
- Add functionality to chart a timeline linking characters and places based on heading tags
- Add functionality to jump to character, place, etc. definitions in another file
- Add some templates for exporting