Add libcontacts.7 and libcontacts.h.0 + minor fixes + reorder stuff in libcontacts.h

Signed-off-by: Mattias Andrée <maandree@kth.se>

9 files changed, 643 insertions, 84 deletions

diff --git a/Makefile b/Makefile
index 01c9712..99c5227 100644
--- a/Makefile
+++ b/Makefile
@@ -42,7 +42,10 @@ HDR =\
 
 LOBJ = $(OBJ:.o=.lo)
 
+MAN0 = libcontacts.h.0
 MAN3 = $(OBJ:.o=.3)
+MAN5 = contacts.5
+MAN7 = libcontacts.7
 
 
 all: libcontacts.a libcontacts.$(LIBEXT) test
@@ -74,13 +77,19 @@ check: test
 install: libcontacts.a libcontacts.$(LIBEXT)
 	mkdir -p -- "$(DESTDIR)$(PREFIX)/lib"
 	mkdir -p -- "$(DESTDIR)$(PREFIX)/include"
+	mkdir -p -- "$(DESTDIR)$(MANPREFIX)/man0"
 	mkdir -p -- "$(DESTDIR)$(MANPREFIX)/man3"
+	mkdir -p -- "$(DESTDIR)$(MANPREFIX)/man5"
+	mkdir -p -- "$(DESTDIR)$(MANPREFIX)/man7"
 	cp -- libcontacts.a "$(DESTDIR)$(PREFIX)/lib/"
 	cp -- libcontacts.h "$(DESTDIR)$(PREFIX)/include/"
 	cp -- libcontacts.$(LIBEXT) "$(DESTDIR)$(PREFIX)/lib/libcontacts.$(LIBMINOREXT)"
 	ln -sf -- libcontacts.$(LIBMINOREXT) "$(DESTDIR)$(PREFIX)/lib/libcontacts.$(LIBMAJOREXT)"
 	ln -sf -- libcontacts.$(LIBMAJOREXT) "$(DESTDIR)$(PREFIX)/lib/libcontacts.$(LIBEXT)"
+	cp -- $(MAN0) "$(DESTDIR)$(MANPREFIX)/man0/"
 	cp -- $(MAN3) "$(DESTDIR)$(MANPREFIX)/man3/"
+	cp -- $(MAN5) "$(DESTDIR)$(MANPREFIX)/man5/"
+	cp -- $(MAN7) "$(DESTDIR)$(MANPREFIX)/man7/"
 
 uninstall:
 	-rm -f -- "$(DESTDIR)$(PREFIX)/lib/libcontacts.$(LIBMAJOREXT)"
@@ -88,7 +97,10 @@ uninstall:
 	-rm -f -- "$(DESTDIR)$(PREFIX)/lib/libcontacts.$(LIBEXT)"
 	-rm -f -- "$(DESTDIR)$(PREFIX)/lib/libcontacts.a"
 	-rm -f -- "$(DESTDIR)$(PREFIX)/include/libcontacts.h"
+	-cd -- "$(DESTDIR)$(MANPREFIX)/man0/" && rm -rf -- $(MAN0)
 	-cd -- "$(DESTDIR)$(MANPREFIX)/man3/" && rm -rf -- $(MAN3)
+	-cd -- "$(DESTDIR)$(MANPREFIX)/man5/" && rm -rf -- $(MAN5)
+	-cd -- "$(DESTDIR)$(MANPREFIX)/man7/" && rm -rf -- $(MAN7)
 
 clean:
 	-rm -rf -- *.o *.a *.lo *.so *.dylib *.dll *.su test .testdir
diff --git a/README b/README
index 98b99c4..8120f7d 100644
--- a/README
+++ b/README
@@ -2,6 +2,9 @@ NAME
 	libcontacts - A library for handling a simple, flexible contact list
 
 DESCRIPTION
-	libcontacts uses the ~/.config/contacts library to store in a simple,
-	human and machine readable text format that can be easily manipulated
-	and inspected with standard tools.
+	libcontacts uses the ~/.config/contacts directory to store contact
+	information in a simple, human and machine readable text format that
+	can be easily manipulated and inspected with standard tools. See
+	contacts(5) for information about the format contact information is
+	stored in. See libcontacts.h(0) for information about what the
+	library provides.
diff --git a/TODO b/TODO
index 8f00e88..a43bf52 100644
--- a/TODO
+++ b/TODO
@@ -1,3 +1 @@
-Add libcontacts.7
-Add libcontacts.h.0
 Add contacts.5
