[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[elpa] externals/ebdb 8ef0b9c 11/12: Document customization options for
|
From: |
Eric Abrahamsen |
|
Subject: |
[elpa] externals/ebdb 8ef0b9c 11/12: Document customization options for *EBDB* buffer display |
|
Date: |
Tue, 12 Jun 2018 22:06:12 -0400 (EDT) |
branch: externals/ebdb
commit 8ef0b9cc6debd79309c41376329b39864529781d
Author: Eric Abrahamsen <address@hidden>
Commit: Eric Abrahamsen <address@hidden>
Document customization options for *EBDB* buffer display
* ebdb-com.el (ebdb-default-oneline-include): Add a new option for the
oneline include. Delete a mysterious duplication of
ebdb-default-multiline-include.
* ebdb.org: Document some/most of the options.
---
ebdb-com.el | 20 ++--
ebdb.info | 304 ++++++++++++++++++++++++++++++++++++++++++------------------
ebdb.org | 123 +++++++++++++++++++++++-
ebdb.texi | 132 +++++++++++++++++++++++++-
4 files changed, 465 insertions(+), 114 deletions(-)
diff --git a/ebdb-com.el b/ebdb-com.el
index 7d4f43c..89a3649 100644
--- a/ebdb-com.el
+++ b/ebdb-com.el
@@ -441,19 +441,6 @@ ignored."
:type 'list
:group 'ebdb-record-display)
-(defcustom ebdb-default-multiline-include nil
- "A list of field types to include in multiline display.
-Valid list values include all field class names (ebdb-field-*),
-as well as the shortcuts 'mail, 'phone, 'address, 'notes, 'tags,
-and 'role, and the special shortcuts 'mail-primary,
-'mail-defunct, 'mail-not-defunct, 'role-defunct, and
-'role-not-defunct.
-
-If this option is set, *only* fields listed here will be
-displayed. Also see `ebdb-default-multiline-exclude'."
- :type 'list
- :group 'ebdb-record-display)
-
(defcustom ebdb-default-multiline-combine
'(ebdb-field-mail ebdb-field-phone)
"A list of field types to combine in the multiline display.
@@ -493,10 +480,15 @@ and 'role, and the special shortcuts 'mail-primary,
:type 'ebdb-formatter-ebdb-multiline
:group 'ebdb-record-display)
+(defcustom ebdb-default-oneline-include '(mail-primary)
+ "Fields to include in the default oneline view."
+ :type 'list
+ :group 'ebdb-record-display)
+
(defcustom ebdb-default-oneline-formatter
(make-instance 'ebdb-formatter-ebdb-oneline
:object-name "oneline formatter"
- :include '(mail-primary))
+ :include ebdb-default-oneline-include)
"The default oneline formatter of *EBDB* buffers."
:type 'ebdb-formatter-ebdb-oneline
:group 'ebdb-record-display)
diff --git a/ebdb.info b/ebdb.info
index 789df2b..4d10e9e 100644
--- a/ebdb.info
+++ b/ebdb.info
@@ -98,6 +98,7 @@ EBDB Buffers
* Searching::
* The Basics of ebdb-mode::
+* Customizing Record Display::
* Marking::
* Exporting/Formatting::
@@ -868,6 +869,7 @@ existing EBDB buffers.
* Searching::
* The Basics of ebdb-mode::
+* Customizing Record Display::
* Marking::
* Exporting/Formatting::
@@ -963,7 +965,7 @@ process happens _after_ the transform functions have run,
so there is a
possibility for unexpected search behavior.
-File: ebdb.info, Node: The Basics of ebdb-mode, Next: Marking, Prev:
Searching, Up: EBDB Buffers
+File: ebdb.info, Node: The Basics of ebdb-mode, Next: Customizing Record
Display, Prev: Searching, Up: EBDB Buffers
6.2 The Basics of ebdb-mode
===========================
@@ -1023,7 +1025,8 @@ keybindings apply.
use the record’s primary address.
‘t’
- Toggle between a multi-line and one-line display
+ Toggle between a multi-line and one-line display (see *note
+ Customizing Record Display: Customizing Record Display.)
(‘ebdb-toggle-records-format’).
‘T’
@@ -1079,9 +1082,106 @@ keybindings apply.
creation and field manipulation.
-File: ebdb.info, Node: Marking, Next: Exporting/Formatting, Prev: The
Basics of ebdb-mode, Up: EBDB Buffers
+File: ebdb.info, Node: Customizing Record Display, Next: Marking, Prev: The
Basics of ebdb-mode, Up: EBDB Buffers
+
+6.3 Customizing Record Display
+==============================
+
+The appearance of records in *EBDB* buffers can be customized. The
+display of records is controlled by objects called formatters, and two
+such objects are provided by default, one creating a multi-line display
+of records (the value of ‘ebdb-default-multiline-formatter’), and
+another creating a single-line display
+(‘ebdb-default-oneline-formatter’). Some customization options are
+provided to influence the behavior of these formatters (see the
+‘ebdb-record-display’ group), but users familiar with EIEIO objects can
+also manipulate formatter slot-values directly, override display
+methods, or write entirely new formatters. Any formatter that inherits
+from ‘ebdb-formatter-ebdb’ will be made available for cycling with the
+‘t’ key in *EBDB* buffers.
+
+ -- User Option: ebdb-dedicated-window
+ If non-nil, *EBDB* windows will be dedicated. Set to ‘ebdb’ to
+ make the window weakly dedicated, and to ‘t’ to make it strongly
+ dedicated.
-6.3 Marking
+ -- User Option: ebdb-join-atomic-windows
+ If non-nil, *EBDB* buffers will join atomic windows when popped up
+ from such a window.
+
+ -- User Option: ebdb-fill-field-values
+ If non-nil, long values will be filled in *EBDB* buffers.
+
+ The following options affect how various fields are displayed in
+*EBDB* buffers. The values of these options are always lists of field
+types as symbols: either the actual names of the field classes
+(‘ebdb-field-*’), or one of the following shortcuts:
+
+ • ‘mail’
+ • ‘phone’
+ • ‘address’
+ • ‘notes’
+ • ‘tags’
+ • ‘role’
+ • ‘mail-primary’
+ • ‘mail-defunct’
+ • ‘mail-not-defunct’
+ • ‘role-defunct’
+ • ‘role-not-defunct’
+
+ -- User Option: ebdb-default-multiline-include
+ A list of field types to include in the multiline formatter.
+
+ -- User Option: ebdb-default-multiline-exclude
+ A list of field types to exclude in the multiline formatter. If
+ the previous option is set, this one is ignored. Defaults to a
+ list of the “plumbing” field types such as uuid and creation date,
+ as well as defunct mail and role fields.
+
+ -- User Option: ebdb-default-multiline-combine
+ A list of field types to combine in the multiline formatter.
+ Multiple instances of “combined” field types are gathered onto a
+ single line, instead of one per line. This defaults to the mail
+ and phone fields.
+
+ -- User Option: ebdb-default-multiline-collapse
+ A list of field types to collapse in the multiline formatter. The
+ meaning of “collapse” may vary between formatters: in the *EBDB*
+ buffers it means that field values are truncated to a single line;
+ in LaTeX or HTML it might mean the values must be clicked to be
+ displayed completely. By default, address fields are collapsed.
+ In *EBDB* buffers, it’s still possible to see the complete field
+ value either in a tooltip when mousing over the field, or by
+ putting point on the field and hitting ‘w f’.
+
+ -- User Option: ebdb-default-oneline-include
+ A list of field types to include in the default oneline format.
+ The oneline formatters can handle the same options as the multiline
+ formatters, but because “include” is the only option that really
+ makes sense, it’s the only one that has its own customization
+ option.
+
+ There are also a number of faces that can be manipulated; see the
+‘ebdb-faces’ group.
+
+ Users who wish for more fine-grained control over output can override
+the formatting methods ‘ebdb-fmt-record’, ‘ebdb-fmt-field-label’, and
+‘ebdb-fmt-field’. It may be necessary to poke around in the source code
+to get things exactly right, but the general signature looks like:
+
+ (cl-defmethod ebdb-fmt-field ((_fmt ebdb-formatter-ebdb)
+ (field ebdb-field)
+ _style
+ (_record ebdb-record))
+ (ebdb-string field))
+
+ Possible values for the “style” argument are ‘nil’, ‘oneline’,
+‘compact’, and ‘collapse’.
+
+
+File: ebdb.info, Node: Marking, Next: Exporting/Formatting, Prev:
Customizing Record Display, Up: EBDB Buffers
+
+6.4 Marking
===========
Records can be marked and acted on in bulk. The ‘#’ key will toggle the
@@ -1092,7 +1192,7 @@ Many editing commands can act on multiple marked records.
File: ebdb.info, Node: Exporting/Formatting, Prev: Marking, Up: EBDB Buffers
-6.4 Exporting/Formatting
+6.5 Exporting/Formatting
========================
It is possible to export (referred to as “formatting”) records in
@@ -1151,8 +1251,9 @@ while the region contains the text “John Doe
<address@hidden>” will
find an existing contact or prompt to create a new one, and then display
that contact.
- Snarfing is a work in progress: at present, only mail addresses, URLs
-and nearby names are acted upon, and it often doesn’t work correctly.
+ Snarfing is a work in progress: at present, only mail addresses,
+phone numbers, URLs, and nearby names are acted upon, and it often
+doesn’t work correctly.
-- Command: ebdb-snarf &optional string start end recs
Extract record-related information from a piece of text. Find,
@@ -1496,7 +1597,7 @@ must not change the database: they may not edit records
or their fields.
-- Method: ebdb-init-field field record
Initialize FIELD against RECORD.
- -- Method: ebdb-delete-field field &optional record unload
+ -- Method: ebdb-delete-field field record &optional unload
Delete FIELD of record RECORD. If the optional argument UNLOAD is
non-nil, it means the record is only being unloaded
@@ -1921,9 +2022,9 @@ Index
* ; t: Interactive Commands.
(line 42)
* ?: The Basics of ebdb-mode.
- (line 102)
+ (line 103)
* ^: Searching. (line 55)
-* Article snarfing: Snarfing. (line 35)
+* Article snarfing: Snarfing. (line 36)
* Article snarfing <1>: Article snarfing. (line 6)
* auto-save of Database: The EBDB Database. (line 24)
* Automatic Rules: Noticing and Automatic Rules.
@@ -1941,7 +2042,7 @@ Index
(line 6)
* C-k <1>: The Basics of ebdb-mode.
(line 45)
-* Command: Snarfing. (line 39)
+* Command: Snarfing. (line 40)
* Creating a database: The EBDB Database. (line 11)
* Creating records: Creating Records. (line 6)
* Customizing search: Changing Search Behavior.
@@ -1982,23 +2083,39 @@ Index
(line 12)
* ebdb-cite-records: Citing Records. (line 11)
* ebdb-cite-records-ebdb: The Basics of ebdb-mode.
- (line 76)
+ (line 77)
* ebdb-clone-buffer: EBDB Buffers. (line 19)
* ebdb-copy-fields-as-kill: The Basics of ebdb-mode.
- (line 83)
+ (line 84)
* ebdb-copy-mail-as-kill: The Basics of ebdb-mode.
- (line 92)
+ (line 93)
* ebdb-copy-records-as-kill: The Basics of ebdb-mode.
- (line 88)
+ (line 89)
* ebdb-create-record: Creating Records. (line 6)
* ebdb-create-record <1>: The Basics of ebdb-mode.
(line 22)
* ebdb-create-record-extended: Creating Records. (line 14)
* ebdb-create-record-extended <1>: The Basics of ebdb-mode.
(line 26)
+* ebdb-dedicated-window: Customizing Record Display.
+ (line 19)
* ebdb-default-address-class: Hacking EBDB. (line 38)
* ebdb-default-mail-class: Hacking EBDB. (line 32)
+* ebdb-default-multiline-collapse: Customizing Record Display.
+ (line 63)
+* ebdb-default-multiline-combine: Customizing Record Display.
+ (line 57)
+* ebdb-default-multiline-exclude: Customizing Record Display.
+ (line 51)
+* ebdb-default-multiline-formatter: Customizing Record Display.
+ (line 6)
+* ebdb-default-multiline-include: Customizing Record Display.
+ (line 48)
* ebdb-default-notes-class: Hacking EBDB. (line 41)
+* ebdb-default-oneline-formatter: Customizing Record Display.
+ (line 6)
+* ebdb-default-oneline-include: Customizing Record Display.
+ (line 73)
* ebdb-default-phone-class: Hacking EBDB. (line 35)
* ebdb-default-record-class: Creating Records. (line 10)
* ebdb-default-record-class <1>: Hacking EBDB. (line 19)
@@ -2010,7 +2127,7 @@ Index
* ebdb-delete-record-or-field: Deleting Records and Fields.
(line 6)
* ebdb-display-records-completely: The Basics of ebdb-mode.
- (line 65)
+ (line 66)
* ebdb-edit-field: Editing Existing Fields.
(line 6)
* ebdb-edit-field <1>: The Basics of ebdb-mode.
@@ -2023,6 +2140,8 @@ Index
(line 41)
* ebdb-field-search: Custom Field Searching.
(line 24)
+* ebdb-fill-field-values: Customizing Record Display.
+ (line 28)
* ebdb-format-all-records: Exporting/Formatting.
(line 20)
* ebdb-format-to-tmp-buffer: Exporting/Formatting.
@@ -2030,7 +2149,7 @@ Index
* ebdb-hash-extra-predicates: Fast Lookups. (line 30)
* ebdb-hashtable: Fast Lookups. (line 10)
* ebdb-help: The Basics of ebdb-mode.
- (line 102)
+ (line 103)
* ebdb-i18n-countries: Internationalization.
(line 44)
* ebdb-i18n-countries-pref-scripts: Internationalization.
@@ -2038,7 +2157,7 @@ Index
* ebdb-ignore-header-list: Auto-Updating Records.
(line 44)
* ebdb-info: The Basics of ebdb-mode.
- (line 105)
+ (line 106)
* ebdb-init-field: Init and Delete Methods.
(line 12)
* ebdb-insert-field: Inserting New Fields.
@@ -2046,6 +2165,8 @@ Index
* ebdb-insert-field <1>: The Basics of ebdb-mode.
(line 30)
* ebdb-join-atomic-windows: Pop-up Buffers. (line 19)
+* ebdb-join-atomic-windows <1>: Customizing Record Display.
+ (line 24)
* ebdb-mail: The Basics of ebdb-mode.
(line 56)
* ebdb-make-buffer-name: Writing Integration For New MUAs.
@@ -2107,7 +2228,7 @@ Index
* ebdb-notice-record-hook: Noticing and Automatic Rules.
(line 11)
* ebdb-omit-records: The Basics of ebdb-mode.
- (line 72)
+ (line 73)
* ebdb-org-agenda-popup: Org Integration. (line 32)
* ebdb-popup-window: Writing Integration For New MUAs.
(line 60)
@@ -2119,10 +2240,10 @@ Index
(line 50)
* ebdb-record-self: Creating Records. (line 21)
* ebdb-reformat-records: The Basics of ebdb-mode.
- (line 69)
+ (line 70)
* ebdb-rename-buffer: EBDB Buffers. (line 23)
* ebdb-save: The Basics of ebdb-mode.
- (line 108)
+ (line 109)
* ebdb-save-on-exit: The EBDB Database. (line 78)
* ebdb-search-invert: Searching. (line 49)
* ebdb-search-pop: Searching. (line 55)
@@ -2130,9 +2251,9 @@ Index
(line 18)
* ebdb-search-transform-functions: Changing Search Behavior.
(line 16)
-* ebdb-snarf: Snarfing. (line 15)
-* ebdb-snarf-name-re: Snarfing. (line 30)
-* ebdb-snarf-routines: Snarfing. (line 25)
+* ebdb-snarf: Snarfing. (line 16)
+* ebdb-snarf-name-re: Snarfing. (line 31)
+* ebdb-snarf-routines: Snarfing. (line 26)
* ebdb-sources: The EBDB Database. (line 11)
* ebdb-toggle-records-format: The Basics of ebdb-mode.
(line 61)
@@ -2150,15 +2271,15 @@ Index
(line 50)
* Field actions <1>: Actions. (line 6)
* g: The Basics of ebdb-mode.
- (line 99)
+ (line 100)
* h: The Basics of ebdb-mode.
- (line 105)
+ (line 106)
* i: Inserting New Fields.
(line 6)
* i <1>: The Basics of ebdb-mode.
(line 30)
* I: The Basics of ebdb-mode.
- (line 76)
+ (line 77)
* Inserting new fields: Inserting New Fields.
(line 6)
* Internationalization: Internationalization.
@@ -2180,25 +2301,25 @@ Index
* N: The Basics of ebdb-mode.
(line 16)
* o: The Basics of ebdb-mode.
- (line 72)
+ (line 73)
* p: The Basics of ebdb-mode.
(line 13)
* P: The Basics of ebdb-mode.
(line 19)
* q: The Basics of ebdb-mode.
- (line 111)
+ (line 112)
* quit-window: The Basics of ebdb-mode.
- (line 111)
+ (line 112)
* r: The Basics of ebdb-mode.
- (line 69)
+ (line 70)
* read-only of Database: The EBDB Database. (line 20)
* record-class of Database: The EBDB Database. (line 37)
* RET: The Basics of ebdb-mode.
(line 50)
* revert-buffer: The Basics of ebdb-mode.
- (line 99)
+ (line 100)
* s: The Basics of ebdb-mode.
- (line 108)
+ (line 109)
* Saving the database: The EBDB Database. (line 78)
* Search history: Searching. (line 51)
* Searching the EBDB: Searching. (line 6)
@@ -2206,72 +2327,73 @@ Index
* t: The Basics of ebdb-mode.
(line 61)
* T: The Basics of ebdb-mode.
- (line 65)
+ (line 66)
* w f: The Basics of ebdb-mode.
- (line 83)
+ (line 84)
* w m: The Basics of ebdb-mode.
- (line 92)
+ (line 93)
* w r: The Basics of ebdb-mode.
- (line 88)
+ (line 89)
Tag Table:
Node: Top806
-Node: Getting Started2425
-Node: Migration from BBDB3080
-Node: Record Migration3291
-Node: Variables and Options4094
-Node: Migration from Org Contacts4580
-Node: The EBDB Database5340
-Node: Creating Records9328
-Node: Record classes10409
-Node: Record names10754
-Node: Record Fields11429
-Node: Inserting New Fields11673
-Node: Editing Existing Fields12469
-Node: Deleting Records and Fields13069
-Node: Field Types13465
-Node: Role fields15752
-Node: Tag field17440
-Node: Mail folder field18084
-Node: MUA Interaction18412
-Node: Loading MUA Code18936
-Node: Display and Updating19649
-Node: Pop-up Buffers20415
-Node: Auto-Updating Records21591
-Node: Noticing and Automatic Rules23991
-Node: Interactive Commands25324
-Node: EBDB and MUA summary buffers27799
-Node: Sender name display28285
-Node: Summary buffer marks29512
-Node: EBDB Buffers30691
-Node: Searching31873
-Node: Changing Search Behavior33535
-Node: The Basics of ebdb-mode34782
-Node: Marking38383
-Node: Exporting/Formatting38807
-Node: Completion39756
-Node: Snarfing40954
-Node: Internationalization42955
-Node: Diary Integration45654
-Node: Mail Aliases46519
-Node: vCard Support47233
-Node: Org Integration47732
-Node: Citing Records49630
-Node: Hacking EBDB50388
-Node: Field Classes52707
-Node: Init and Delete Methods55838
-Node: The Labeled Field Class57345
-Node: The Singleton Field Class58199
-Node: Actions58637
-Node: Custom Field Searching59309
-Node: Fast Lookups62176
-Node: Formatting in the EBDB Buffer63986
-Node: Writing Internationalization Libraries66062
-Node: Writing Integration For New MUAs70476
-Node: Article snarfing73923
-Node: Index74641
+Node: Getting Started2456
+Node: Migration from BBDB3111
+Node: Record Migration3322
+Node: Variables and Options4125
+Node: Migration from Org Contacts4611
+Node: The EBDB Database5371
+Node: Creating Records9359
+Node: Record classes10440
+Node: Record names10785
+Node: Record Fields11460
+Node: Inserting New Fields11704
+Node: Editing Existing Fields12500
+Node: Deleting Records and Fields13100
+Node: Field Types13496
+Node: Role fields15783
+Node: Tag field17471
+Node: Mail folder field18115
+Node: MUA Interaction18443
+Node: Loading MUA Code18967
+Node: Display and Updating19680
+Node: Pop-up Buffers20446
+Node: Auto-Updating Records21622
+Node: Noticing and Automatic Rules24022
+Node: Interactive Commands25355
+Node: EBDB and MUA summary buffers27830
+Node: Sender name display28316
+Node: Summary buffer marks29543
+Node: EBDB Buffers30722
+Node: Searching31935
+Node: Changing Search Behavior33597
+Node: The Basics of ebdb-mode34844
+Node: Customizing Record Display38537
+Node: Marking42857
+Node: Exporting/Formatting43284
+Node: Completion44233
+Node: Snarfing45431
+Node: Internationalization47448
+Node: Diary Integration50147
+Node: Mail Aliases51012
+Node: vCard Support51726
+Node: Org Integration52225
+Node: Citing Records54123
+Node: Hacking EBDB54881
+Node: Field Classes57200
+Node: Init and Delete Methods60331
+Node: The Labeled Field Class61838
+Node: The Singleton Field Class62692
+Node: Actions63130
+Node: Custom Field Searching63802
+Node: Fast Lookups66669
+Node: Formatting in the EBDB Buffer68479
+Node: Writing Internationalization Libraries70555
+Node: Writing Integration For New MUAs74969
+Node: Article snarfing78416
+Node: Index79134
End Tag Table
diff --git a/ebdb.org b/ebdb.org
index afaa69e..41fa931 100644
--- a/ebdb.org
+++ b/ebdb.org
@@ -913,8 +913,8 @@ keybindings apply.
#+KINDEX: t
#+FINDEX: ebdb-toggle-records-format
- Toggle between a multi-line and one-line display
- (~ebdb-toggle-records-format~).
+ Toggle between a multi-line and one-line display (see
[[id:20fc7a2a-55a9-43ef-9534-9e5887682a88][Customizing
+ Record Display]]) (~ebdb-toggle-records-format~).
- T ::
@@ -1003,6 +1003,120 @@ keybindings apply.
[[id:692cde31-73be-4faf-b436-7eae8a5d02d1][Creating Records]] and
[[id:4170bd36-64bf-44b4-87d0-29fbed968851][Record Fields]] for more on record
creation and
field manipulation.
+** Customizing Record Display
+:PROPERTIES:
+:ID: 20fc7a2a-55a9-43ef-9534-9e5887682a88
+:END:
+#+VINDEX: ebdb-default-multiline-formatter
+#+VINDEX: ebdb-default-oneline-formatter
+The appearance of records in {{{buf(EBDB)}}} buffers can be
+customized. The display of records is controlled by objects called
+formatters, and two such objects are provided by default, one creating
+a multi-line display of records (the value of
+~ebdb-default-multiline-formatter~), and another creating a
+single-line display (~ebdb-default-oneline-formatter~). Some
+customization options are provided to influence the behavior of these
+formatters (see the ~ebdb-record-display~ group), but users familiar
+with EIEIO objects can also manipulate formatter slot-values directly,
+override display methods, or write entirely new formatters. Any
+formatter that inherits from ~ebdb-formatter-ebdb~ will be made
+available for cycling with the {{{kbd(t)}}} key in {{{buf(EBDB)}}}
+buffers.
+
+#+attr_texinfo: :options ebdb-dedicated-window
+#+BEGIN_defopt
+If non-nil, {{{buf(EBDB)}}} windows will be dedicated. Set to ~ebdb~
+to make the window weakly dedicated, and to ~t~ to make it strongly
+dedicated.
+#+END_defopt
+
+#+attr_texinfo: :options ebdb-join-atomic-windows
+#+BEGIN_defopt
+If non-nil, {{{buf(EBDB)}}} buffers will join atomic windows when
+popped up from such a window.
+#+END_defopt
+
+#+attr_texinfo: :options ebdb-fill-field-values
+#+BEGIN_defopt
+If non-nil, long values will be filled in {{{buf(EBDB)}}} buffers.
+#+END_defopt
+
+The following options affect how various fields are displayed in
+{{{buf(EBDB)}}} buffers. The values of these options are always lists
+of field types as symbols: either the actual names of the field
+classes (~ebdb-field-*~), or one of the following shortcuts:
+
+- ~mail~
+- ~phone~
+- ~address~
+- ~notes~
+- ~tags~
+- ~role~
+- ~mail-primary~
+- ~mail-defunct~
+- ~mail-not-defunct~
+- ~role-defunct~
+- ~role-not-defunct~
+
+#+attr_texinfo: :options ebdb-default-multiline-include
+#+BEGIN_defopt
+A list of field types to include in the multiline formatter.
+#+END_defopt
+
+#+attr_texinfo: :options ebdb-default-multiline-exclude
+#+BEGIN_defopt
+A list of field types to exclude in the multiline formatter. If the
+previous option is set, this one is ignored. Defaults to a list of
+the "plumbing" field types such as uuid and creation date, as well as
+defunct mail and role fields.
+#+END_defopt
+
+#+attr_texinfo: :options ebdb-default-multiline-combine
+#+BEGIN_defopt
+A list of field types to combine in the multiline formatter. Multiple
+instances of "combined" field types are gathered onto a single line,
+instead of one per line. This defaults to the mail and phone fields.
+#+END_defopt
+
+#+attr_texinfo: :options ebdb-default-multiline-collapse
+#+BEGIN_defopt
+A list of field types to collapse in the multiline formatter. The
+meaning of "collapse" may vary between formatters: in the
+{{{buf(EBDB)}}} buffers it means that field values are truncated to a
+single line; in LaTeX or HTML it might mean the values must be clicked
+to be displayed completely. By default, address fields are collapsed.
+In {{{buf(EBDB)}}} buffers, it's still possible to see the complete
+field value either in a tooltip when mousing over the field, or by
+putting point on the field and hitting {{{kbd(w f)}}}.
+#+END_defopt
+
+#+attr_texinfo: :options ebdb-default-oneline-include
+#+BEGIN_defopt
+A list of field types to include in the default oneline format. The
+oneline formatters can handle the same options as the multiline
+formatters, but because "include" is the only option that really makes
+sense, it's the only one that has its own customization option.
+#+END_defopt
+
+There are also a number of faces that can be manipulated; see the
+~ebdb-faces~ group.
+
+Users who wish for more fine-grained control over output can override
+the formatting methods ~ebdb-fmt-record~, ~ebdb-fmt-field-label~, and
+~ebdb-fmt-field~. It may be necessary to poke around in the source
+code to get things exactly right, but the general signature looks
+like:
+
+#+BEGIN_SRC elisp
+ (cl-defmethod ebdb-fmt-field ((_fmt ebdb-formatter-ebdb)
+ (field ebdb-field)
+ _style
+ (_record ebdb-record))
+ (ebdb-string field))
+#+END_SRC
+
+Possible values for the "style" argument are ~nil~, ~oneline~,
+~compact~, and ~collapse~.
** Marking
:PROPERTIES:
@@ -1072,8 +1186,9 @@ information related to EBDB records from it. For
example, calling
<address@hidden>" will find an existing contact or prompt to create a
new one, and then display that contact.
-Snarfing is a work in progress: at present, only mail addresses, URLs
-and nearby names are acted upon, and it often doesn't work correctly.
+Snarfing is a work in progress: at present, only mail addresses, phone
+numbers, URLs, and nearby names are acted upon, and it often doesn't
+work correctly.
#+attr_texinfo: :options Command ebdb-snarf &optional string start end recs
#+BEGIN_deffn
diff --git a/ebdb.texi b/ebdb.texi
index 877a0f9..f8716f3 100644
--- a/ebdb.texi
+++ b/ebdb.texi
@@ -121,6 +121,7 @@ EBDB Buffers
* Searching::
* The Basics of ebdb-mode::
+* Customizing Record Display::
* Marking::
* Exporting/Formatting::
@@ -918,6 +919,7 @@ recreated next time the MUA requests another pop up.
@menu
* Searching::
* The Basics of ebdb-mode::
+* Customizing Record Display::
* Marking::
* Exporting/Formatting::
@end menu
@@ -1118,8 +1120,8 @@ use; otherwise use the record's primary address.
@item t
@kindex t
@findex ebdb-toggle-records-format
-Toggle between a multi-line and one-line display
-(@code{ebdb-toggle-records-format}).
+Toggle between a multi-line and one-line display (see @ref{Customizing Record
Display, , Customizing
+Record Display}) (@code{ebdb-toggle-records-format}).
@item T
@kindex T
@@ -1198,6 +1200,125 @@ Delete the *EBDB* window (@code{quit-window}).
@ref{Creating Records} and @ref{Record Fields} for more on record creation and
field manipulation.
address@hidden Customizing Record Display
address@hidden Customizing Record Display
+
address@hidden ebdb-default-multiline-formatter
address@hidden ebdb-default-oneline-formatter
+The appearance of records in *EBDB* buffers can be
+customized. The display of records is controlled by objects called
+formatters, and two such objects are provided by default, one creating
+a multi-line display of records (the value of
address@hidden), and another creating a
+single-line display (@code{ebdb-default-oneline-formatter}). Some
+customization options are provided to influence the behavior of these
+formatters (see the @code{ebdb-record-display} group), but users familiar
+with EIEIO objects can also manipulate formatter slot-values directly,
+override display methods, or write entirely new formatters. Any
+formatter that inherits from @code{ebdb-formatter-ebdb} will be made
+available for cycling with the @kbd{t} key in *EBDB*
+buffers.
+
address@hidden ebdb-dedicated-window
+If non-nil, *EBDB* windows will be dedicated. Set to @code{ebdb}
+to make the window weakly dedicated, and to @code{t} to make it strongly
+dedicated.
address@hidden defopt
+
address@hidden ebdb-join-atomic-windows
+If non-nil, *EBDB* buffers will join atomic windows when
+popped up from such a window.
address@hidden defopt
+
address@hidden ebdb-fill-field-values
+If non-nil, long values will be filled in *EBDB* buffers.
address@hidden defopt
+
+The following options affect how various fields are displayed in
+*EBDB* buffers. The values of these options are always lists
+of field types as symbols: either the actual names of the field
+classes (@code{ebdb-field-*}), or one of the following shortcuts:
+
address@hidden
address@hidden
address@hidden
address@hidden
address@hidden
address@hidden
address@hidden
address@hidden
address@hidden
address@hidden
address@hidden
address@hidden
address@hidden
address@hidden
address@hidden
address@hidden
address@hidden
address@hidden
address@hidden
address@hidden
address@hidden
address@hidden
address@hidden
address@hidden itemize
+
address@hidden ebdb-default-multiline-include
+A list of field types to include in the multiline formatter.
address@hidden defopt
+
address@hidden ebdb-default-multiline-exclude
+A list of field types to exclude in the multiline formatter. If the
+previous option is set, this one is ignored. Defaults to a list of
+the ``plumbing'' field types such as uuid and creation date, as well as
+defunct mail and role fields.
address@hidden defopt
+
address@hidden ebdb-default-multiline-combine
+A list of field types to combine in the multiline formatter. Multiple
+instances of ``combined'' field types are gathered onto a single line,
+instead of one per line. This defaults to the mail and phone fields.
address@hidden defopt
+
address@hidden ebdb-default-multiline-collapse
+A list of field types to collapse in the multiline formatter. The
+meaning of ``collapse'' may vary between formatters: in the
+*EBDB* buffers it means that field values are truncated to a
+single line; in @LaTeX{} or HTML it might mean the values must be clicked
+to be displayed completely. By default, address fields are collapsed.
+In *EBDB* buffers, it's still possible to see the complete
+field value either in a tooltip when mousing over the field, or by
+putting point on the field and hitting @kbd{w f}.
address@hidden defopt
+
address@hidden ebdb-default-oneline-include
+A list of field types to include in the default oneline format. The
+oneline formatters can handle the same options as the multiline
+formatters, but because ``include'' is the only option that really makes
+sense, it's the only one that has its own customization option.
address@hidden defopt
+
+There are also a number of faces that can be manipulated; see the
address@hidden group.
+
+Users who wish for more fine-grained control over output can override
+the formatting methods @code{ebdb-fmt-record}, @code{ebdb-fmt-field-label}, and
address@hidden It may be necessary to poke around in the source
+code to get things exactly right, but the general signature looks
+like:
+
address@hidden
+(cl-defmethod ebdb-fmt-field ((_fmt ebdb-formatter-ebdb)
+ (field ebdb-field)
+ _style
+ (_record ebdb-record))
+ (ebdb-string field))
address@hidden lisp
+
+Possible values for the ``style'' argument are @code{nil}, @code{oneline},
address@hidden, and @code{collapse}.
+
@node Marking
@section Marking
@@ -1270,8 +1391,9 @@ information related to EBDB records from it. For
example, calling
<j.doe@@email.com>'' will find an existing contact or prompt to create a
new one, and then display that contact.
-Snarfing is a work in progress: at present, only mail addresses, URLs
-and nearby names are acted upon, and it often doesn't work correctly.
+Snarfing is a work in progress: at present, only mail addresses, phone
+numbers, URLs, and nearby names are acted upon, and it often doesn't
+work correctly.
@deffn Command ebdb-snarf &optional string start end recs
Extract record-related information from a piece of text. Find,
@@ -1623,7 +1745,7 @@ their fields.
Initialize @var{field} against @var{record}.
@end deffn
address@hidden Method ebdb-delete-field field &optional record unload
address@hidden Method ebdb-delete-field field record &optional unload
Delete @var{field} of record @var{record}. If
the optional argument @var{unload} is non-nil, it means
the record is only being unloaded
- [elpa] externals/ebdb 365fa1c 04/12: Add nicknames to person record cache 'alt-names, (continued)
- [elpa] externals/ebdb 365fa1c 04/12: Add nicknames to person record cache 'alt-names, Eric Abrahamsen, 2018/06/12
- [elpa] externals/ebdb 9febf18 02/12: New command ebdb-save-ebdb, Eric Abrahamsen, 2018/06/12
- [elpa] externals/ebdb 91f0953 05/12: Let the typos begin!, Eric Abrahamsen, 2018/06/12
- [elpa] externals/ebdb b2b56f8 07/12: Fix to "add nicknames to person record cache", Eric Abrahamsen, 2018/06/12
- [elpa] externals/ebdb 60f8828 12/12: Bump and flush: 0.5.3, Eric Abrahamsen, 2018/06/12
- [elpa] externals/ebdb 140381f 09/12: Update README.org (#70), Eric Abrahamsen, 2018/06/12
- [elpa] externals/ebdb 49a2e8d 03/12: Make "record" argument to field init and delete non-optional, Eric Abrahamsen, 2018/06/12
- [elpa] externals/ebdb 5f00a46 10/12: Tweak default formatter settings, Eric Abrahamsen, 2018/06/12
- [elpa] externals/ebdb 7d20db4 06/12: Further improvements to snarfing, Eric Abrahamsen, 2018/06/12
- [elpa] externals/ebdb b89a009 08/12: Move defmethods beneath all classes used as specializers, Eric Abrahamsen, 2018/06/12
- [elpa] externals/ebdb 8ef0b9c 11/12: Document customization options for *EBDB* buffer display,
Eric Abrahamsen <=