utf-translate-cjk-mode undocumented

utf-translate-cjk-mode undocumented

[Werner LEMBERG]

[CVS 2004-07-25]

One of the most important new functions IMHO, utf-translate-cjk-mode,
is neither documented in elisp.info nor in emacs.info...


    Werner

Re: utf-translate-cjk-mode undocumented

[Miles Bader]

On Wed, Jul 28, 2004 at 01:07:35AM +0200, Werner LEMBERG wrote:
> One of the most important new functions IMHO, utf-translate-cjk-mode,
> is neither documented in elisp.info nor in emacs.info...

It's supposed to be turned on by default now, so I'm not sure there will be
much reason for anybody to ever invoke it (which would just turn it off)...

-Miles
-- 
I'm beginning to think that life is just one long Yoko Ono album; no rhyme
or reason, just a lot of incoherent shrieks and then it's over.  --Ian Wolff

Re: utf-translate-cjk-mode undocumented

[Werner LEMBERG]

> > One of the most important new functions IMHO,
> > utf-translate-cjk-mode, is neither documented in elisp.info nor in
> > emacs.info...
> 
> It's supposed to be turned on by default now, so I'm not sure there
> will be much reason for anybody to ever invoke it (which would just
> turn it off)...

Well, I like to have everything documented...  But on the other hand I
agree that the elisp/emacs manuals are already far too voluminous.


    Werner

Re: utf-translate-cjk-mode undocumented

[Richard Stallman]

    One of the most important new functions IMHO, utf-translate-cjk-mode,
    is neither documented in elisp.info nor in emacs.info...

I can't understand what it does; its doc string makes no sense
for a function:

    Whether the UTF based coding systems should decode/encode CJK characters.

Could you fix that up to say what the function *does*?
Even if people rarely need to call it, its doc string
should make sense.

Re: utf-translate-cjk-mode undocumented

[Andreas Schwab]

Richard Stallman <rms@gnu.org> writes:

>     One of the most important new functions IMHO, utf-translate-cjk-mode,
>     is neither documented in elisp.info nor in emacs.info...
>
> I can't understand what it does; its doc string makes no sense
> for a function:
>
>     Whether the UTF based coding systems should decode/encode CJK characters.
>
> Could you fix that up to say what the function *does*?
> Even if people rarely need to call it, its doc string
> should make sense.

This is a minor-mode toggle.

Andreas.

-- 
Andreas Schwab, SuSE Labs, schwab@suse.de
SuSE Linux AG, Maxfeldstraße 5, 90409 Nürnberg, Germany
Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

Re: utf-translate-cjk-mode undocumented

[Richard Stallman]

    >     One of the most important new functions IMHO, utf-translate-cjk-mode,
    >     is neither documented in elisp.info nor in emacs.info...
    >
    > I can't understand what it does; its doc string makes no sense
    > for a function:
    >
    >     Whether the UTF based coding systems should decode/encode CJK characters.

    This is a minor-mode toggle.

Could you fix the doc string accordingly?

Re: utf-translate-cjk-mode undocumented

[Andreas Schwab]

Richard Stallman <rms@gnu.org> writes:

>     >     One of the most important new functions IMHO, utf-translate-cjk-mode,
>     >     is neither documented in elisp.info nor in emacs.info...
>     >
>     > I can't understand what it does; its doc string makes no sense
>     > for a function:
>     >
>     >     Whether the UTF based coding systems should decode/encode CJK characters.
>
>     This is a minor-mode toggle.
>
> Could you fix the doc string accordingly?

I think prepending "Toggle" to the doc string is enough to make it
clear.  Do you agree?

Andreas.

-- 
Andreas Schwab, SuSE Labs, schwab@suse.de
SuSE Linux AG, Maxfeldstraße 5, 90409 Nürnberg, Germany
Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

Re: utf-translate-cjk-mode undocumented

[Luc Teirlinck]

