Start writing manpages for lesana and its subcommands

3 files changed, 117 insertions, 2 deletions

diff --git a/README.rst b/README.rst
index 2dac769..366446b 100644
--- a/README.rst
+++ b/README.rst
@@ -20,8 +20,7 @@ in the documentation file ``field_types``.
 
 Some example collection schemas are provided, but one big strenght of
 lesana is the ability to customize your collection with custom fields
-either by simply writing a personalize schema.yaml or, in more complex
-cases, by inheriting from it in another module.
+by simply writing a personalized ``settings.yaml``.
 
 Installation
 ------------
diff --git a/docs/man/lesana-init.rst b/docs/man/lesana-init.rst
new file mode 100644
index 0000000..92527c0
--- /dev/null
+++ b/docs/man/lesana-init.rst
@@ -0,0 +1,40 @@
+===========
+lesana-init
+===========
+
+------------------------------
+initialize a lesana collection
+------------------------------
+
+:Author: valhalla@trueelena.org
+:Manual section: 1
+
+SYNOPSIS
+========
+
+lesana init [--help] [--collection <collection>] [--no-git]
+
+DESCRIPTION
+===========
+
+lesana init initializes a new lesana collection.
+
+It will create the directory (if it does not exist) and, unless
+``--no-git`` is specified it will initialize it as a git repository and
+create a ``.gitignore`` file with some relevant contents.
+
+It will then create a skeleton ``settings.yaml`` file and open it in an
+editor to start configuring the collection.
+
+When leaving the editor, again unless ``--no-git`` is used, it will add
+this file to the git staging area, but not commit it.
+
+OPTIONS
+=======
+
+--help, -h
+   Prints an help message and exits.
+--collection COLLECTION, -c COLLECTION
+   The directory where the collection will be initialized. Default is .
+--no-git
+   Do not use git in the current collection.
diff --git a/docs/man/lesana.rst b/docs/man/lesana.rst
new file mode 100644
index 0000000..0d60e4f
--- /dev/null
+++ b/docs/man/lesana.rst
@@ -0,0 +1,76 @@
+======
+lesana
+======
+
+------------------------------
+manages collection inventories
+------------------------------
+
+:Author: valhalla@trueelena.org
+:Manual section: 1
+
+SYNOPSIS
+========
+
+lesana [--help] <command>
+
+DESCRIPTION
+===========
+
+lesana is a tool to organize collections of various kinds.  It is
+designed to have a data storage / serialization format that is friendly
+to git and other VCSs, but decent performances.
+
+To reach this aim it uses yaml_ as its serialization format, which is
+easy to store in a VCS, share between people and syncronize between
+different computers, but it also keeps an index of this data in a local
+xapian_ database in order to allow for fast searches.
+
+.. _yaml: http://yaml.org/
+.. _xapian: https://xapian.org/
+
+lesana supports collections of any kind, as long as their entries can be
+described with a mostly flat dictionary of fields of the types described
+in the documentation file ``field_types``.
+
+Some example collection schemas are provided, but one big strenght of
+lesana is the ability to customize your collection with custom fields
+either by simply writing a personalized ``settings.yaml``.
+
+OPTIONS
+=======
+
+-h, --help
+   Prints an help message and exits.
+
+COMMANDS
+========
+
+new(1)
+   Creates a new entry.
+edit(1)
+   Edits an existing entry.
+show(1)
+   Shows an existing entry.
+index(1)
+   Index some entries in the xapian cache.
+search(1)
+   Searches for entries in the xapian cache.
+export(1)
+   Exports entries from one lesana collection to another
+init(1)
+   Initialize a new lesana collection
+rm(1)
+   Removes an entry.
+
+TEXT EDITOR
+===========
+
+Many lesana subcommands will try to open files in a text editor choosen
+as follows:
+
+* first, the value of $EDITOR is tried
+* then the command ``sensible-editor``, as available under e.g. Debian
+  and its derivatives
+* lastly, it will try to fallback to ``vi``, which should be available
+  under any posix system.