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.

documentation bug

[Tyler Smith]

Hi,

I'm using org-mode 7.8.03, which shipped with Emacs 24.0.94.1. The
documentation for exporting html includes the following:

12.5.1 HTML export commands
---------------------------

`C-c C-e h     (`org-export-as-html')'
     Export as HTML file.  [...] If there is an active region(1), only
the region will be
     exported.

However, I think this is incorrect. If there is an active region,
org-export will turn on subtree-p. This results in unexpected
behaviour. For example, if an active region is marked that contains
two subtrees, but point is at the beginning of a third subtree, then
instead of exporting the two subtrees in the active region, you get
only the third subtree which is outside the region. The same problem
appears to hold for C-c C-e R. You actually need to call C-c C-e 1 h
to get the expected behaviour.

I'm not sure if this is a problem with the docs or the code itself,
but they don't seem to match up on this point.

Thanks,

Tyler

Re: documentation bug

[Giovanni Ridolfi]

Da: Tyler Smith <tyler.smith@mail.mcgill.ca>

Inviato: Giovedì 13 Settembre 2012 16:50

> I'm using org-mode 7.8.03, which shipped with Emacs 24.0.94.1. 

> `C-c C-e h     (`org-export-as-html')'
>     Export as HTML file.  [...] If there is an active region(1), only
>   the region will be      exported.
> However, I think this is incorrect. 
> If there is an active region, org-export will turn on subtree-p. This results in unexpected
> behaviour. For example, if an active region is marked that contains
> two subtrees, 

This is a corner case. With your org version you are expected to export a well organized document:
- A headline and its subtrees
- or a subtree, 

not two subtrees.

But, here, Org-mode version 7.9.1 (2eb1456bfd
the new exporter handles this case well and exports the two subtrees.

Please upgrade Org and use the new exporter as suggested in the release notes:

http://orgmode.org/Changes.html

cheers,

Giovanni

Re: documentation bug

[Bastien]

Hi Tyler,

Tyler Smith <tyler.smith@mail.mcgill.ca> writes:

> I'm using org-mode 7.8.03, which shipped with Emacs 24.0.94.1. The
> documentation for exporting html includes the following:
>
> 12.5.1 HTML export commands
> ---------------------------
>
> `C-c C-e h     (`org-export-as-html')'
>      Export as HTML file.  [...] If there is an active region(1), only
> the region will be
>      exported.
>
> However, I think this is incorrect. 

You're right there was a problem here, fixed now.

On top of this, pressing 1 after C-c C-e will now highlight 
the subtree to be exported.

Thanks,

-- 
 Bastien