From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: "Drew Adams" Newsgroups: gmane.emacs.devel Subject: RE: Fontless Info Date: Tue, 19 Feb 2013 20:02:56 -0800 Message-ID: References: <874nh8ybnz.fsf@dimension8.tehua.net><87mwv0zk06.fsf@thinkpad.tsdh.de> <83r4kcp95y.fsf@gnu.org> <20130219232347.GC4377@acm.acm> 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 1361333512 17426 80.91.229.3 (20 Feb 2013 04:11:52 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Wed, 20 Feb 2013 04:11:52 +0000 (UTC) Cc: 'Eli Zaretskii' , emacs-devel@gnu.org, aidalgol@no8wireless.co.nz, 'Tassilo Horn' To: "'Alan Mackenzie'" Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Wed Feb 20 05:12:14 2013 Return-path: Envelope-to: ged-emacs-devel@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 1U812R-00074M-Un for ged-emacs-devel@m.gmane.org; Wed, 20 Feb 2013 05:12:12 +0100 Original-Received: from localhost ([::1]:42101 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1U8127-0002mf-A8 for ged-emacs-devel@m.gmane.org; Tue, 19 Feb 2013 23:11:51 -0500 Original-Received: from eggs.gnu.org ([208.118.235.92]:46453) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1U8120-0002m0-Ok for emacs-devel@gnu.org; Tue, 19 Feb 2013 23:11:46 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1U811z-0000MZ-Iq for emacs-devel@gnu.org; Tue, 19 Feb 2013 23:11:44 -0500 Original-Received: from aserp1040.oracle.com ([141.146.126.69]:28127) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1U80te-0006V4-Jf; Tue, 19 Feb 2013 23:03:06 -0500 Original-Received: from ucsinet21.oracle.com (ucsinet21.oracle.com [156.151.31.93]) by aserp1040.oracle.com (Sentrion-MTA-4.3.1/Sentrion-MTA-4.3.1) with ESMTP id r1K433qG003454 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Wed, 20 Feb 2013 04:03:04 GMT Original-Received: from acsmt356.oracle.com (acsmt356.oracle.com [141.146.40.156]) by ucsinet21.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id r1K4328j004509 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO); Wed, 20 Feb 2013 04:03:02 GMT Original-Received: from abhmt108.oracle.com (abhmt108.oracle.com [141.146.116.60]) by acsmt356.oracle.com (8.12.11.20060308/8.12.11) with ESMTP id r1K432xW002399; Tue, 19 Feb 2013 22:03:02 -0600 Original-Received: from dradamslap1 (/71.202.147.44) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Tue, 19 Feb 2013 20:03:02 -0800 X-Mailer: Microsoft Office Outlook 11 In-Reply-To: <20130219232347.GC4377@acm.acm> X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.6157 Thread-Index: Ac4O+ECrVnOo0tVPSEaDVqibyf+SLAAJE47Q X-Source-IP: ucsinet21.oracle.com [156.151.31.93] X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.4.x-2.6.x [generic] X-Received-From: 141.146.126.69 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:157185 Archived-At: > > Our help system sends the user on a wild goose chase here. > > S?he has no hope of reorientation and finding a way out > > of the swamp. You can't get there from here. > > I agree with you, here. However, that info, "font-core.el" > needs to be in the C-h f somewhere, since that is where the > macro invocation is that generated > `global-font-lock-mode-check-buffers'. But information is > missing, more precisely, that that defun was generated by > the macro define-globalized-minor-mode. Yes, that's the info missing. More precisely, that that function is created in the process of defining globalized minor mode whatever. At least it is good that the link takes you to the right place. That in itself is a strong hint that maybe the `define-globalized-mode' also creates this function. > May I suggest, even request, that you specify what the > information from C-h f should look like, See previous - say that it is defined as part of the process of defining the mode. And say what its relation is to the mode: it is a helper function that does... The description of what the function does, including how it is related to the particular mode, could be added to the doc generated doc string. But the `C-h f' info that introduces that doc, and which describes the location of the definition, should mention that it is defined in the process of defining the mode by `define-globalized-minor-mode. Or some such. The point is to add both: (a) some orientation info on where to find the definition (i.e., the fact that it gets defined as part of the mode definition) and (b) info about the relation of the generated function to the mode - what it does for the mode etc. > and perhaps even extend the infrastructure to implement it. Someone else will need to do that, I'm afraid. > > Emacs seems to be little-by-little losing its character of being > > self-documenting, by the use more and more of macros that > > generate functions without doc. And by the use more and more > > of `defstruct' without providing doc for accessor etc. > > functions. Dommage. > > > At the very least..., the doc for `define-globalized-minor-mode' > > should mention the objects that it creates, such as function > > `MODE-check-buffers'. > > This is partly done, in that a doc string for the global minor mode > function is generated, even if not for the helper functions. Yes, but that generated mode doc string does not mention the helper functions. The doc string for the mode should mention its associated functions, just like the doc for a defstruct should mention its helper functions. And the doc for each helper function should mention what it helps, and how. This is part of describing what it's for, what it does. > > > Since the voodoo of easy-mmode is beyond me, I'll let > > > others fix this. > > > Hear, hear. "Easy", indeed. Easy for those defining > > things, perhaps. Hard on Emacs users. Dommage. > > Shame indeed, but not beyond repair. That's good to hear.