#================================================================
# address.rnc:  Address book schema in Relax NG Compact Syntax
#   $Revision: 1.1 $  $Date: 2004/08/03 22:52:49 $
#----------------------------------------------------------------
start = address-book

#================================================================
# The root element is <address-book>.  The <heading> element is
# required and first; its attributes are revision= and date=, for
# RCS tags.  Any number of <entry> elements may follow.
#----------------------------------------------------------------
address-book = element address-book
{ attribute revision { text }?,
  attribute date { text }?,
  heading, entry*
}

#================================================================
# The <heading> element has a required attribute date= attribute.
# Its textual content will be reproduced in the output and is
# intended for things like "Return to ... emergency contact ..."
#----------------------------------------------------------------
heading = element heading
{ attribute date { text },
  text
}

#================================================================
# Each <entry> element describes one entity and all its forms of
# access.  An entity may be one or more people (e.g., couples
# living together) and/or one or more organizations.  It will
# be indexed or cross-referenced under all these names.
# - date="D" says when this entry was last good (optional)
# - hide="yes" means don't show this except in my private version
# - status="old" means it's just a memory, not needed in the
#       current phonebook
# - The <xref> child gives alternative cross-reference strings
# - The "id" children describe the entity or entities
# - The "comm" children describe ways of communicating with or
#       visiting them
# - The <directions> child describes how to get there
# - The <notes> child is for any other miscellaneous text
#----------------------------------------------------------------
entry  =  element entry
{ attribute date { text }?,
  attribute status { text }?,
  attribute hide { "yes" | "no" }?,
  xref*, id, comm, directions*, notes?
}

#================================================================
# Each <xref> element contains a string under which this entry
# should be cross-referenced, e.g., `plumbers', or the person's
# former name.  The text may contain colons to define multiple
# levels, e.g., `plumbers: Socorro'.
#----------------------------------------------------------------
xref = element xref { text }

#================================================================
# The various "id" elements contain one or more names under which
# the entry should appear.  It can be any mixture of <person>
# elements for people and/or <org> elements for organizations.
#----------------------------------------------------------------
id          =  (person* & org*)+
person      =  element person { last, first?, nick? }
first       =  element first { text }
nick        =  element nick { text }
last        =  element last { text }
org         =  element org { mixed { contact* } }
contact     =  element contact { text }

#================================================================
# The various "comm" elements contain all the ways of contacting
# them.  Several have a kind= attribute for distinguishing
# multiple options, e.g., kind="cell" for a phone number,
# kind="home" for a location.
#----------------------------------------------------------------
comm        =  (e-mail* & location* & phone*)*
kind        =  attribute kind { text }
e-mail      =  element e-mail { kind*, text }

#================================================================
# The <location> element is for U. S. mailing addresses
# (mail="yes") or street/UPS address (mail="no", the default.)
# Use the kind= attribute, e.g., for "h" (home) or "w" (work).
#----------------------------------------------------------------
addr-group  =  (a*, city?, state?, zip?, nation?)
location    =  element location
{   kind?,
    attribute mail { "yes" | "no" }*,
    addr-group
}
a           =  element a { text }
city        =  element city { text }
state       =  element state { text }
zip         =  element zip { text }
nation      =  element nation { text }

#================================================================
# The <phone> element describes one phone number.
# - kind is "cell", "fax", "h" for home, "w" for work, etc.
# - primary is "yes" if this is the main number
# - unlisted is "yes" if it is unlisted
#----------------------------------------------------------------
phone       = element phone
{   kind?,
    attribute unlisted { "yes" }?,
    text
}

#================================================================

# The <directions> element contains directions in a standard
# form I invented.  Each leg of the directions has three parts:
# <on>, the route and direction of travel; <when>, the next
# landmark to watch for; and <then>, what to do at the landmark.
#----------------------------------------------------------------
directions  = element directions { leg+ }
leg         = element leg { on, when, then }
on          = element on { text }
when        = element when { text }
then        = element then { text }

#================================================================
# Finally, the <notes> element gives us a place to store any other
# relevant information about the entry.
#----------------------------------------------------------------
notes       = element notes { text }