document t-archive and t-kill

docs/source/index.rst

@@ -4,13 +4,13 @@ Tiempo
 Synopsys
 --------
 
-**t** -h|--help
+``t -h|--help``
 
-**t** help SUBCOMMAND
+``t help SUBCOMMAND``
 
-**t** SUBCOMMAND -h|--help
+``t SUBCOMMAND -h|--help``
 
-**t** SUBCOMMAND [OPTIONS]
+``t SUBCOMMAND [OPTIONS]``
 
 Subcommands
 -----------
@@ -90,20 +90,28 @@ Tutorial
 Subcommands
 -----------
 
+.. _t-archive:
+
 t-archive
 .........
 
 ``t a|archive [OPTIONS] [SHEET]``
 
+To archive means to move entries from the current or specified timesheet to a
+different "hidden" sheet so that when you query the current sheet you don't see
+them but they are kept in the database. Archived entries are stored in a sheet
+with the same name of the original with an underscore as prefix. Use
+:ref:`t-list` to see archived sheets.
+
 By default this command will ask for you confirmation, then archive ALL entries
 in the current timesheet. Pass ``--fake`` to only display the entries using the
 ``text`` formatter (useful if you want to make sure that the archived
 time/entries are correct).
 
 Using ``--start`` and ``--end`` you can further limit the period of time that
-will be archived (See **Specifying times** section of the docs on the accepted
-formats). You can use ``--grep`` to only archive certain entries that match the
-given regular expression.
+will be archived (See :ref:`specifying-times` section of the docs on the
+accepted formats). You can use ``--grep`` to only archive certain entries that
+match the given regular expression.
 
 If what you need is to archive a specific elapsed time, for example only 15
 hours out of however many the timesheet has use ``--time`` with the amount of
@@ -182,12 +190,12 @@ file. If you pass arguments they'll be used to edit your config file in place.
 
 --default-formatter <FORMATTER>
    The format to use when display commands are invoked without a ``--format``
-   option. Defaults to ``'text'``. See **Settings** section of the docs for
+   option. Defaults to ``'text'``. See :ref:`settings` section of the docs for
    per-command default formatter.
 
 ``--formatter-search-paths <PATH>[,<PATH>...]``
-   comma separated paths to search for user defined fomatters. See **Custom
-   formatters** section for more info on this.
+   comma separated paths to search for user defined fomatters. See
+   :ref:`custom-formatters` section for more info on this.
 
 --interactive-entries <N>
    How many unique previous notes to show when selecting interactively. An
@@ -256,7 +264,7 @@ new text will be appended to the previous one using whatever string is set as
 :ref:`append_notes_delimiter` in the settings file.
 
 The last entry is defined as the one that was started last, not necessarily the
-one with the highest ID in the current timesheet. 
+one with the highest ID in the current timesheet.
 
 You can also leave the note untouched and edit other parts of the entry like its
 start and end times using ``--start`` and ``--end`` respectively, see
@@ -310,6 +318,31 @@ ago:
 t-kill
 ......
 
+``t k|kill (--id ID|--last|SHEET)``
+
+Use this to completely delete entries. Pass a timesheet name to delete all
+entries from it or use ``--id`` to delete an entry by its ID. IDs from entries
+can be shown passing ``-v`` to the 'display' family of subcommands. To delete
+only the last entry from the sheet pass ``--last`` as single argument.
+
+This command will ask for confirmation before touching the database.
+
+If you'd prefer to keep record of entries but have them out of the way use
+:ref:`t-archive`.
+
+**Options**
+
+-l, --last
+   Delete the last entry of the current sheet
+
+--id <ID>
+   Delete entry with this ID instead of sheet
+
+``<SHEET>``
+   Delete an entire sheet by its name
+
+.. _t-list:
+
 t-list
 ......
 
@@ -426,7 +459,7 @@ Files and paths
 
 .. note::
 
-   explain the config file, and database path
+   explain the config file, database path and environment variables
 
 .. _specifying-times: