emacs-elpa-diffs
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

[elpa] externals/ebdb a035748 318/350: Mention role fields in the manual


From: Eric Abrahamsen
Subject: [elpa] externals/ebdb a035748 318/350: Mention role fields in the manual
Date: Mon, 14 Aug 2017 11:47:02 -0400 (EDT)

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

    Mention role fields in the manual
    
    * ebdb.org(Role Fields): New manual section.
    * ebdb.info: etc
    * ebdb.texi: etc
---
 ebdb.info | 180 +++++++++++++++++++++++++++++++++++++++-----------------------
 ebdb.org  |  46 ++++++++++++++--
 ebdb.texi |  78 +++++++++++++++++++++------
 3 files changed, 216 insertions(+), 88 deletions(-)

diff --git a/ebdb.info b/ebdb.info
index 5b8c5f8..f322754 100644
--- a/ebdb.info
+++ b/ebdb.info
@@ -63,13 +63,18 @@ Creating Records
 
 Record Fields
 
-* Inserting new fields::
-* Editing existing fields::
-* Deleting records and fields::
-* Field types::
+* Inserting New Fields::
+* Editing Existing Fields::
+* Deleting Records and Fields::
+* Field Types::
 
 
 
+
+Field Types
+
+* Role Fields::
+
 MUA Interaction
 
 * Loading MUA Code::
@@ -307,6 +312,7 @@ File: ebdb.info,  Node: Record classes,  Next: Record 
names,  Up: Creating Recor
 
 EBDB comes with two record classes, representing individuals
 (‘ebdb-record-person’) and organizations (‘ebdb-record-organization’).
+Records can have “roles” at organizations *note Role Fields::.
 
 
 File: ebdb.info,  Node: Record names,  Prev: Record classes,  Up: Creating 
Records
@@ -333,15 +339,15 @@ File: ebdb.info,  Node: Record Fields,  Next: MUA 
Interaction,  Prev: Creating R
 
 * Menu:
 
-* Inserting new fields::
-* Editing existing fields::
-* Deleting records and fields::
-* Field types::
+* Inserting New Fields::
+* Editing Existing Fields::
+* Deleting Records and Fields::
+* Field Types::
 
 
-File: ebdb.info,  Node: Inserting new fields,  Next: Editing existing fields,  
Up: Record Fields
+File: ebdb.info,  Node: Inserting New Fields,  Next: Editing Existing Fields,  
Up: Record Fields
 
-4.1 Inserting new fields
+4.1 Inserting New Fields
 ========================
 
 Pressing “i” (‘ebdb-insert-field’) with point on a record will prompt
@@ -356,9 +362,9 @@ allow you to create an arbitrary number of street lines.  
When you’ve
 added enough, either enter a blank string, or hit “C-g”.
 
 
-File: ebdb.info,  Node: Editing existing fields,  Next: Deleting records and 
fields,  Prev: Inserting new fields,  Up: Record Fields
+File: ebdb.info,  Node: Editing Existing Fields,  Next: Deleting Records and 
Fields,  Prev: Inserting New Fields,  Up: Record Fields
 
-4.2 Editing existing fields
+4.2 Editing Existing Fields
 ===========================
 
 Pressing “e” (‘ebdb-edit-field’) with point on a field will allow you to
@@ -370,9 +376,9 @@ that can only be edited this way; other fields have slots 
that cannot be
 edited at all once the field is created.
 
 
-File: ebdb.info,  Node: Deleting records and fields,  Next: Field types,  
Prev: Editing existing fields,  Up: Record Fields
+File: ebdb.info,  Node: Deleting Records and Fields,  Next: Field Types,  
Prev: Editing Existing Fields,  Up: Record Fields
 
-4.3 Deleting records and fields
+4.3 Deleting Records and Fields
 ===============================
 
 Pressing “C-k” on a field will ask you for confirmation, then delete the
@@ -380,9 +386,9 @@ field.  Pressing “C-k” while point is on or before a 
record’s main name
 will instead prompt to delete the whole record.
 
 
-File: ebdb.info,  Node: Field types,  Prev: Deleting records and fields,  Up: 
Record Fields
+File: ebdb.info,  Node: Field Types,  Prev: Deleting Records and Fields,  Up: 
Record Fields
 
-4.4 Field types
+4.4 Field Types
 ===============
 
 :ID: cb2190f4-f2e6-4082-9671-24e11e5cc0c6 Fields can be classed in a few
