Merge branch 'master' into types

1 files changed, 62 insertions, 0 deletions

diff --git a/docs/source/getting_started_command_line.rst b/docs/source/getting_started_command_line.rst
new file mode 100644
index 0000000..0c4d507
--- /dev/null
+++ b/docs/source/getting_started_command_line.rst
@@ -0,0 +1,62 @@
+******************************
+Getting Started (Command Line)
+******************************
+
+lesana can be used from the command line through the ``lesana`` command;
+for more details run ``lesana help``.
+
+Many commands will try to open some file in an editor: they will attempt
+to use, in this order, ``$EDITOR``, ``sensible-editor`` or as a fallback
+``vi``, which should be installed on any POSIX-like system.
+
+To start a new collection, create a directory and run ``lesana
+init`` into it::
+
+    mkdir $DIRECTORY
+    cd $DIRECTORY
+    lesana init
+
+It will create the basic file structure of a lesana collection,
+including a ``settings.yaml`` skeleton and it will initialize a git
+repository (use ``--no-git`` to skip this part and ignore all further
+git commands).
+
+It will then open ``settings.yaml`` in an editor: fill in your list of
+fields and all other data, save and exit.
+You are now ready to commit the configuration for your new collection::
+
+    git commit -m 'Collection settings'
+
+An empty collection is not very interesting: let us start adding new
+entries::
+
+   lesana new
+
+It will again open an editor on a skeleton of entry where you can fill
+in the values. When you close the editor it will print the entry id,
+that you can use e.g. to edit again the same entry::
+
+   lesana edit $ENTRY_ID
+
+After you've added a few entries, you can now search for some word that
+you entered in one of the indexed fields::
+
+   lesana search some words
+
+this will also print the entry ids of matching items, so that you can
+open them with ``lesana edit``.
+
+If you're using git, entries will be autoadded to the staging area, but
+you need to commit them, so that you can choose how often you do so.
+
+Search results are limited by default to 12 matches; to get all results
+for your query you can use the option ``--all``. This is especially
+useful when passing the results to a template::
+
+   lesana search --template templates/my_report.html --all \
+       some search terms \
+       > some_search_terms-report.html
+
+will generate an html file based on the jinja2 template
+``templates/my_report.html`` with all the entries found for those search
+terms.