diff options
Diffstat (limited to 'docs/source/man')
| -rw-r--r-- | docs/source/man/Makefile | 12 | ||||
| -rw-r--r-- | docs/source/man/index.rst | 17 | ||||
| -rw-r--r-- | docs/source/man/lesana-edit.rst | 35 | ||||
| -rw-r--r-- | docs/source/man/lesana-export.rst | 32 | ||||
| -rw-r--r-- | docs/source/man/lesana-index.rst | 30 | ||||
| -rw-r--r-- | docs/source/man/lesana-init.rst | 40 | ||||
| -rw-r--r-- | docs/source/man/lesana-new.rst | 37 | ||||
| -rw-r--r-- | docs/source/man/lesana-rm.rst | 30 | ||||
| -rw-r--r-- | docs/source/man/lesana-search.rst | 37 | ||||
| -rw-r--r-- | docs/source/man/lesana-show.rst | 45 | ||||
| -rw-r--r-- | docs/source/man/lesana.rst | 76 |
11 files changed, 391 insertions, 0 deletions
diff --git a/docs/source/man/Makefile b/docs/source/man/Makefile new file mode 100644 index 0000000..0369f59 --- /dev/null +++ b/docs/source/man/Makefile @@ -0,0 +1,12 @@ + +MAN_TARGETS = $(patsubst %.rst,%.1,$(wildcard *.rst)) + +all: $(MAN_TARGETS) + +%.1: %.rst + rst2man $< > $@ + +clean: + rm *.1 + +.PHONY: all clean diff --git a/docs/source/man/index.rst b/docs/source/man/index.rst new file mode 100644 index 0000000..65d92a1 --- /dev/null +++ b/docs/source/man/index.rst @@ -0,0 +1,17 @@ +********* +Man Pages +********* + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + lesana-edit + lesana-export + lesana-index + lesana-init + lesana-new + lesana-rm + lesana + lesana-search + lesana-show diff --git a/docs/source/man/lesana-edit.rst b/docs/source/man/lesana-edit.rst new file mode 100644 index 0000000..75bcaeb --- /dev/null +++ b/docs/source/man/lesana-edit.rst @@ -0,0 +1,35 @@ +=========== +lesana-edit +=========== + +------------------------------ +edits an existing lesana entry +------------------------------ + +:Author: valhalla@trueelena.org +:Manual section: 1 + +SYNOPSIS +======== + +lesana edit [--help] [--collection <collection>] [--no-git] <entry> + +DESCRIPTION +=========== + +Lesana edit will open an existing entry (specified by id or partial id) +in an editor, so that it can be changed. + +If the collection is configured to use git, after the editor has been +closed, it will add the file to the git staging area, unless +``--no-git`` is given. + +OPTIONS +======= + +-h, --help + Prints an help message and exits. +--collection COLLECTION, -c COLLECTION + The collection to work on. Default is ``.`` +--no-git + Don't add the new entry to git. diff --git a/docs/source/man/lesana-export.rst b/docs/source/man/lesana-export.rst new file mode 100644 index 0000000..6088dbf --- /dev/null +++ b/docs/source/man/lesana-export.rst @@ -0,0 +1,32 @@ +============= +lesana-export +============= + +------------------------------------------------- +export data from one lesana collection to another +------------------------------------------------- + +:Author: valhalla@trueelena.org +:Manual section: 1 + +SYNOPSIS +======== + +lesana export [-h] [--collection COLLECTION] [--query QUERY] destination template + +DESCRIPTION +=========== + +Lesana export converts entries from one lesana collection to another, +using a jinja2 template. + +OPTIONS +======= + +-h, --help + Prints an help message and exits. +--collection COLLECTION, -c COLLECTION + The collection to work on. Default is ``.`` +--query QUERY, -q QUERY + Xapian query to search in the collection + diff --git a/docs/source/man/lesana-index.rst b/docs/source/man/lesana-index.rst new file mode 100644 index 0000000..d535c02 --- /dev/null +++ b/docs/source/man/lesana-index.rst @@ -0,0 +1,30 @@ +============ +lesana-index +============ + +------------------ +Index some entries +------------------ + +:Author: valhalla@trueelena.org +:Manual section: 1 + +SYNOPSIS +======== + +lesana index [--help] [--collection COLLECTION] [files [files ...]] + +DESCRIPTION +=========== + +Lesana index adds some entries to the xapian cache, listed by filename +(by default all of the files found in the items directory). + +OPTIONS +======= + +-h, --help + Prints an help message and exits. +--collection COLLECTION, -c COLLECTION + The collection to work on. Default is ``.`` + diff --git a/docs/source/man/lesana-init.rst b/docs/source/man/lesana-init.rst new file mode 100644 index 0000000..92527c0 --- /dev/null +++ b/docs/source/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/source/man/lesana-new.rst b/docs/source/man/lesana-new.rst new file mode 100644 index 0000000..4c7a10d --- /dev/null +++ b/docs/source/man/lesana-new.rst @@ -0,0 +1,37 @@ +========== +lesana-new +========== + +------------------------- +create a new lesana entry +------------------------- + +:Author: valhalla@trueelena.org +:Manual section: 1 + +SYNOPSIS +======== + +lesana new [--help] [--collection <collection>] [--no-git] + +DESCRIPTION +=========== + +Lesana new creates a new lesana entry. + +It will create an empty entry and open an editor so that it can be +filled. + +If the collection is configured to use git, after the editor has been +closed, it will add the file to the git staging area, unless +``--no-git`` is given. + +OPTIONS +======= + +-h, --help + Prints an help message and exits. +--collection COLLECTION, -c COLLECTION + The collection to work on. Default is ``.`` +--no-git + Don't add the new entry to git. diff --git a/docs/source/man/lesana-rm.rst b/docs/source/man/lesana-rm.rst new file mode 100644 index 0000000..4f765a5 --- /dev/null +++ b/docs/source/man/lesana-rm.rst @@ -0,0 +1,30 @@ +========= +lesana-rm +========= + +---------------------------------------- +remove an entry from a lesana collection +---------------------------------------- + +:Author: valhalla@trueelena.org +:Manual section: 1 + +SYNOPSIS +======== + +lesana rm [-h] [--collection COLLECTION] entries [entries ...] + +DESCRIPTION +=========== + +Lesana rm removes an entry from the collection, removing both the file +and the cached entry. + +OPTIONS +======= + +-h, --help + Prints an help message and exits. +--collection COLLECTION, -c COLLECTION + The collection to work on. Default is ``.`` + diff --git a/docs/source/man/lesana-search.rst b/docs/source/man/lesana-search.rst new file mode 100644 index 0000000..9375541 --- /dev/null +++ b/docs/source/man/lesana-search.rst @@ -0,0 +1,37 @@ +============= +lesana-search +============= + +--------------------------------- +search inside a lesana collection +--------------------------------- + +:Author: valhalla@trueelena.org +:Manual section: 1 + +SYNOPSIS +======== + +lesana search [--help] [--collection COLLECTION] [--template TEMPLATE] \ +[--offset OFFSET] [--pagesize PAGESIZE] [--all] query [query ...] + +DESCRIPTION +=========== + + +OPTIONS +======= + +-h, --help + Prints an help message and exits. +--collection COLLECTION, -c COLLECTION + The collection to work on. Default is ``.`` +--template TEMPLATE, -t TEMPLATE + Template to use when displaying results +--offset OFFSET + . +--pagesize PAGESIZE + . +--all + Return all available results + diff --git a/docs/source/man/lesana-show.rst b/docs/source/man/lesana-show.rst new file mode 100644 index 0000000..516f9de --- /dev/null +++ b/docs/source/man/lesana-show.rst @@ -0,0 +1,45 @@ +=========== +lesana-show +=========== + +------------------- +show a lesana entry +------------------- + +:Author: valhalla@trueelena.org +:Manual section: 1 + +SYNOPSIS +======== + +lesana show [--help] [--collection COLLECTION] [--template TEMPLATE] <entry> + +DESCRIPTION +=========== + +``lesana show`` will print an entry (specified by id or partial id) to +stdout. + +A template can be specified with ``--template <template>`` to pretty +print entries. + +OPTIONS +======= + +-h, --help + Prints an help message and exits. +--collection COLLECTION, -c COLLECTION + The collection to work on. Default is ``.`` +--template TEMPLATE, -t TEMPLATE + Use the specified template to display results. + +TEMPLATES +========= + +The templates used by ``lesana show`` are jinja2 templates. + +The entry fields are available as variables, and the full entry is +available as the variable ``entry`` and can be used to give access to +fields with names that aren't valid jinja2 variables e.g. as +``entry.data[<field-name>]``. + diff --git a/docs/source/man/lesana.rst b/docs/source/man/lesana.rst new file mode 100644 index 0000000..0d60e4f --- /dev/null +++ b/docs/source/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. |