Re: a property "definition-type" would help find macro-defined tests

[Eli Zaretskii <eliz@gnu.org>]

> From: Stephen Gildea <stepheng+emacs@gildea.com>
> 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.