diff options
| -rw-r--r-- | TODO | 1 | ||||
| -rw-r--r-- | contacts.5 | 299 | ||||
| -rw-r--r-- | libcontacts.h.0 | 4 |
3 files changed, 301 insertions, 3 deletions
@@ -1 +0,0 @@ -Add contacts.5 diff --git a/contacts.5 b/contacts.5 new file mode 100644 index 0000000..010225f --- /dev/null +++ b/contacts.5 @@ -0,0 +1,299 @@ +.TH CONTACTS 5 LIBCONTACTS +.SH NAME +contacts \- Simple and flexible contact information file format + +.SH DESCRIPTION +The directory +.I ~/.config/contacts +is used to store files with contact information, one +person per file, in the format specified by this document. +File names that end with a tilde +.RB ( ~ ) +are reserved for temporary storage while saving a file +so that an already existing file (with the same name minus +the tilde) is replaced before the new version is completed, +and also so that other processes do not read incomplete files. +File names that start with a dot +.RB ( . ) +are reserved for special purpose entries. +It is recommended that file names do not contain any other +characters than lower case ASCII letters, ASCII digits and +ASCII hyphen +.RB ( - ). +Subdirectories are prohibited. +.PP +The recommended default format for a file name is the +name as the user prefers it to be displayed in the latin +alphabet, in lower case with all non-letters (e.g. hyphens) +removed, and spaces replaced with hyphens. +.PP +The currently defined special puporse entries are: +.TP +.B .me +The user himself. +.TP +.B .nobody +Unused data, such as created groups without any members. +.PP +The files in +.I ~/.config/contacts +are UTF-8 text files, meaning that they must not contain +any NUL bytes and each line is terminated by a <newline> +.RB ( \(aq\en\(aq ). +.PP +Each line in the file is a data entry and should begin +with combination of printable ASCII characters, mostly +upper case letters, called a tag, (non-standard entires +should also begin with +.BR X- ), +followed by either a colon +.RB ( : ), +or a regular blank space (horizontal tab should also be +tolerated) followed by the data for the entry. Some lines +however are only flags and only contain the tag. Lines +using the colon alternative must end with that colon, +and subsequent lines starting a horizontal tab (one or more +regular blank spaces and horizontal tabs should also be +tolerated), until but excluding the subsequent first line +that does not start this way, shall be considered subentries +(this indentation is excluded in the description above, but +is there for subentries, top-level entries are not +indented). There is no prescribed order for entries. +.PP +Standard entires are, unless otherwise specified that +must be specified multiple times.: +.TP +.B NAME +The name of the contact as it should be displayed. +May only be specified once. +.TP +.B FNAME +The contact's given name. +May only be specified once. +.TP +.B LNAME +The contact's family name, if any. +May only be specified once. +.TP +.B FLNAME +The full name of the contact. There is no prescribed +format, and there never will be. Application are advised +not to presume any format. May only be specified once. +.TP +.B NICK +The contact's nickname (once upon a time known as surname), +if any. May only be specified once. +.TP +.B PHOTO +Pathname to photo of the contact; should either be an +absolute path or a path 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. +.TP +.B GROUP +Contact group that the contact is a member of. + +For the special pseudocontact +.BR .nobody , +it specified that the group shall exist, even if it may +be empty. +.TP +.B NOTES +Personal note about the contact. +.TP +.B BLOCK: +Contact block information for the contact. Standard +subentries are: +.RS +.TP +.B SRV +TODO +.TP +.B EXPLICIT +TODO +.TP +.B ASK +TODO +.TP +.B REMOVE +TODO +.TP +.B OFF +TODO +.TP +.B BUSY +TODO +.TP +.B IGNORE +TODO +.RE +.TP +.B ORG: +Organisation membership for the contact. Standard +subentries are: +.RS +.TP +.B ORG +TODO +.TP +.B TITLE +TODO +.RE +.TP +.B EMAIL: +E-mail address for the contact. Standard subentries are: +.RS +.TP +.B CTX +TODO +.TP +.B ADDR +TODO +.RE +.TP +.B KEY: +PGP-key for the contact. Standard subentries are: +.RS +.TP +.B CTX +TODO +.TP +.B ID +TODO +.RE +.TP +.B PHONE: +Telephone numbers for the contact. Standard subentries are: +.RS +.TP +.B CTX +TODO +.TP +.B NUMBER +TODO +.TP +.B MOBILE +TODO +.TP +.B FAX +TODO +.PP +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. +.RE +.TP +.B ADDR: +Address (physical location) for the contact. Standard +subentries are: +.RS +.TP +.B CTX +TODO +.TP +.B COUNTRY +TODO +.TP +.B C/O +TODO +.TP +.B ADDR +TODO +.TP +.B CODE +TODO +.TP +.B CITY +TODO +.TP +.B COORD +TODO +.RE +.TP +.B SITE: +Internet sites (e.g. Web sites) that the contact own or +has an account on. Standard subentries are: +.RS +.TP +.B CTX +TODO +.TP +.B ADDR +TODO +.RE +.TP +.B CHAT: +The contact's contact information for a services, like +an instant messenging service. Standard subentries are: +.RS +.TP +.B CTX +TODO +.TP +.B SRV +TODO +.TP +.B ADDR +TODO +.PP +Entries shall be added by the applications that use the +chat services. +.RE +.TP +.B BIRTH: +When the contact celebrates his birthday. Standard +subentries are: +.RS +.TP +.B YEAR +TODO +.TP +.B MONTH +TODO +.TP +.B DAY +TODO +.TP +.B EARLY +TODO +.PP +May only be specified once. +.RE +.TP +.B ICE +Whether the contact shall be listed as an In Case of Emergency +(ICE) contact that can be view without unlocking the phone. +No data may be added to this entry. May only be specified once. +.TP +.B NPERSON +The contact is not a person, it may be for example be a +company or the voice-mail inbox service. No data may be +added to this entry. May only be specified once and cannot +be combined with +.B MALE +or +.BR FEMALE . +.TP +.B MALE +The contact is a male. No data may be added to this entry. +May only be specified once and cannot be combined with +.B NPERSON +or +.BR FEMALE . +.TP +.B FEMALE +The contact is a female. No data may be added to this entry. +May only be specified once and cannot be combined with +.B NPERSON +or +.BR MALE . + +.SH SEE ALSO +.BR libcontacts (7), +.BR libcontacts.h (0) diff --git a/libcontacts.h.0 b/libcontacts.h.0 index 4745c9c..b28deb1 100644 --- a/libcontacts.h.0 +++ b/libcontacts.h.0 @@ -69,8 +69,8 @@ This list is .IR NULL -terminated. .TP .BI "char **" groups -List of groups the contact is a member of. For the -special pseudocontact +List of contact 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 |