[elpa] externals/ebdb bc3c712 332/350: Move "Writing Internationalization Libraries" in manual

[Eric Abrahamsen]

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

    Move "Writing Internationalization Libraries" in manual
    
    * ebdb.org (Writing Internationalization Libraries): Move it to the
      hacking section.
    * ebdb.info: etc
    * ebdb.texi: etc
---
 ebdb.info | 302 ++++++++++++++++++++++++++++++--------------------------------
 ebdb.org  | 186 +++++++++++++++++++-------------------
 ebdb.texi | 230 +++++++++++++++++++++++------------------------
 3 files changed, 353 insertions(+), 365 deletions(-)

diff --git a/ebdb.info b/ebdb.info
index 2b2c062..5553b90 100644
--- a/ebdb.info
+++ b/ebdb.info
@@ -108,10 +108,6 @@ Searching
 
 
 
-Internationalization
-
-* Writing Internationalization Libraries::
-
 
 
 
@@ -121,6 +117,7 @@ Internationalization
 Hacking EBDB
 
 * Field Classes::
+* Writing Internationalization Libraries::
 
 Field Classes
 
@@ -1190,108 +1187,6 @@ can (depending on country libraries’ behavior) increase 
database load
 times, though it should not significantly affect search or display
 performance.
 
-* Menu:
-
-* Writing Internationalization Libraries::
-
-
-File: ebdb.info,  Node: Writing Internationalization Libraries,  Up: 
Internationalization
-
-9.1 Writing Internationalization Libraries
-==========================================
-
-Writing new internationalization libraries involves using generic
-functions.  *note Generic Functions: (elisp)Generic%20Functions.  It
-will also require a bit of familiarity with EBDB’s internals.
-
-   Internationalization affects three different field types: addresses,
-phone numbers, and names.  It works by providing “i18n” versions of
-common methods for those three fields:
-
-Regular method      Internationalized method
------------------------------------------------
-ebdb-read           ebdb-read-i18n
-ebdb-parse          ebdb-parse-i18n
-ebdb-string         ebdb-string-i18n
-ebdb-init-field     ebdb-init-field-i18n
-ebdb-delete-field   ebdb-delete-field-i18n
-
-   When the “ebdb-i18n” library is loaded and the left-column
-(“vanilla”) versions of field methods are called, EBDB first checks to
-see if a valid “internationalized” (right-column) method exists.  If it
-does, that method is used instead of the vanilla one.
-
-   What is a “valid internationalized method”?  That depends on the
-field type.  Each field type uses a different key or “spec” to determine
-the nationality or locality of the field instance.
-
-   • Address fields use a three-character symbol derived from the ISO
-     316601 alpha 3 (https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3)
-     country codes.  These codes can be found in the variable
-     ‘ebdb-i18n-countries’.
-
-   • Phone fields use the phone number’s numerical country code as a
-     spec.  These codes can be found in the variable
-     ‘ebdb-i18n-phone-codes’.
-
-   • Name fields are keyed to the symbol representing the script used to
-     write them.  Specifically, the first character CHAR of the name is
-     tested in this way: (aref char-script-table CHAR), which returns a
-     symbol.
-
-   How are these “specs” used?  Each internationalized version of the
-above methods accepts the spec as an additional argument, which it is
-able to specialize on.  Every country-specific method should check the
-spec to see if it is relevant to that library.  If so, it handles the
-necessary behavior; if not, it passes by using ‘cl-call-next-method’.
-See the function signatures of each internationalized method to find how
-to handle the extra argument, called SPEC.
-
-   Here’s a concrete example:
-
-   Say we want to make sure all French phone numbers are represented by
-a string that looks like “+33 05 12 34 56 79”.  This is not how they are
-stored in the database, but this is how they should be represented to
-the user.  We need to override the ‘ebdb-string-i18n’ method for the
-phone field class.  This method takes two arguments – the field
-instance, and the country-code spec – and needs to specialize on both
-arguments.  The method signature will look like this:
-
-     (cl-defmethod ebdb-string-i18n ((phone ebdb-field-phone)
-                               (_cc (eql 33))))
-
-   See the manual on generic functions for details; suffice it to say
-that this method will only run when the first argument is an instance of
-the ‘ebdb-field-phone’ class (or a subclass), and the second argument is
-the number 33.
-
-   Now we know that this method will only run for French phone numbers,
-so we can format the number correctly:
-
-     (cl-defmethod ebdb-string-i18n ((phone ebdb-field-phone)
-                               (_cc (eql 33)))
-       (with-slots (area-code number extension) phone
-         (concat
-          "+33 "
-          (when area-code
-            (format "%02d" area-code))
-          (format "%s%s %s%s %s%s %s%s"
-            (split-string number "" t))
-          (when extension
-            (format "X%d" extension)))))
-
-   Again this only affects the display of numbers, not how they are
-stored in the database.
-
-   Note that, while phone numbers themselves are stored as strings (they
-do not represent a quantity, after all), the country and area codes are
-stored as numbers, precisely so that they can be specialized on using
-‘eql’.
-
-   See the signatures of the other internationalized methods for how to
-use them.  The symbol specs for country codes and script names can also
-be specialized on with the ‘eql’ specializer.
-
 
 File: ebdb.info,  Node: Diary Integration,  Next: Mail Aliases,  Prev: 
