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. --- ctct.1.in | 288 ++++++++++++++++++++++++++++++++++---------------------------- 1 file changed, 158 insertions(+), 130 deletions(-) (limited to 'ctct.1.in') 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 -- cgit v1.2.3