docs: readme+license

3 files changed, 250 insertions, 0 deletions

diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000..135a148
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hachem
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..e487077
--- /dev/null
+++ b/README.md
@@ -0,0 +1,59 @@
+# todo
+
+a little modal todo list that lives in my terminal.
+
+## keys
+
+```text
+= movement
+  h j k l        move (h/l caret in the item, j/k between items)
+  w / b          next / previous word
+  { / }          previous / next section
+  gg / G         top / bottom
+  3j, 2dd, ...   a count repeats the next motion or operator
+
+= editing
+  o              add a new item below
+  i              insert at the cursor
+  A              append to the item's text
+  R              replace the item's text
+  x              toggle done
+  space          cycle todo -> doing -> done
+  dd             cut the item
+  D              clear every done item
+  yy p P         yank, paste below, paste above
+  J / K          move the item down / up (on a heading, moves the whole section)
+
+= other
+  / n N          search, next match, previous match
+  u  ctrl-r      undo, redo
+  :w :q :wq :x   write, quit, write and quit
+  :reset         set every item back to todo
+  :clear         remove every item
+```
+
+## items
+
+```text
+= project          a section        -> I. project
+== phase one       a subsection     -> i. phase one
+- write the docs   a subtask
+buy milk           a plain task
+```
+
+## build
+
+```sh
+$ sudo make install            # -> /usr/local/bin + man page
+$ make install PREFIX=~/.local # or somewhere without sudo
+```
+
+it's one file, so if you don't want the makefile:
+
+```sh
+$ cc -O2 todo.c -o todo
+```
+
+## license
+
+`todo` is licensed under the mit license. see [license](LICENSE) for more.
diff --git a/todo.1 b/todo.1
new file mode 100644
index 0000000..9deb04e
--- /dev/null
+++ b/todo.1
@@ -0,0 +1,170 @@
+.TH TODO 1 "2026-09-29" "todo 0.1.0" "User Commands"
+.SH NAME
+todo \- a little modal todo list
+.SH SYNOPSIS
+.B todo
+.br
+.B todo
+.BR \-h | \-\-help
+.br
+.B todo
+.BR \-v | \-\-version
+.SH DESCRIPTION
+.B todo
+is an interactive todo list you drive like vim. It has modes: normal mode to
+move around and act, insert mode to edit text, and a command line for
+.BR : " and " /
+commands. The list is stored as a plain text file you can also edit by hand or
+from scripts.
+.PP
+The header shows the current date and time, localized through the environment.
+Items sort so that unfinished ones stay above finished ones within each group,
+and finished items are dimmed and struck through.
+.PP
+Nothing is written to disk until you save with
+.BR :w .
+.SH ITEMS
+An item's kind is decided by how its text begins.
+.TP
+.I text
+A plain task, shown with a checkbox and a number.
+.TP
+.BI = " name"
+A section, shown as an uppercase roman heading
+.RB ( I. ", " II. )
+with its contents indented beneath it. Repeat the
+.B =
+for deeper levels
+.RB ( == " is a subsection, shown as " i. ", " ii. ).
+.TP
+.BI \- " name"
+A subtask of the task above it, indented further. A task is finished
+automatically once all of its subtasks are done.
+.PP
+Each task carries one of three states, written in its checkbox:
+.B [\ ]
+todo,
+.B [\-]
+doing,
+.B [x]
+done.
+.SH KEYS
+.SS Movement
+.TP
+.BR h ", " j ", " k ", " l
+Move: \fBh\fR/\fBl\fR move the cursor within the item, \fBj\fR/\fBk\fR between
+items. Arrow keys work too.
+.TP
+.BR w ", " b
+Move to the next or previous word.
+.TP
+.BR { ", " }
+Jump to the previous or next section.
+.TP
+.BR gg ", " G
+Jump to the top or bottom.
+.TP
+.I count
+A leading number repeats the next motion or operator, e.g.\&
+.BR 3j ", " 2dd .
+.SS Editing
+.TP
+.B o
+Add a new item below the cursor.
+.TP
+.B i
+Enter insert mode at the cursor.
+.TP
+.B A
+Append to the item's text.
+.TP
+.B R
+Replace the item's text.
+.TP
+.B x
+Toggle the item between done and not done.
+.TP
+.B space
+Cycle the item through todo, doing and done.
+.TP
+.B dd
+Cut the item (also copies it for pasting).
+.TP
+.B D
+Remove every done item.
+.TP
+.BR yy ", " p ", " P
+Yank the item, paste it below, or paste it above.
+.TP
+.BR J ", " K
+Move the item down or up. On a section heading this moves the whole section.
+.SS Other
+.TP
+.BR / ", " n ", " N
+Search for text, then jump to the next or previous match.
+.TP
+.BR u ", " "ctrl-r"
+Undo and redo.
+.SH "INSERT MODE"
+Type to insert at the cursor.
+.B enter
+commits the item and opens another below it;
+.B escape
+returns to normal mode, dropping the item if it is empty.
+.B backspace
+deletes, and the arrow keys move the cursor.
+.SH COMMANDS
+Press
+.B :
+to enter a command, then
+.BR enter :
+.TP
+.B :w
+Write the list to its file.
+.TP
+.B :q
+Quit, discarding changes since the last write.
+.TP
+.BR :wq ", " :x
+Write and quit.
+.TP
+.B :reset
+Set every item back to todo, clearing all done and doing states.
+.TP
+.B :clear
+Remove every item, emptying the list.
+.SH OPTIONS
+.TP
+.BR \-h ", " \-\-help
+Print a usage summary and exit.
+.TP
+.BR \-v ", " \-\-version
+Print the version and exit.
+.SH FILES
+.TP
+.B ~/.todo.txt
+The default list. Each line is a task
+.RB ( "[ ] text" ", " "[-] text" ", " "[x] text" ),
+a section
+.RB ( "= name" ),
+or a subtask
+.RB ( "- name" ).
+Override the location with
+.BR $TODO_FILE .
+.SH ENVIRONMENT
+.TP
+.B TODO_FILE
+Path to the list file, used instead of
+.BR ~/.todo.txt .
+.TP
+.B LC_TIME
+Sets the locale for the date and time in the header.
+.SH "EXIT STATUS"
+.TP
+.B 0
+Success.
+.TP
+.B 1
+The terminal could not be initialized, or memory ran out.
+.SH AUTHOR
+hachem <im@hachem.wtf>