.\" ctct.1 - the man page for ctct
.\"
.\" Copyright 2015 - 2019 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 <https://www.gnu.org/licenses/>.
.\"
.TH CTCT 1 "2019-01-10" "ctct @PACKAGE_VERSION@"
.\"
.\"
.SH NAME
ctct \- a simple console contact manager
.\"
.\"
.SH SYNOPSIS
.B ctct
.I name
.br
.B ctct \-s
.I pattern
.br
.B ctct \-S
.I regex
.br
.B ctct \-e
.I name
.br
.B ctct \-d
.IR name " \.\.\."
.br
.B ctct \-\-rename
.I old new
.br
.B ctct \-\-version
.br
.B ctct \-h
.\"
.\"
.SH DESCRIPTION
.P
.B ctct
manages a set of simple contact entries, identified by name\.
If called with no special arguments,
the contact entry identified by
.I name
is displayed\.
If no such contact entry exists, the result will be similar to that
provided by the
.B --search-by-name
option\.
.P
.I name
may optionally contain exactly one dot (\(aq\.\(aq), which serves as a
separator between two name parts considered equal in relevance\.
This syntax is intended for first and last names of natural persons,
however is obviously not restricted to such\.
.P
It is recommended to stick to a common semantical order at creation, such
as
.IR first \. last
where
.I first
and
.I last
denote the first respectively last name of a natural person,
so that for example the listing of all contact entries is in a reasonable
order\.
.\"This will notably allow for a listing of all the contact entries in a
.\"reasonable order\.
.P
A name or name's part may further contain \(aq_\(aq and \(aq\-\(aq as
separators\.
These may be useful in compound names\.
All other characters must be common letters, according to your locale\.
.P
Contact entries are stored in separate files and may contain arbitrary
text\.
It may be a good idea though to stick to a common syntax\.
For example, a table of the form
.I attribute: value
might make for a good header\.
.P
Configuration is done in
.BR ctct_config (5)\.
For example, the program used to display a contact entry may be changed
(e\.g\.,
.BR less (1))\.
Also, encryption of contact entries may be configured, using your favourite
encryption program (e\.g\.,
.BR gpg (1))\.
.\"
.\"
.SH OPTIONS
.TP
.BR \-s ", " \-\-search\-by\-name " \fIpattern\fP \.\.\."
Search for contacts whose names contain
.I pattern
as a substring\.
If the name is constituted of two dot separated parts,
.I pattern
must be a substring of one of them, hence
.I pattern
will not match if it contains a dot (\(aq\.\(aq)\.
If several patterns are given, all must match\.
Comparison is case insensitive\.
.\"
.TP
.BR \-S ", " \-\-search\-by\-data " \fIregexp\fP \.\.\."
Search for entries that match all the provided extended regular
expressions\.
Matching is case insensitive\.
See also
.BR grep (1)\.
.\"
.TP
.BR \-l ", " \-\-list\-all
List all contacts alphabetically by name\.
If a contact entry is composed of two dot separated parts, these parts'
order is the one chosen at creation respectively renaming\.
.\"
.TP
.BR \-e ", " \-\-edit " \fIname\fP"
Edit and, if non-existent, create the entry identified by
.IR name \.
For the format of
.IR name ,
see
.BR DESCRIPTION \.
Due to the format limitations, it may be a good idea to correctly specify
the actual name inside the contact entry, on whose format there are
precisely no restrictions\.
.\"
.TP
.BR \-d ", " \-\-delete " \fIname\fP \.\.\."
Delete all specified contact entries\.
.\"
.TP
.BI "\-\-rename " "old new"
Rename the entry
.I old
to
.IR new \.
.\"
.TP
.B \-\-version
Show brief version and licensing information\.
.\"
.TP
.BR \-h ", " \-\-help
Show a simple help text basically depicting the above options\.
.\"
.\"
.SH EXIT STATUS
.TP
.B @ret_success@
Successfull operation\.
In case of
.BR \-\-search\-by\-name
or
.BR \-\-search\-by\-data ,
at least one matching entry was found\.
.\"
.TP
.B @ret_failure@
In case of
.BR \-\-search\-by\-name
or
.BR \-\-search\-by\-data ,
no matching entry was found\.
Elsewise, the action did not succeed, for example due to the requested name
not referring to an existing contact entry\.
.\"
.TP
.B @ret_badsyntax@
The used command contains bad syntax which will fail under any conditions\.
.\"
.TP
.B @ret_error@
An unexpected error occurred, for example due to missing permissions in
.BR datadir \.
.\"
.\"
.SH ENVIRONMENT
.TP
.B VISUAL
The editor to use when \fBctct\fP is called with the \fB\-\-edit\fP
option and \fBdefault_editor\fP is not set in \fBctct_config\fP(5)\.
Supersedes $\fBEDITOR\fP, if set\.
.\"
.TP
.B EDITOR
The editor to use when \fBctct\fP is called with the \fB\-\-edit\fP
option and neither \fBdefault_editor\fP is set in \fBctct_config\fP(5),
nor the environment variable $\fBEDITOR\fP\.
.\"
.\"
.SH SEE ALSO
.BR ctct_config (5),
.BR grep (1)
.\"
.\" vi: tw=75