Internationalization,  Up: Top
 
@@ -1461,9 +1356,10 @@ existing objects.  This may be addressed in the future.
 * Menu:
 
 * Field Classes::
+* Writing Internationalization Libraries::
 
 
-File: ebdb.info,  Node: Field Classes,  Up: Hacking EBDB
+File: ebdb.info,  Node: Field Classes,  Next: Writing Internationalization 
Libraries,  Up: Hacking EBDB
 
 15.1 Field Classes
 ==================
@@ -1686,6 +1582,104 @@ quiet: the arguments are necessary for dispatch, but 
aren’t actually
 used in the body of the method.
 
 
+File: ebdb.info,  Node: Writing Internationalization Libraries,  Prev: Field 
Classes,  Up: Hacking EBDB
+
+15.2 Writing Internationalization Libraries
+===========================================
+
+Writing new internationalization libraries involves using generic
+functions.  *note Generic Functions: (elisp)Generic%20Functions.  It
+will also require a bit of familiarity with EBDB’s internals.
+
+   Internationalization affects three different field types: addresses,
+phone numbers, and names.  It works by providing “i18n” versions of
+common methods for those three fields:
+
+Regular method      Internationalized method
+-----------------------------------------------
+ebdb-read           ebdb-read-i18n
+ebdb-parse          ebdb-parse-i18n
+ebdb-string         ebdb-string-i18n
+ebdb-init-field     ebdb-init-field-i18n
+ebdb-delete-field   ebdb-delete-field-i18n
+
+   When the “ebdb-i18n” library is loaded and the left-column
+(“vanilla”) versions of field methods are called, EBDB first checks to
+see if a valid “internationalized” (right-column) method exists.  If it
+does, that method is used instead of the vanilla one.
+
+   What is a “valid internationalized method”?  That depends on the
+field type.  Each field type uses a different key or “spec” to determine
+the nationality or locality of the field instance.
+
+   • Address fields use a three-character symbol derived from the ISO
+     316601 alpha 3 (https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3)
+     country codes.  These codes can be found in the variable
+     ‘ebdb-i18n-countries’.
+
+   • Phone fields use the phone number’s numerical country code as a
+     spec.  These codes can be found in the variable
+     ‘ebdb-i18n-phone-codes’.
+
+   • Name fields are keyed to the symbol representing the script used to
+     write them.  Specifically, the first character CHAR of the name is
+     tested in this way: (aref char-script-table CHAR), which returns a
+     symbol.
+
+   How are these “specs” used?  Each internationalized version of the
+above methods accepts the spec as an additional argument, which it is
+able to specialize on.  Every country-specific method should check the
+spec to see if it is relevant to that library.  If so, it handles the
+necessary behavior; if not, it passes by using ‘cl-call-next-method’.
+See the function signatures of each internationalized method to find how
+to handle the extra argument, called SPEC.
+
+   Here’s a concrete example:
+
+   Say we want to make sure all French phone numbers are represented by
+a string that looks like “+33 05 12 34 56 79”.  This is not how they are
+stored in the database, but this is how they should be represented to
+the user.  We need to override the ‘ebdb-string-i18n’ method for the
+phone field class.  This method takes two arguments – the field
+instance, and the country-code spec – and needs to specialize on both
+arguments.  The method signature will look like this:
+
+     (cl-defmethod ebdb-string-i18n ((phone ebdb-field-phone)
+                               (_cc (eql 33))))
+
+   See the manual on generic functions for details; suffice it to say
+that this method will only run when the first argument is an instance of
+the ‘ebdb-field-phone’ class (or a subclass), and the second argument is
+the number 33.
+
+   Now we know that this method will only run for French phone numbers,
+so we can format the number correctly:
+
+     (cl-defmethod ebdb-string-i18n ((phone ebdb-field-phone)
+                               (_cc (eql 33)))
+       (with-slots (area-code number extension) phone
+         (concat
+          "+33 "
+          (when area-code
+            (format "%02d" area-code))
+          (format "%s%s %s%s %s%s %s%s"
+            (split-string number "" t))
+          (when extension
+            (format "X%d" extension)))))
+
+   Again this only affects the display of numbers, not how they are
+stored in the database.
+
+   Note that, while phone numbers themselves are stored as strings (they
+do not represent a quantity, after all), the country and area codes are
+stored as numbers, precisely so that they can be specialized on using
+‘eql’.
+
+   See the signatures of the other internationalized methods for how to
+use them.  The symbol specs for country codes and script names can also
+be specialized on with the ‘eql’ specializer.
+
+
 File: ebdb.info,  Node: Index,  Prev: Hacking EBDB,  Up: Top
 
 Index
