documentation bug

documentation bug

[Frederik Fouvry]

This bug report will be sent to the Free Software Foundation,
not to your local site managers!
Please write in English, because the Emacs maintainers do not have
translators to read other languages for them.

Your bug report will be posted to the bug-gnu-emacs@gnu.org mailing list,
and to the gnu.emacs.bug news group.

In GNU Emacs 21.3.1 (i686-pc-linux-gnu, X toolkit, Xaw3d scroll bars)
 of 2004-02-19 on cc.at.coli.uni-sb.de
configured using `configure  --prefix=/export/black --with-xpm --with-jpeg --with-tiff --with-gif --with-png --with-x --with-gcc --with-pop --with-sound'
Important settings:
  value of $LC_ALL: nil
  value of $LC_COLLATE: POSIX
  value of $LC_CTYPE: nil
  value of $LC_MESSAGES: nil
  value of $LC_MONETARY: de_DE@euro
  value of $LC_NUMERIC: nil
  value of $LC_TIME: nil
  value of $LANG: en_GB
  locale-coding-system: iso-latin-1
  default-enable-multibyte-characters: t

Please describe exactly what actions triggered the bug
and the precise symptoms of the bug:

In the Elisp manual, there is the following section (in
"Conventions for Writing Minor Modes"):

     The command should accept one optional argument.  If the argument
     is `nil', it should toggle the mode (turn it on if it is off, and
     off if it is on).  Otherwise, it should turn the mode on if the
     argument is a positive integer, a symbol other than `nil' or `-',
     or a list whose CAR is such an integer or symbol; it should turn
     the mode off otherwise.

     Here is an example taken from the definition of
     `transient-mark-mode'.  It shows the use of `transient-mark-mode'
     as a variable that enables or disables the mode's behavior, and
     also shows the proper way to toggle, enable or disable the minor
     mode based on the raw prefix argument value.

          (setq transient-mark-mode
                (if (null arg) (not transient-mark-mode)
                  (> (prefix-numeric-value arg) 0)))


The given example does not behave as documented for the arguments
'(-) and '(nil):

(prefix-numeric-value '(-)) -> 1
(prefix-numeric-value '(nil)) -> 1

According to the quoted text, these arguments should switch off
the mode.

Either prefix-numeric-value() is not behaving correctly, or the
example is not complete.  In the latter case, one could write

          (setq transient-mark-mode
	        (let ((larg (if (consp arg) (car arg) arg)))
                  (if (null larg) (not transient-mark-mode)
		    (> (prefix-numeric-value larg) 0))))

documentation bug

[harven]

In Gnu Emacs Manual version 22.1,
there is an entry "television" in the index.
It refers to section Appending Kills.
I can't see anything relevant to "television"
in this section, so may be the entry should
be removed.

Re: documentation bug

[Eli Zaretskii]

> From: harven <harven@free.fr>
> Date: Thu, 8 May 2008 09:49:20 -0700 (PDT)
> 
> In Gnu Emacs Manual version 22.1,
> there is an entry "television" in the index.
> It refers to section Appending Kills.
> I can't see anything relevant to "television"
> in this section, so may be the entry should
> be removed.

It was a joke.  The version of the manual from long ago had this text
at the beginning of this node:

    Normally, each kill command pushes a new block onto the kill ring.
  However, two or more kill commands in a row combine their text into a
  single entry, so that a single @kbd{C-y} gets it all back as it was before
  it was killed.  This means that you don't have to kill all the text in one
  command; you can keep killing line after line, or word after word, until
  you have killed it all, and you can still get it all back at once.  (Thus
  we join television in leading people to kill thoughtlessly.)

The sentence in parentheses was removed somewhere between Emacs 18.59
and Emacs 19.34, perhaps because someone found it tasteless or
offending, but the index entry remained.

Richard, can you shed some light on this?  Should we just remove the
index entry?

Re: documentation bug

[Richard M Stallman]

    Richard, can you shed some light on this?  Should we just remove the
    index entry?

Please do.  The index entry serves no purpose without the joke.