bug#4026: `characterp' undocumented optional arg 'ignore'

bug#4026: `characterp' undocumented optional arg 'ignore'

[MON KEY]

`characterp' has undocumented optional arg 'ignore'

This may be another one of the +/- 500 `bootstrapping documentation' arg bugs...
If not, following is what I found:

---
@Circa line 313 in "../src/character.c"

       doc: /* Return non-nil if OBJECT is a character.  */)

---
(describe-function 'characterp)

;;; docstring in *Help*

"characterp is a built-in function in `character.c'.

(characterp object &optional ignore)

Return non-nil if object is a character."

---
(info "(elisp)Character Codes)")

@Circa line 313 of "../info/elisp-7" as from "./elisp.texi" of Emacs
version 23.1.50

" -- Function: characterp charcode
     This returns `t' if CHARCODE is a valid character, and `nil'
     otherwise."

----
In GNU Emacs 23.1.50.1 (i386-mingw-nt5.1.2600)
 of 2009-06-30 on LENNART-69DE564 (patched)
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (3.4) --cflags -Ic:/g/include'

bug#4026: `characterp' undocumented optional arg 'ignore'

[martin rudalics]

 > `characterp' has undocumented optional arg 'ignore'
 >
 > This may be another one of the +/- 500 `bootstrapping documentation' arg bugs...

... which are not really bugs.

 > If not, following is what I found:
 >
 > ---
 > @Circa line 313 in "../src/character.c"
 >
 >        doc: /* Return non-nil if OBJECT is a character.  */)
 >
 > ---
 > (describe-function 'characterp)
 >
 > ;;; docstring in *Help*
 >
 > "characterp is a built-in function in `character.c'.
 >
 > (characterp object &optional ignore)
 >
 > Return non-nil if object is a character."
 >
 > ---
 > (info "(elisp)Character Codes)")
 >
 > @Circa line 313 of "../info/elisp-7" as from "./elisp.texi" of Emacs
 > version 23.1.50
 >
 > " -- Function: characterp charcode
 >      This returns `t' if CHARCODE is a valid character, and `nil'
 >      otherwise."

In my code I run an extra check whether an argument is called IGNORE(D)
and do _not_ flag an error in that case.  A more comprehensive list of
what my code currently considers a bug in the Elisp manual is given
below.  I'd appreciate if people could help me point out other false
positives.

martin



buffers.texi:725:8 `inhibit-read-only' is an option
commands.texi:130:9 `interactive' has mismatching optional or rest of arguments
commands.texi:948:8 `global-disable-point-adjustment' is an option
commands.texi:1201:6 Use @kbd for @code{M-f3}
commands.texi:1453:6 Use @kbd for @code{M-double-mouse-2}
commands.texi:3135:7 `recursive-edit' is a command
compile.texi:637:15 `disassemble' lacks description of argument `indent'
control.texi:757:7 `error' has mismatching optional or rest of arguments
debugging.texi:431:7 `debug' is a command
display.texi:126:8 `redisplay-dont-pause' is an option
display.texi:132:8 `redisplay-preemption-period' is an option
display.texi:178:8 `default-truncate-lines' is not an option
display.texi:2289:7 `set-face-foreground' is a command
display.texi:2290:8 `set-face-background' is a command
display.texi:2296:7 `set-face-stipple' is a command
display.texi:2301:7 `set-face-font' is a command
display.texi:2318:7 `set-face-underline-p' is a command
display.texi:2323:7 `set-face-inverse-video-p' is a command
display.texi:2328:7 `invert-face' is a command
display.texi:2365:7 `face-font' lacks description of argument `character'
display.texi:2574:7 `make-face' is a command
display.texi:2574:7 `make-face' lacks description of optional argument(s).
display.texi:2599:7 `face-id' lacks description of optional argument(s).
display.texi:2826:8 `font-list-limit' is an option
display.texi:3159:8 `fringes-outside-margins' is an option
display.texi:3165:8 `left-fringe-width' is an option
display.texi:3171:8 `right-fringe-width' is an option
display.texi:3261:8 `fringe-indicator-alist' is an option
display.texi:3356:8 `fringe-cursor-alist' is an option
display.texi:3608:8 `scroll-bar-width' is an option
display.texi:3968:8 `left-margin-width' is an option
display.texi:3973:8 `right-margin-width' is an option
files.texi:2994:64 Use non-@code{nil} instead of non-nil
files.texi:3029:8 `buffer-auto-save-file-format' is an option
frames.texi:115:7 `make-frame' is a command
frames.texi:1363:7 `select-frame' is a command
frames.texi:1837:8 `void-text-area-pointer' is an option
frames.texi:1876:15 `x-set-selection' is not a command
functions.texi:517:9 `defun' lacks description of argument `body...'
functions.texi:782:7 `ignore' is a command
functions.texi:1199:7 `make-obsolete' is a command
help.texi:494:7 `read-kbd-macro' is a command
help.texi:607:7 `describe-prefix-bindings' is a command
keymaps.texi:1267:6 Use @kbd for @code{C-H-left}
keymaps.texi:2706:8 `auto-resize-tool-bars' is an option
keymaps.texi:2719:8 `auto-raise-tool-bar-buttons' is an option
keymaps.texi:2724:8 `tool-bar-button-margin' is an option
keymaps.texi:2729:8 `tool-bar-button-relief' is an option
keymaps.texi:2734:8 `tool-bar-border' is an option
macros.texi:205:9 `defmacro' lacks description of argument `[decl]'
maps.texi:80:19 Use @key for @kbd{ESC}
minibuf.texi:503:8 `history-add-new-input' is an option
minibuf.texi:1325:11 Use non-@code{nil} instead of non-nil
minibuf.texi:1395:41 Use @kbd for @code{M-x set-visited-file-name}
modes.texi:716:15 `describe-mode' lacks description of optional argument(s).
modes.texi:740:8 `define-derived-mode' has mismatching optional or rest of arguments
modes.texi:1398:8 `define-minor-mode' has mismatching optional or rest of arguments
modes.texi:2166:7 `imenu-add-to-menubar' is a command
modes.texi:2679:8 `font-lock-keywords-case-fold-search' is an option
modes.texi:2766:8 `font-lock-mark-block-function' is an option
modes.texi:2969:8 `font-lock-keywords-only' is an option
modes.texi:2983:8 `font-lock-beginning-of-syntax-function' is an option
nonascii.texi:107:8 `default-enable-multibyte-characters' is an option
nonascii.texi:617:7 `decode-char' lacks description of optional argument(s).
nonascii.texi:628:7 `encode-char' lacks description of optional argument(s).
nonascii.texi:985:8 `file-name-coding-system' is an option
nonascii.texi:1138:41 Use @key for @code{ESC}
nonascii.texi:1780:8 `default-buffer-file-type' is not an option
nonascii.texi:1818:15 `set-input-method' lacks description of optional argument(s).
os.texi:861:15 `setenv' lacks description of argument `substitute-env-vars'
os.texi:1661:8 `timer-max-repeats' is an option
os.texi:2044:7 `play-sound-file' is a command
processes.texi:98:8 `exec-suffixes' is an option
processes.texi:600:7 `start-file-process-shell-command' has mismatching optional or rest of arguments
processes.texi:1039:54 Use @key for @code{DEL}
processes.texi:1076:7 `signal-process' is a command
streams.texi:802:8 `print-circle' is an option
streams.texi:814:8 `print-continuous-numbering' is an option
text.texi:1724:7 `fill-context-prefix' lacks description of optional argument(s).
text.texi:3489:61 Use @key for @kbd{RET}
text.texi:4028:15 `base64-encode-string' is not a command
text.texi:4040:7 `base64-decode-region' is a command
variables.texi:432:9 `defvar' has mismatching optional or rest of arguments
variables.texi:1752:7 `dir-locals-set-directory-class' lacks description of optional argument(s).
variables.texi:1835:7 `make-obsolete-variable' is a command
windows.texi:1788:8 `auto-window-vscroll' is an option
windows.texi:2219:8 `window-size-fixed' is an option

bug#4026: `characterp' undocumented optional arg 'ignore'

[MON KEY]

Tue, Aug 4, 2009 at 12:44 PM, martin rudalics<rudalics@gmx.at> wrote:
This may be another one of the +/- 500 `bootstrapping documentation' arg
>> bugs...
>
> ... which are not really bugs.

Well they certainly aren't features! :)

> below.  I'd appreciate if people could help me point out other false
> positives.

How would you like these to be formatted/pointed out.
What is most useful for you/your code?
What are your criterion for 'false positives'?

> martin

s_P

bug#4026: `characterp' undocumented optional arg 'ignore'

[martin rudalics]

 >> below.  I'd appreciate if people could help me point out other false
 >> positives.
 >
 > How would you like these to be formatted/pointed out.
 > What is most useful for you/your code?

People would have to look at the functions/variables they are familar
with and check whether my code flags the error correctly.  If it does,
the manual (or the definition) should be corrected.  If it is flagged
incorrectly, a simple note why it is correct should be sufficent for me
to change my code appropriately.

Obviously, anyone seriously interested should run my code because it can
automatically display (in separate windows) the corresponding texinfo
lines and the Elisp source.

 > What are your criterion for 'false positives'?

Social feedback - and this goes for false negatives as well ;-)

