.\" ctct.1 - the man page for ctct
.\"
.\" Copyright 2015, 2016 Einhard Leichtfuß
.\"
.\" This file is part of ctct.
.\" 
.\" ctct is free software: you can redistribute it and/or modify
.\" it under the terms of the GNU Affero General Public License as published
.\" by the Free Software Foundation, either version 3 of the License, or
.\" (at your option) any later version.
.\"
.\" ctct is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU Affero General Public License for more details.
.\"
.\" You should have received a copy of the GNU Affero General Public License
.\" along with ctct.  If not, see <http://www.gnu.org/licenses/>.
.\"
.TH CTCT 1 "January 2016"
.SH NAME
ctct \- a simple console contact manager
.SH SYNOPSIS
.BR "ctct " [ -sSed ]
.I NAME
.br
.B ctct -l
.SH DESCRIPTION
.P
.BR ctct " is a contact manager adhering to the KISS principle\."
.P
Any contact entry is stored in a separate file whose name is constituted of
either one pattern or two patterns separated by a dot (\'\.\')\.
These patterns must only consist of common letters according to your locale
and \'_\' and \'\-\' as separators\.
.P
Two such patterns separated by a dot are considered equal in relevance and
are therefore interchangeable, except upon creation\.
This syntax is intended for first and last names of natural persons,
however is obviously not restricted to such\.
Even though upon regular requests the order does not matter,
it is highly recommended to stick to a common syntax,
so that e\.g\. the listing of all contacts is in a reasonable order\.
.P
For the content of such a file there are no rules\.
One can create and edit them in one's favourite editor
.RB "using the " --edit " option"
.RB "or by manually accessing the files in the " datadir \.
Any such file's content is simply displayed when asked for\.
.SH OPTIONS
.TP
.BI "-s, --search-by-name " "PATTERN \fR[\fP\.\.\.\fR]\fP"
.RI "Search for any contact whose name contains " PATTERN " as a substring\.
If the name is constituted by two dot separated parts,
.IR PATTERN " must be a substring of one of them,
i\.e\. it must not contain a dot (\'\.\')\.
If several patterns are given, all must match\.
.TP
.BI "-S, --search-by-data " "PATTERN \fR[\fP\.\.\.\fR]\fP"
Search for entries that contain all the provided patterns\.
A pattern should generally not contain newline characters ('\\n'),
since this may lead to unexpected results\.
.TP
.B -l, --list-all
List all contacts alphabetically by name\.
.TP
.BI "-e, --edit " CONTACT
.RI "Edit or, if non-existent, create the entry " CONTACT \.
.br
If the entry is newly created and the name is intended
.RI "to be dot separated, " CONTACT " should be of the form"
.IR FIRST \. LAST " where " FIRST " and " LAST " stand for the first
and last name, respectively\.
Capitals and any special characters are disallowed, except for '-' and '_'
which can be useful in case of compound names\.
If the actual name contains any special characters, it can be specified
correctly inside the entry itself, on whose format there are precisely no
restrictions\.
.TP
.BI "-d, --delete " CONTACT
.RI "Delete the entry " CONTACT \.
.TP
.BI "--rename " "OLD NEW"
.RI "Rename the entry " OLD " to " NEW \.
.TP
.B --version
Show brief version and licensing information\.
.TP
.B -h, --help
Show a simple help text basically depicting the above options\.
.SH CONFIGURATION
.P
.RI "The main configuration file is " @default_confdir@/config\.sh \.
.TP
.B user_config_dir
.RI "The directory where the per user configuration file " config\.sh
is searched for\.
.RI "If set, this variable must contain the prefix " $HOME
or alternatively any other variable resolving to a directory
below the respective home directory\.
.RI "The default value is " @default_user_config_dir@ \.
.TP
.B datadir
The location of the directory where the contact data are stored\.
.RB "Typically, " datadir " should contain the prefix
.IR $HOME \.
.RI "The default value is " @default_datadir@ \.
.TP
.B default_editor
.RB "The editor to use when " ctct " is called with"
.RI "the " --edit " option\.
.RB "If set, supersedes both the " EDITOR " environment variable"
.RB "and the " fallback_editor \.
.TP
.B fallback_editor
.RB "The editor to fall back to if neither the environment variable " EDITOR
.RB "nor " default_editor " is set\."
.RI "The default value is " @default_fallback_editor@ \.
.TP
.B input_program
The program with arguments
that gets passed the data written after editing a contact entry\.
.RB "This is mostly useful in combination with an " output_program
to enable encryption\.
.br
.RB "If both " input_program " and " output_program"
.RI "are set to " cat ", they have no special effect\."
.RB "Elsewise, calling " ctct " with"
.RI "the " --edit " option, will create a temporary file which, if existent,"
.RB "will contain the contact data as print by the " output_program \.
This temporary file will then be opened in the respective editor
.RB "and afterwards passed to the " input_program " on stdin
whose stdout is finally written to disk permanently\.
.RI "The default value is " @default_input_program@ \.
.TP
.B output_program
The program with arguments
that any contact data that are to be print are passed to\.
Note, that the respective program must accept its input on stdin and print
its output on stdout\.
This option is hence not useful for pagers such as
.BR less "(1) or " more "(1)\."
.RB "Use " visual_program " for this purpose\."
.RI "The default value is " @default_output_program@ \.
.RB "For further details, see " input_program \.
.TP
.B visual_program
.RB "The program that the data as written by the " output_program
are passed to\. It can be used with any program accepting its input on stdin,
though the most common options are 
.BR cat "(1), " less "(1) and " more "(1)\."
.RI "If it is set to " cat ", it has no effect\."
.RI "The default value is " @default_visual_program@ \.
.TP
.B confirm_deletion
Whether to ask for confirmation upon deleting an entry,
.RB "i\.e\. when called with the " --delete " option\."
.RI "The default value is " @default_confirm_deletion@ \.
.TP
.B confirm_default_yes
Whether to assume yes as answer to confirmation when no answer,
i\.e\. an empty answer is given\.
.RB "This option only has an effect, if " confirm_deletion
is set to true\.
.RI "The default value is " @default_confirm_default_yes@ \.
.SH ENVIROMENT
.TP
.B EDITOR
.RB "The editor to use when " ctct " is called"
.RI "with the " --edit " option\.
.RB "If " default_editor " is set, " EDITOR " has no effect\."
.TP
.B HOME
The directory below of which the contact data and the user configuration
file are stored by default\.
.SH FILES
.TP
.I @default_confdir@/config\.sh
System wide configuration file
.TP
.I @default_user_config_dir@/config\.sh
Default location of the user configuration file
.TP
.I @default_datadir@/
.RB "Default " datadir