simplify/shorten msva-query-agent documentation

diff --git a/msva-query-agent b/msva-query-agent
index 79b76f7e3414974235bf716cde0131ccafbbc9be..ea1f7f2f25821f0fe2b1e684534549cf16dbc2e5 100755 (executable)
--- a/msva-query-agent
+++ b/msva-query-agent
@@ -45,61 +45,51 @@ msva-query-agent - query a Monkeysphere Validation Agent
 
 =head1 SYNOPSIS
 
-msva-query-agent CONTEXT PEER PKC_TYPE < PKC_DATA
+msva-query-agent CONTEXT PEER PKC_TYPE < /path/to/public_key_carrier
 
 =head1 ABSTRACT
 
-msva-query-agent provides a means of querying a Monkeysphere
-Validation Agent for certificate validation.
-
-=head1 INTRODUCTION
-
-The Monkeysphere Validation Agent offers a local service for tools to
-validate certificates (both X.509 and OpenPGP) and other public keys.
-
-Clients of the validation agent query it with a public key carrier (a
-raw public key, or some flavor of certificate), the supposed name of
-the remote peer offering the pubkey, and the context in which the
-validation check is relevant (e.g. ssh, https, etc).
-
-The validation agent tells the client whether it was able to
-successfully validate the peer's use of the public key in the given
-context.
+msva-query-agent validates certificates for a given use by querying a
+running Monkeysphere Validation Agent.
 
 =head1 USAGE
 
-msva-query-agent create an agent post data (APD) object which is sent
-to the msva.  The return code of the client indicates the validity of
-the certificate.  If the certificate is valid, the return code is 0.
-Otherwise, the return code if 1.
+msva-query-agent reads a certificate from standard input, and posts it
+to the running Monkeysphere Validation Agent.  The return code
+indicates the validity (as determined by the agent) of the certificate
+for the specified purpose.  The agent's return message (if any) is
+emitted on stderr.
 
-The APD is created from certificate data provided on stdin (PKC_DATA),
-and the following information provided on the command line:
+Three command-line arguments are all required, supplied in order, as
+follows:
 
 =over 4
 
 =item CONTEXT
 
-Context of query, e.g. 'https', 'ssh', etc.
+Context in which the certificate is being validated (e.g. 'https',
+'ssh', 'ike')
 
 =item PEER
 
-Service address portion of url, e.g. 'foo.example.net'.
+The name of the intended peer.  When validating a certificate for a
+service, supply the host's full DNS name (e.g.  'foo.example.net')
 
 =item PKC_TYPE
 
-Type of public key carrier data provided on stdin, e.g. 'x509der',
-etc.
+The format of public key carrier data provided on standard input
+(e.g. 'x509der')
 
-=item PKC_DATA
+=back
 
-Public key carrier data provided on stdin.
+=head1 RETURN CODE
 
-=back
+If the certificate is valid for the requested peer in the given
+context, the return code is 0.  Otherwise, the return code is 1.
 
 =head1 ENVIRONMENT VARIABLES
 
-msva-query-agent accepts some environment variables:
+msva-query-agent's behavior is controlled by environment variables:
 
 =over 4
 
@@ -115,16 +105,6 @@ its verbosity, and should be one of (in increasing verbosity): silent,
 quiet, fatal, error, info, verbose, debug, debug1, debug2, debug3.
 Default is 'error'.
 
-=item MSVA_KEYSERVER_POLICY
-
-msva-perl must decide when to check with keyservers (for new keys,
-revocation certificates, new certifications, etc).  There are three
-possible options: 'always' means to check with the keyserver on every
-query it receives.  'never' means to never check with a
-keyserver. 'unlessvalid' will only check with the keyserver on a
-specific query if no keys are already locally known to be valid for
-the requested peer.  Default is 'unlessvalid'.
-
 =back
 
 =head1 COMMUNICATION PROTOCOL DETAILS
@@ -141,8 +121,8 @@ msva-perl(1), monkeysphere(1), monkeysphere(7)
 
 =head1 BUGS AND FEEDBACK
 
-Bugs or feature requests for msva-perl should be filed with the
-Monkeysphere project's bug tracker at
+Bugs or feature requests for msva-perl and associated tools should be
+filed with the Monkeysphere project's bug tracker at
 https://labs.riseup.net/code/projects/monkeysphere/issues/
 
 =head1 AUTHORS AND CONTRIBUTORS
@@ -154,6 +134,6 @@ The Monkeysphere Team http://web.monkeysphere.info/
 
 =head1 COPYRIGHT AND LICENSE
 
-Copyright © Jameson Graef Rollins and others from the Monkeysphere
+Copyright © 2010, Jameson Graef Rollins and others from the Monkeysphere
 team.  msva-query-agent is free software, distributed under the GNU
 Public License, version 3 or later.