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.

8 files changed, 206 insertions, 154 deletions

diff --git a/CHANGELOG b/CHANGELOG
index c0a2c5c..efa17ae 100644
--- a/CHANGELOG
+++ b/CHANGELOG
@@ -16,6 +16,12 @@ General:
 - Switch to extended regular expressions (EREs) for `--search-by-data'.
 
 
+Manual:
+-------
+
+- Improve and correct ctct(1).
+
+
 Compatibility:
 --------------
 - Fixed incompatibility with OpenBSD.
diff --git a/README b/README
index 00832e1..dd5bda5 100644
--- a/README
+++ b/README
@@ -1,6 +1,6 @@
 README for ctct - a simple console contact manager
 
-Version 0.2.X
+Version 0.2.3-dev
 
 
 How to install:
diff --git a/TODO b/TODO
index 6dea8e3..09b7fab 100644
--- a/TODO
+++ b/TODO
@@ -4,23 +4,34 @@ TODO file for ctct
 * consider using an array for *_program to specify arguments
  `- to circumvent the necessity for eval
 * Honor $VISUAL.
+* Use git tags for future versions.
+* Rename ctct/config.sh to ctct_config.
+* On `ctct -s <pattern>', do not match illegal sequences (e.g. a+b).
+* On `ctct -l', do only list legal names (e.g. not a+b).
+* [consider] On `ctct -d', check format of string.
+* [consider] Remove character restriction except '.', '/'.
+* [consider] Use `grep -F' for --search-by-name.
+* Use the EXIT_* variables.
 
 [CONFIGURE SCRIPT]
 * Take care of some_dir=/ (man page).
 
 [FEATURES]