@@ -1798,53 +1792,53 @@ Index
 
 Tag Table:
 Node: Top806
-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: Internationalization38932
-Node: Writing Internationalization Libraries40410
-Node: Diary Integration44698
-Node: Mail Aliases45564
-Node: vCard Support46273
-Node: Org Integration46772
-Node: Citing Records48346
-Node: Hacking EBDB49105
-Node: Field Classes51355
-Node: Init and Delete Methods54245
-Node: The Labeled Field Class55801
-Node: Actions56637
-Node: Custom Field Searching57302
-Node: Formatting in the EBDB Buffer59090
-Node: Index61089
+Node: Getting Started2225
+Node: Migration from BBDB2847
+Node: Record Migration3022
+Node: Variables and Options3559
+Node: The EBDB Database4045
+Node: Creating Records7201
+Node: Record classes8248
+Node: Record names8581
+Node: Record Fields9256
+Node: Inserting New Fields9500
+Node: Editing Existing Fields10296
+Node: Deleting Records and Fields10896
+Node: Field Types11292
+Node: Role Fields13137
+Node: MUA Interaction14828
+Node: Loading MUA Code15352
+Node: Display and Updating16065
+Node: Pop-up Buffers16834
+Node: Auto-Updating Records17699
+Node: Noticing and Automatic Rules20084
+Node: Interactive Commands21427
+Node: EBDB and MUA summary buffers23916
+Node: Sender name display24402
+Node: Summary buffer marks25690
+Node: EBDB Buffers26885
+Node: Searching28078
+Node: Changing Search Behavior29788
+Node: The Basics of ebdb-mode31038
+Node: Marking34402
+Node: Exporting/Formatting34830
+Node: Completion35789
+Node: Snarfing36930
+Node: Internationalization38909
+Node: Diary Integration40334
+Node: Mail Aliases41200
+Node: vCard Support41909
+Node: Org Integration42408
+Node: Citing Records43982
+Node: Hacking EBDB44741
+Node: Field Classes47034
+Node: Init and Delete Methods49971
+Node: The Labeled Field Class51527
+Node: Actions52363
+Node: Custom Field Searching53028
+Node: Formatting in the EBDB Buffer54816
+Node: Writing Internationalization Libraries56815
+Node: Index61119
 
 End Tag Table
 