martin, who'd like that list get empty before the next release

bug#4026: `characterp' undocumented optional arg 'ignore'

[MON KEY]

On Tue, Aug 4, 2009 at 1:31 PM, martin rudalics<rudalics@gmx.at> wrote:
> Obviously, anyone seriously interested should run my code because it can
> automatically display (in separate windows) the corresponding texinfo
> lines and the Elisp source.
>

Sorry in advance for being so dense, but what/where specifically is this code?

s_P

bug#4026: `characterp' undocumented optional arg 'ignore'

[martin rudalics]

[-- Attachment #1: Type: text/plain, Size: 410 bytes --]

 > Sorry in advance for being so dense, but what/where specifically is this code?

It's code on my machine; see the attached copy.  Your entry point is
`elinfo-check-directory'.  If you set `elinfo-log-warnings' to a non-nil
value, you should be also able to see some 600 "bugs" where the argument
names differ in code and manual.  So I hope to convince you that fixing
all these is hardly fesible ;-)

martin

[-- Attachment #2: elinfo.el --]
[-- Type: application/emacs-lisp, Size: 49693 bytes --]

bug#4026: `characterp' undocumented optional arg 'ignore'

[Stefan Monnier]

>> Sorry in advance for being so dense, but what/where specifically is
>> this code?

> It's code on my machine; see the attached copy.  Your entry point is
> `elinfo-check-directory'.  If you set `elinfo-log-warnings' to a non-nil
> value, you should be also able to see some 600 "bugs" where the argument
> names differ in code and manual.  So I hope to convince you that fixing
> all these is hardly fesible ;-)

Why don't you add it somewhere (e.g. maybe in the `admin' or `test'
subdir)?


        Stefan

bug#4026: `characterp' undocumented optional arg 'ignore'

[martin rudalics]

 > Why don't you add it somewhere (e.g. maybe in the `admin' or `test'
 > subdir)?

I haven't tested most of its functionality yet.  As soon as I've done
that I can add it to `admin'.

martin

bug#4026: `characterp' undocumented optional arg 'ignore'

[Lars Magne Ingebrigtsen]

MON KEY <monkey@sandpframing.com> writes:

> `characterp' has undocumented optional arg 'ignore'

It's called `ignore', and it's optional.  I think you can ignore it.

Closing this bug report.

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/

bug#4026: `characterp' undocumented optional arg 'ignore'

[Andreas Schwab]

The ignored argument is no longer advertised.

Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."