From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: "Drew Adams" Newsgroups: gmane.emacs.bugs Subject: bug#12686: PATCH: ambiguous help doc strings Date: Thu, 25 Oct 2012 13:13:06 -0700 Message-ID: <45567D843F264708B215C86AABDF77C3@us.oracle.com> References: <87wqyh7i20.fsf@mail.jurta.org> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit X-Trace: ger.gmane.org 1351196045 4426 80.91.229.3 (25 Oct 2012 20:14:05 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Thu, 25 Oct 2012 20:14:05 +0000 (UTC) Cc: 12686@debbugs.gnu.org, "'Aaron S. Hawley'" To: "'Stefan Monnier'" Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Thu Oct 25 22:14:13 2012 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1TRToh-0003z9-4w for geb-bug-gnu-emacs@m.gmane.org; Thu, 25 Oct 2012 22:14:11 +0200 Original-Received: from localhost ([::1]:51995 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1TRToX-0003QV-J0 for geb-bug-gnu-emacs@m.gmane.org; Thu, 25 Oct 2012 16:14:01 -0400 Original-Received: from eggs.gnu.org ([208.118.235.92]:41726) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1TRToV-0003QP-1e for bug-gnu-emacs@gnu.org; Thu, 25 Oct 2012 16:14:00 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1TRToT-0004KF-N9 for bug-gnu-emacs@gnu.org; Thu, 25 Oct 2012 16:13:58 -0400 Original-Received: from debbugs.gnu.org ([140.186.70.43]:51697) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1TRToT-0004KB-Jc for bug-gnu-emacs@gnu.org; Thu, 25 Oct 2012 16:13:57 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.72) (envelope-from ) id 1TRTqT-0007yz-L9 for bug-gnu-emacs@gnu.org; Thu, 25 Oct 2012 16:16:01 -0400 X-Loop: help-debbugs@gnu.org Resent-From: "Drew Adams" Original-Sender: debbugs-submit-bounces@debbugs.gnu.org Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Thu, 25 Oct 2012 20:16:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 12686 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: Original-Received: via spool by 12686-submit@debbugs.gnu.org id=B12686.135119611929209 (code B ref 12686); Thu, 25 Oct 2012 20:16:01 +0000 Original-Received: (at 12686) by debbugs.gnu.org; 25 Oct 2012 20:15:19 +0000 Original-Received: from localhost ([127.0.0.1]:33715 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.72) (envelope-from ) id 1TRTpm-0007aI-KH for submit@debbugs.gnu.org; Thu, 25 Oct 2012 16:15:19 -0400 Original-Received: from userp1040.oracle.com ([156.151.31.81]:32385) by debbugs.gnu.org with esmtp (Exim 4.72) (envelope-from ) id 1TRTpj-0007V6-Lc for 12686@debbugs.gnu.org; Thu, 25 Oct 2012 16:15:17 -0400 Original-Received: from ucsinet22.oracle.com (ucsinet22.oracle.com [156.151.31.94]) by userp1040.oracle.com (Sentrion-MTA-4.2.2/Sentrion-MTA-4.2.2) with ESMTP id q9PKD8UE025315 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Thu, 25 Oct 2012 20:13:09 GMT Original-Received: from acsmt357.oracle.com (acsmt357.oracle.com [141.146.40.157]) by ucsinet22.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id q9PKD89U028436 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO); Thu, 25 Oct 2012 20:13:08 GMT Original-Received: from abhmt110.oracle.com (abhmt110.oracle.com [141.146.116.62]) by acsmt357.oracle.com (8.12.11.20060308/8.12.11) with ESMTP id q9PKD7Ti026725; Thu, 25 Oct 2012 15:13:07 -0500 Original-Received: from dradamslap1 (/130.35.178.248) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Thu, 25 Oct 2012 13:13:07 -0700 X-Mailer: Microsoft Office Outlook 11 In-Reply-To: Thread-Index: Ac2y5eTUr0XIbdRzR7aTp7QuQQvHrgAA0HeQ X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.6157 X-Source-IP: ucsinet22.oracle.com [156.151.31.94] X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.13 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 2) X-Received-From: 140.186.70.43 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: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Original-Sender: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.bugs:66055 Archived-At: > > But if this is not done right away, why not at least do as > > I suggested in the meantime: move the var-or-fn clause > > first, so that if a symbol is both it gets treated as both. > > > > And that would seem to be appropriate anyway, even if you > > also do as you suggest, to accommodate other symbols that do > > not correspond to a minor-mode but which have both var and > > fun definitions. IOW, minor modes are not the only case > > to consider, even if they are an important case. > > If the docstring explicitly refers to the function, I see no > reason why Emacs should show both the function and the var. 1. What doc string ("the docstring")? The fn has a doc string and so does the var. Perhaps you are talking about a (probably minority) case where one doc string explicitly refers to the other, e.g., a fn doc string mentions the var or vice versa, using a keyword (e.g. `variable'). If so, then yes, in that case there is no _need_ to show both together, and it would be fine not to. If you have an easy way of distinguishing that case, fine, it can be excluded. If you have no easy way, do you really want to scan the string to see if it mentions the same symbol preceded by a different keyword (e.g. `variable' or `option', for a fun doc string)? 2. But even if you do not bother to exclude that case, and you show both doc strings systematically, it's not a big deal. Typically, one or the other (usually the var) doc string is quite short. For example, the minor-mode varible `icicle-mode' has only this (boilerplate) as its doc (whereas the minor-mode function `icicle-mode' has a _long_ doc string): icicle-mode is a variable defined in `icicles-mode.el'. Its value is t Original value was nil Documentation: Non-nil if Icicle mode is enabled. See the command `icicle-mode' for a description of this minor mode. Setting this variable directly does not take effect; either customize it (see the info node `Easy Customization') or call the function `icicle-mode'. You can customize this variable. And I think things are similar for most cases that are not minor modes. 3. If you really want to think about improving *Help* in a general way then I'd suggest that the problem is not (within reason) the amount of info we provide but inadequate organization of it. For `C-h m' we have tried to impose at least some organization, but essentially that amounts to only (a) a header line of links to (b) sequentially listed "sections" that are Emacs pages. Kind of like a 1990s FAQ web page with an index/TOC at the top followed by all of the FAQs. Those header links for `C-h m' are ugly (bold should be banned from Emacs defaults, because it just doesn't work well for lots of faces), but they are better than nothing. Better might be a tabbed organization of the info. For a symbol such as `icicle-mode' there could be tabs for the command and the option, for example. For `C-h m' there could be a major-mode tab and a tab for each minor mode. Or some such. And there are other ways to organize info, besides tabs. The point here really is that rather than getting excited about finding ways to exclude some information we should start by including as much as might be pertinent (fn, var, face,...) and then work on designing a better organized UI.