From mboxrd@z Thu Jan 1 00:00:00 1970 Path: main.gmane.org!not-for-mail From: Luc Teirlinck Newsgroups: gmane.emacs.devel Subject: Undocumented hyperlinks in doc strings. Date: Wed, 8 Oct 2003 19:50:18 -0500 (CDT) Sender: emacs-devel-bounces+emacs-devel=quimby.gnus.org@gnu.org Message-ID: <200310090050.h990oIa15681@raven.dms.auburn.edu> NNTP-Posting-Host: deer.gmane.org X-Trace: sea.gmane.org 1065661046 31053 80.91.224.253 (9 Oct 2003 00:57:26 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Thu, 9 Oct 2003 00:57:26 +0000 (UTC) Original-X-From: emacs-devel-bounces+emacs-devel=quimby.gnus.org@gnu.org Thu Oct 09 02:57:24 2003 Return-path: Original-Received: from quimby.gnus.org ([80.91.224.244]) by deer.gmane.org with esmtp (Exim 3.35 #1 (Debian)) id 1A7P7M-0001U2-00 for ; Thu, 09 Oct 2003 02:57:24 +0200 Original-Received: from monty-python.gnu.org ([199.232.76.173]) by quimby.gnus.org with esmtp (Exim 3.35 #1 (Debian)) id 1A7P7M-00012R-00 for ; Thu, 09 Oct 2003 02:57:24 +0200 Original-Received: from localhost ([127.0.0.1] helo=monty-python.gnu.org) by monty-python.gnu.org with esmtp (Exim 4.24) id 1A7P5P-0004k7-Qo for emacs-devel@quimby.gnus.org; Wed, 08 Oct 2003 20:55:23 -0400 Original-Received: from list by monty-python.gnu.org with tmda-scanned (Exim 4.24) id 1A7P55-0004jy-85 for emacs-devel@gnu.org; Wed, 08 Oct 2003 20:55:03 -0400 Original-Received: from mail by monty-python.gnu.org with spam-scanned (Exim 4.24) id 1A7P4Z-0004SR-Am for emacs-devel@gnu.org; Wed, 08 Oct 2003 20:55:02 -0400 Original-Received: from [131.204.53.104] (helo=manatee.dms.auburn.edu) by monty-python.gnu.org with esmtp (Exim 4.24) id 1A7P4Y-0004R9-Mt for emacs-devel@gnu.org; Wed, 08 Oct 2003 20:54:30 -0400 Original-Received: from raven.dms.auburn.edu (raven.dms.auburn.edu [131.204.53.29]) by manatee.dms.auburn.edu (8.12.10/8.12.10) with ESMTP id h990sQAJ017691 for ; Wed, 8 Oct 2003 19:54:26 -0500 (CDT) Original-Received: (from teirllm@localhost) by raven.dms.auburn.edu (8.11.6+Sun/8.11.6) id h990oIa15681; Wed, 8 Oct 2003 19:50:18 -0500 (CDT) X-Authentication-Warning: raven.dms.auburn.edu: teirllm set sender to teirllm@dms.auburn.edu using -f Original-To: emacs-devel@gnu.org X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.2 Precedence: list List-Id: Emacs development discussions. List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+emacs-devel=quimby.gnus.org@gnu.org Xref: main.gmane.org gmane.emacs.devel:17007 X-Report-Spam: http://spam.gmane.org/gmane.emacs.devel:17007 Why does `default' get a hyperlink in the documentation string of `fringe-mode'? Is this a bug or a "feature"? `default' is not defined as a variable nor as a function, nor is it preceded by `info node' or `Info node', hence it is not covered by the list of possibilities described in (elisp)Documentation Tips. It is extremely important that this list be completely exhaustive and accurate if we want package authors to write good documentation strings. If the reason would be that `default' is a face, then apart from the lack of documentation (which could easily be fixed), I would also have the less easily fixed objection that faces just tend to have extremely common names such as `default', `mouse', `menu', `region', `button' `border', `fringe', `bold', and countless equally common ones, that are used for tons of other purposes. Systematically having to write `symbol' in front of them would be a lot more of a nuisance than for variables or functions, simply because the situation occurs so much more frequently. "Fake" hyperlinks like the one for `default' in the documentation string below are distracting and confusing. It misleadingly suggests that if you follow it, you will get more information about what the value `default' means. Instead you get to stare at completely unrelated face documentation. (defun fringe-mode (&optional mode) "Toggle appearance of fringes on all frames. Valid values for MODE include `none', `default', `left-only', `right-only', `minimal' and `half'. MODE can also be a cons cell where the integer in car will be used as left fringe width and the integer in cdr will be used as right fringe width. If MODE is not specified, the user is queried. It applies to all frames that exist and frames to be created in the future. If you want to set appearance of fringes on the selected frame only, see `set-fringe-style'." Sincerely, Luc.