Doc fixes.

(ogonek-jak, ogonek-how): Examples of customization fixed.

1 files changed, 159 insertions, 166 deletions

diff --git a/lisp/international/ogonek.el b/lisp/international/ogonek.el
index 044012d392a..932dc44ecf5 100644
--- a/lisp/international/ogonek.el
+++ b/lisp/international/ogonek.el
@@ -56,55 +56,55 @@
                      136 141 171 184 196 151 230 144 253))
  ) 
   "The constant `ogonek-name-encoding-alist' is a list of (NAME.LIST) pairs.
-Each LIST contains codes for 18 Polish diacritic characters.
-The codes are given in the following order:
+Each LIST contains codes for 18 Polish diacritic characters. The codes
+are given in the following order:
   Aogonek Cacute Eogonek Lslash Nacute Oacute Sacute Zacute Zdotaccent
   aogonek cacute eogonek lslash nacute oacute sacute zacute zdotaccent.")
 
-; ------ A Little Info in Polish ---------------
+;; ------ A Little Info in Polish ---------------
 
 (defconst ogonek-informacja
-  "   FUNKCJE INTERAKCYJNE UDOST/EPNIANE PRZEZ BIBLIOTEK/E `ogonek'
+  "   FUNKCJE INTERAKCYJNE UDOST/EPNIANE PRZEZ BIBLIOTEK/E `ogonek'.
 
-Je/sli czytasz ten tekst, to albo przegl/adasz plik /zr/od/lowy
+Je/sli czytasz ten tekst, to albo przegl/adasz plik /xr/od/lowy
 biblioteki `ogonek.el', albo wywo/la/le/s polecenie `ogonek-jak'. 
 W drugim przypadku mo/zesz usun/a/c tekst z ekranu, stosuj/ac 
 polecenie `M-x kill-buffer'.
 
-Niniejsza bibliteka dostarcza funkcji do zmiany kodowania polskich
+Niniejsza biblioteka dostarcza funkcji do zmiany kodowania polskich
 znak/ow diakrytycznych. Funkcje te mo/zna pogrupowa/c nast/epuj/aco.
 
- 1. Funkcje `ogonek-recode-region' oraz `ogonek-recode-buffer' 
-    przekodowu/j/a zaznaczony fragment wzgl/ednie ca/ly buffor.    
+ 1. `ogonek-recode-region' oraz `ogonek-recode-buffer' 
+    przekodowuj/a zaznaczony fragment wzgl/ednie ca/ly buffor.    
     Po wywo/laniu interakcyjnym funkcji zadawane s/a
-    pytania o parametry przekodowania, czyli o nazw/e kodowania
-    w tek/scie /zr/od/lowym i nazw/e kodowania docelowego. 
-    Poni/zsze przyk/lady pokazuj/a, jakich parametr/ow 
+    pytania o parametry przekodowania: nazw/e kodowania
+    w tek/scie /xr/od/lowym i nazw/e kodowania docelowego. 
+    Poni/zsze przyk/lady powinny wyja/sni/c, jakich parametr/ow 
     oczekuj/a wymienione funkcje:
 
-      (ogonek-recode-region (poczatek) (koniec)
+      (ogonek-recode-region (poczatek-fragmentu) (koniec-fragmentu)
          nazwa-kodowania-w-tekscie-zrodlowym nazwa-kodowania-docelowa)
       (ogonek-recode-buffer 
          nazwa-kodowania-w-tekscie-zrodlowym nazwa-kodowania-docelowa)    
 
- 2. Funkcje `ogonek-prefixify-region' oraz `ogonek-prefixify-buffer'
-    do wprowadzania notacji prefiksowej.
+ 2. `ogonek-prefixify-region' oraz `ogonek-prefixify-buffer'
+    s/lu/z/a do wprowadzania notacji prefiksowej.
 
-      (ogonek-prefixify-region (poczatek) (koniec)
+      (ogonek-prefixify-region (poczatek-fragmentu) (koniec-fragmentu)
          nazwa-kodowania-w-tekscie-zrodlowym znak-prefiksu)
       (ogonek-prefixify-buffer 
          nazwa-kodowania-w-tekscie-zrodlowym znak-prefiksu)     
 
- 3. Funkcje `ogonek-deprefixify-region' oraz `ogonek-deprefixify-buffer' 
-    do usuwania notacji prefiksowej.
+ 3. `ogonek-deprefixify-region' oraz `ogonek-deprefixify-buffer' 
+    s/lu/z/a do usuwania notacji prefiksowej.
      
-      (ogonek-deprefixify-region (poczatek) (koniec)
+      (ogonek-deprefixify-region (poczatek-fragmentu) (koniec-fragmentu)
          znak-prefiksu nazwa-kodowania-docelowa)
       (ogonek-prefixify-buffer 
          znak-prefiksu nazwa-kodowania-docelowa)         
 
  U/zycie klawisza TAB w trybie interakcyjnym powoduje wy/swietlenie
- listy dopuszczalnych nazw kod/ow, odczytywanych ze sta/lej
+ listy dopuszczalnych nazw kod/ow, pami/etanych w sta/lej
  `ogonek-name-encoding-alist'. 
 
  Funkcje biblioteki odwo/luj/a si/e do pi/eciu zmiennych, kt/ore 
@@ -112,7 +112,7 @@ znak/ow diakrytycznych. Funkcje te mo/zna pogrupowa/c nast/epuj/aco.
  oraz ich warto/sci domy/slne s/a nast/epuj/ace: 
 
    ogonek-from-encoding           iso8859-2
-   ogonek-to-encoding             mazovia
+   ogonek-to-encoding             ascii
    ogonek-prefix-char              /
    ogonek-prefix-from-encoding    iso8859-2
    ogonek-prefix-to-encoding      iso8859-2
@@ -120,159 +120,146 @@ znak/ow diakrytycznych. Funkcje te mo/zna pogrupowa/c nast/epuj/aco.
  Powy/zsze warto/sci domy/slne mo/zna zmieni/c przez umieszczenie w pliku
  konfiguracyjnym `~/.emacs' odpowiednich przypisa/n, na przyk/lad:
 
- (setq ogonek-prefix-char ?/)
- (setq ogonek-prefix-to-encoding \"iso8859-2\")
+   (setq ogonek-prefix-char ?/)
+   (setq ogonek-prefix-to-encoding \"iso8859-2\")
 
  Zamiast wczytywania ca/lej biblioteki `ogonek.el' mo/zna w pliku
- `~/.emacs' za/z/ada/c wczytania wybranych funkcji i to dopiero w
- chwili ich wywo/lania:
+ `~/.emacs' za/z/ada/c wczytania wybranych funkcji, na dodatek dopiero 
+ w chwili ich rzeczywistego u/zycia:
 
- (autoload 'ogonek-jak \"ogonek\")
- (autoload 'ogonek-recode-region \"ogonek\")
- (autoload 'ogonek-prefixify-region \"ogonek\")
- (autoload 'ogonek-deprefixify-region \"ogonek\")
+   (autoload 'ogonek-jak \"ogonek\")
+   (autoload 'ogonek-recode-region \"ogonek\")
+   (autoload 'ogonek-prefixify-region \"ogonek\")
+   (autoload 'ogonek-deprefixify-region \"ogonek\")
 
  Cz/esto wyst/epuj/ace kombinacje wywo/la/n funkcji mo/zna dla wygody
  skr/oci/c i przypisa/c klawiszom. Oto praktyczne przyk/lady:
 
- (defun deprefixify-iso8859-2-region ()
-   (interactive \"*\")
-   (ogonek-deprefixify-region 
-    (region-beginning) (region-end) ?/ \"iso8859-2\"))
- (global-set-key \"\\C-cd\" 'deprefixify-iso8859-2-region) ; ctrl-c d
+   (defun deprefixify-iso8859-2-region (start end)
+     (interactive \"*r\")
+     (ogonek-deprefixify-region start end ?/ \"iso8859-2\"))
+   (global-set-key \"\\C-cd\" 'deprefixify-iso8859-2-region) ; ctrl-c d
 
- (defun mazovia-to-iso8859-2 () 
-   (interactive \"*\")
-   (ogonek-recode-region \"mazovia\" \"iso8859-2\"))
- (global-set-key \"\\C-cr\" 'mazovia-to-iso8859-2) ; ctrl-c r
+   (defun mazovia-to-iso8859-2 (start end) 
+     (interactive \"*r\")
+     (ogonek-recode-region start end \"mazovia\" \"iso8859-2\"))
+   (global-set-key \"\\C-cr\" 'mazovia-to-iso8859-2) ; ctrl-c r
 
- (defun prefixify-iso8859-2-region ()
-   (interactive \"*\")
-   (ogonek-prefixify-region 
-    (region-beginning) (region-end) \"iso8859-2\" ?/))
- (global-set-key \"\\C-cp\" 'prefixify-iso8859-2-region) ; ctrl-c p
+   (defun prefixify-iso8859-2-region (start end)
+     (interactive \"*r\")
+     (ogonek-prefixify-region start end \"iso8859-2\" ?/))
+   (global-set-key \"\\C-cp\" 'prefixify-iso8859-2-region) ; ctrl-c p
 
  Ka/zd/a operacj/e przekodowania mo/zna w ca/lo/sci odwo/la/c
  przez wykonanie polecenia `undo'.")
 
 (defun ogonek-jak ()
-  "Display the string constant `ogonek-informacja' 
-by inserting it into an auxiliary *ogonek-jak* buffer."
+  "Display `ogonek-informacja' in an auxiliary *ogonek-jak* buffer."
   (interactive)
   (set-buffer  (get-buffer-create " *ogonek-jak*"))
   (insert ogonek-informacja)
   (switch-to-buffer " *ogonek-jak*")
   (beginning-of-buffer))
 
-; ------ A Little Info in English --------
+;; ------ A Little Info in English --------
 
 (defconst ogonek-information
-  "   INTERACTIVE FUNCTIONS PROVIDED BY THE LIBRARY `ogonek'.
+  "  THE INTERACTIVE FUNCTIONS PROVIDED BY THE LIBRARY `ogonek'.
 
 If you read this text then you are either looking at the library's
-source text or you have called the `ogonek-howto' command. In the
+source text or you have called the `ogonek-how' command. In the
 latter case you may remove this text using `M-x kill-buffer'.
 
 The library provides functions for changing the encoding of Polish
 diacritic characters, the ones with an `ogonek' below or above them.
-The functions come in the following gropus.
-
- 1. Functions `ogonek-recode-region' and `ogonek-recode-buffer' to
-    change between one-character encodings, such as `iso-8859-2',
-    `mazovia', plain `ascii' or `TeX'. As the names suggest you may
-    recode either the entire current buffer or just a marked region 
-    of it. You may use these functions interactively as commands. Once 
-    you call a command you will be asked about the code used in 
-    the source text and the target encoding, the one you want to get. 
-    The following examples show a non-interactive use of the functions 
-    in a program. They also illustrtate what parameters the functions 
-    expect:
-
-      (ogonek-recode-region (region-beginning) (region-end)
-                                from-code-name to-code-name)
+The functions come in the following groups.
+
+ 1. `ogonek-recode-region' and `ogonek-recode-buffer' to change
+    between one-character encodings, such as `iso-8859-2', `mazovia', 
+    plain `ascii' or `TeX'. As the names suggest you may recode 
+    either the entire current buffer or just a marked region 
+    in it. You may use the functions interactively as commands. 
+    Once you call a command you will be asked about the code 
+    currently used in your text and the target encoding, the one 
+    you want to get. The following example shows a non-interactive 
+    use of the functions in a program. This also illustrates what 
+    type of parameters the functions expect to be called with:
+
+      (ogonek-recode-region 
+        (region-beginning) (region-end) from-code-name to-code-name)
       (ogonek-recode-buffer from-code-name to-code-name)         
 
- 2. Functions `ogonek-prefixify-region' and `ogonek-prefixify-buffer'.
-    for introducing prefix notation:
+ 2. `ogonek-prefixify-region' and `ogonek-prefixify-buffer' for 
+    introducing prefix notation:
 
-      (ogonek-prefixify-region (region-beginning) (region-end)
-                                     from-code-name prefix-char)
+      (ogonek-prefixify-region 
+        (region-beginning) (region-end) from-code-name prefix-char)
       (ogonek-prefixify-buffer from-code-name prefix-char)         
   
- 3. Functions  `ogonek-deprefixify-region' and `ogonek-deprefixify-buffer' 
-    for removing prefix notation:
+ 3. `ogonek-deprefixify-region' and `ogonek-deprefixify-buffer' for 
+    removing prefix notation:
      
-      (ogonek-deprefixify-region (region-beginning) (region-end)
-                                   prefix-char to-code-name)
+      (ogonek-deprefixify-region 
+        (region-beginning) (region-end) prefix-char to-code-name)
       (ogonek-prefixify-buffer prefix-char to-code-name)         
 
- The use of the TAB character in interactive makes `emacs' display
- the list of encodings recognized by the library - the code names
- are stored in the constant  `ogonek-name-encoding-alist'
+ The TAB character used in interactive mode makes `emacs'
+ display the list of encodings recognized by the library. The list 
+ is stored in the constant `ogonek-name-encoding-alist'.
 
- The functions of the library refer to five variables that keep
- hints to the questions asked. The names of those variables as well
- as their default values are:
+ The `ogonek' functions refer to five variables in which the suggested
+ answers to dialogue questions are stored. The variables and their 
+ default values are:
  
    ogonek-from-encoding           iso8859-2
-   ogonek-to-encoding             mazovia
-   ogonek-prefix-char              /
+   ogonek-to-encoding             ascii
+   ogonek-prefix-char             /
    ogonek-prefix-from-encoding    iso8859-2
    ogonek-prefix-to-encoding      iso8859-2
 
  The above default values can be changed by placing appropriate settings 
  in the '~/.emacs' file:
 
- (setq ogonek-prefix-char ?/)
- (setq ogonek-prefix-to-encoding \"iso8859-2\")
+   (setq ogonek-prefix-char ?/)
+   (setq ogonek-prefix-to-encoding \"iso8859-2\")
 
- Instead of loading the whole library `ogonek.el' it may be better to
- autoload chosen functions in `~/.emacs':
+ Instead of loading the whole library `ogonek' it may be better to
+ autoload the needed functions, for example by placing in `~/.emacs':
 
- (autoload 'ogonek-jak \"ogonek\")
- (autoload 'ogonek-recode-region \"ogonek\")
- (autoload 'ogonek-prefixify-region \"ogonek\")
- (autoload 'ogonek-deprefixify-region \"ogonek\")
+   (autoload 'ogonek-how \"ogonek\")
+   (autoload 'ogonek-recode-region \"ogonek\")
+   (autoload 'ogonek-prefixify-region \"ogonek\")
+   (autoload 'ogonek-deprefixify-region \"ogonek\")
 
  The most frequent function calls can be abbreviated and assigned to
  keyboard keys. Here are a few practical examples:
 
- (setq ogonek-from-code-name \"iso8859-2\")
- (setq ogonek-to-code-name \"mazovia\")
- (setq ogonek-prefix-char ?/)
- (setq ogonek-prefix-from-code-name \"iso8859-2\")
- (setq ogonek-prefix-to-code-name \"iso8859-2\")
-
- (defun deprefixify-iso8859-2-region ()
-   (interactive \"*\")
-   (ogonek-deprefixify-region 
-    (region-beginning) (region-end) ?/ \"iso8859-2\"))
- (global-set-key \"\\C-cd\" 'deprefixify-iso8859-2-region) ; ctrl-c d
+   (defun deprefixify-iso8859-2-region (start end)
+     (interactive \"*r\")
+     (ogonek-deprefixify-region start end ?/ \"iso8859-2\"))
+   (global-set-key \"\\C-cd\" 'deprefixify-iso8859-2-region) ; ctrl-c d
 
- (defun mazovia-to-iso8859-2 () 
-   (interactive \"*\")
-   (ogonek-recode-region \"mazovia\" \"iso8859-2\"))
- (global-set-key \"\\C-cr\" 'mazovia-to-iso8859-2) ; ctrl-c r
+   (defun mazovia-to-iso8859-2 (start end) 
+     (interactive \"*r\")
+     (ogonek-recode-region start end \"mazovia\" \"iso8859-2\"))
+   (global-set-key \"\\C-cr\" 'mazovia-to-iso8859-2) ; ctrl-c r
 
- (defun prefixify-iso8859-2-region ()
-   (interactive \"*\")
-   (ogonek-prefixify-region 
-    (region-beginning) (region-end) \"iso8859-2\" ?/))
- (global-set-key \"\\C-cp\" 'prefixify-iso8859-2-region) ; ctrl-c p
+   (defun prefixify-iso8859-2-region (start end)
+     (interactive \"*r\")
+     (ogonek-prefixify-region start end \"iso8859-2\" ?/))
+   (global-set-key \"\\C-cp\" 'prefixify-iso8859-2-region) ; ctrl-c p
 
- Each recoding opertation can be called off by executing the `undo'
- command.")
+ Each recoding operation can be called off using the `undo' command.")
 
 (defun ogonek-how ()
-  "Display the string constant `ogonek-information' 
-by inserting it into an auxiliary *recode-help* buffer."
+  "Display `ogonek-information' in an auxiliary *recode-how* buffer."
   (interactive "*")
-  (set-buffer  (get-buffer-create " *ogonek-help*"))
+  (set-buffer  (get-buffer-create " *ogonek-how*"))
   (insert ogonek-information)
-  (switch-to-buffer " *ogonek-help*")
+  (switch-to-buffer " *ogonek-how*")
   (beginning-of-buffer))
 
-;; ------ Variables for keeping hints to the questions ---------
+;; ---- Variables keeping the suggested answers to dialogue questions -----
 
 (defvar ogonek-from-encoding "iso8859-2"
   "*Encoding in the source file of recoding.")
@@ -285,65 +272,68 @@ by inserting it into an auxiliary *recode-help* buffer."
 (defvar ogonek-prefix-to-encoding "iso8859-2"
   "*Encoding in the target file subject to deprefixifation.") 
 
-;; ------- Utilities for reading function parameters -------------
+;; ---- Auxiliary functions for reading parameters in interactive mode ----
 
 (defun ogonek-read-encoding (prompt default-name-var)
-  "Change with completion based on alist `ogonek-name-encoding-alist'."
+  "Read encoding name with completion based on `ogonek-name-encoding-alist'.
+Store the name in the the parameter-variable DEFAULT-NAME-VAR.
+PROMPT is a string to be shown when the user is asked for a name."
  (let ((encoding 
         (completing-read 
          (format "%s (default %s): " prompt (eval default-name-var))
          ogonek-name-encoding-alist nil t)))
-  ; set the new default name to be the one just read
-   (set default-name-var 
-       (if (string= encoding "") (eval default-name-var) encoding))  
-  ; return the new default as the name you read
+  ;; change the default name to the one just read
+  (set default-name-var 
+    (if (string= encoding "") (eval default-name-var) encoding))  
+  ;; return the new default as the name you read
   (eval default-name-var)))
 
 (defun ogonek-read-prefix (prompt default-prefix-var)
-  "Change prefix."
+  "Read a prefix character for prefix notation.
+The result is stored in the variable DEFAULT-PREFIX-VAR. 
+PROMPT is a string to be shown when the user is asked for a new prefix."
   (let ((prefix-string 
          (read-string 
           (format "%s (default %s): " prompt 
                   (char-to-string (eval default-prefix-var))))))
     (if (> (length prefix-string) 1)
         (error "! Only one character expected.") 
-      ; set the default prefix character to the one just read
+      ;; set the default prefix character to the one just read
       (set default-prefix-var
            (if (string= prefix-string "") 
              (eval default-prefix-var) 
            (string-to-char prefix-string)))
-      ; return the new default prefix as the code you read)
+      ;; the new default prefix is the function's result:
       (eval default-prefix-var))))
 
 (defun ogonek-lookup-encoding (encoding)
-  "Pick up an association for `encoding' in `ogonek-name-encoding-alist'.
-Before returning a result test whether it has been properly set
-which should be true if the encoding is one of those in
-`ogonek-name-encoding-alist'"
+  "Pick up an association for ENCODING in `ogonek-name-encoding-alist'.
+Before returning a result test whether the string ENCODING is in 
+the list `ogonek-name-encoding-alist'"
   (let ((code-list (assoc encoding ogonek-name-encoding-alist)))
     (if (null code-list)
       (error "! Name `%s' not known in `ogonek-name-encoding-alist'."
                encoding)
       (cdr code-list))))
 
-; -------  A utility for zipping two lists -----------
+;; ----  An auxiliary function for zipping two lists of equal length ----
 
 (defun ogonek-zip-lists (xs ys)
-  "Build a list of pairs with elements from lists `xs' and `ys'. 
-We assume that `xs' and `ys' are of the same length."
+  "Build a list of pairs from lists XS and YS of the same length." 
   (let ((pairs nil)) 
     (while xs
       (setq pairs (cons (cons (car xs) (car ys)) pairs))
       (setq xs (cdr xs))
       (setq ys (cdr ys)))
-;   `pairs' are the function's result
+    ;; `pairs' are the function's result
     pairs))
 
-; -------- Dealing with one-character cencodings -------
+;; ---- An auxiliary function building a one-to-one recoding table -----
 
 (defun ogonek-build-table (recoding-pairs) 
-  "Build a table nedeed by emacs's `translate-region' function.
-The  `recoding-pairs' argument is a list of pairs of characters.
+  "Build a table required by Emacs's `translate-region' function.
+RECODING-PAIRS is a list of character pairs for which recoding
+is not an identity. 
 By using the built-in `translate-region' function
 we gain better performance compared to converting characters
 by a hand-written routine as it is done for prefix encodings."
@@ -352,17 +342,19 @@ by a hand-written routine as it is done for prefix encodings."
     (while (< i 256) 
       (aset table i i) 
       (setq i (1+ i)))
-    ; make changes in `table' according to `recoding-pairs'
+    ;; make changes in `table' according to `recoding-pairs'
     (while recoding-pairs
       (aset table (car (car recoding-pairs)) (cdr (car recoding-pairs)))
       (setq recoding-pairs (cdr recoding-pairs)))
-    ; return the table just built
+    ;; return the table just built
     table))
 
+;; ---- Commands for one-to-one recoding -------------------------------
+
 (defun ogonek-recode-region (start end from-encoding to-encoding) 
-  "This function recodes text in a region delineated by the current-mark 
-and the current point according to the defaults set by the variables
-`ogonek-from-encoding' and `ogonek-to-encoding'."
+  "Recode text in a marked region in one-to-one manner.
+When called interactively ask the user for the names of the FROM- 
+and TO- encodings."   
   (interactive (progn (barf-if-buffer-read-only)
                 (list 
                 (region-beginning) 
@@ -378,7 +370,9 @@ and the current point according to the defaults set by the variables
        (ogonek-lookup-encoding to-encoding))))))
 
 (defun ogonek-recode-buffer (from-encoding to-encoding)
-  "Call `ogonek-region' on the entire buffer."
+  "Call `ogonek-recode-region' on the entire buffer.
+When called interactively ask the user for the names of the FROM- 
+and TO- encodings."
   (interactive (progn (barf-if-buffer-read-only)
                 (list 
                 (ogonek-read-encoding "From code" 'ogonek-from-encoding)
@@ -386,19 +380,16 @@ and the current point according to the defaults set by the variables
   (ogonek-recode-region 
    (point-min) (point-max) from-encoding to-encoding))
 
-; --------------------------------
-; Recoding with prefix notation 
-; --------------------------------
+;; ---- Recoding with prefix notation -------------------------------
 
-(defconst prefix-code '(?A  ?C  ?E  ?L  ?N  ?O  ?S  ?X  ?Z 
-                        ?a  ?c  ?e  ?l  ?n  ?o  ?s  ?x  ?z)) 
+(defconst ogonek-prefix-code '(?A  ?C  ?E  ?L  ?N  ?O  ?S  ?X  ?Z 
+                               ?a  ?c  ?e  ?l  ?n  ?o  ?s  ?x  ?z)) 
     
 (defun ogonek-prefixify-region (start end from-encoding prefix-char)
-  "Replace -- in the region delineated by the current-mark 
-and the point -- each character from `ogonek-from-encoding'
-by two characters: `ogonek-prefix-char' and the corresponding 
-character from the `prefix' list. Double the character 
-`ogonek-prefix-char'"
+  "In a region, replace FROM-encoded Polish characters with PREFIX pairs.
+A PREFIX pair generated consists of PREFIX-CHAR and the respective 
+character listed in the `ogonek-prefix-code' constant. 
+PREFIX-CHAR itself gets doubled."
   (interactive (progn (barf-if-buffer-read-only)
     (list 
     (region-beginning) 
@@ -407,8 +398,8 @@ character from the `prefix' list. Double the character
     (ogonek-read-prefix "Prefix character" 'ogonek-prefix-char))))
   (let* 
       ((from-code (ogonek-lookup-encoding from-encoding))
-       (to-code prefix-code)
-       (recoding-pairs  ; we add `ogonek-prefix-char' for doubling
+       (to-code ogonek-prefix-code)
+       (recoding-pairs  ; `ogonek-prefix-char' added for doubling
         (ogonek-zip-lists 
          (cons prefix-char from-code)  
          (cons prefix-char to-code))))
@@ -417,13 +408,13 @@ character from the `prefix' list. Double the character
       (while (< (point) end)
         (let ((pair (assoc (following-char) recoding-pairs)))
           (if (null pair)
-              ; not a Polish character -- skip it
+              ;; not a Polish character -- skip it
               (forward-char 1)
-            ; Polish character -- replace it by a two characters
+            ;; Polish character -- insert a prefix pair instead
             (delete-char 1)
             (insert ogonek-prefix-char)
             (insert (cdr pair))
-            ; the region is now one character longer
+            ;; the region is now one character longer
             (setq end (1+ end))))))))
 
 (defun ogonek-prefixify-buffer (from-encoding prefix-char)
@@ -436,10 +427,12 @@ character from the `prefix' list. Double the character
    (point-min) (point-max) from-encoding prefix-char))
 
 (defun ogonek-deprefixify-region (start end prefix-char to-encoding)
-  "Replace `ogonek-prefix-char' followed by a character from 
-the `prefix' list or another `ogonek-prefix-char' by 
-the corresponding character from `ogonek-from-encoding' 
-or by one `ogonek-prefix-char'."
+  "In a region, replace PREFIX pairs with their corresponding TO-encodings.
+PREFIX-CHAR followed by a Polish character from the `ogonek-prefix-code' 
+list is replaced with the corresponding TO-encoded character. A doubled
+PREFIX-CHAR gets replaced with a single one. A combination of PREFIX-CHAR 
+followed by a non-Polish character, that is one not listed in the 
+`ogonek-prefix-code' constant, is left unchanged."
   (interactive (progn (barf-if-buffer-read-only)
                 (list (region-beginning) 
                       (region-end)
@@ -448,7 +441,7 @@ or by one `ogonek-prefix-char'."
                       (ogonek-read-encoding 
                        "To code" 'ogonek-prefix-to-encoding))))
   (let* 
-      ((from-code prefix-code)
+      ((from-code ogonek-prefix-code)
        (to-code (ogonek-lookup-encoding to-encoding))
        (recoding-pairs 
         (ogonek-zip-lists 
@@ -459,20 +452,20 @@ or by one `ogonek-prefix-char'."
       (while (< (point) end)
         (forward-char 1)
        (if (or (not (= (preceding-char) prefix-char)) (= (point) end))
-           ; non-prefix character or the end-of-region -- do nothing
+           ;; non-prefix character or the end-of-region -- do nothing
            ()
-         ; now, we can check the next character
+         ;; now, we can check the next character
          (let ((pair (assoc (following-char) recoding-pairs)))
            (if (null pair) 
-               ; `following-char' is not a Polish character nor it is
-               ;  `prefix-char' since the one is among `recoding-pairs'
+               ;; `following-char' is not a Polish character nor it is
+               ;;  `prefix-char' since the one is among `recoding-pairs'
                (forward-char 1)     
-           ; else prefix followed by a Polish character has been found
-           ; replace it by the corresponding Polish character
+           ;; else prefix followed by a Polish character has been found
+           ;; replace it by the corresponding Polish character
            (backward-char 1)
            (delete-char 2)
            (insert (cdr pair))
-           ; the region got shorter by one character
+           ;; the region got shorter by one character
            (setq end (1- end)))))))))
 
 (defun ogonek-deprefixify-buffer (prefix-char to-encoding)