Andreas Schwab wrote (in response to Richard Stallman:

   >     This is a minor-mode toggle.
   >
   > Could you fix the doc string accordingly?

   I think prepending "Toggle" to the doc string is enough to make it
   clear.  Do you agree?

The first line ia already six characters longer than the maximum
allowed 67 (for apropos).  It still does not mention that this is a
minor mode.  It does not say what the ARG argument does.  It refers to
the function as being a customizable _option_ (variable) in the last
paragraph.  I believe that the following would fix all of this:

===File ~/utf8.el-diff======================================
*** utf-8.el	13 Jun 2004 17:49:29 -0500	1.40
--- utf-8.el	30 Jul 2004 10:21:51 -0500	
***************
*** 284,290 ****
  	   (get 'utf-subst-table-for-encode 'translation-hash-table)))
    
  (define-minor-mode utf-translate-cjk-mode
!   "Whether the UTF based coding systems should decode/encode CJK characters.
  Enabling this allows the coding systems mule-utf-8,
  mule-utf-16le and mule-utf-16be to encode characters in the charsets
  `korean-ksc5601', `chinese-gb2312', `chinese-big5-1',
--- 284,292 ----
  	   (get 'utf-subst-table-for-encode 'translation-hash-table)))
    
  (define-minor-mode utf-translate-cjk-mode
!   "Toggle whether UTF based coding systems de/encode CJK characters.
! If ARG is an integer, enable if ARG is positive and disable if
! zero or negative.  This is a minor mode.
  Enabling this allows the coding systems mule-utf-8,
  mule-utf-16le and mule-utf-16be to encode characters in the charsets
  `korean-ksc5601', `chinese-gb2312', `chinese-big5-1',
***************
*** 296,304 ****
  turned on: ksc5601 for Korean, gb2312 for Chinese-GB, big5 for
  Chinese-Big5 and jisx for other environments.
  
! This option is on by default.  If you are not interested in CJK
  characters and want to avoid some overhead on encoding/decoding
! by the above coding systems, you can customize this option to nil."
    :init-value t
    :version "21.4"
    :type 'boolean
--- 298,307 ----
  turned on: ksc5601 for Korean, gb2312 for Chinese-GB, big5 for
  Chinese-Big5 and jisx for other environments.
  
! This is on by default.  If you are not interested in CJK
  characters and want to avoid some overhead on encoding/decoding
! by the above coding systems, you can customize the user option
! `utf-translate-cjk-mode' to nil."
    :init-value t
    :version "21.4"
    :type 'boolean
============================================================

Re: utf-translate-cjk-mode undocumented

[Andreas Schwab]

Luc Teirlinck <teirllm@dms.auburn.edu> writes:

> --- 298,307 ----
>   turned on: ksc5601 for Korean, gb2312 for Chinese-GB, big5 for
>   Chinese-Big5 and jisx for other environments.
>   
> ! This is on by default.  If you are not interested in CJK

IMHO "This mode is on by default" whould be a wee bit better.

Andreas.

-- 
Andreas Schwab, SuSE Labs, schwab@suse.de
SuSE Linux AG, Maxfeldstraße 5, 90409 Nürnberg, Germany
Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

Re: utf-translate-cjk-mode undocumented

[Luc Teirlinck]

Andreas Schwab wrote:

   > ! This is on by default.  If you are not interested in CJK

   IMHO "This mode is on by default" whould be a wee bit better.

I agree.

Sincerely,

Luc.

Re: utf-translate-cjk-mode undocumented

[Richard Stallman]

      (define-minor-mode utf-translate-cjk-mode
    !   "Toggle whether UTF based coding systems de/encode CJK characters.
    ! If ARG is an integer, enable if ARG is positive and disable if
    ! zero or negative.  This is a minor mode.

Your patch looks good.  Please install it.

    IMHO "This mode is on by default" whould be a wee bit better.

I agree.