Improve ctct(1)

- Try to conform to man-pages(7).
 `- Try to avoid technical information.
 `- Remove the CONFIGURATION section.  It's contents are to reappear in
    ctct_config(5) which ctct(1) already references.
- Add some commented blank lines to improve readability.

Also, in the main script:
- Add EXIT_* variables.  Not yet used.
- Improve the naming in the help output.
- Stop option parsing on '--'.
- In the default case (i.e. no special option), return 1 if only a non
  exact match was found.

1 files changed, 158 insertions, 130 deletions

diff --git a/ctct.1.in b/ctct.1.in
index b686659..1f1debf 100644
--- a/ctct.1.in
+++ b/ctct.1.in
@@ -1,6 +1,6 @@
 .\" ctct.1 - the man page for ctct
 .\"
-.\" Copyright 2015 - 2017 Einhard Leichtfuß
+.\" Copyright 2015 - 2018 Einhard Leichtfuß
 .\"
 .\" This file is part of ctct.
 .\" 
@@ -17,170 +17,198 @@
 .\" 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 "August 2017"
+.TH CTCT 1 "2018-12-24" "ctct @PACKAGE_VERSION@"
+.\"
+.\"
 .SH NAME
 ctct \- a simple console contact manager
+.\"
+.\"
 .SH SYNOPSIS
-.BR "ctct " [ -sSed ]
-.I NAME
+.B ctct
+.I name
+.br
+.B ctct \-s
+.I pattern
+.br
+.B ctct \-S
+.I regex
 .br
-.B ctct -l
+.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
-.BR ctct " is a contact manager adhering to the KISS principle\."
+.B ctct
+manages a set of simple contact entries, identified by
+.IR 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
-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\.
+.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\.
-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\.
+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
-.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 (\'\.\')\.
+.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
-.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\.
+.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
-.B -l, --list-all
+.B \-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
-.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\.
+.BI "\-e, \-\-edit " name
+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
-.BI "-d, --delete " CONTACT
-.RI "Delete the entry " CONTACT \.
+.BI "\-d, \-\-delete " name \.\.\.
+Delete all specified contact entries\.
+.\"
 .TP
-.BI "--rename " "OLD NEW"
-.RI "Rename the entry " OLD " to " NEW \.
+.BI "\-\-rename " "old new"
+Rename the entry
+.I old
+to
+.IR new \.
+.\"
 .TP
-.B --version
+.B \-\-version
 Show brief version and licensing information\.
+.\"
 .TP
-.B -h, --help
+.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 \.
-.R By default, unset.
-.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@ \.
+.\"
+.\"
+.SH EXIT STATUS
+.TP
+.B 0
+Successfull operation\.
+In case of
+.BR \-\-search\-by\-name
+or
+.BR \-\-search\-by\-data ,
+at least one matching entry was found\.
+.\"
 .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@ \.
+.B 1
+An error occurred or, in case of
+.B \-\-search\-by\-name
+or
+.BR \-\-search\-by\-data ,
+no matching entry was found\.
+.\"
+.\"
 .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\."
+The editor to use when \fBctct\fP is called with the \fI\-\-edit\fP
+option and \fBdefault_editor\fP is not set in \fBctct_config\fP(5)\.
+.\"
 .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
+System wide configuration file\.
+.\"
 .TP
 .I @default_user_config_dir@/config\.sh
-Default location of the user configuration file
+Default location of the user configuration file\.
+.\"
 .TP
 .I @default_datadir@/
-.RB "Default " datadir
+.RB "Default " datadir\.
+.\"
+.\"
+.SH SEE ALSO
+.BR ctct_config (5),
+.BR grep (1)
+.\" vi: tw=75