Split off ctct_config(5)

6 files changed, 206 insertions, 22 deletions

diff --git a/CHANGELOG b/CHANGELOG
index efa17ae..43f9792 100644
--- a/CHANGELOG
+++ b/CHANGELOG
@@ -14,12 +14,14 @@ General:
  `- This might have particularly have been an issue, if a de-/encrypting
     {input,ouput}_program was used.
 - Switch to extended regular expressions (EREs) for `--search-by-data'.
+- Improve exit codes.
 
 
 Manual:
 -------
 
-- Improve and correct ctct(1).
+- Split off ctct_config(5).
+- Improve and correct ctct(1) and ctct_config(5).
 
 
 Compatibility:
diff --git a/TODO b/TODO
index 09b7fab..0994a89 100644
--- a/TODO
+++ b/TODO
@@ -26,9 +26,11 @@ TODO file for ctct
 * Support templates.
 * Different return types for errors and non-matches.
 * Quiet option for --search-by-*.
+* [consider] Use another default editor.
+ `- nano, easily understandable.
+ `- ed, the editor.
 
 [MANUAL]
-* Split off ctct_config(5).
 * Add an EXAMPLE section to ctct(1).
 
 [BUGS]
diff --git a/configure b/configure
index 280f460..2e278a5 100755
--- a/configure
+++ b/configure
@@ -1711,7 +1711,7 @@ ac_link='$CC -o conftest$ac_exeext $CFLAGS $CPPFLAGS $LDFLAGS conftest.$ac_ext $
 ac_compiler_gnu=$ac_cv_c_compiler_gnu
 
 
-ac_config_files="$ac_config_files Makefile ctct.1 ctct.bash_completion config.sh"
+ac_config_files="$ac_config_files Makefile ctct.1 ctct_config.5 ctct.bash_completion config.sh"
 
 ac_config_files="$ac_config_files ctct"
 
@@ -2492,6 +2492,7 @@ do
   case $ac_config_target in
     "Makefile") CONFIG_FILES="$CONFIG_FILES Makefile" ;;
     "ctct.1") CONFIG_FILES="$CONFIG_FILES ctct.1" ;;
+    "ctct_config.5") CONFIG_FILES="$CONFIG_FILES ctct_config.5" ;;
     "ctct.bash_completion") CONFIG_FILES="$CONFIG_FILES ctct.bash_completion" ;;
     "config.sh") CONFIG_FILES="$CONFIG_FILES config.sh" ;;
     "ctct") CONFIG_FILES="$CONFIG_FILES ctct" ;;
diff --git a/configure.ac b/configure.ac
index c2f8011..8ffce4e 100644
--- a/configure.ac
+++ b/configure.ac
@@ -22,6 +22,7 @@ AC_INIT([ctct], [0.2.3-dev], [alguien@respiranto.de])
 AC_CONFIG_FILES(
 	[Makefile]
 	[ctct.1]
+	[ctct_config.5]
 	[ctct.bash_completion]
 	[config.sh]
 )
diff --git a/ctct.1.in b/ctct.1.in
index 1f1debf..d621778 100644
--- a/ctct.1.in
+++ b/ctct.1.in
@@ -188,25 +188,6 @@ no matching entry was found\.
 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\.
-.\"
-.TP
-.I @default_user_config_dir@/config\.sh
-Default location of the user configuration file\.
-.\"
-.TP
-.I @default_datadir@/
-.RB "Default " datadir\.
-.\"
 .\"
 .SH SEE ALSO
 .BR ctct_config (5),
diff --git a/ctct_config.5.in b/ctct_config.5.in
new file mode 100644
index 0000000..a1f6184
--- /dev/null
+++ b/ctct_config.5.in
@@ -0,0 +1,197 @@
+.\" ctct_config.5 - the man page for configuration of ctct
+.\"
+.\" Copyright 2015 - 2018 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_CONFIG 5 "2018-12-24" "ctct @PACKAGE_VERSION@"
+.\"
+.\"
+.SH NAME
+ctct_config \- configuration of ctct
+.SH DESCRIPTION
+.P
+The main configuration file for
+.BR ctct (1)
+is
+.IR @default_confdir@/config\.sh \.
+The file is a
+.BR bash (1)
+script which is simply sourced by
+.BR ctct (1)\.
+It must not exit\.
+Any configuration is done by setting shell variables\.
+Configuration may be overriden in per-user configuration scripts, see
+.BR user_config_dir \.
+.P
+The following variables are recognized:
+.\"
+.TP
+.B user_config_dir
+The directory where the per user configuration file
+.I config\.sh
+is searched for\.
+If set, this variable must contain the prefix
+.I $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\.
+Typically,
+.B datadir
+should contain the prefix
+.IR $HOME \.
+The default value is
+.IR @default_datadir@ \.
+.\"
+.TP
+.B default_editor
+The editor to use when
+.B ctct
+is called with the
+.B \-\-edit
+option\.
+If set, supersedes both the
+.RB $ EDITOR
+environment variable
+and the
+.BR fallback_editor \.
+By default, unset.
+.\"
+.TP
+.B fallback_editor
+The editor to fall back to if neither the environment variable
+.RB $ EDITOR
+nor
+.B default_editor
+is set\.
+The default value is
+.IR @default_fallback_editor@ \.
+.\"
+.TP
+.B input_program
+The program with arguments
+that gets passed the data written after editing a contact entry\.
+This is mostly useful in combination with an
+.B output_program
+to enable encryption\.
+.br
+If both
+.B input_program
+and
+.B output_program
+are set to
+.IR cat ,
+they have no special effect\.
+Elsewise
+.BR ctct (1)
+supplied with the
+.B \-\-edit
+option, will operate on a temporary file populated by the output of
+.BR output_program \.
+When editing is done, the
+.B input_program
+will receive the content of that temporary file on stdin and its stdout
+will be written on disk.
+The default value is
+.IR @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
+.BR more (1)\.
+Use
+.B visual_program
+for this purpose\.
+The default value is
+.IR @default_output_program@ \.
+For further details, see
+.BR input_program \.
+.\"
+.TP
+.B visual_program
+The program that the data as written by the
+.B output_program
+are passed to\.
+It can be used with any program accepting its input on stdin.
+Common options are 
+.BR less (1)
+and
+.BR more (1)\.
+If it is set to
+.IR cat ,
+it has no effect\.
+The default value is
+.IR @default_visual_program@ \.
+.\"
+.TP
+.B confirm_deletion
+Whether to ask for confirmation upon deleting an entry, that is when
+.BR ctct (1)
+is called with the
+.B \-\-delete
+option\.
+The default value is
+.IR @default_confirm_deletion@ \.
+.\"
+.TP
+.B confirm_default_yes
+Whether to assume yes as answer to confirmation when no answer,
+that is an empty answer is given\.
+This option only has an effect, if
+.B confirm_deletion
+is set to true\.
+The default value is
+.IR @default_confirm_default_yes@ \.
+.\"
+.\"
+.SH ENVIROMENT
+.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@/
+Default
+.BR datadir \.
+.\"
+.\"
+.SH SEE ALSO
+.BR ctct (1),
+.BR vi (1),
+.BR less (1),
+.BR more (1)
+.\" vi: tw=75