Improve documentation.

* TODO: Update.
* doc/Makefile.am: Update.
* doc/eclat-describe-addresses.1: New file.
* doc/eclat-create-tags.1: Fix extra prefix in command synopsis.
* doc/eclat-delete-tags.1: Likewise.
* doc/eclat-describe-tags.1: Likewise.
* doc/eclat-tmpl.1: Likewise.
* src/eclat.c: Sort options.

6 files changed, 115 insertions, 15 deletions

diff --git a/doc/Makefile.am b/doc/Makefile.am
index eff235d..3e2a642 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -21,6 +21,7 @@ dist_man_MANS=\
  eclat-create-tags.1\
  eclat-delete-snapshot.1\
  eclat-delete-tags.1\
+ eclat-describe-addresses.1\
  eclat-describe-snapshots.1\
  eclat-describe-tags.1\
  eclat-disassociate-address.1\
diff --git a/doc/eclat-create-tags.1 b/doc/eclat-create-tags.1
index b9f90da..b01885b 100644
--- a/doc/eclat-create-tags.1
+++ b/doc/eclat-create-tags.1
@@ -15,14 +15,14 @@
 .\" along with Eclat.  If not, see <http://www.gnu.org/licenses/>.
 .TH CREATE\-TAGS 1 "October 15, 2012" "ECLAT" "Eclat User Reference"
 .SH NAME
-eclat eclat\-create\-tags \- create or replace tags for a resource
+eclat create\-tags \- create or replace tags for a resource
 .SH SYNOPSIS
-eclat eclat\-create\-tags [\fB\-a\fR \fIID\fR] [\fB\-i\fR \fIID\fR]\
+eclat create\-tags [\fB\-a\fR \fIID\fR] [\fB\-i\fR \fIID\fR]\
  [\fB\-r\fR \fIID\fR] [\fB\-v\fR \fIID\fR]
-                        [\fB\-\-ami\fR \fIID\fR] [\fB\-\-instance\fR \fIID\fR] [\fB\-\-resource\-id\fR \fIID\fR]
-                        [\fB\-\-volume\fR \fIID\fR] \fITAG\fR[=\fIVAL\fR]...
+                  [\fB\-\-ami\fR \fIID\fR] [\fB\-\-instance\fR \fIID\fR] [\fB\-\-resource\-id\fR \fIID\fR]
+                  [\fB\-\-volume\fR \fIID\fR] \fITAG\fR[=\fIVAL\fR]...
 
-eclat eclat\-create\-tags \fB\-\-help\fR
+eclat create\-tags \fB\-\-help\fR
 .SH DESCRIPTION
 This command creates or replaces one or more tags for a given
 resource.  Tags are specified by their names.  If a tag name is
diff --git a/doc/eclat-delete-tags.1 b/doc/eclat-delete-tags.1
index e255bde..ae84a59 100644
--- a/doc/eclat-delete-tags.1
+++ b/doc/eclat-delete-tags.1
@@ -15,14 +15,14 @@
 .\" along with Eclat.  If not, see <http://www.gnu.org/licenses/>.
 .TH DELETE\-TAGS 1 "October 15, 2012" "ECLAT" "Eclat User Reference"
 .SH NAME
-eclat eclat\-delete\-tags \- delete or replace tags for a resource
+eclat delete\-tags \- delete or replace tags for a resource
 .SH SYNOPSIS
-eclat eclat\-delete\-tags [\fB\-a\fR \fIID\fR] [\fB\-i\fR \fIID\fR]\
+eclat delete\-tags [\fB\-a\fR \fIID\fR] [\fB\-i\fR \fIID\fR]\
  [\fB\-r\fR \fIID\fR] [\fB\-v\fR \fIID\fR]
-                        [\fB\-\-ami\fR \fIID\fR] [\fB\-\-instance\fR \fIID\fR] [\fB\-\-resource\-id\fR \fIID\fR]
-                        [\fB\-\-volume\fR \fIID\fR] \fITAG\fR[=\fIVAL\fR]...
+                  [\fB\-\-ami\fR \fIID\fR] [\fB\-\-instance\fR \fIID\fR] [\fB\-\-resource\-id\fR \fIID\fR]
+                  [\fB\-\-volume\fR \fIID\fR] \fITAG\fR[=\fIVAL\fR]...
 
-eclat eclat\-delete\-tags \fB\-\-help\fR
+eclat delete\-tags \fB\-\-help\fR
 .SH DESCRIPTION
 This command deletes more tags for a given resource.  Tags are
 specified by their names.  If a tag name is followed by an equals
