.\" $HeadURL$ $LastChangedRevision$
.\" vim: filetype=nroff
.\"
.TH PIN 1 "ADE_APP_TOKEN_RELEASE_DATE_MAN"
.SH NAME
pin \- create, edit, search record-based text files
.br
.ne 5
.SH SYNOPSIS
.B pin
\*[ade_standard_synopsis_component]
[
.B \-P
.I progname
|
.B \-\-progname=\fIprogname\fR
]
{
.B \-i
| [ 
.B \-s 
]
.I search\-term
|
[ 
.B \-e 
] }
.br
.ne 5
.SH DESCRIPTION
.B Pin
is used to create, edit and search record-based text files.
Text records may be single lines of text, single paragraphs of text or something else;
in this last case the records are not searchable. 
The records are stored in a single-file database, which may be encrypted with
.B gpg\fR(1).
.PP
Possible uses might be: password wallet (encrypted database with paragraph-based records), 
shopping list (plaintext database with line-based records), calendar (encrypted or plaintext database
with paragraph based-records).
.PP
.B Pin
should probably be invoked via a symlink (see
.B ln\fR(1))
rather than being called directly. This is because core configuration attributes are 
stored in a single-file database that is indexed on the name under which 
.B pin
was invoked.
.br
.ne 5
.SH CONFIGURATION
.PP
Ensure a GPG identity capable of encryption (so not a DSA-key based identity) is available (see
.B gpg\fR(1)).
.PP
Create a suitably-named symlink to the
.B pin
command.
.PP
Call the symlink with the
.B \-i 
option and answer the questions presented.
.PP
Call the symlink without any options or arguments, which will invoke the preferred editor (default
.B vi\fR(1), 
and start adding records.
Records should be either newline-separated or double-newline-separated for line-based or
paragraph-based records, respectively.
.br
.ne 5
.SH OPTIONS
\*[ade_standard_options_component]
.TP 
.B \-i
Initialise the database.
.TP
.B \-e
Edit the database. 
This option may be omitted, since the absence of search terms on the commandline makes
it clear that the database is to be edited.
.TP
.B \-P \fIprogname\fR, \fB\-\-progname=\fIprogname\fR
Invoke
.B pin
under the specified name, forcing it to refer the correspondingly named database.
.TP
.B \-s
Search the database.
This option may be omitted, since the presence of search terms on the commandline makes
it clear that the database is to be searched.
.br
.ne 5
.SH EXIT STATUS
On success
.B pin
returns zero. On failure it returns non-zero and displays a diagnostic
message.
.br
.ne 5
.SH FILES
.TP
.B ~/.pin/databases.conf
.B Pin\fR's
top-level configuration file, which specifies, for each name under which
.B pin
can be invoked, whether the database is encrypted, and if so then with which
GPG identity, whether the database contains line-based or paragraph-based
records.
.br
.ne 5
.SH ENVIRONMENT VARIABLES
.TP 25
PIN_DIR
This is used to detemine where
.B pin\fR's
databases and database.conf file will be stored.
The default is
.B $HOME/.pin\fR.
.br
.ne 5
.SH EXAMPLES
Define a phone-list:
.IP
.nf
.fam C
.B ln \-s \*[ade_bin_prefix]/pin phone
.fam T
.PP
Initialise the phone-list:
.IP
.fam C
.B phone \-i
encrypted (y/n) [n]: \fBn\fR
each entry is (l)ine, (p)aragraph or (u)nsearchable [p]: \fBl\fR
.fam T
.PP
Invoke the editor to start adding records:
.IP
.fam C
.B phone
.fam T
.PP
Add records:
.IP
.fam C
.B Fred Bloggs
.B Work-Tel: +1 555 1234 5678
.B Email: fred@bloggs.com

.B Joe Bloggs
.B Word-Tel: +1 555 8765 4321
.B Email: joe@bloggs.com
.fam T
.PP
Look up Fred's details by running:
.IP
.fam C
.B phone fred
.fam T
.fi
.br
.ne 5
.SH CAVEATS
None.
.br
.ne 5
.SH STANDARDS
This manual page documents version ADE_APP_TOKEN_RELEASE_ID of
.B pin\fR.
.br
.ne 5
.SH SEE ALSO
gpg(1), ln(1), pass(1), pin-config(1), vi(1)
.br
.ne 5
.SH AUTHOR
ADE_APP_TOKEN_AUTHOR_NAME <ADE_APP_TOKEN_AUTHOR_EMAIL>
.br
.ne 5
.SH COPYRIGHT & DISTRIBUTION POLICY
Copyright (C) 2010-ADE_APP_TOKEN_RELEASE_YEAR ADE_APP_TOKEN_AUTHOR_NAME
\*[ade_standard_copyright_component]