============= Address Books ============= The XML_ files used to store our contact details are called address books. Here is an example .. literalinclude:: sample_addressbook.xml :language: xml :linenos: Elements ======== addressbook ----------- This is the top level element in a whoswho file. There should only be one instance of this element in each address book file. It must contain the "name" attribute. This will be used as the page title when generating an HTML representation. Each addressbook element can contain 0, 1 or more :ref:`person` elements. Each addressbook element can contain 0, 1 or more :ref:`organisation` elements. .. _person: person ------ This element contains all of the details we want to record about an individual. Each person element must have an "id" attribute and this value must be unique through all of your address books. Each person element may have a "name" attribute. This can be the commonly used name of the person rather than their full name that is recorded in the name element. The first sub element of a person is 0, 1 or more category elements. These allow you to 'tag' the person with labels that can then be used in searches. You can use whatever text you like in category elements. A person's name is recorded in a specific element (with the tag "person"). Each person must have "first" and "surname" sub-elements. They can optionally have "title" and "middle" sub-elements as well. The simplest name will look like this:: Andrew Todd The full version will look something like this:: Mr. Andrew J. Todd The order of the sub-elements is important, they must be ``title`` (if used), then ``first``, then ``middle`` (if used) and finally ``surname``. The simplest person entry will just have the ``name`` containing ``first`` and ``surname`` within the person element as shown in the first example above. After a person's name you can indicate where they work and their job title in a ``company`` element:: Acme Corporation Widget Wrangler The ``name`` sub-element is required but the role is optional. You can then include a ``date-of-birth``. The format of the text between these tags is up to you. There is no strict format enforced. Next you can include an :ref:`address` For person elements you can only specify one address. After the address you can have 0, 1 or more :ref:`phone` elements. After phone numbers you can have 0, 1 or more ``instantmessage`` elements. The format of the text between these tags is up to you. Next you can have 0, 1 or more :ref:`email` elements. For nostalgia's sake you can then have 0, 1 or more :ref:`fax` elements. Then you can have 0, 1 or more :ref:`web` elements defining URLs associated with this person. The last element is a ``notes`` tag. This can contain any text you would like to store about this person. .. _organisation: organisation ------------ This element contains all of the details that we want to record about a company or other organisation. Each organisation element must have an "id" attribute and this value must be unique amongst all person and organisation entries through all of your address books. Each organisation element may have a "name" attribute. This can be the commonly used name of the organisation rather than their full name that is recorded in the name element The first sub element of an organisation is 0, 1 or more category elements. These allow you to 'tag' the organisation with labels that can then be used in searches. You can use whatever text you like in category elements. The next sub element is the ``name``. This is a simple tag (unlike the :ref:`person` ``name`` tag) and should just contain the organisation's name between the tags. Next comes the :ref:`address` of the organisation. Only one may be defined in this format. After the address you can have 0, 1 or more :ref:`phone` elements. Next you can have 0, 1 or more :ref:`email` elements. For nostalgia's sake you can then have 0, 1 or more :ref:`fax` elements. Then you can have 0, 1 or more :ref:`web` elements defining URLs associated with this organisation. The last element is a ``notes`` tag. This can contain any text you would like to store about this organisation. All sub elements of an organisation are optional. .. _address: address ------- An address is a postal or street address identifying a location. The format is somewhat flexible but is mainly designed for UK, US or Australian addresses as these are the ones that I have the most experience with. Each of the sub elements is optional and if necessary you can put the full address as text between the start and end ``address`` tags. The first part of the address should be stored as text immediately after the opening ``address`` tag. You can then add one or more of the following (optional) sub elements * ``city`` (or ``town``) * ``state`` (or ``county``) * ``postalcode`` * ``country`` Simply put the appropriate contents between the start and end tags. There is no pre-determined format for the contents of any one. .. _phone: phone ----- You can place phone numbers for :ref:`person` or :ref:`organisation` entries between ``phone`` tags. There is no specific format required. Each ``phone`` element must have a ``type`` attribute that is one of; * home * mobile * work .. _fax: fax --- A ``fax`` element is fundamentally the same as a :ref:`phone` element. It must also have a ``type`` attribute. For fax elements this must be one of; * home * work .. _email: email ----- An ``email`` element is a way of storing an email address. Just put the address as text between the start and end tags. It must also have a ``type`` attribute that is one of; * home * work .. _web: web --- This element contains the URL of a web site associated with an address book entry. The URL is contained between the start and end tags. It should usually refer to a web URL but there is no restriction on other types of address or prefixes such as 'ftp' or other web protocols. A ``web`` element must have a ``type`` attribute. It must be one of; * personal * work Validating your Address Books ============================= The whoswho application has a module that you can use to validate your address books. Just run:: $ python validate_whoswho.py This will validate the address books defined in your :doc:`configuration` file and tell you if they are valid. If any address book fails validation the XML parser error messages will be displayed on the command line. RelaxNG Schema ============== .. literalinclude:: ../whoswho.rng :language: xml .. _XML: https://en.wikipedia.org/wiki/XML