From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.devel Subject: Re: a property "definition-type" would help find macro-defined tests Date: Fri, 10 Jan 2025 09:08:53 +0200 Message-ID: <86o70f16yi.fsf@gnu.org> References: <409838.1736484448@pental.sg.gildea.net> Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="964"; mail-complaints-to="usenet@ciao.gmane.io" Cc: emacs-devel@gnu.org To: Stephen Gildea Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Fri Jan 10 08:09:47 2025 Return-path: Envelope-to: ged-emacs-devel@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1tW99P-000Aeb-2i for ged-emacs-devel@m.gmane-mx.org; Fri, 10 Jan 2025 08:09:47 +0100 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tW98f-0008K5-D7; Fri, 10 Jan 2025 02:09:01 -0500 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1tW98c-0008Jh-95 for emacs-devel@gnu.org; Fri, 10 Jan 2025 02:08:59 -0500 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1tW98b-0007nh-4e; Fri, 10 Jan 2025 02:08:57 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=References:Subject:In-Reply-To:To:From:Date: mime-version; bh=hyvUgwMEgqRCGfVMXkuLfL0pbagwyI0VSta5lYFaNcY=; b=cJgpcXc6j5aO sIynCvm/SI0/GFKamclSCLeKyZsVtpD6vcRDSBPFCyqg8kq8keD5RlSIrDxaXbsLkiadQVOI8HNga 8g8HKNwDpZIL34Pw/fX/EKcXX5R0DRUsJSrOs4yE54WUE/+Q1MyhfhaJvmGyBElU1hQ7/AM/tyHuf 3YxSYoc3BEPlRyFoqMoH1PA6ouJEMM64uPoc2UjJp+8jot9Qs3U9GKL9ptXLXVR8qG1ZdGJYFUaWS CGz/EOikH1U7gFR53/7qkfvvitJA9/aucaJnledNVFkCAeD+S941nI2139PIc4Mkkfs8XpnvQsx8q W6oMKw+JVhFobOaQT56rHw==; In-Reply-To: <409838.1736484448@pental.sg.gildea.net> (message from Stephen Gildea on Thu, 09 Jan 2025 20:47:28 -0800) X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.29 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-mx.org@gnu.org Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Xref: news.gmane.io gmane.emacs.devel:327827 Archived-At: > From: Stephen Gildea > Date: Thu, 09 Jan 2025 20:47:28 -0800 > > I have made the changes requested and one other: > > - added a NEWS entry > > - find-function-search-for-symbol doc string additions > trimmed of detail that is available from the manual. > > - in the manual, added an index entry for the new property, > definition-type, and for all the existing properties that > did not have index entries (which was most of them). > > - in the code example, put each top-level form in @group. > > - new in this version of the patch: added a cross reference > from where Coding Conventions discusses how to write macros > that define functions. Thanks. A few remaining nits below. > ++++ > +** New property 'definition-type' used by find-function and friends. "find-function" should be quoted 'like this'. > +Macros that define an object in a way makes the object's name and the ^ I think "that" is missing there. > @item :advertised-binding > +@cindex @code{:advertised-binding} property I think all these index entries should use "symbol property" instead of the more general "property", to distinguish them from other kinds of properties we have in Emacs. Also, please move the index entries to _before_ the corresponding @item's, so that following the index search will place point on the line produced from the @item, not the line after it. > @item customized-face > +@cindex @code{customized-face} property > @itemx face-defface-spec > +@cindex @code{face-defface-spec} property > @itemx saved-face > +@cindex @code{saved-face} property > @itemx theme-face > +@cindex @code{theme-face} property I generally find it to be more useful to have all the index entries together before the @item..@itemx...@item lines. That way, when the readers follow the index search, they see names of all the items discussed in the following text, which I think is better. > +Here is an example using a function to find the definition: > + > +@example > +@group > +(defmacro define-foo-test (data) > + "Define a test of the foo system using DATA." > + (declare (debug (&rest sexp))) > + (let ((test-name (intern (concat ...)))) > + `(progn > + (put ',test-name 'definition-type 'foo-test-type) > + (ert-deftest ,test-name () > + ,(concat "Test foo with " ...) > + ...)))) > +@end group > +@end example > + > +@example > +@group You don't need to @end example when you @end group. Instead, have only one @example..@end example around all the groups. The "@group..@end group" will prevent Texinfo from inserting a page break inside the groups, so page breaks will be only between the groups. Thanks again for working on this.