diff --git a/ebdb.org b/ebdb.org
index 47ab7fa..62ae649 100644
--- a/ebdb.org
+++ b/ebdb.org
@@ -902,99 +902,6 @@ parses and displays field values, and can also store extra 
information
 Loading this library can (depending on country libraries' behavior)
 increase database load times, though it should not significantly
 affect search or display performance.
-** Writing Internationalization Libraries
-Writing new internationalization libraries involves using generic
-functions. [[info:elisp#Generic%20Functions][Generic Functions]].  It will 
also require a bit of
-familiarity with EBDB's internals.
-
-Internationalization affects three different field types: addresses,
-phone numbers, and names.  It works by providing "i18n" versions of
-common methods for those three fields:
-
-| Regular method    | Internationalized method |
-|-------------------+--------------------------|
-| ebdb-read         | ebdb-read-i18n           |
-| ebdb-parse        | ebdb-parse-i18n          |
-| ebdb-string       | ebdb-string-i18n         |
-| ebdb-init-field   | ebdb-init-field-i18n     |
-| ebdb-delete-field | ebdb-delete-field-i18n   |
-
-When the "ebdb-i18n" library is loaded and the left-column ("vanilla")
-versions of field methods are called, EBDB first checks to see if a
-valid "internationalized" (right-column) method exists.  If it does,
-that method is used instead of the vanilla one.
-
-What is a "valid internationalized method"?  That depends on the field
-type.  Each field type uses a different key or "spec" to determine the
-nationality or locality of the field instance.
-
-- Address fields use a three-character symbol derived from the 
[[https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3][ISO
-  316601 alpha 3]] country codes.  These codes can be found in the
-  variable ~ebdb-i18n-countries~.
-- Phone fields use the phone number's numerical country code as a
-  spec.  These codes can be found in the variable
-  ~ebdb-i18n-phone-codes~.
-- Name fields are keyed to the symbol representing the script used to
-  write them. Specifically, the first character CHAR of the name is
-  tested in this way: =(aref char-script-table CHAR)=, which returns a
-  symbol.
-
-How are these "specs" used?  Each internationalized version of the
-above methods accepts the spec as an additional argument, which it is
-able to specialize on.  Every country-specific method should check the
-spec to see if it is relevant to that library. If so, it handles the
-necessary behavior; if not, it passes by using ~cl-call-next-method~.
-See the function signatures of each internationalized method to find
-how to handle the extra argument, called SPEC.
-
-Here's a concrete example:
-
-Say we want to make sure all French phone numbers are represented by a
-string that looks like "+33 05 12 34 56 79".  This is not how they are
-stored in the database, but this is how they should be represented to
-the user.  We need to override the ~ebdb-string-i18n~ method for the
-phone field class.  This method takes two arguments -- the field
-instance, and the country-code spec -- and needs to specialize on both
-arguments.  The method signature will look like this:
-
-#+BEGIN_SRC emacs-lisp
-  (cl-defmethod ebdb-string-i18n ((phone ebdb-field-phone)
-                                  (_cc (eql 33))))
-#+END_SRC
-
-See the manual on generic functions for details; suffice it to say
-that this method will only run when the first argument is an instance
-of the ~ebdb-field-phone~ class (or a subclass), and the second
-argument is the number 33.
-
-Now we know that this method will only run for French phone numbers,
-so we can format the number correctly:
-
-#+BEGIN_SRC emacs-lisp
-  (cl-defmethod ebdb-string-i18n ((phone ebdb-field-phone)
-                                  (_cc (eql 33)))
-    (with-slots (area-code number extension) phone
-      (concat
-       "+33 "
-       (when area-code
-         (format "%02d" area-code))
-       (format "%s%s %s%s %s%s %s%s"
-               (split-string number "" t))
-       (when extension
-         (format "X%d" extension)))))
-#+END_SRC
-
-Again this only affects the display of numbers, not how they are
-stored in the database.
-
-Note that, while phone numbers themselves are stored as strings (they
-do not represent a quantity, after all), the country and area codes
-are stored as numbers, precisely so that they can be specialized on
-using ~eql~.
-
-See the signatures of the other internationalized methods for how to
-use them.  The symbol specs for country codes and script names can
-also be specialized on with the ~eql~ specializer.
 * Diary Integration
 #+CINDEX: Diary integration
 Some EBDB fields hold dates or anniversaries (most notably the
@@ -1319,6 +1226,99 @@ The leading underscores on parameters are there to keep 
the compiler
 quiet: the arguments are necessary for dispatch, but aren't actually
 used in the body of the method.
 
+** Writing Internationalization Libraries
+Writing new internationalization libraries involves using generic
+functions. [[info:elisp#Generic%20Functions][Generic Functions]].  It will 
also require a bit of
+familiarity with EBDB's internals.
+
+Internationalization affects three different field types: addresses,
+phone numbers, and names.  It works by providing "i18n" versions of
+common methods for those three fields:
+
+| Regular method    | Internationalized method |
+|-------------------+--------------------------|
+| ebdb-read         | ebdb-read-i18n           |
+| ebdb-parse        | ebdb-parse-i18n          |
+| ebdb-string       | ebdb-string-i18n         |
+| ebdb-init-field   | ebdb-init-field-i18n     |
+| ebdb-delete-field | ebdb-delete-field-i18n   |
+
+When the "ebdb-i18n" library is loaded and the left-column ("vanilla")
+versions of field methods are called, EBDB first checks to see if a
+valid "internationalized" (right-column) method exists.  If it does,
+that method is used instead of the vanilla one.
+
+What is a "valid internationalized method"?  That depends on the field
+type.  Each field type uses a different key or "spec" to determine the
+nationality or locality of the field instance.
+
+- Address fields use a three-character symbol derived from the 
[[https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3][ISO
+  316601 alpha 3]] country codes.  These codes can be found in the
+  variable ~ebdb-i18n-countries~.
+- Phone fields use the phone number's numerical country code as a
+  spec.  These codes can be found in the variable
+  ~ebdb-i18n-phone-codes~.
+- Name fields are keyed to the symbol representing the script used to
+  write them. Specifically, the first character CHAR of the name is
+  tested in this way: =(aref char-script-table CHAR)=, which returns a
+  symbol.
+
+How are these "specs" used?  Each internationalized version of the
+above methods accepts the spec as an additional argument, which it is
+able to specialize on.  Every country-specific method should check the
+spec to see if it is relevant to that library. If so, it handles the
+necessary behavior; if not, it passes by using ~cl-call-next-method~.
+See the function signatures of each internationalized method to find
+how to handle the extra argument, called SPEC.
+
+Here's a concrete example:
+
+Say we want to make sure all French phone numbers are represented by a
+string that looks like "+33 05 12 34 56 79".  This is not how they are
+stored in the database, but this is how they should be represented to
+the user.  We need to override the ~ebdb-string-i18n~ method for the
+phone field class.  This method takes two arguments -- the field
+instance, and the country-code spec -- and needs to specialize on both
+arguments.  The method signature will look like this:
+
+#+BEGIN_SRC emacs-lisp
+  (cl-defmethod ebdb-string-i18n ((phone ebdb-field-phone)
+                                  (_cc (eql 33))))
+#+END_SRC
+
+See the manual on generic functions for details; suffice it to say
+that this method will only run when the first argument is an instance
+of the ~ebdb-field-phone~ class (or a subclass), and the second
+argument is the number 33.
+
+Now we know that this method will only run for French phone numbers,
+so we can format the number correctly:
+
+#+BEGIN_SRC emacs-lisp
+  (cl-defmethod ebdb-string-i18n ((phone ebdb-field-phone)
+                                  (_cc (eql 33)))
+    (with-slots (area-code number extension) phone
+      (concat
+       "+33 "
+       (when area-code
+         (format "%02d" area-code))
+       (format "%s%s %s%s %s%s %s%s"
+               (split-string number "" t))
+       (when extension
+         (format "X%d" extension)))))
+#+END_SRC
+
+Again this only affects the display of numbers, not how they are
+stored in the database.
+
+Note that, while phone numbers themselves are stored as strings (they
+do not represent a quantity, after all), the country and area codes
+are stored as numbers, precisely so that they can be specialized on
+using ~eql~.
+
+See the signatures of the other internationalized methods for how to
+use them.  The symbol specs for country codes and script names can
+also be specialized on with the ~eql~ specializer.
 * Index
 :PROPERTIES:
 :INDEX:    cp
diff --git a/ebdb.texi b/ebdb.texi
index 521ff39..5ea0bd6 100644
--- a/ebdb.texi
+++ b/ebdb.texi
@@ -129,10 +129,6 @@ Searching
 
 
 
-Internationalization
-
-* Writing Internationalization Libraries::
-
 
 
 
@@ -142,6 +138,7 @@ Internationalization
 Hacking EBDB
 
 * Field Classes::
+* Writing Internationalization Libraries::
 
 Field Classes
 
@@ -1298,120 +1295,6 @@ Loading this library can (depending on country 
libraries' behavior)
 increase database load times, though it should not significantly
 affect search or display performance.
 
address@hidden
-* Writing Internationalization Libraries::
address@hidden menu
-
address@hidden Writing Internationalization Libraries
address@hidden Writing Internationalization Libraries
-
-Writing new internationalization libraries involves using generic
-functions. @ref{Generic%20Functions,Generic Functions,,elisp,}.  It will also 
require a bit of
-familiarity with EBDB's internals.
-
-Internationalization affects three different field types: addresses,
-phone numbers, and names.  It works by providing ``i18n'' versions of
-common methods for those three fields:
-
address@hidden {aaaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaa}
address@hidden Regular method
address@hidden Internationalized method
address@hidden ebdb-read
address@hidden ebdb-read-i18n
address@hidden ebdb-parse
address@hidden ebdb-parse-i18n
address@hidden ebdb-string
address@hidden ebdb-string-i18n
address@hidden ebdb-init-field
address@hidden ebdb-init-field-i18n
address@hidden ebdb-delete-field
address@hidden ebdb-delete-field-i18n
address@hidden multitable
-
-When the ``ebdb-i18n'' library is loaded and the left-column (``vanilla'')
-versions of field methods are called, EBDB first checks to see if a
-valid ``internationalized'' (right-column) method exists.  If it does,
-that method is used instead of the vanilla one.
-
-What is a ``valid internationalized method''?  That depends on the field
-type.  Each field type uses a different key or ``spec'' to determine the
-nationality or locality of the field instance.
-
address@hidden
address@hidden
-Address fields use a three-character symbol derived from the 
@uref{https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3, ISO
-316601 alpha 3} country codes.  These codes can be found in the
-variable @code{ebdb-i18n-countries}.
-
address@hidden
-Phone fields use the phone number's numerical country code as a
-spec.  These codes can be found in the variable
address@hidden
-
address@hidden
-Name fields are keyed to the symbol representing the script used to
-write them. Specifically, the first character CHAR of the name is
-tested in this way: @verb{~(aref char-script-table CHAR)~}, which returns a
-symbol.
address@hidden itemize
-
-How are these ``specs'' used?  Each internationalized version of the
-above methods accepts the spec as an additional argument, which it is
-able to specialize on.  Every country-specific method should check the
-spec to see if it is relevant to that library. If so, it handles the
-necessary behavior; if not, it passes by using @code{cl-call-next-method}.
-See the function signatures of each internationalized method to find
-how to handle the extra argument, called SPEC.
-
-Here's a concrete example:
-
-Say we want to make sure all French phone numbers are represented by a
-string that looks like ``+33 05 12 34 56 79''.  This is not how they are
-stored in the database, but this is how they should be represented to
-the user.  We need to override the @code{ebdb-string-i18n} method for the
-phone field class.  This method takes two arguments -- the field
-instance, and the country-code spec -- and needs to specialize on both
-arguments.  The method signature will look like this:
-
address@hidden
-(cl-defmethod ebdb-string-i18n ((phone ebdb-field-phone)
-                               (_cc (eql 33))))
address@hidden lisp
-
-See the manual on generic functions for details; suffice it to say
-that this method will only run when the first argument is an instance
-of the @code{ebdb-field-phone} class (or a subclass), and the second
-argument is the number 33.
-
-Now we know that this method will only run for French phone numbers,
-so we can format the number correctly:
-
address@hidden
-(cl-defmethod ebdb-string-i18n ((phone ebdb-field-phone)
-                               (_cc (eql 33)))
-  (with-slots (area-code number extension) phone
-    (concat
-     "+33 "
-     (when area-code
-       (format "%02d" area-code))
-     (format "%s%s %s%s %s%s %s%s"
-            (split-string number "" t))
-     (when extension
-       (format "X%d" extension)))))
address@hidden lisp
-
-Again this only affects the display of numbers, not how they are
-stored in the database.
-
-Note that, while phone numbers themselves are stored as strings (they
-do not represent a quantity, after all), the country and area codes
-are stored as numbers, precisely so that they can be specialized on
-using @code{eql}.
-
-See the signatures of the other internationalized methods for how to
-use them.  The symbol specs for country codes and script names can
-also be specialized on with the @code{eql} specializer.
-
 @node Diary Integration
 @chapter Diary Integration
 
@@ -1577,6 +1460,7 @@ existing objects.  This may be addressed in the future.
 
 @menu
 * Field Classes::
+* Writing Internationalization Libraries::
 @end menu
 
 @node Field Classes
@@ -1805,6 +1689,116 @@ The leading underscores on parameters are there to keep 
the compiler
 quiet: the arguments are necessary for dispatch, but aren't actually
 used in the body of the method.
 
address@hidden Writing Internationalization Libraries
address@hidden Writing Internationalization Libraries
+
+Writing new internationalization libraries involves using generic
+functions. @ref{Generic%20Functions,Generic Functions,,elisp,}.  It will also 
require a bit of
+familiarity with EBDB's internals.
+
+Internationalization affects three different field types: addresses,
+phone numbers, and names.  It works by providing ``i18n'' versions of
+common methods for those three fields:
+
address@hidden {aaaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaa}
address@hidden Regular method
address@hidden Internationalized method
address@hidden ebdb-read
address@hidden ebdb-read-i18n
address@hidden ebdb-parse
address@hidden ebdb-parse-i18n
address@hidden ebdb-string
address@hidden ebdb-string-i18n
address@hidden ebdb-init-field
address@hidden ebdb-init-field-i18n
address@hidden ebdb-delete-field
address@hidden ebdb-delete-field-i18n
address@hidden multitable
+
+When the ``ebdb-i18n'' library is loaded and the left-column (``vanilla'')
+versions of field methods are called, EBDB first checks to see if a
+valid ``internationalized'' (right-column) method exists.  If it does,
+that method is used instead of the vanilla one.
+
+What is a ``valid internationalized method''?  That depends on the field
+type.  Each field type uses a different key or ``spec'' to determine the
+nationality or locality of the field instance.
+
address@hidden
address@hidden
+Address fields use a three-character symbol derived from the 
@uref{https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3, ISO
+316601 alpha 3} country codes.  These codes can be found in the
+variable @code{ebdb-i18n-countries}.
+
address@hidden
+Phone fields use the phone number's numerical country code as a
+spec.  These codes can be found in the variable
address@hidden
+
address@hidden
+Name fields are keyed to the symbol representing the script used to
+write them. Specifically, the first character CHAR of the name is
+tested in this way: @verb{~(aref char-script-table CHAR)~}, which returns a
+symbol.
address@hidden itemize
+
+How are these ``specs'' used?  Each internationalized version of the
+above methods accepts the spec as an additional argument, which it is
+able to specialize on.  Every country-specific method should check the
+spec to see if it is relevant to that library. If so, it handles the
+necessary behavior; if not, it passes by using @code{cl-call-next-method}.
+See the function signatures of each internationalized method to find
+how to handle the extra argument, called SPEC.
+
+Here's a concrete example:
+
+Say we want to make sure all French phone numbers are represented by a
+string that looks like ``+33 05 12 34 56 79''.  This is not how they are
+stored in the database, but this is how they should be represented to
+the user.  We need to override the @code{ebdb-string-i18n} method for the
+phone field class.  This method takes two arguments -- the field
+instance, and the country-code spec -- and needs to specialize on both
+arguments.  The method signature will look like this:
+
address@hidden
+(cl-defmethod ebdb-string-i18n ((phone ebdb-field-phone)
+                               (_cc (eql 33))))
address@hidden lisp
+
+See the manual on generic functions for details; suffice it to say
+that this method will only run when the first argument is an instance
+of the @code{ebdb-field-phone} class (or a subclass), and the second
+argument is the number 33.
+
+Now we know that this method will only run for French phone numbers,
+so we can format the number correctly:
+
address@hidden
+(cl-defmethod ebdb-string-i18n ((phone ebdb-field-phone)
+                               (_cc (eql 33)))
+  (with-slots (area-code number extension) phone
+    (concat
+     "+33 "
+     (when area-code
+       (format "%02d" area-code))
+     (format "%s%s %s%s %s%s %s%s"
+            (split-string number "" t))
+     (when extension
+       (format "X%d" extension)))))
address@hidden lisp
+
+Again this only affects the display of numbers, not how they are
+stored in the database.
+
+Note that, while phone numbers themselves are stored as strings (they
+do not represent a quantity, after all), the country and area codes
+are stored as numbers, precisely so that they can be specialized on
+using @code{eql}.
+
+See the signatures of the other internationalized methods for how to
+use them.  The symbol specs for country codes and script names can
+also be specialized on with the @code{eql} specializer.
+
 @node Index
 @unnumbered Index