diff --git a/doc/eclat-describe-addresses.1 b/doc/eclat-describe-addresses.1
new file mode 100644
index 0000000..68135e4
--- /dev/null
+++ b/doc/eclat-describe-addresses.1
@@ -0,0 +1,99 @@
+.\" This file is part of Eclat -*- nroff -*-
+.\" Copyright (C) 2012 Sergey Poznyakoff
+.\"
+.\" Eclat is free software; you can redistribute it and/or modify
+.\" it under the terms of the GNU General Public License as published by
+.\" the Free Software Foundation; either version 3, or (at your option)
+.\" any later version.
+.\"
+.\" Eclat 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 General Public License for more details.
+.\"
+.\" You should have received a copy of the GNU General Public License
+.\" along with Eclat.  If not, see <http://www.gnu.org/licenses/>.
+.TH DESCRIBE\-ADDRESSES 1 "October 15, 2012" "ECLAT" "Eclat User Reference"
+.SH NAME
+eclat describe\-addresses \- return information about IP addresses in
+your account
+.SH SYNOPSIS
+eclat describe\-addresses [\fB\-v\fR] [\fB\-\-vpc\fR] [\fBFILTER\fR...]
+
+eclat describe\-addresses \fB\-\-help\fR
+.SH DESCRIPTION
+This command returns information about Elastic IP addresses allocated
+for your account.  By default all allocated addresses are described.
+This can be changed by specifying one or more filters.  When filters
+are supplied, only those addresses that match all of them are returned.
+.SH OPTIONS
+.TP
+.BR \-v , \-\-vpc
+Describe VPC addresses.  By default, standard (EC2) addresses are
+displayed.  This option alters this behavior.
+.SH FILTERS
+.TP
+\fBinstance\-id\fR=\fIstring\fR
+The ID of the instance the address is associated with.
+.TP
+\fBpublic\-ip\fR=\fIstring\fR
+Piblic IP address.
+.TP
+\fBallocation\-id\fR=\fIstring\fR
+The allocation ID of the address (for VPC addresses only).
+.TP
+\fBassociation\-id\fR=\fIstring\fR
+The association ID of the address (for VPC addresses only).
+.TP
+\fBnetwork\-interface\-id\fR=\fIstringf\fR
+The network interface this IP is associated with (for VPC addresses only).
+.TP
+\fBnetwork\-interface\-owner\-id\fR=\fIstring\fR
+The owner ID.
+.TP
+\fBprivate\-ip\-address\fR=\fIstring\fR
+The private IP address associated with the Elastic IP (for VPC
+addresses only).
+.SH OUTPUT
+The default output is organized in three to eight columns separated by
+single \fBTAB\fR characters.  The first three columns are common for
+any address domain.  The first column lists the interface type
+(\fBstandard\fR of \fBvpc\fR).  The second one shows the IP address.
+The third column contains the ID of the instance this address is
+associated with.  For VPC addresses, additional five columns are
+output: interface ID, interface owner ID, private IP address,
+allocation ID and association ID.
+.SH EXAMPLE
+.sp
+.nf
+.in +2
+$ eclat describe-addresses
+standard	192.0.2.1	i-f15ebb98
+standard	198.51.100.2
+.in
+.fi
+.SH "SEE ALSO"
+.BR eclat (1),
+.BR eclat\-associate\-address (1),
+.BR eclat\-disassociate\-address (1).
+.SH AUTHORS
+Sergey Poznyakoff
+.SH "BUG REPORTS"
+Report bugs to <bug\-eclat@gnu.org.ua>.
+.SH COPYRIGHT
+Copyright \(co 2012 Sergey Poznyakoff
+.br
+.na
+License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
+.br
+.ad
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.\" Local variables:
+.\" eval: (add-hook 'write-file-hooks 'time-stamp)
+.\" time-stamp-start: ".TH [A-Z_][A-Z0-9_.-]* [0-9] \""
+.\" time-stamp-format: "%:B %:d, %:y"
+.\" time-stamp-end: "\""
+.\" time-stamp-line-limit: 20
+.\" end:
+
diff --git a/doc/eclat-describe-tags.1 b/doc/eclat-describe-tags.1
index 93a9dd1..3cbd171 100644
--- a/doc/eclat-describe-tags.1
+++ b/doc/eclat-describe-tags.1
@@ -15,11 +15,11 @@
 .\" along with Eclat.  If not, see <http://www.gnu.org/licenses/>.
 .TH DESCRIBE\-TAGS 1 "October 15, 2012" "ECLAT" "Eclat User Reference"
 .SH NAME
-eclat eclat\-describe\-tags \- list the EC2 tags 
+eclat describe\-tags \- list the EC2 tags 
 .SH SYNOPSIS
-eclat eclat\-describe\-tags [\fBFILTER\fR...]
+eclat describe\-tags [\fBFILTER\fR...]
 
-eclat eclat\-describe\-tags \fB\-\-help\fR
+eclat describe\-tags \fB\-\-help\fR
 .SH DESCRIPTION
 This command lists the EC2 tags.  If no filter has been supplied, all
 tags are listed.  
diff --git a/doc/eclat-tmpl.1 b/doc/eclat-tmpl.1
index baccfae..8faa135 100644
--- a/doc/eclat-tmpl.1
+++ b/doc/eclat-tmpl.1
@@ -15,10 +15,10 @@
 .\" along with Eclat.  If not, see <http://www.gnu.org/licenses/>.
 .TH COMMAND 1 "October 15, 2012" "ECLAT" "Eclat User Reference"
 .SH NAME
-eclat eclat\-command \-
+eclat command \-
 .SH SYNOPSIS
 
-eclat eclat\-command \fB\-\-help\fR
+eclat command \fB\-\-help\fR
 .SH DESCRIPTION
 .SH OPTIONS
 .SH FILTERS