Begin documentation

shushcat · Oct 16, 2020 · 99bb9a2 · 99bb9a2
1 parent cc0cfe4
commit 99bb9a2
Show file tree

Hide file tree

Showing 2 changed files with 30 additions and 20 deletions.
diff --git a/README.md b/README.md
@@ -1,27 +1,29 @@
 # txt-agenda
 
-`txt-agenda` is a script for keeping track of dates and deadlines scattered throughout a series of text files.  So far as I know, it is entirely POSIX compliant with the `-f` flag, and when that flag is omitted, the only additional dependency is [fzf]().  While this documentation is obviously incomplete, the script itself is functional.
+Txt-agenda is a script for keeping track of dates and deadlines kept in text files.  It's core logic is POSIX compliant, but it opportunistically uses [fzf](https://github.com/junegunn/fzf) to filter, display, and jump to lines.
 
-## Syntax
+## Demo
 
-The deadline and reminder syntax used by `txt-agenda` is taken from [Howm mode](http://howm.osdn.jp/) for Emacs, but the agenda behavior when using [fzf](https://github.com/junegunn/fzf) is closer to that of [Org-mode](https://orgmode.org/).
+Coming soon....
+
+![](http://johnob.sdf.org/resources/txt-agenda_demo.gif)
 
-The format is as follows:
+## Usage
 
-- Reminders `[YYYY-MM-DD]-` sink after the date
-- Tasks `[YYYY-MM-DD]+` float after the date
-- Deadlines `[YYYY-MM-DD]!` float before and after the date
+When invoked as `txt-agenda FILES`, Txt-agenda generates a chronological list of the dates found in the text files `FILES`.  In order for a date to be recognized by Txt-agenda, it must be in one of three forms:
 
-As with Howm, repeated entries are achieved by entering multiple dates.
+- Reminders `[YYYY-MM-DD]-` sink after their date,
+- Tasks `[YYYY-MM-DD]+` float after their date, and
+- Deadlines `[YYYY-MM-DD]!` float before and after their date.
 
-## Flags
+What that means is that a line containing the date `[2077-10-16]-` will not appear until October 16th (of 2077), then will sink as time passes until it falls outside the agenda span.  In contrast to that behavior, a line containing `[2077-10-16]+` will float near the top of the agenda once the 16th arrives, and a line containing `[2077-10-16]!` will appear at the top of the agenda several weeks before the 16th, then will float afterwards.
 
+ | ---  | ---                                                           | 
  | `-f` | Report without `fzf`                                          | 
  | `-h` | Print help message                                            | 
  | `-y` | Output agenda items for the year centered on the current date | 
 
-
-## progress
+## Progress
 
 - [ ] Vim plugin for fzf.
 - [ ] Setup man file (will need to look into roff).
@@ -38,9 +40,6 @@ As with Howm, repeated entries are achieved by entering multiple dates.
 - [X] fix line display; ex: `[YYYY-MM-DD]+:LINUM:LINE:FILE`
 - [X] preserve references to files while arranging the agenda
 
-## Related Projects and Resources
+## Credit
 
-- On the pattern of https://github.com/msprev/fzf-bibtex, using Go.
-- https://github.com/bigH/git-fuzzy
-- Howm: http://howm.osdn.jp/
-- Ascetic bullet journaling: http://karolis.koncevicius.lt/posts/ascetic_bullet_journal/
+The deadline and reminder syntax used by `txt-agenda` is taken from [Howm mode](http://howm.osdn.jp/) for Emacs, but the agenda behavior when using [fzf](https://github.com/junegunn/fzf) is closer to that of [Org-mode](https://orgmode.org/).
diff --git a/txt-agenda.sh b/txt-agenda.sh
@@ -11,11 +11,23 @@ fi
 RNGCMD=set_month_range
 
 usage() {
-        # TODO update this so it actually means something
 	cat 1>&2 <<-EOF
 	${1:+Error: ${1}}
-	USAGE:  ${0##*/} [-efhy] files
-        Some day, you will look to txt-agenda(1) for surehanded guidance in all things.
+	USAGE:  ${0##*/} [-fhy] FILES
+
+	Display an agenda based on [YYYY-MM-DD] formated dates in FILES.
+
+	Syntax:
+	[YYYY-MM-DD]-	is a sinking reminder,
+	[YYYY-MM-DD]+	is a floating task, and
+	[YYYY-MM-DD]!	is a looming deadline.
+	
+	Flags: 
+	-f	Suppress fzf on systems where it is present.
+	-h	Show this message.
+	-y	Output a yearlong agenda, centered on today.
+
+	Some day, you will look to txt-agenda(1) for surehanded guidance in all things.
 
 	EOF
 	exit ${1:+1}
@@ -137,7 +149,6 @@ fzf_report() {
                 --preview-window=up)
         selected_file_name=$(echo "${selected}" | cut -d':' -f2)
         selected_line_num=$(echo "${selected}" | cut -d':' -f3)
-        # TODO Settle on nice, portable format.
         exec "echo" "$selected_line_num" "$selected_file_name"
 }