; Improve doc strings of Ethiopic support functions and variables

* lisp/language/ethio-util.el (ethio-primary-language)
(ethio-secondary-language, ethio-use-colon-for-colon)
(ethio-use-three-dot-question, ethio-quote-vowel-always)
(ethio-W-sixth-always, ethio-sera-to-fidel-buffer)
(ethio-sera-to-fidel-region, ethio-sera-to-fidel-marker)
(ethio-fidel-to-sera-buffer, ethio-fidel-to-sera-region)
(ethio-fidel-to-sera-marker, ethio-get-consonant)
(ethio-fidel-to-tex-buffer, ethio-tex-to-fidel-buffer)
(ethio-fidel-to-java-buffer, ethio-java-to-fidel-buffer)
(ethio-find-file, ethio-write-file, ethio-gemination)
("ethiopic-sera"): Doc fixes.

1 files changed, 68 insertions, 17 deletions

diff --git a/lisp/language/ethio-util.el b/lisp/language/ethio-util.el
index 3744b7b24f9..5b4252d779c 100644
--- a/lisp/language/ethio-util.el
+++ b/lisp/language/ethio-util.el
@@ -112,6 +112,8 @@
 
 (defcustom ethio-primary-language 'tigrigna
   "Symbol that defines the primary language in SERA --> FIDEL conversion.
+FIDEL is the Amharic alphabet; SERA (System for Ethiopic Representation
+in ASCII) is the Latin representation of Ethiopic script.
 The value should be one of: `tigrigna', `amharic' or `english'."
   :version "28.1"
   :type '(choice (const :tag "Tigrigna" tigrigna)
@@ -120,6 +122,8 @@ The value should be one of: `tigrigna', `amharic' or `english'."
 
 (defcustom ethio-secondary-language 'english
   "Symbol that defines the secondary language in SERA --> FIDEL conversion.
+FIDEL is the Amharic alphabet; SERA (System for Ethiopic Representation
+in ASCII) is the Latin representation of Ethiopic script.
 The value should be one of: `tigrigna', `amharic' or `english'."
   :version "28.1"
   :type '(choice (const :tag "Tigrigna" tigrigna)
@@ -130,7 +134,9 @@ The value should be one of: `tigrigna', `amharic' or `english'."
   "Non-nil means associate ASCII colon with Ethiopic colon.
 If nil, associate ASCII colon with Ethiopic word separator, i.e., two
 vertically stacked dots.  All SERA <--> FIDEL converters refer this
-variable."
+variable.
+FIDEL is the Amharic alphabet; SERA (System for Ethiopic Representation
+in ASCII) is the Latin representation of Ethiopic script."
   :version "28.1"
   :type 'boolean)
 
@@ -138,7 +144,9 @@ variable."
   "If non-nil, associate ASCII question mark with Ethiopic question mark.
 The Ethiopic old style question mark is three vertically stacked dots.
 If nil, associate ASCII question mark with Ethiopic stylized question
-mark.  All SERA <--> FIDEL converters refer this variable."
+mark.  All SERA <--> FIDEL converters refer this variable.
+FIDEL is the Amharic alphabet; SERA (System for Ethiopic Representation
+in ASCII) is the Latin representation of Ethiopic script."
   :version "28.1"
   :type 'boolean)
 
@@ -147,13 +155,17 @@ mark.  All SERA <--> FIDEL converters refer this variable."
 This happens in FIDEL --> SERA conversions.  Isolated vowels at
 word beginning do not get an apostrophe put before them.
 If nil, put an apostrophe only between a 6th-form consonant and an
-isolated vowel."
+isolated vowel.
+FIDEL is the Amharic alphabet; SERA (System for Ethiopic Representation
+in ASCII) is the Latin representation of Ethiopic script."
   :version "28.1"
   :type 'boolean)
 
 (defcustom ethio-W-sixth-always nil
   "Non-nil means convert the Wu-form of a 12-form consonant to \"W'\".
-This is instead of \"Wu\" in FIDEL --> SERA conversion."
+This is instead of \"Wu\" in FIDEL --> SERA conversion.
+FIDEL is the Amharic alphabet; SERA (System for Ethiopic Representation
+in ASCII) is the Latin representation of Ethiopic script."
   :version "28.1"
   :type 'boolean)
 
@@ -223,6 +235,8 @@ If nil, use uppercases."
 (defun ethio-sera-to-fidel-buffer (&optional secondary force)
   "Convert the current buffer from SERA to FIDEL.
 
+FIDEL is the Amharic alphabet; SERA (System for Ethiopic Representation
+in ASCII) is the Latin representation of Ethiopic script.
 The variable `ethio-primary-language' specifies the primary
 language and `ethio-secondary-language' specifies the secondary.
 
@@ -248,6 +262,8 @@ See also the descriptions of the variables
 (defun ethio-sera-to-fidel-region (begin end &optional secondary force)
   "Convert the characters in region from SERA to FIDEL.
 
+FIDEL is the Amharic alphabet; SERA (System for Ethiopic Representation
+in ASCII) is the Latin representation of Ethiopic script.
 The variable `ethio-primary-language' specifies the primary
 language and `ethio-secondary-language' specifies the secondary.
 
@@ -503,7 +519,9 @@ changing anything."
 
 ;;;###autoload
 (defun ethio-sera-to-fidel-marker (&optional force)
-  "Convert the regions surrounded by \"<sera>\" and \"</sera>\" from SERA to FIDEL.
+  "Convert regions surrounded by \"<sera>\" and \"</sera>\" from SERA to FIDEL.
+FIDEL is the Amharic alphabet; SERA (System for Ethiopic Representation
+in ASCII) is the Latin representation of Ethiopic script.
 Assume that each region begins with `ethio-primary-language'.
 The markers \"<sera>\" and \"</sera>\" themselves are not deleted."
   (interactive "P")
@@ -535,7 +553,9 @@ The markers \"<sera>\" and \"</sera>\" themselves are not deleted."
 
 ;;;###autoload
 (defun ethio-fidel-to-sera-buffer (&optional secondary force)
-  "Replace all the FIDEL characters in the current buffer to the SERA format.
+  "Convert all the FIDEL characters in the current buffer to the SERA format.
+FIDEL is the Amharic alphabet; SERA (System for Ethiopic Representation
+in ASCII) is the Latin representation of Ethiopic script.
 The variable `ethio-primary-language' specifies the primary
 language and `ethio-secondary-language' specifies the secondary.
 
@@ -555,8 +575,10 @@ See also the descriptions of the variables
 
 ;;;###autoload
 (defun ethio-fidel-to-sera-region (begin end &optional secondary force)
-  "Replace all the FIDEL characters in the region to the SERA format.
+  "Convert all the FIDEL characters in the region to the SERA format.
 
+FIDEL is the Amharic alphabet; SERA (System for Ethiopic Representation
+in ASCII) is the Latin representation of Ethiopic script.
 The variable `ethio-primary-language' specifies the primary
 language and `ethio-secondary-language' specifies the secondary.
 
@@ -674,6 +696,8 @@ See also the descriptions of the variables
 ;;;###autoload
 (defun ethio-fidel-to-sera-marker (&optional force)
   "Convert the regions surrounded by \"<sera>\" and \"</sera>\" from FIDEL to SERA.
+FIDEL is the Amharic alphabet; SERA (System for Ethiopic Representation
+in ASCII) is the Latin representation of Ethiopic script.
 The markers \"<sera>\" and \"</sera>\" themselves are not deleted."
 
   (interactive "P")
@@ -698,7 +722,8 @@ The markers \"<sera>\" and \"</sera>\" themselves are not deleted."
 
 ;;;###autoload
 (defun ethio-modify-vowel nil
-  "Modify the vowel of the FIDEL that is under the cursor."
+  "Modify the vowel of the FIDEL that is under the cursor.
+FIDEL is the Amharic/Ethiopic alphabet."
   (interactive)
   (ethio-adjust-robin)
   (let ((consonant (ethio-get-consonant (following-char)))
@@ -715,7 +740,9 @@ The markers \"<sera>\" and \"</sera>\" themselves are not deleted."
 	  (robin-convert-region (point-min) (point-max) "ethiopic-sera"))))))
 
 (defun ethio-get-consonant (ch)
-  "Return the consonant part of CH's SERA spelling in ethiopic-sera."
+  "Return the consonant part of CH's SERA spelling in ethiopic-sera.
+SERA (System for Ethiopic Representation in ASCII) is the Latin
+representation of Ethiopic script."
   (let ((sera (get-char-code-property ch 'ethiopic-sera)))
     (cond
      ((null sera) nil)
@@ -820,7 +847,8 @@ The 2nd and 3rd arguments BEGIN and END specify the region."
 
 ;;;###autoload
 (defun ethio-fidel-to-tex-buffer nil
-  "Convert each fidel characters in the current buffer into a fidel-tex command."
+  "Convert each FIDEL characters in the current buffer into a fidel-tex command.
+FIDEL is the Amharic/Ethiopic alphabet."
   (interactive)
   (let ((buffer-read-only nil)
 	comp)
@@ -867,7 +895,8 @@ The 2nd and 3rd arguments BEGIN and END specify the region."
 
 ;;;###autoload
 (defun ethio-tex-to-fidel-buffer ()
-  "Convert fidel-tex commands in the current buffer into fidel chars."
+  "Convert fidel-tex commands in the current buffer into FIDEL chars.
+FIDEL is the Amharic/Ethiopic alphabet."
   (interactive)
   (let ((inhibit-read-only t)
 	;; (p) (ch)
@@ -895,7 +924,7 @@ The 2nd and 3rd arguments BEGIN and END specify the region."
 
 ;;;###autoload
 (defun ethio-fidel-to-java-buffer nil
-  "Convert Ethiopic characters into the Java escape sequences.
+  "Convert Ethiopic characters in the buffer into the Java escape sequences.
 
 Each escape sequence is of the form \\uXXXX, where XXXX is the
 character's codepoint (in hex) in Unicode.
@@ -914,7 +943,7 @@ Otherwise, [0-9A-F]."
 
 ;;;###autoload
 (defun ethio-java-to-fidel-buffer nil
-  "Convert the Java escape sequences into corresponding Ethiopic characters."
+  "Convert the Java escape sequences in the buffer into Ethiopic characters."
   (let ((case-fold-search t)
 	(ucode))
     (goto-char (point-min))
@@ -929,7 +958,17 @@ Otherwise, [0-9A-F]."
 
 ;;;###autoload
 (defun ethio-find-file nil
-  "Transliterate file content into Ethiopic depending on filename suffix."
+  "Transliterate file content into Ethiopic depending on filename suffix.
+If the file-name extension is \".sera\", convert from SERA to FIDEL.
+If the file-name extension is \".html\", convert regions enclosed
+by \"<sera>..</sera>\" from SERA to FIDEL.
+If the file-name extension is \".tex\", convert fidel-tex commands
+to FIDEL characters.
+If the file-name extension is \".java\", convert Java escape sequences
+to FIDEL characters.
+
+FIDEL is the Amharic alphabet; SERA (System for Ethiopic Representation
+in ASCII) is the Latin representation of Ethiopic script."
   (cond
 
    ((string-match "\\.sera$" (buffer-file-name))
@@ -963,7 +1002,17 @@ Otherwise, [0-9A-F]."
 
 ;;;###autoload
 (defun ethio-write-file nil
-  "Transliterate Ethiopic characters in ASCII depending on the file extension."
+  "Transliterate Ethiopic characters to ASCII depending on the file extension.
+If the file-name extension is \".sera\", convert from FIDEL to SERA.
+If the file-name extension is \".html\", convert FIDEL characters to
+SERA regions enclosed by \"<sera>..</sera>\".
+If the file-name extension is \".tex\", convert FIDEL characters
+to fidel-tex commands.
+If the file-name extension is \".java\", convert FIDEL characters to
+Java escape sequences.
+
+FIDEL is the Amharic alphabet; SERA (System for Ethiopic Representation
+in ASCII) is the Latin representation of Ethiopic script."
   (cond
 
    ((string-match "\\.sera$" (buffer-file-name))
@@ -1069,7 +1118,7 @@ With ARG, insert that many delimiters."
 
 ;; This function is not used any more.
 (defun ethio-gemination nil
-  "Compose the character before the point with the Ethiopic gemination mark.
+  "Compose the character before point with the Ethiopic gemination mark.
 If the character is already composed, decompose it and remove the gemination
 mark."
   (interactive "*")
@@ -1088,7 +1137,9 @@ mark."
 ;;;
 
 (robin-define-package "ethiopic-sera"
- "SERA transliteration system for Ethiopic."
+ "SERA transliteration system for Ethiopic.
+SERA (System for Ethiopic Representation in ASCII) is the Latin
+representation of Ethiopic script."
 
  ("he" ?ሀ)
  ("hu" ?ሁ)