README

== Introduction ==

display-quote (short: dq) prints a
text from a configured collection.

Its main differences to display-dhammapada and fortune are:

1.) Supports various database formats to be displayed.

2.) Supports a system, user and profiled-based
configuring of what
files are accounted and to which percentage instead of
commandline switches.

3.) A C++ shared library allows the functionality
to be used in every program without calling
display-from-collection externally. This is possible
because the configuration does not happen with
commandline switches.


== Compile ==

Make sure that you have elektra and cmake installed.
Use cmake as usual:

    mkdir build
    cd build
    cmake ..
    make
    make install

or build the debian package with

    git-buildpackage

== Usage ==


First you have to add a new archive to one of the profiles
for example:

 dq public dhamma /usr/share/doc/display-dhammapada/dhammapada-english-transl.txt dhammapada

adds the archive with the name "dhamma" to the profile "public" using
the type (of the database format - see below) dhammapada.

Note that currently the file name (path) must be absolute.
Note that dq currently is only able to add profiles to the
user configuration.

 dq

The default output is one of the quotes of the default profile.


 dq <profile>

Allows you to output a quote from another profile.


 dq <profile> <name of archive> <absolute file> <type of archive>


== Configuration ==

The configuration is below:

/sw/elektra/dq/#0/

in given profiles
the default profile is default
it is possible to merge various profiles
not used profiles are completely ignored

The profiles can be useful to distuingish between
private collections, offensive collections, private
collections and collections for public quoting.

in given entries
for every file you must write an entry

for every entry you can configure:
1.) The name of the file to be used
/sw/elektra/dq/#0/profile/entry/path (type:path)

2.) How often it should be picked (a larger number and it will be picked
	more often)
/sw/elektra/dq/#0/profile/entry/contingency (type:integer)

3.) The format of the database: (dhammapada|quote|paragraph|lines|wiki|task)
/sw/elektra/dq/#0/profile/entry/type (type:enum)

== Databases ==

Plugins do the actual work to read a database.
They will be called for reading the actual
phrase out of the database.

Currently supported are:
=== dhammapada ===
Searches for a paragraph with a number in the end.
Is fair without having an index.

=== quotes ===
A line containing "%" and nothing else opens a new quote.

=== paragraph ===
Every paragraph is considered to be a quote.
(An empty line starts a new quote.)

=== lines ===
Every line is considered to be a quote.
Empty lines are ignored.

== wiki ===
Every Heading (lines starting with =) are considered
to be the separator for quotes. This file itself is
an example.

== task ==
Like lines, but also lines with # are ignored.