A package to collect contacts from org-agenda files, and allow
operations to be carried out on them.

By default all tree-items with a "contact" tag, which contain
properties, are considered contacts.

An example pair of contacts would look like this inside an org-mode
file:

  * People
    ** Alice                        :family:contact:
    :PROPERTIES:
    :ADDRESS: 32 Something Street
    :EMAIL: alice@example.com
    :PHONE: +123 456 789
    :CHILDREN: Mallory
    :NICKNAME: Allu
    :END:
    ** Bob                           :colleague:contact:
    :PROPERTIES:
    :ADDRESS: 32 Something Lane
    :EMAIL: bob@example.com
    :PHONE: +123 456 987
    :END:

The specific properties used don't matter, although it seems natural
to use :ADDRESS, :EMAIL, and :PHONE.  A contact will be discovered
if there is at least one property present alongside the mandatory
"contact" tag.  (You can change the name of the tag used to search for
people by setting `org-people-search-tag' to your preferred alternative.)


; Basic operations

Once your agenda files have been loaded `org-people-summary' will
show a buffer of all known contacts, and from there you can copy
attributes, jump to their definitions, & etc.

`org-people-insert' allows you to interactively insert data from
your contacts with helpful TAB-completion, on both the name of the
contact and the attribute name to be inserted.

We provide a new link-type `org-people:' which allows you to jump
to a contact's definition when followed.   If you have such links
within your document (e.g. a link such as [[org-people:Steve Kemp]]
you can use the helper `org-people-add-descriptions' to automatically
add the contact description automatically - although if you used
C-c C-l to insert such a link the description should be auto-populated.


; org-table helpers

Contacts need the "contacts" tag to be present to be discovered and
included in the `org-people' functions, but you can also use the
standard `org-mode' facilities to add additional tags to entries too.
Using the extra tags you may build simple tables of matching entries.
For example the following can auto-update when you select the code-block
and run "C-c C-c":

   #+NAME: get-family-contacts
   #+BEGIN_SRC elisp :results value table
   (org-people-tags-to-table "family")
   #+END_SRC

If you prefer to include different columns in your generated table you
can specify those directly:

  #+NAME: get-family-contacts
  #+BEGIN_SRC elisp :results value table
  (org-people-tags-to-table "family" '(:LINK :PHONE))
  #+END_SRC

You may also create a table including all known data about a single named
individual:

   #+NAME: steve-kemp
   #+BEGIN_SRC elisp :results value table :colnames '("Field" "Value")
   (org-people-person-to-table "Steve Kemp")
   #+END_SRC

In this case properties listed in `org-people-ignored-properties` will
be ignored and excluded from the generated table.


; summary-view

There is the ability to mark/unmark rows within the list of people
generated by `org-people-summary'.

Using that facility you can write code that operates on either the
people who are currently marked, or if none then the person upon
the current row.  See `org-people-summary-marked-or-current' for
a useful helper to simplify that.

A similar helper `org-people-get-property-marked-or-current' allows
fetching the values of a given property for each marked contact,
or the person upon the current row if nothing is marked.

The vCARD and CSV exporter functions use this facility, as does
the "open website" and "compose email" functions which are bound
by default within the summary-view.

Pressing TAB within the summary will allow you to view all defined
property for the contact at the point, and pressing again will hide
the inline display.


; complete-at-point

There are a pair of functions provided for the complete-at-point
framework - one for names and one for email addresses.  They might
be enabled like so:

 (add-hook 'message-mode-hook
         (lambda ()
                 (add-hook 'completion-at-point-functions
                     #'org-people-email-capf
                     nil t)))

 (add-hook 'text-mode-hook
         (lambda ()
           (add-hook 'completion-at-point-functions
                     #'org-people-capf
                     nil t)))


; hl-line-mode

If you want to enable `hl-line-mode` that is supported, and there are local
configurations setup so that only people are highlighted - rather than any
inline property blocks which might be present.

Simply add this to your configuration:

  (add-hook 'org-people-summary-mode-hook #'(lambda () (hl-line-mode 1)))