[elpa] externals/ebdb 20785a1 029/350: Additions to README and manual

[Eric Abrahamsen]

branch: externals/ebdb
commit 20785a1a359a4e84edbee8e6aec8941037c2dd50
Author: Eric Abrahamsen <address@hidden>
Commit: Eric Abrahamsen <address@hidden>

    Additions to README and manual
---
 README.org |  15 ++++-----
 ebdb.org   | 101 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++-----
 2 files changed, 101 insertions(+), 15 deletions(-)

diff --git a/README.org b/README.org
index f889818..fc9791c 100644
--- a/README.org
+++ b/README.org
@@ -37,7 +37,8 @@ EBDB as it stands provides a few enhancements over BBDB.
 4. Records can have relations to other records.
 5. ebdb-i18n.el. This pluggable internationalization framework allows
    developers to write country-specific libraries providing different
-   behavior for records and fields depending on nationality.
+   behavior for records and fields depending on nationality. It works
+   for all countries except Abkhazia and the Vatican (don't ask).
 6. High configurability. EBDB has many customization options (though
    fewer than BBDB had), but users and developers who are familiar
    with generic functions can use them to fundamentally alter the
@@ -45,7 +46,8 @@ EBDB as it stands provides a few enhancements over BBDB.
    low risk of breakage. Want to prepend the string "Hi my name is "
    to all the contact names in your *BBDB* buffer? That would be three
    lines of code.
-7. A native Vcard database class is on its way.
+7. A native Vcard database class is on its way. A native CardDav
+   database class is following at a significant distance.
 ** What Are the Drawbacks?
 
 Buggy code! Potential data loss! This is still very much alpha. Many
@@ -56,11 +58,10 @@ Also, many of the customization options are likely to 
change as the
 package gets through beta to something stable.
 
 Other than that, load and save times are a bit slow, and the database
-persistence file is significantly larger than it was in BBDB. In part
-this is because there's simply more data being recorded, and the
-persistence format is verbose. It's likely that optimizations can be
-made to reduce load times.
-** I Still Want to Try This, Is There A Migration Scheme?
+persistence file is significantly larger than it was in BBDB. It's
+likely that optimizations can be made to reduce load times, and the
+size of the persistence file.
+** I Still Want to Try This, Is There a Migration Scheme?
 Yes, EBDB will read and migrate from a BBDB v3 data file. Actually,
 EBDB preserves the BBDB's old migration routines, so theoretically you
 could go from a BBDB v2 file, through BBDB v3, straight to EBDB. I
diff --git a/ebdb.org b/ebdb.org
index 50ab540..150f38b 100644
--- a/ebdb.org
+++ b/ebdb.org
@@ -6,6 +6,7 @@
 #+TEXINFO_DIR_TITLE: EBDB: (ebdb)
 #+TEXINFO_DIR_DESC: Contact management package
 #+OPTIONS: *:nil num:t toc:nil
+#+MACRO: ebuf \ast{}EBDB\ast{}
 
 * Introduction
 This manual is for EBDB version 0.1
@@ -44,7 +45,7 @@ Databases have a few user-facing settings:
   Set to nil to prevent auto-saving of the database's records.
 - Option: buffer-char
   Set to a single character that will be displayed next to records in
-  the \ast{}EBDB\ast{} buffer, indicating which database they belong
+  the {{{ebuf}}} buffer, indicating which database they belong
   to.
 - Option: uuid-prefix
   A string to be appended to the uuids of all records created in this
@@ -58,23 +59,107 @@ Databases have a few user-facing settings:
 
 While it's possible to edit database definitions directly in the file,
 it's safer to use the customization interface to do so from the
-\ast{}EBDB\ast{} buffer.
+{{{ebuf}}} buffer.
 
 - Command: ebdb-customize-database db
   Use the customize interface to edit the definition of DB.
 
-Records can be moved or copied from one database to another.  It's
-also possible for a single record to live in more than one database,
-though this functionality is experimental.  When a record is loaded
-from more than one database, the two copies are compared using the
-"timestamp" field, and the most recently updated copy is kept.
+Records can be moved or copied from one database to another. It's also
+possible for a single record to live in more than one database, though
+this functionality is experimental. When a record is loaded from more
+than one database, the two copies are compared using the "timestamp"
+field, and the older copy is discarded.
 
 - Command: ebdb-move-record record to-db
   More RECORD from its existing database to TO-DB.
 
 - Command: ebdb-copy-record record to-db
   Copy RECORD into TO-DB, leaving it in its existing database(s).
-
+* Creating records
+
+Create a record using "c" (`ebdb-create') in the {{{ebuf}}} buffer.
+With no prefix arg, this command will create an instance of the
+default record class, in the database at the head of `ebdb-sources'.
+
+- Variable: ebdb-default-record-class
+  The default record class to use when creating new records.
+
+Alternately create a record using "C" (`ebdb-create-extended'), which
+will prompt for a record class to use, as well as a database to store
+the record in, if there is more than one.
+** Record classes
+EBDB comes with two record classes, representing individuals and
+organizations.
+
+* Record fields
+** Inserting new fields
+Press "i" (`ebdb-insert-field') with point on a record will prompt for
+a field type, then field values, and add the field to the record.  See
+[[id:cb2190f4-f2e6-4082-9671-24e11e5cc0c6][Field types]] for more information 
about the various kinds of fields.
+
+When entering field data, optional data can be skipped by entering a
+blank string, or by pressing "C-g".  The first "C-g" will cancel the
+current data prompt; the second "C-g" will cancel the creation of the
+field altogether.  For instance, when creating address fields, EBDB
+will allow you to create an arbitrary number of street lines.  When
+you've added enough, either enter a blank string, or hit "C-g".
+** Editing existing fields
+Pressing "e" (`ebdb-edit-field') with point on a field will allow you
+to edit an existing field, with the previous values as defaults.
+
+Alternately, press "E" (`ebdb-edit-field-customize') to edit the
+field's values using the Customize interface.  Some fields have slots
+that can only be edited this way; other fields have slots that cannot
+be edited at all once the field is created.
+** Deleting records and fields
+Pressing "C-k" on a field will ask you for confirmation, then delete
+the field.  Pressing "C-k" while point is on or before a record's main
+name will instead prompt to delete the whole record.
+** Field types
+:PROPERTIES:
+:ID:       cb2190f4-f2e6-4082-9671-24e11e5cc0c6
+:END:
+Fields can be classed in a few different categories.  Some are
+"plumbing" fields, that are present for all records, but not generally
+visible or user-editable: these include the creation date, timestamp,
+and UUID.  Others are "built-in" fields: basic fields that get special
+treatment.  These include the name, mail, phone, address, and notes
+fields.  EBDB comes with default classes for these fields: if you
+would like to use different defaults, you can create new classes
+(inheriting from the existing ones), then set these user options to
+your custom class name:
+
+- Variable: ebdb-default-name-class
+  Defaults to `ebdb-field-name-complex'.  In fact, person records are
+  created with name fields of `ebdb-field-name-complex', and
+  organization records are created with `ebdb-field-name-simple'.
+- Variable: ebdb-default-mail-class
+  Defaults to `ebdb-field-mail'.
+- Variable: ebdb-default-phone-class
+  Defaults to `ebdb-field-phone'.
+- Variable: ebdb-default-address-class
+  Defaults to `ebdb-field-address'.
+- Variable: ebdb-default-notes-class
+  Defaults to `ebdb-field-notes'.
+
+Besides the "plumbing" and "built-in" fields, all other fields belong
+to one of two types: `ebdb-field-user' and `ebdb-field-user-simple'.
+The former is an abstract class, used to built fields with more
+complicated structures.  The latter is a simple class with a string
+label and a string value.
+
+When adding fields to a record, EBDB offers up all the known labels of
+the simple user field class as possible choices.  Typing in an unknown
+string will define a new label, which will be offered as a choice in
+the future.
+
+Fields built from `ebdb-field-user' will have their own identifier.
+EBDB comes with classes including "anniversary", "url", "id",
+"relation", "role" and more.  Many of these fields have their own list
+of labels (for instance, "anniversary" fields may be labeled
+"birthday", "wedding", etc).
+
+Loading secondary libraries may make more field types available.
 * MUA Interaction
 One of EBDB's most important features is the ability to create, update
 and display records based on messages received in your mail user