From 54185616ef81fa1da57b3d3bad4d9f5f71c0b07c Mon Sep 17 00:00:00 2001 From: Elena ``of Valhalla'' Grandi Date: Thu, 8 Oct 2020 20:42:54 +0200 Subject: Split documentation by target --- docs/source/user/getting_started_command_line.rst | 62 +++++++++++++++++++++++ 1 file changed, 62 insertions(+) create mode 100644 docs/source/user/getting_started_command_line.rst (limited to 'docs/source/user/getting_started_command_line.rst') diff --git a/docs/source/user/getting_started_command_line.rst b/docs/source/user/getting_started_command_line.rst new file mode 100644 index 0000000..0c4d507 --- /dev/null +++ b/docs/source/user/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. -- cgit v1.2.3