From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: MON KEY Newsgroups: gmane.emacs.bugs Subject: bug#6486: documentation of `byte-code-function-p' should mention `symbol-function' and xref manual Date: Tue, 22 Jun 2010 17:56:16 -0400 Message-ID: References: NNTP-Posting-Host: lo.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=UTF-8 X-Trace: dough.gmane.org 1277243950 29489 80.91.229.12 (22 Jun 2010 21:59:10 GMT) X-Complaints-To: usenet@dough.gmane.org NNTP-Posting-Date: Tue, 22 Jun 2010 21:59:10 +0000 (UTC) Cc: kevin.d.rodgers@gmail.com To: 6486@debbugs.gnu.org Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Tue Jun 22 23:59:08 2010 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([199.232.76.165]) by lo.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1ORBUp-0002X5-BU for geb-bug-gnu-emacs@m.gmane.org; Tue, 22 Jun 2010 23:59:07 +0200 Original-Received: from localhost ([127.0.0.1]:41773 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1ORBUo-0000aB-T1 for geb-bug-gnu-emacs@m.gmane.org; Tue, 22 Jun 2010 17:59:06 -0400 Original-Received: from [140.186.70.92] (port=50678 helo=eggs.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1ORBUi-0000a6-ML for bug-gnu-emacs@gnu.org; Tue, 22 Jun 2010 17:59:01 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.69) (envelope-from ) id 1ORBUh-0003nb-3y for bug-gnu-emacs@gnu.org; Tue, 22 Jun 2010 17:59:00 -0400 Original-Received: from debbugs.gnu.org ([140.186.70.43]:34199) by eggs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1ORBUg-0003nU-WC for bug-gnu-emacs@gnu.org; Tue, 22 Jun 2010 17:58:59 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.69) (envelope-from ) id 1ORBSo-00039O-A4; Tue, 22 Jun 2010 17:57:02 -0400 X-Loop: help-debbugs@gnu.org In-Reply-To: Resent-From: MON KEY Original-Sender: debbugs-submit-bounces@debbugs.gnu.org Resent-To: owner@debbugs.gnu.org Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Tue, 22 Jun 2010 21:57:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 6486 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: Original-Received: via spool by 6486-submit@debbugs.gnu.org id=B6486.127724378312102 (code B ref 6486); Tue, 22 Jun 2010 21:57:02 +0000 Original-Received: (at 6486) by debbugs.gnu.org; 22 Jun 2010 21:56:23 +0000 Original-Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1ORBSA-000399-D3 for submit@debbugs.gnu.org; Tue, 22 Jun 2010 17:56:23 -0400 Original-Received: from mail-gx0-f172.google.com ([209.85.161.172]) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1ORBS8-000394-K1 for 6486@debbugs.gnu.org; Tue, 22 Jun 2010 17:56:21 -0400 Original-Received: by gxk8 with SMTP id 8so467151gxk.3 for <6486@debbugs.gnu.org>; Tue, 22 Jun 2010 14:56:16 -0700 (PDT) Original-Received: by 10.150.160.18 with SMTP id i18mr6828137ybe.100.1277243776444; Tue, 22 Jun 2010 14:56:16 -0700 (PDT) Original-Received: by 10.150.181.11 with HTTP; Tue, 22 Jun 2010 14:56:16 -0700 (PDT) X-Google-Sender-Auth: oaa5nL4zPJyCoJ0IoYuWBlgzUIE X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list Resent-Date: Tue, 22 Jun 2010 17:57:02 -0400 X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 3) X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Original-Sender: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.bugs:37955 Archived-At: Kevin Rodgers wrote: >> How is the user supposed to know that OBJECT will only return t if >> it is the unreadable vector returned by `symbol-function'? > From (elisp)What Is a Function: > Unlike `functionp', the next three functions do _not_ treat a > symbol as its function definition. This doesn't address the "unreadable vector" return value though. It says (briefly) that we may have such a thing returned but not under which circumstances nor does it say what to do with such a thing once we have hold of it. e.g. that (require 'disass) ;; assuming it isn't loaded yet (vconcat (symbol-function 'disassemble-internal)) will return something readable. >> Please add documentation of such, along with info node xref such >> as: See info node `(elisp) Byte-Code Objects' > Nah, that is why we have M-x elisp-index-search -- So why then do certain function docs do have info node xrefs. If including info xrefs in docstrings extends clarity where there was none before what is the disadvantage to adding one here for `byte-code-function-p' as well? Why is Juri Linkov working on extending info like capablities to `help-mode' and vice versa? Because having relevant documentation at hand is useful. Especially so since, "Emacs is the extensible, customizable, --> self-documenting real-time display editor." Besides, last I checked Info was a separate (though incestuously coupled) facility from Emacs. e.g. from command-line: $> info emacs The point being that where info might provide additional relevant information w/re `byte-code-function-p' it does so only tangentially. IOW `byte-code-function-p' is to Emacs-Lisp as the `lsearch' function is to libc. That each is documented by the Info facility does not mean that Emacs Lisp doesnn't maintain an internal documentation consistent with its usage. > although it might be nice if such links were automatically generated > by the describe-* commands. Yes well, hooking this into describe-* commands will most-likely require the implementor(s) to understand usage of the `byte-code-function-p' predicate :P This goes doubly so for those wishing to extend such a feature to third party packages... >> Also, note that the nature of the data-structure/readability of a >> byte-code'd function can not be deduced by the user by simply >> reading the manual section: >> (info "(elisp)What Is a Function") > The nature of several types can't be deduced by the node that > describes the corresponding predicate, but by the node that actually > describes the type (under the Programming Types or Editing Types > node). The problem in this particular circumstance is that the objects returnd by `symbol-function' and `indirect-function' are: a) variadic according to whether the function is subr'd, byte-code'd, interpreted, indirect'd, macro'd, autoload'd (byte-code-function-p (symbol-function 'concat)) ;=> nil (symbol-function 'concat) ;=> # (subrp (symbol-function 'concat)) ;=>t (symbol-function 'with-current-buffer) ;=> (macro . #[ ... ]) (symbol-function 'lisp-mode) ;=> #[ ... ] (symbol-function 'common-lisp-mode) ;=> lisp-mode (indirect-function 'common-lisp-mode) ;=> #[ ... ] (eq (indirect-function 'common-lisp-mode) (symbol-function 'lisp-mode)) ;=> t (symbol-function 'dunnet) ;=> (autoload "dunnet" 940287 t nil) (byte-code-function-p (symbol-function 'dunnet)) ;=> nil (require 'dunnet) ;=> brought autoload'd symbol `dunnet' into environment. (symbol-function 'dunnet) ;=> #[ ... ] (byte-code-function-p (symbol-function 'dunnet)) ;=> t (defun my-bubba (x) "bubba returns t when X is eq X." (eq x x)) (symbol-function 'my-bubba) ;=> (lambda (x) "bubba returns t when X is eq X." (eq x x)) (defalias 'bubba-in-disguise 'my-bubba) (symbol-function 'bubba-in-disguise) ;=> my-bubba (indirect-function 'bubba-in-disguise) ;=> (lambda (x) "bubba returns t when X is eq X." (eq x x)) (byte-compile 'my-bubba) ;=> #[(x) "\x8\211=\207" [x] 2 "bubba returns t when X is eq X."] (symbol-function 'my-bubba) ;=> #[(x) "\x8\211=\207" [x] 2 "bubba returns t when X is eq X."] (symbol-function 'bubba-in-disguise) ;=> my-bubba (indirect-function 'bubba-in-disguise) ;=> #[(x) "\x8\211=\207" [x] 2 "bubba returns t when X is eq X."] b) apropos a two of the "types" of return values above aren't readable c) apropos b one of the "types" can't even be coerced into readability. e.g. this is coercable: (vconcat (cdr (symbol-function 'with-current-buffer))) :NOTE FOLLOWING FORM MAY HANG EVAL IN A DISPOSABLE Emacs! this is not: (read (symbol-function 'concat)) c) apropos b and c, and because we don't have features like `print-unreadable-object' or `readably-printable' to help us w/ frobbing "type" it is important that the user be afforded some additional clarity within the docs independently of the manual w/re how to accomplish such things. > (elisp)What Is a Function does say: > "byte-code function" > A "byte-code function" is a function that has been compiled by the > byte compiler. *Note Byte-Code Type::. Unless it is a subr or an autoload or a macro... See above. > And (elisp)Byte-Code Type (referenced above) says: > > The printed representation and read syntax for a byte-code function > object is like that for a vector, with an additional `#' before the > opening `['. So, currently an un-informed user now has to xref 3x info nodes: (info "(elisp)Byte-Code Type") (info "(elisp)Byte-Code Objects") (info "(elisp)What Is a Function") To reach the conclusion that the OBJECT arg to byte-code-function-p is (with qualifications) per the return value of `symbol-function', `indirect-function'. This is why I feel justified in asserting that the docstring of `byte-code-function-p', "does not adequately indicate that the OBJECT arg is as per the return value of `symbol-function'." And requested that, "documentation of such, along with info node xref such as: See info node `(elisp) Byte-Code Objects'" be provided. Neither of which strike me as all that unreasonable. > Kevin Rodgers -- /s_P\