-* care about pictures/ subdirectory
-* care about directories in general
-* autocompletion for '--search-by-name' (questionable)
-* upon a single result ('--search-by-*), directly display the contents of the
-  entry
+* [consider] Allow for directories with special meaning (e.g. pictures/).
+* [consider] Autocompletion for '--search-by-name' (questionable).
+* [consider] Upon a single result ('--search-by-*), directly display the
+  contents of the entry
  `- should be made customizable
 * [optional] Do not create a new entry if nothing is entered in the editor.
+* Support templates.
+* Different return types for errors and non-matches.
+* Quiet option for --search-by-*.
+
+[MANUAL]
+* Split off ctct_config(5).
+* Add an EXAMPLE section to ctct(1).
 
 [BUGS]
 * strange behaviour:
  `- `ctct -S $'mobile\nabc'
  `- `ctct -S $'mobile\na'
-
-[MISC]
-* Merge the many versions' different CHANGELOGs.
diff --git a/configure b/configure
index 82d5c3f..280f460 100755
--- a/configure
+++ b/configure
@@ -1,6 +1,6 @@
 #! /bin/sh
 # Guess values for system-dependent variables and create Makefiles.
-# Generated by GNU Autoconf 2.69 for ctct 0.2.X.
+# Generated by GNU Autoconf 2.69 for ctct 0.2.3-dev.
 #
 # Report bugs to <alguien@respiranto.de>.
 #
@@ -579,8 +579,8 @@ MAKEFLAGS=
 # Identity of this package.
 PACKAGE_NAME='ctct'
 PACKAGE_TARNAME='ctct'
-PACKAGE_VERSION='0.2.X'
-PACKAGE_STRING='ctct 0.2.X'
+PACKAGE_VERSION='0.2.3-dev'
+PACKAGE_STRING='ctct 0.2.3-dev'
 PACKAGE_BUGREPORT='alguien@respiranto.de'
 PACKAGE_URL=''
 
@@ -1192,7 +1192,7 @@ if test "$ac_init_help" = "long"; then
   # Omit some internal or obsolete options to make the list less imposing.
   # This message is too long to be a string in the A/UX 3.1 sh.
   cat <<_ACEOF
-\`configure' configures ctct 0.2.X to adapt to many kinds of systems.
+\`configure' configures ctct 0.2.3-dev to adapt to many kinds of systems.
 
 Usage: $0 [OPTION]... [VAR=VALUE]...
 
@@ -1253,7 +1253,7 @@ fi
 
 if test -n "$ac_init_help"; then
   case $ac_init_help in
-     short | recursive ) echo "Configuration of ctct 0.2.X:";;
+     short | recursive ) echo "Configuration of ctct 0.2.3-dev:";;
    esac
   cat <<\_ACEOF
 
@@ -1346,7 +1346,7 @@ fi
 test -n "$ac_init_help" && exit $ac_status
 if $ac_init_version; then
   cat <<\_ACEOF
-ctct configure 0.2.X
+ctct configure 0.2.3-dev
 generated by GNU Autoconf 2.69
 
 Copyright (C) 2012 Free Software Foundation, Inc.
@@ -1363,7 +1363,7 @@ cat >config.log <<_ACEOF
 This file contains any messages produced by compilers while
 running configure, to aid debugging if configure makes a mistake.
 
-It was created by ctct $as_me 0.2.X, which was
+It was created by ctct $as_me 0.2.3-dev, which was
 generated by GNU Autoconf 2.69.  Invocation command line was
 
   $ $0 $@
@@ -2327,7 +2327,7 @@ cat >>$CONFIG_STATUS <<\_ACEOF || ac_write_fail=1
 # report actual input values of CONFIG_FILES etc. instead of their
 # values after options handling.
 ac_log="
-This file was extended by ctct $as_me 0.2.X, which was
+This file was extended by ctct $as_me 0.2.3-dev, which was
 generated by GNU Autoconf 2.69.  Invocation command line was
 
   CONFIG_FILES    = $CONFIG_FILES
@@ -2380,7 +2380,7 @@ _ACEOF
 cat >>$CONFIG_STATUS <<_ACEOF || ac_write_fail=1
 ac_cs_config="`$as_echo "$ac_configure_args" | sed 's/^ //; s/[\\""\`\$]/\\\\&/g'`"
 ac_cs_version="\\
-ctct config.status 0.2.X
+ctct config.status 0.2.3-dev
 configured by $0, generated by GNU Autoconf 2.69,
   with options \\"\$ac_cs_config\\"
 
diff --git a/configure.ac b/configure.ac
index d69c7a6..c2f8011 100644
--- a/configure.ac
+++ b/configure.ac
@@ -18,7 +18,7 @@
 # along with ctct.  If not, see <https://www.gnu.org/licenses/>.
 #
 
-AC_INIT([ctct], [0.2.X], [alguien@respiranto.de])
+AC_INIT([ctct], [0.2.3-dev], [alguien@respiranto.de])
 AC_CONFIG_FILES(
 	[Makefile]
 	[ctct.1]
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
diff --git a/ctct.in b/ctct.in
index 93c5ff2..ef7b588 100644
--- a/ctct.in
+++ b/ctct.in
@@ -38,6 +38,9 @@ test -f "$user_config_dir/config.sh" \
 
 ## CONSTANTS:
 exec_name="${0##*/}"
+EXIT_SUCCESS=0
+EXIT_FAILURE=1
+EXIT_ERROR=2
 TRUE=0
 FALSE=1
 
@@ -47,8 +50,8 @@ cat << EOF
 usage:
   $exec_name <name>                   - show contact
   $exec_name -l                       - list all entries
-  $exec_name [-s] <part> [...]        - search by name
-  $exec_name -S <part> [...]          - search by data
+  $exec_name -s <pattern> [...]       - search by name
+  $exec_name -S <regex> [...]         - search by data
   $exec_name -e <name>                - edit / create entry
   $exec_name -d <name> [...]          - delete entries
   $exec_name --rename <old> <new>     - rename entry
@@ -107,7 +110,12 @@ function main()
 		 	( test $# -lt 3 && print_error "$exec_name: no new name specified." ) \
 			&& exit 1
 		rename_file "$2" "$3"; exit $?
-	elif [[ "$1" =~ ^- ]]; then
+	elif [[ "$1" == '--' ]]
+	then
+		shift 1
+		test $# -eq 0 && print_help && exit 1
+	elif [[ "$1" =~ ^- ]]
+	then
 		print_error "$exec_name: unknown option '$1'"; exit 1
 	fi
 	
@@ -116,8 +124,8 @@ function main()
 		if ! find_similar "Did you mean:" "$@"
 		then
 			print_msg "No match found."
-			return 1
 		fi
+		return 1
 	fi
 }
 
diff --git a/version.files b/version.files
index 85d958b..b67ce41 100644
--- a/version.files
+++ b/version.files
@@ -1,3 +1,2 @@
 configure.ac
-CHANGELOG
 README