.\" 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
the contact\'s first and last name separated by a dot (\'\.\')\.
Allowed characters are the small letters of the english alphabet and
\'_\' and \'\-\' as separators\.
.P
Obviously nobody is required to actually use the first and last name
of a natural person, nor to stick to the rule to use the first name first\.
Actually the order does not matter much, since a contact can always also be
specified in reverse order of first and last name,
except for the case that it is newly created.
Though 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"
or by manually accessing the files in the
.BR 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 first or last name contains " PATTERN "
as a substring\. 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')\.
If any pattern though does, it is treated as a list of patterns,
separated by newlines, which all have to match\.
.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
.RI "If the entry is newly created, " 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
.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 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@ \.
.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
.SH TODO
.P
.RB "Add an option to specify the output program - e\.g\. " cat (1)
.RB "or " less (1)\.