diff --git a/libcontacts.7 b/libcontacts.7
new file mode 100644
index 0000000..1e9cd41
--- /dev/null
+++ b/libcontacts.7
@@ -0,0 +1,16 @@
+.TH LIBCONTACTS 7 LIBCONTACTS
+.SH NAME
+libcontacts \- A library for handling a simple, flexible contact list
+
+.SH DESCRIPTION
+.B libcontacts
+uses the
+.I ~/.config/contacts
+directory to store contact information in a simple, human and
+machine readable text format that can be easily manipulated
+and inspected with standard tools. See
+.BR contacts (5)
+for information about the format contact information is
+stored in. See 
+.BR libcontacts.h (0)
+for information about what the library provides.
diff --git a/libcontacts.h b/libcontacts.h
index 6ce77d2..f0aa70b 100644
--- a/libcontacts.h
+++ b/libcontacts.h
@@ -7,6 +7,16 @@
 
 
 /**
+ * Block type for contact
+ */
+enum libcontacts_block_type {
+	LIBCONTACTS_SILENT,      /* The phone shall not call its owner's attention */
+	LIBCONTACTS_BLOCK_OFF,   /* The phone shall appear as turned off */
+	LIBCONTACTS_BLOCK_BUSY,  /* The phone shall appear as busy */
+	LIBCONTACTS_BLOCK_IGNORE /* The phone shall appear as on but with no one answering */
+};
+
+/**
  * Gender of contact
  */
 enum libcontacts_gender {
@@ -17,13 +27,54 @@ enum libcontacts_gender {
 };
 
 /**
- * Block type for contact
+ * Address for contact
  */
-enum libcontacts_block_type {
-	LIBCONTACTS_SILENT,      /* The contact is blocked blocked, the phone shall not call its owner's attention */
-	LIBCONTACTS_BLOCK_OFF,   /* The contact is blocked, phone shall appear as turned off */
-	LIBCONTACTS_BLOCK_BUSY,  /* The contact is blocked, phone shall appear as turned busy */
-	LIBCONTACTS_BLOCK_IGNORE /* The contact is blocked, phone shall appear as on but with no one answering */
+struct libcontacts_address {
+	char *context;            /* Work address (which job)? Home? Summer cabin? … */
+	char *care_of;            /* Care of address, if any */
+	char *address;            /* Address, all lines in one */
+	char *postcode;           /* Post code */
+	char *city;               /* Which city is the post code tied to? */
+	char *country;            /* Which country? */
+	int have_coordinates;     /* Are `.latitude` and `.longitude` defined? */
+	double latitude;          /* Latitudinal GPS coordinate */
+	double longitude;         /* Longitudinal GPS coordinate */
+	char **unrecognised_data; /* Data not recognised by the library */
+};
+
+/**
+ * Birthday of contact
+ */
+struct libcontacts_birthday {
+	unsigned int year;        /* asis,        0 for unknown */
+	unsigned char month;      /* january = 1, 0 for unknown */
+	unsigned char day;        /* asis,        0 for unknown */
+
+	/**
+	 * This is applicable only if the birthday
+	 * is on a leap day. One non-leap years, a
+	 * birthday that occurs on a leap day is
+	 * observed the day after the leap day had
+	 * it existed; but if this flag is set, the
+	 * person observes his birthday the day
+	 * before instead.
+	 * 
+	 * (Even if it is not true (as it wasn't in
+	 * the past), the leap day is treated as if at
+	 * the end of the month, for example a person
+	 * born 1970-02-27, would celebrate his birthday
+	 * on 1980-02-27, not on 1980-02-28; similarly,
+	 * person born 1980-02-27 would celebrate his
+	 * birthday on 1989-02-27, not on 1989-02-26.)
+	 * 
+	 * For example, if a person is born 2000-02-29,
+	 * his birthday is observed 2011-03-01, but if
+	 * this flag is set, he observes it on 2011-02-28
+	 * instead.
+	 */
+	unsigned char before_on_common;
+
+	char **unrecognised_data; /* Data not recognised by the library */
 };
 
 /**
@@ -47,11 +98,12 @@ struct libcontacts_block {
 };
 
 /**
- * Organisation information for contact
+ * Chat address for contact
  */
-struct libcontacts_organisation {
-	char *organisation;       /* Orginisation the contact belongs to */
-	char *title;              /* The contact's title/role in the orginisation */
+struct libcontacts_chat {
+	char *context;            /* Work account (which job?)? Personal account? … */
+	char *service;            /* What service is the account, must not begin with a dot */
+	char *address;            /* What is the name/address/number of the account */
 	char **unrecognised_data; /* Data not recognised by the library */
 };
 
@@ -65,15 +117,6 @@ struct libcontacts_email {
 };
 
 /**
- * PGP-keys for contact
- */
-struct libcontacts_pgpkey {
-	char *context;            /* Work key (which job?)? Personal key? … */
-	char *id;                 /* The key's fingerprint */
-	char **unrecognised_data; /* Data not recognised by the library */
-};
-
-/**
  * Telephone number for contact
  */
 struct libcontacts_number {
@@ -85,72 +128,29 @@ struct libcontacts_number {
 };
 
 /**
- * Address for contact
- */
-struct libcontacts_address {
-	char *context;            /* Work address (which job)? Home? Summer cabin? … */
-	char *care_of;            /* Care of address, if any */
-	char *address;            /* Address, all lines in one */
-	char *postcode;           /* Post code */
-	char *city;               /* Which city is the post code tied to? */
-	char *country;            /* Which country? */
-	int have_coordinates;     /* Are `.latitude` and `.longitude` defined? */
-	double latitude;          /* Latitudal GPS coordinate */
-	double longitude;         /* Longitudal GPS coordinate */
-	char **unrecognised_data; /* Data not recognised by the library */
-};
-
-/**
- * Site (e.g. web and gopher) for contact
+ * Organisation information for contact
  */
-struct libcontacts_site {
-	char *context;            /* Work site (which job?)? Personal site (what is it used for?)? … */
-	char *address;            /* Address to the site, including protocol */
+struct libcontacts_organisation {
+	char *organisation;       /* Orginisation the contact belongs to */
+	char *title;              /* The contact's title/role in the orginisation */
 	char **unrecognised_data; /* Data not recognised by the library */
 };
 
 /**
- * Chat address for contact
+ * PGP-keys for contact
  */
-struct libcontacts_chat {
-	char *context;            /* Work account (which job?)? Personal account? … */
-	char *service;            /* What service is the account, must not begin with a dot */
-	char *address;            /* What is the name/address/number of the account */
+struct libcontacts_pgpkey {
+	char *context;            /* Work key (which job?)? Personal key? … */
+	char *id;                 /* The key's fingerprint */
 	char **unrecognised_data; /* Data not recognised by the library */
 };
 
 /**
- * Birthday of contact
+ * Site (e.g. web and gopher) for contact
  */
-struct libcontacts_birthday {
-	unsigned int year;        /* asis,        0 for unknown */
-	unsigned char month;      /* january = 1, 0 for unknown */
-	unsigned char day;        /* asis,        0 for unknown */
-
-	/**
-	 * This is applicable only if the birthday
-	 * is on a leap day. One non-leap years, a
-	 * birthday that occurs on a leap day is
-	 * observed the day after the leap day had
-	 * it existed; but if this flag is set, the
-	 * person observes his birthday the day
-	 * before instead.
-	 * 
-	 * (Even if it is not true (as it wasn't in
-	 * the past), the leap day is treated as if at
-	 * the end of the month, for example a person
-	 * born 1970-02-27, would celebrate his birthday
-	 * on 1980-02-27, not on 1980-02-28; similarly,
-	 * person born 1980-02-27 would celebrate his
-	 * birthday on 1989-02-27, not on 1989-02-26.)
-	 * 
-	 * For example, if a person is born 2000-02-29,
-	 * his birthday is observed 2011-03-01, but if
-	 * this flag is set, he observes it on 2011-02-28
-	 * instead.
-	 */
-	unsigned char before_on_common;
-
+struct libcontacts_site {
+	char *context;            /* Work site (which job?)? Personal site (what is it used for?)? … */
+	char *address;            /* Address to the site, including protocol */
 	char **unrecognised_data; /* Data not recognised by the library */
 };
 
@@ -196,11 +196,11 @@ struct libcontacts_contact {
 	char *nickname;
 
 	/**
-	 * Pathname to photoes of the contact, use
+	 * Pathnames to photos of the contact, use
 	 * absolute paths or paths relative to the
 	 * user's home directory
 	 * 
-	 * Applications may desired which photo to
+	 * Applications may decide which photo to
 	 * use based on their size, but put the in
 	 * order of preference
 	 * 
diff --git a/libcontacts.h.0 b/libcontacts.h.0
new file mode 100644
index 0000000..4745c9c
--- /dev/null
+++ b/libcontacts.h.0
@@ -0,0 +1,530 @@
+.TH LIBCONTACTS.H 0 LIBCONTACTS
+.SH NAME
+libcontacts.h \- Simple, flexible contact list library header
+
+.SH SYNOPSIS
+#include <libcontacts.h>
+
+.SH DESCRIPTION
+The
+.B <libcontacts.h>
+header defines
+.B struct libcontacts_contact
+with the following fields:
+.RS
+.TP
+.BI "char *" id
+The ID of the contact, used to select filename.
+This must not begin with a dot
+.RB ( . ),
+(unless it is reserved) end with a tilde
+.RB ( ~ ),
+or contain a slash
+.RB ( / ),
+and it is recommended that it only contains
+lower case ASCII letters, ASCII digits, and ASCII hyphen
+.RB ( - ).
+Reserved values are:
+.RS
+.TP
+.B .me
+The user himself.
+.TP
+.B .nobody
+Unused data, such as created groups without any members.
+.RE
+.TP
+.BI "char *" name
+The name of the contact as it should be displayed.
+.TP
+.BI "char *" first_name
+The contact's given name (even if it is pronounced
+after the family name).
+.TP
+.BI "char *" last_name
+The contact's family name (even if it is pronounced
+after the given name), if any.
+.TP
+.BI "char *" full_name
+The full name of the contact. There is no prescribed
+format, and there never will be. Application are
+advised not to presume any format.
+.TP
+.BI "char *" nickname.
+The contact's nickname (once upon a time known as
+surname), if any.
+.TP
+.BI "char **" photos.
+Pathnames to photos of the contact. They are either
+absolute paths or relative to the user's home directory.
+
+Applications may decide which photo to use based on
+their size, but user shall put the order of preference.
+
+For each telephone number, applications should only use
+photos that are shared exactly between the contacts that
+share that telephone number.
+
+This list is
+.IR NULL -terminated.
+.TP
+.BI "char **" groups
+List of groups the contact is a member of. For the
+special pseudocontact
+.BR .nobody ,
+this list only contains groups that should be exist,
+but the contact should not be a member of them, allowing
+the existance of empty groups. This list is
+.IR NULL -terminated.
+.TP
+.BI "char *" notes
+Multiline entry for personal notes about the contact.
+.TP
+.BI "struct libcontacts_block **" blocks
+List of contact block information for the contact.
+This list is
+.IR NULL -terminated.
+.TP
+.BI "struct libcontacts_organisation **" organisations
+List of organisation memberships for the contact.
+This list is
+.IR NULL -terminated.
+.TP
+.BI "struct libcontacts_email **" emails
+List of e-mail addresses for the contact.
+This list is
+.IR NULL -terminated.
+.TP
+.BI "struct libcontacts_pgpkey **" pgpkeys
+List of PGP-keys for the contact.
+This list is
+.IR NULL -terminated.
+.TP
+.BI "struct libcontacts_number **" numbers
+List of telephone numbers for the contact.
+This list is
+.IR NULL -terminated.
+
+Telephone numbers can be shared, in case of an incoming call
+where the phone number is shared, the application shall list
+contacts that telephone number.
+.TP
+.BI "struct libcontacts_address **" addresses
+Address (physical location) information for the contact.
+This list is
+.IR NULL -terminated.
+.TP
+.BI "struct libcontacts_site **" sites
+Internet sites (e.g. Web sites) that the contact own or
+has an account on. This list is
+.IR NULL -terminated.
+.TP
+.BI "struct libcontacts_chat **" chats
+The contact's contact information for different services,
+like instant messengers. Entries shall be added by the
+applications that use the chat services. This list is
+.IR NULL -terminated.
+.TP
+.BI "struct libcontacts_birthday *" birthday
+When the contact celebrates his birthday.
+.TP
+.BI "int " in_case_of_emergency
+Whether the contact shall be listed as an
+In Case of Emergency (ICE) contact that can be
+view without unlocking the phone.
+.TP
+.BI "enum libcontacts_gender " gender
+The gender of the contact. This lets applications select
+a default profile picture for the contact.
+.TP
+.BI "char **" unrecognised_data
+List of entries, for the contact, that was not recognised by
+.BR libcontacts .
+This list is
+.IR NULL -terminated.
+.RE
+.PP
+The
+.B <libcontacts.h>
+header defines
+.B struct libcontacts_address
+with the following fields:
+.RS
+.TP
+.BI "char *" context
+What is the address for. For example,
+.B \(dqhome\(dq
+may be used if it is the contact's home address,
+.B \(dqcabin\(dq
+if its his summer cabin, or
+.B \(dqwork\(dq
+if its his workplace. If the contact for example
+has to workplaces, Alphatech and Betatech,
+.B \(dqwork, alphatech\(dq
+and
+.B \(dqwork, betatech\(dq
+would be useful values.
+.TP
+.BI "char *" care_of
+Care of address.
+.TP
+.BI "char *" address
+Steet address, street number, floor number, appartment number, etc.,
+all in one line.
+.TP
+.BI "char *" postcode
+The post code.
+.TP
+.BI "char *" city
+The post town.
+.TP
+.BI "char *" country
+The country.
+.TP
+.BI "int " have_coordinates
+Non-zero if
+.I latitude
+and
+.I longitude
+are defined.
+.TP
+.BI "double " latitude
+Latitudinal GPS coordinate.
+.TP
+.BI "double " latitude
+Longitudinal GPS coordinate.
+.TP
+.BI "char **" unrecognised_data
+List of entries, for the address, that was not recognised by
+.BR libcontacts .
+.RE
+.PP
+The
+.B <libcontacts.h>
+header defines
+.B struct libcontacts_birthday
+with the following fields:
+.RS
+.TP
+.BI "unsigned int " year
+The year, the contact was born, 0 if unknown.
+.TP
+.BI "unsigned int " month
+The month, the contact was born, 0 if unknown.
+.TP
+.BI "unsigned int " day
+The day of the month, the contact was born, 0 if unknown.
+.TP
+.BI "int " before_on_common
+This field is applicable only if the contact's birthday is
+on February 29. If non-zero, he prefers to celebrate his
+birthday one day early: on February 29, on common years.
+If zero, he prefers to celebrate his birthday on the proper
+date: on March 1, on common years.
+.TP
+.BI "char **" unrecognised_data
+List of entries, for the birthday, that was not recognised by
+.BR libcontacts .
+.RE
+.PP
+The
+.B <libcontacts.h>
+header defines
+.B struct libcontacts_block
+with the following fields:
+.RS
+.TP
+.BI "char *" service
+The service the block is applied to. Names beginning with a
+dot are reserved, currently defined special service names are:
+.RS
+.TP
+.B .call
+Telephone calls.
+.TP
+.B .sms
+SMS, MMS, and similar.
+.TP
+.B .global
+The block allows everywhere. When checking if a contact
+is blocked, this entry is least prioritised, meaning that
+if a block entry that is specific the service that makes
+checks exists, that entry is used, otherwise this entry
+is used.
+.PP
+Other values are defines by the services that use them,
+and should, if appropriate, be the package name of the
+application's reference implementation. In some situation,
+the protocol may be standardised, in which case the name
+of the protocol should be used. These values
+shall be identical to those used in
+.BR "struct libcontacts_chat" .
+.RE
+.TP
+.BI "int " explicit
+Whether the contact shall be let known that he is being
+blocked.
+.TP
+.BI "enum libcontacts_block_type " shadow_block
+How the service shall behave if it does not let the contact
+know he is being blocked.
+.TP
+.BI "time_t " soft_unblock
+POSIX time that if passed, the service shall ask the user
+if the contact shall be unblocked. 0 if never.
+.TP
+.BI "time_t " hard_unblock
+POSIX time that if passed, the service shall automatically
+unblock the contact. 0 if never.
+.TP
+.BI "char **" unrecognised_data
+List of entries, for the block entry, that was not recognised by
+.BR libcontacts .
+.RE
+.PP
+The
+.B <libcontacts.h>
+header defines
+.B struct libcontacts_chat
+with the following fields:
+.RS
+.TP
+.BI "char *" context
+The context in which the chat account is used. For example
+.B \(dqpersonal\(dq
+or
+.BR \(dqwork\(dq .
+.TP
+.BI "char *" service
+The service in which the account exists. For example
+.BR \(dqmatrix\(dq .
+Values are defines by the services that use them,
+and should, if appropriate, be the package name of the
+application's reference implementation. In some situation,
+the protocol may be standardised, in which case the name
+of the protocol should be used.
+.TP
+.BI "char *" address
+The account username, telephone number, ID or other address.
+.TP
+.BI "char **" unrecognised_data
+List of entries, for the chat account, that was not recognised by
+.BR libcontacts .
+.RE
+.PP
+The
+.B <libcontacts.h>
+header defines
+.B struct libcontacts_email
+with the following fields:
+.RS
+.TP
+.BI "char *" context
+The context in which the e-mail account is used. For example
+.B \(dqpersonal\(dq
+or
+.BR \(dqwork\(dq .
+.TP
+.BI "char *" address
+The e-mail address.
+.TP
+.BI "char **" unrecognised_data
+List of entries, for the e-mail account, that was not recognised by
+.BR libcontacts .
+.RE
+.PP
+The
+.B <libcontacts.h>
+header defines
+.B struct libcontacts_number
+with the following fields:
+.RS
+.TP
+.BI "char *" context
+The context in which the telephone number is used. For example
+.BR \(dqhome\(dq ,
+.BR \(dqpersonal\(dq ,
+or
+.BR \(dqwork\(dq .
+.TP
+.BI "char *" number
+The telephone number.
+.TP
+.BI "int " is_mobile
+Whether the number is to a device that can receive SMS-message, e.g. a mobile telephone.
+.TP
+.BI "int " is_facsimile
+Whether the number is to a facsimile machine (fax).
+.TP
+.BI "char **" unrecognised_data
+List of entries, for the telephone number, that was not recognised by
+.BR libcontacts .
+.RE
+.PP
+The
+.B <libcontacts.h>
+header defines
+.B struct libcontacts_organisation
+with the following fields:
+.RS
+.TP
+.BI "char *" organisation
+The name of the organisation the contact is a member of.
+.TP
+.BI "char *" title
+The contact's title or role within the orginisation.
+.TP
+.BI "char **" unrecognised_data
+List of entries, for the organisation membership, that was not recognised by
+.BR libcontacts .
+.RE
+.PP
+The
+.B <libcontacts.h>
+header defines
+.B struct libcontacts_pgpkey
+with the following fields:
+.RS
+.TP
+.BI "char *" context
+The context in which the PGP-key is used. For example
+.B \(dqpersonal\(dq
+or
+.BR \(dqwork\(dq .
+.TP
+.BI "char *" id
+The fingerprint if the PGP-key.
+.TP
+.BI "char **" unrecognised_data
+List of entries, for the PGP-key, that was not recognised by
+.BR libcontacts .
+.RE
+.PP
+The
+.B <libcontacts.h>
+header defines
+.B struct libcontacts_site
+with the following fields:
+.RS
+.TP
+.BI "char *" context
+The context in which the site is used. For example
+.B \(dqblog\(dq
+or
+.BR \(dqsoftware\(dq .
+.TP
+.BI "char *" address
+Address to the site, including protocol. For example
+.B https://example.org
+or
+.BR gopher://example.org .
+.TP
+.BI "char **" unrecognised_data
+List of entries, for the site, that was not recognised by
+.BR libcontacts .
+.RE
+.PP
+The
+.B <libcontacts.h>
+header defines
+.B enum libcontacts_block_type
+with the following values:
+.RS
+.TP
+.B LIBCONTACTS_SILENT
+The phone shall not call its owner's attention.
+.TP
+.B LIBCONTACTS_BLOCK_OFF
+The phone shall appear to the caller as as turned off.
+.TP
+.B LIBCONTACTS_BLOCK_BUSY
+The phone shall appear to the caller as as busy.
+.TP
+.B LIBCONTACTS_BLOCK_IGNORE
+The phone shall appear to the caller as turned on
+but with no one answering.
+.RE
+.PP
+The
+.B <libcontacts.h>
+header defines
+.B enum libcontacts_gender
+with the following values:
+.RS
+.TP
+.B LIBCONTACTS_UNSPECIFIED_GENDER
+No gender has been specified for the contact.
+.TP
+.B LIBCONTACTS_NOT_A_PERSON
+The contact is not to a person. It may be to a company or service.
+.TP
+.B LIBCONTACTS_MALE
+The contact is a male.
+.TP
+.B LIBCONTACTS_FEMALE
+The contact is a female.
+.RE
+.PP
+The
+.B <libcontacts.h>
+header defines the following functions:
+.RS
+.TP
+.BR libcontacts_list_contacts (3)
+Get a list of all contacts.
+.TP
+.BR libcontacts_load_contact (3)
+Load a contact.
+.TP
+.BR libcontacts_load_contacts (3)
+Load all contacts.
+.TP
+.BR libcontacts_save_contact (3)
+Save a contact.
+.TP
+.BR libcontacts_contact_destroy (3)
+Deallocate memory for a contact entry.
+.TP
+.BR libcontacts_address_destroy (3)
+Deallocate memory for a contact address entry.
+.TP
+.BR libcontacts_birthday_destroy (3)
+Deallocate memory for a contact birthday entry.
+.TP
+.BR libcontacts_block_destroy (3)
+Deallocate memory for a contact block entry.
+.TP
+.BR libcontacts_chat_destroy (3)
+Deallocate memory for a contact chat service address entry.
+.TP
+.BR libcontacts_email_destroy (3)
+Deallocate memory for a contact e-mail address entry.
+.TP
+.BR libcontacts_number_destroy (3)
+Deallocate memory for a contact telephone number entry.
+.TP
+.BR libcontacts_organisation_destroy (3)
+Deallocate memory for a contact organisation membership entry.
+.TP
+.BR libcontacts_pgp_destroy (3)
+Deallocate memory for a contact PGP-key fingerprint entry.
+.TP
+.BR libcontacts_site_destroy (3)
+Deallocate memory for a contact Internet site entry.
+.TP
+.BR libcontacts_get_path (3)
+Get the file information for a contact is or would be stored in.
+.TP
+.BR libcontacts_parse_contact (3)
+Parse a contact file.
+.TP
+.BR libcontacts_format_contact (3)
+Construct a contact file.
+.TP
+.BR libcontacts_same_number (3)
+Compare two telephone numbers for equality.
+.RE
+
+.SH SEE ALSO
+.BR libcontacts (7),
+.BR contacts (5)
diff --git a/libcontacts_get_path.3 b/libcontacts_get_path.3
index d1e62f2..a87e93d 100644
--- a/libcontacts_get_path.3
+++ b/libcontacts_get_path.3
@@ -77,7 +77,7 @@ currently define ones are:
 .B .me
 Contact information for the user.
 .TP
-.B .groups
+.B .nobody
 Pseudo-contact where groups that how no members can be
 stored.
 .PP
diff --git a/libcontacts_same_number.3 b/libcontacts_same_number.3
index 3b30a89..c7a81d3 100644
--- a/libcontacts_same_number.3
+++ b/libcontacts_same_number.3
@@ -1,6 +1,6 @@
 .TH LIBCONTACTS_SAME_NUMBER 3 LIBCONTACTS
 .SH NAME
-libcontacts_same_number \- Save a contact
+libcontacts_same_number \- Compare two telephone numbers for equality
 .SH SYNOPSIS
 .nf
 #include <libcontacts.h>
diff --git a/test.c b/test.c
index a7dae8b..eb8b7f4 100644
--- a/test.c
+++ b/test.c
@@ -74,7 +74,7 @@ main(void)
 
 	touch(".testdir/.config/contacts/alpha");
 	touch(".testdir/.config/contacts/.me");
-	touch(".testdir/.config/contacts/.groups");
+	touch(".testdir/.config/contacts/.nobody");
 	touch(".testdir/.config/contacts/beta");
 	touch(".testdir/.config/contacts/.exclude");
 	touch(".testdir/.config/contacts/gamma");