Matthias Beyer
db3bb95227
This patch adds user documentation in for of a mdbook, using a travis job for running the build of the book in CI to be sure it builds properly. Signed-off-by: Matthias Beyer <mail@beyermatthias.de>
46 lines
1.5 KiB
Markdown
46 lines
1.5 KiB
Markdown
# Conventions
|
|
|
|
imag has a few conventions which we try to enforce in all module
|
|
implementations. This chapter explains the conventions an end-user of imag can
|
|
rely on.
|
|
|
|
|
|
## Commandline interface
|
|
|
|
The commandline interface of every subcommand has a "--help" flag which can be
|
|
used to print helptext for the subcommand.
|
|
|
|
Every imag module implementation can be used for scripting, where it behaves in
|
|
the following ways:
|
|
|
|
* If the standard input is a pipe, imag module implementations assume that store
|
|
ids are written to that pipe line by line.
|
|
* If the standard output is a pipe, every imag module prints the StoreIDs it
|
|
touched while running to the pipe.
|
|
All other output is written to stderr.
|
|
Piping can be used to combine imag commands.
|
|
* If the standard output is not a pipe, the imag module does not print the
|
|
StoreIDs it touched.
|
|
|
|
This behaviour can be overridden with the `--ignore-ids` flag.
|
|
|
|
## Versioning
|
|
|
|
imag modules are compatible to eachother as long as the version number is in the
|
|
`0.x.y` range.
|
|
Modules from different imag versions are not supported to be compatible to
|
|
eachother.
|
|
|
|
|
|
## Commandline capabilities
|
|
|
|
The imag commands can be used to access _all_ data that is stored in the imag
|
|
store.
|
|
Alternatively, standard unix commandline tools (like `grep`, `cut`, `sed`, ...)
|
|
can be used to access all data and all data-points.
|
|
|
|
In short: All data imag stores is stored in plain text, containing a structured
|
|
part (in the markup language "toml") and a plain-text part (which should be
|
|
UTF-8 encoded).
|
|
|
|
|