@@ -416,6 +422,47 @@ of labels (for instance, anniversary fields may be labeled 
“birthday”,
 
    Loading secondary libraries may make more field types available.
 
+* Menu:
+
+* Role Fields::
+
+
+File: ebdb.info,  Node: Role Fields,  Up: Field Types
+
+4.4.1 Role Fields
+-----------------
+
+One type of field worth mentioning in particular is the role field.
+EBDB records come in two types at present: person and organization.
+People have roles at organizations: jobs, volunteer positions, etc.
+People are also likely to have roles at more than one organization.
+
+   When adding a role field to a record, you’ll be prompted to choose
+the relevant organization role, prompted for a string label denoting eg.
+a job title, and prompted for a mail address that belongs only to this
+role field (ie. an institutional email address).  If the organization
+has a “domain” field type, and the person has an existing mail address
+that matches that domain, you’ll be prompted to move that address to the
+role field.
+
+   When viewing organization records, the role fields for all related
+person records are also displayed as part of the organization record.
+
+   If a person’s role at an organization later comes to an end, the role
+field can be deleted, or marked as “defunct”, if record keeping is
+desired.  This can only be done using the customize-based editing
+interface (the “E” key on the role field).
+
+   In fact, in addition to a mail field, role fields can contain an
+arbitrary number of other fields, representing metadata about the role
+(an employee number, employment start date, etc).  The author has yet to
+come up with a good interface for viewing and manipulating these extra
+fields, however, so the functionality remains hidden.  Suggestions are
+very welcome.
+
+   Manipulating role fields is generally a little clunky, at present.
+This will be addressed in future.
+
 
 File: ebdb.info,  Node: MUA Interaction,  Next: EBDB Buffers,  Prev: Record 
Fields,  Up: Top
 
@@ -1137,7 +1184,7 @@ welcome, though less enthusiastically, are requests for 
new libraries.
    Internationalization libraries do not modify the database in any way,
 and can be safely unloaded.  They simply alter the way EBDB reads,
 parses and displays field values, and can also store extra information
-(eg.g for searching purposes) in a record’s cache.  Loading this library
+(eg. for searching purposes) in a record’s cache.  Loading this library
 can (depending on country libraries’ behavior) increase database load
 times, though it should not significantly affect search or display
 performance.
@@ -1648,7 +1695,7 @@ Index
 
 * Creating a database:                   The EBDB Database.   (line  11)
 * Creating records:                      Creating Records.    (line   6)
-* Deleting records and fields:           Deleting records and fields.
+* Deleting records and fields:           Deleting Records and Fields.
                                                               (line   6)
 * Diary integration:                     Diary Integration.   (line   6)
 * ebdb-cite-records:                     Citing Records.      (line  11)
@@ -1731,9 +1778,9 @@ Index
 * ebdb-snarf &optional string start end recs: Snarfing.       (line  15)
 * ebdb-toggle-records-format:            The Basics of ebdb-mode.
                                                               (line  69)
-* Editing fields:                        Editing existing fields.
+* Editing fields:                        Editing Existing Fields.
                                                               (line   6)
-* Inserting new fields:                  Inserting new fields.
+* Inserting new fields:                  Inserting New Fields.
                                                               (line   6)
 * Internationalization:                  Internationalization.
                                                               (line   6)
@@ -1750,52 +1797,53 @@ Index
 
 Tag Table:
 Node: Top806
-Node: Getting Started2217
-Node: Migration from BBDB2839
-Node: Record Migration3014
-Node: Variables and Options3551
-Node: The EBDB Database4037
-Node: Creating Records7193
-Node: Record classes8240
-Node: Record names8506
-Node: Record Fields9181
-Node: Inserting new fields9425
-Node: Editing existing fields10221
-Node: Deleting records and fields10821
-Node: Field types11217
-Node: MUA Interaction13036
-Node: Loading MUA Code13560
-Node: Display and Updating14273
-Node: Pop-up Buffers15042
-Node: Auto-Updating Records15907
-Node: Noticing and Automatic Rules18292
-Node: Interactive Commands19635
-Node: EBDB and MUA summary buffers22124
-Node: Sender name display22610
-Node: Summary buffer marks23898
-Node: EBDB Buffers25093
-Node: Searching26286
-Node: Changing Search Behavior27996
-Node: The Basics of ebdb-mode29246
-Node: Marking32610
-Node: Exporting/Formatting33038
-Node: Completion33997
-Node: Snarfing35138
-Node: Internationalization37042
-Node: Writing Internationalization Libraries38521
-Node: Diary Integration42809
-Node: Mail Aliases43675
-Node: vCard Support44384
-Node: Org Integration44883
-Node: Citing Records46457
-Node: Hacking EBDB47216
-Node: Field Classes49466
-Node: Init and Delete Methods52356
-Node: The Labeled Field Class53912
-Node: Actions54748
-Node: Custom Field Searching55413
-Node: Formatting in the EBDB Buffer57201
-Node: Index59200
+Node: Getting Started2248
+Node: Migration from BBDB2870
+Node: Record Migration3045
+Node: Variables and Options3582
+Node: The EBDB Database4068
+Node: Creating Records7224
+Node: Record classes8271
+Node: Record names8604
+Node: Record Fields9279
+Node: Inserting New Fields9523
+Node: Editing Existing Fields10319
+Node: Deleting Records and Fields10919
+Node: Field Types11315
+Node: Role Fields13160
+Node: MUA Interaction14851
+Node: Loading MUA Code15375
+Node: Display and Updating16088
+Node: Pop-up Buffers16857
+Node: Auto-Updating Records17722
+Node: Noticing and Automatic Rules20107
+Node: Interactive Commands21450
+Node: EBDB and MUA summary buffers23939
+Node: Sender name display24425
+Node: Summary buffer marks25713
+Node: EBDB Buffers26908
+Node: Searching28101
+Node: Changing Search Behavior29811
+Node: The Basics of ebdb-mode31061
+Node: Marking34425
+Node: Exporting/Formatting34853
+Node: Completion35812
+Node: Snarfing36953
+Node: Internationalization38857
+Node: Writing Internationalization Libraries40335
+Node: Diary Integration44623
+Node: Mail Aliases45489
+Node: vCard Support46198
+Node: Org Integration46697
+Node: Citing Records48271
+Node: Hacking EBDB49030
+Node: Field Classes51280
+Node: Init and Delete Methods54170
+Node: The Labeled Field Class55726
+Node: Actions56562
+Node: Custom Field Searching57227
+Node: Formatting in the EBDB Buffer59015
+Node: Index61014
 
 End Tag Table
 
diff --git a/ebdb.org b/ebdb.org
index bf9be26..ea11b0f 100644
--- a/ebdb.org
+++ b/ebdb.org
@@ -178,6 +178,7 @@ Currently this option's only use is to serve as a source for
 :END:
 EBDB comes with two record classes, representing individuals
 (~ebdb-record-person~) and organizations (~ebdb-record-organization~).
+Records can have "roles" at organizations 
[[id:1398bd78-b380-4f36-ab05-44ea5ca8632f][Role Fields]].
 ** Record names
 :PROPERTIES:
 
@@ -196,7 +197,7 @@ class is labeled "alt name".
 :PROPERTIES:
 :ID:       4170bd36-64bf-44b4-87d0-29fbed968851
 :END:
-** Inserting new fields
+** Inserting New Fields
 #+CINDEX: Inserting new fields
 Pressing "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.
@@ -208,7 +209,7 @@ 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
+** Editing Existing Fields
 :PROPERTIES:
 
 :END:
@@ -220,7 +221,7 @@ 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
+** Deleting Records and Fields
 :PROPERTIES:
 
 :END:
@@ -228,7 +229,7 @@ be edited at all once the field is created.
 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
+** Field Types
 :PROPERTIES:
 :ID:       cb2190f4-f2e6-4082-9671-24e11e5cc0c6
 
@@ -263,6 +264,41 @@ of labels (for instance, anniversary fields may be labeled 
"birthday",
 "wedding", etc).
 
 Loading secondary libraries may make more field types available.
+*** Role Fields
+:PROPERTIES:
+:ID:       1398bd78-b380-4f36-ab05-44ea5ca8632f
+:END:
+One type of field worth mentioning in particular is the role field.
+EBDB records come in two types at present: person and organization.
+People have roles at organizations: jobs, volunteer positions, etc.
+People are also likely to have roles at more than one organization.
+
+When adding a role field to a record, you'll be prompted to choose the
+relevant organization role, prompted for a string label denoting
+eg.@@texinfo:@:@@ a job title, and prompted for a mail address that
+belongs only to this role field (ie.@@texinfo:@:@@ an institutional
+email address).  If the organization has a "domain" field type, and
+the person has an existing mail address that matches that domain,
+you'll be prompted to move that address to the role field.
+
+When viewing organization records, the role fields for all related
+person records are also displayed as part of the organization record.
+
+If a person's role at an organization later comes to an end, the role
+field can be deleted, or marked as "defunct", if record keeping is
+desired.  This can only be done using the customize-based editing
+interface (the "E" key on the role field).
+
+In fact, in addition to a mail field, role fields can contain an
+arbitrary number of other fields, representing metadata about the role
+(an employee number, employment start date, etc).  The author has yet
+to come up with a good interface for viewing and manipulating these
+extra fields, however, so the functionality remains hidden.
+Suggestions are very welcome.
+
+Manipulating role fields is generally a little clunky, at present.
+This will be addressed in future.
+
 * MUA Interaction
 One of EBDB's most important features is the ability to create, update
 and display records based on messages received or sent in your mail
@@ -861,7 +897,7 @@ welcome, though less enthusiastically, are requests for new 
libraries.
 Internationalization libraries do not modify the database in any way,
 and can be safely unloaded.  They simply alter the way EBDB reads,
 parses and displays field values, and can also store extra information
-(eg.@@texinfo:@:@@g for searching purposes) in a record's cache.
+(eg.@@texinfo:@:@@ for searching purposes) in a record's cache.
 Loading this library can (depending on country libraries' behavior)
 increase database load times, though it should not significantly
 affect search or display performance.
diff --git a/ebdb.texi b/ebdb.texi
index 02ebe4c..aa85154 100644
--- a/ebdb.texi
+++ b/ebdb.texi
@@ -84,13 +84,18 @@ Creating Records
 
 Record Fields
 
-* Inserting new fields::
-* Editing existing fields::
-* Deleting records and fields::
-* Field types::
+* Inserting New Fields::
+* Editing Existing Fields::
+* Deleting Records and Fields::
+* Field Types::
 
 
 
+
+Field Types
+
+* Role Fields::
+
 MUA Interaction
 
 * Loading MUA Code::
@@ -336,6 +341,7 @@ Currently this option's only use is to serve as a source for
 
 EBDB comes with two record classes, representing individuals
 (@code{ebdb-record-person}) and organizations 
(@code{ebdb-record-organization}).
+Records can have ``roles'' at organizations @ref{Role Fields}.
 
 @node Record names
 @section Record names
@@ -355,14 +361,14 @@ class is labeled ``alt name''.
 @chapter Record Fields
 
 @menu
-* Inserting new fields::
-* Editing existing fields::
-* Deleting records and fields::
-* Field types::
+* Inserting New Fields::
+* Editing Existing Fields::
+* Deleting Records and Fields::
+* Field Types::
 @end menu
 
address@hidden Inserting new fields
address@hidden Inserting new fields
address@hidden Inserting New Fields
address@hidden Inserting New Fields
 
 @cindex Inserting new fields
 Pressing ``i'' (@code{ebdb-insert-field}) with point on a record will prompt
@@ -376,8 +382,8 @@ 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''.
 
address@hidden Editing existing fields
address@hidden Editing existing fields
address@hidden Editing Existing Fields
address@hidden Editing Existing Fields
 
 @cindex Editing fields
 Pressing ``e'' (@code{ebdb-edit-field}) with point on a field will allow you
@@ -388,16 +394,16 @@ 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.
 
address@hidden Deleting records and fields
address@hidden Deleting records and fields
address@hidden Deleting Records and Fields
address@hidden Deleting Records and Fields
 
 @cindex 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.
 
address@hidden Field types
address@hidden Field types
address@hidden Field Types
address@hidden Field Types
 
 :ID:       cb2190f4-f2e6-4082-9671-24e11e5cc0c6
 Fields can be classed in a few different categories.  Some are
@@ -431,6 +437,44 @@ of labels (for instance, anniversary fields may be labeled 
``birthday'',
 
 Loading secondary libraries may make more field types available.
 
address@hidden
+* Role Fields::
address@hidden menu
+
address@hidden Role Fields
address@hidden Role Fields
+
+One type of field worth mentioning in particular is the role field.
+EBDB records come in two types at present: person and organization.
+People have roles at organizations: jobs, volunteer positions, etc.
+People are also likely to have roles at more than one organization.
+
+When adding a role field to a record, you'll be prompted to choose the
+relevant organization role, prompted for a string label denoting
+eg.@: a job title, and prompted for a mail address that
+belongs only to this role field (ie.@: an institutional
+email address).  If the organization has a ``domain'' field type, and
+the person has an existing mail address that matches that domain,
+you'll be prompted to move that address to the role field.
+
+When viewing organization records, the role fields for all related
+person records are also displayed as part of the organization record.
+
+If a person's role at an organization later comes to an end, the role
+field can be deleted, or marked as ``defunct'', if record keeping is
+desired.  This can only be done using the customize-based editing
+interface (the ``E'' key on the role field).
+
+In fact, in addition to a mail field, role fields can contain an
+arbitrary number of other fields, representing metadata about the role
+(an employee number, employment start date, etc).  The author has yet
+to come up with a good interface for viewing and manipulating these
+extra fields, however, so the functionality remains hidden.
+Suggestions are very welcome.
+
+Manipulating role fields is generally a little clunky, at present.
+This will be addressed in future.
+
 @node MUA Interaction
 @chapter MUA Interaction
 
@@ -1248,7 +1292,7 @@ welcome, though less enthusiastically, are requests for 
new libraries.
 Internationalization libraries do not modify the database in any way,
 and can be safely unloaded.  They simply alter the way EBDB reads,
 parses and displays field values, and can also store extra information
-(eg.@:g for searching purposes) in a record's cache.
+(eg.@: for searching purposes) in a record's cache.
 Loading this library can (depending on country libraries' behavior)
 increase database load times, though it should not significantly
 affect search or display performance.



reply via email to

[Prev in Thread] Current Thread [Next in Thread]