From f440a9c21188195ad111cf01d4e00c0874e72bb1 Mon Sep 17 00:00:00 2001 From: Einhard Leichtfuß Date: Mon, 24 Dec 2018 18:41:03 +0100 Subject: 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. --- CHANGELOG | 6 ++ README | 2 +- TODO | 27 ++++-- configure | 18 ++-- configure.ac | 2 +- ctct.1.in | 288 ++++++++++++++++++++++++++++++++-------------------------- ctct.in | 16 +++- version.files | 1 - 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 ', 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 . # @@ -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 . # -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 . .\" -.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 - show contact $exec_name -l - list all entries - $exec_name [-s] [...] - search by name - $exec_name -S [...] - search by data + $exec_name -s [...] - search by name + $exec_name -S [...] - search by data $exec_name -e - edit / create entry $exec_name -d [...] - delete entries $exec_name --rename - 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 -- cgit v1.2.3