Re: master 2a7488d: Add support for displaying short documentation for function groups

Re: master 2a7488d: Add support for displaying short documentation for function groups

[Lars Ingebrigtsen]

larsi@gnus.org (Lars Ingebrigtsen) writes:

>     Add support for displaying short documentation for function groups

After tinkering with this for a while on a branch, I've now merged the
shortdoc stuff into the trunk.  The main idea is taken from what is,
according to the entire internet, the Platonic ideal in documentation:

  https://github.com/magnars/s.el

So it's a list of functions and examples.

It could probably do with a bit more tinkering, looks-wise.

The easiest way to experience it is to say `C-h f string-trim RET' and
then clicking on the button.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: master 2a7488d: Add support for displaying short documentation for function groups

[Eli Zaretskii]

> From: Lars Ingebrigtsen <larsi@gnus.org>
> Date: Sun, 11 Oct 2020 05:55:23 +0200
> 
> After tinkering with this for a while on a branch, I've now merged the
> shortdoc stuff into the trunk.

Thanks.  I think this is a very useful documentation feature.

Some comments and thoughts:

1) Is "shortdoc" the best name for this?  This is not really some
short form of existing documentation, it is something else.  Unless we
plan to add more similar features, how about "help-func-groups" or
"help-func-summaries" instead?

2) A better name for the shortdoc-display-group command would be
something like describe-function-group or somesuch -- this is
basically a help command.  (And how about adding it to the Help menu?)

3) An apropos-style command regarding the known groups should probably
be added.  As long as the list of the groups is short, just C-h (which
already works) is enough, but that will become inconvenient as the
list grows, I think.

4) Invoking shortdoc-display-group with "file" as the group signals an
error.  Looks like we lack some auto-loading machinery here.

5) Pushing the button with a function name in the group display pops
up the ELisp manual.  I wonder whether this is a good idea: why not
show the full doc string of the function instead?  Come think about
it, why not _insert_ the full doc string right after the function's
signature, in the same buffer, instead of popping up a new buffer?

6) I question the particular faces used for the display.  Do you
really find the gray background to be such a good idea?

7) Loading the entire database of all the groups at once sounds
un-economical, especially if we envision that the groups will grow and
their number will increase.  Should we perhaps have a separate DB file
for each group?

8) The information stored in the group consists of 2 separate parts:

  . the functions that belong to a group
  . the examples of using each function

These 2 are not necessarily tightly coupled, and the examples are
useful on their own right.  For example, should we perhaps make the
examples of using a particular function accessible from the *Help*
buffer that describes that function?  The "group" button is not an
efficient way of seeing those examples because it shows the entire
group, not the function from which we started.

Also, how about some facility to add a description or explanation of
what each example does?  It's IME sub-optimal to expect the reader to
glean that on his/her own just by looking at the call and the result,
especially when there are several non-trivial arguments.

9) Do we really need all the type keywords (:eval, :eg-result, etc.)?
I'm not sure I understand why not just evaluate the example and
produce the result automatically, without all those different types?
E.g., it sounds artificial to me to use :no-eval* to get "[it
depends]", instead of just saying "[it depends]" explicitly.

10) This should be documented in the user manual, as all other Help
commands.

Re: master 2a7488d: Add support for displaying short documentation for function groups

[Lars Ingebrigtsen]

Eli Zaretskii <eliz@gnu.org> writes:

> 1) Is "shortdoc" the best name for this?  This is not really some
> short form of existing documentation, it is something else.  Unless we
> plan to add more similar features, how about "help-func-groups" or
> "help-func-summaries" instead?

Yes, it's a bad name; I tried coming up with a better name over a
month's time, but I just blanked.

> 2) A better name for the shortdoc-display-group command would be
> something like describe-function-group or somesuch -- this is
> basically a help command.  (And how about adding it to the Help menu?)

Hm...  function-overview?  function-group-overview?

And, yes, it should go in the Help menu.

> 3) An apropos-style command regarding the known groups should probably
> be added.  As long as the list of the groups is short, just C-h (which
> already works) is enough, but that will become inconvenient as the
> list grows, I think.

I'm not sure the list will grow all that much, though.  This stuff is
primarily useful for function discovery, and that's mostly useful when
talking about the "built-in", base functions, like the
string/list/vector manipulation functions, and not something like, say,
shr.  The latter is best handled in a traditional manual.

> 4) Invoking shortdoc-display-group with "file" as the group signals an
> error.  Looks like we lack some auto-loading machinery here.

I'll have a look.

> 5) Pushing the button with a function name in the group display pops
> up the ELisp manual.  I wonder whether this is a good idea: why not
> show the full doc string of the function instead?  Come think about
> it, why not _insert_ the full doc string right after the function's
> signature, in the same buffer, instead of popping up a new buffer?

I think the manual gives superior information in most cases, so I'd
really like this to link to the manual and not the doc strings.  This is
also a way to guide users into the manual and read more in-depth about
not just the functions described, but the machinery surrounding them,
giving them more context.

> 6) I question the particular faces used for the display.  Do you
> really find the gray background to be such a good idea?

No.  But I experimented with various ways of grouping, and I couldn't
find anything that wouldn't just make everything look like...  mush...
and still be compact.  Suggestions are very welcome.

The problem is that the text is sparse, and it can be problematic seeing
where the next function definition starts when you're skimming the list,
and skimming is what it's all about.

> 7) Loading the entire database of all the groups at once sounds
> un-economical, especially if we envision that the groups will grow and
> their number will increase.  Should we perhaps have a separate DB file
> for each group?

I don't envision that the list will increase greatly.  Perhaps a couple
more groups, but that's it.

> 8) The information stored in the group consists of 2 separate parts:
>
>   . the functions that belong to a group
>   . the examples of using each function
>
> These 2 are not necessarily tightly coupled, and the examples are
> useful on their own right.  For example, should we perhaps make the
> examples of using a particular function accessible from the *Help*
> buffer that describes that function?  The "group" button is not an
> efficient way of seeing those examples because it shows the entire
> group, not the function from which we started.

Yes, using the examples in the normal *Help* output would make sense.

> Also, how about some facility to add a description or explanation of
> what each example does?  It's IME sub-optimal to expect the reader to
> glean that on his/her own just by looking at the call and the result,
> especially when there are several non-trivial arguments.

No, adding more text here would be counter-productive.  I think that
there's a substantial number of programmers that don't like reading
words, but they love seeing examples.  If they liked reading, they'd be
reading the manual already.

> 9) Do we really need all the type keywords (:eval, :eg-result, etc.)?
> I'm not sure I understand why not just evaluate the example and
> produce the result automatically, without all those different types?
> E.g., it sounds artificial to me to use :no-eval* to get "[it
> depends]", instead of just saying "[it depends]" explicitly.

:eval is for side-effect-free forms, and the result shown is what they
actually eval to.  The rest are needed when we can't eval, but we still
want to show an example of what form the result from the function would
typically be on.

But, yes, the :no-eval* bit could use some work.

> 10) This should be documented in the user manual, as all other Help
> commands.

I'll add that.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

RE: master 2a7488d: Add support for displaying short documentation for function groups

[Drew Adams]

> I think the manual gives superior information in most cases, so I'd
> really like this to link to the manual and not the doc strings.  This is
> also a way to guide users into the manual and read more in-depth about
> not just the functions described, but the machinery surrounding them,
> giving them more context.

*Help* should have a link to the relevant manual node.
See thread "How to make Emacs popular again."  That's not
hard to do, and it's been done (e.g. in `help-fns+.el').

The reverse isn't true.  (But of course `C-h S' works
anywhere.)  Better to show *Help*, which would have not
only a link to the relevant node(s) in manual(s) but also
links to the functions, vars, and faces mentioned in the
*Help*.

RE: master 2a7488d: Add support for displaying short documentation for function groups

[Gregory Heytings via Emacs development discussions.]

>> I think the manual gives superior information in most cases, so I'd 
>> really like this to link to the manual and not the doc strings.  This 
>> is also a way to guide users into the manual and read more in-depth 
>> about not just the functions described, but the machinery surrounding 
>> them, giving them more context.
>
> *Help* should have a link to the relevant manual node. See thread "How 
> to make Emacs popular again."  That's not hard to do, and it's been done 
> (e.g. in `help-fns+.el').
>

As I already explained repeatedly, this is _not_ the meaning of my 
proposal in that thread.

My proposal is to _manually_ add pointers to the relevant manual 
_chapters_ in docstrings.  For example, the docstring of kill-buffer would 
have two links, one to (info "(emacs)Buffers") and another one to (info 
"(elisp)Buffers"), with some explanation.  For example:

See also the following manual chapters: for interactive use, see `(emacs) 
Buffers'; for Emacs Lisp programming use, see `(elisp) Buffers'.

Your proposal is to merge a feature of help-fns+.el in help-fns.el.  This 
feature adds a link in *Help* buffers, and when the user clicks on that 
link the indexes of a (user chosen) list of manuals are checked to see if 
they contain pointers to the subject of the *Help* buffer.  Doing this is, 
as you said yourself, inefficient.  The result of this scan is presented 
in another buffer as a list of links, and when the user clicks on these 
links the place where the subject of the *Help* buffer is documented in 
the manual is displayed.

These are two very different proposals.

RE: master 2a7488d: Add support for displaying short documentation for function groups

[Drew Adams]

> >> I think the manual gives superior information in most cases, so I'd
> >> really like this to link to the manual and not the doc strings.  This
> >> is also a way to guide users into the manual and read more in-depth
> >> about not just the functions described, but the machinery surrounding
> >> them, giving them more context.
> >
> > *Help* should have a link to the relevant manual node. See thread "How
> > to make Emacs popular again."  That's not hard to do, and it's been done
> > (e.g. in `help-fns+.el').
> >
> 
> As I already explained repeatedly, this is _not_ the meaning of my
> proposal in that thread.

The thread is not only about your posts to it.

> My proposal is to _manually_ add pointers to the
> relevant manual _chapters_ in docstrings.

Yes, and I've voiced no objection to that.  I was the
one who pointed you to an example where we do that
already.

But you also said that you think we cannot provide
such links automatically.  And my response to that
is that we can.  And I have.  (And so have others.)
We can use that code, or we can use different code.

We can do both: we can have manual fiddling to add
links override/replace/augment any programmatically
provided links, when that's helpful.

So far, we have _VERY_ few manually provided links.
Nothing is stopping someone from proposing adding
this or that link manually.  Still, we have very
few, so far.

Today, you can use `C-h k C-h m' to get the *Help*
for `describe-mode', then click its `manuals' link:

  For more information see the manuals.

That gives you an Info Index buffer with two links:

  Index Matches
  *************

  Index entries that match `describe-mode':

  * Menu:

  * describe-mode [elisp]:   (elisp)Mode Help. (line 11)
  * describe-mode [emacs]:   (emacs)Misc Help. (line 36)

And those take you to these nodes, which provide the
doc for `describe-mode':

1. (emacs) Top > Help > Misc Help
2. (elisp) Top > Modes > Major Modes > Mode Help

> For example, the docstring of kill-buffer would
> have two links, one to (info "(emacs)Buffers") and another one to (info
> "(elisp)Buffers"), with some explanation.  For example:
> 
> See also the following manual chapters: for interactive use, see `(emacs)
> Buffers'; for Emacs Lisp programming use, see `(elisp) Buffers'.

And for `kill-buffer' the `manuals' link gives you
an Info Index buffer with these two links:

 * kill-buffer [elisp]:   (elisp)Killing Buffers. (line 31)
 * kill-buffer [emacs]:   (emacs)Kill Buffer. (line 22)

I think those are more appropriate targets than your
`Buffers' nodes.  But nothing prevents us from using
code that does what you prefer, if that's agreed upon.
It's not hard to get to the "chapter" node for a node
that the Index takes us to.

But there's a good reason why the Index entries for
`kill-buffer' take us to the nodes they do: they're
specifically about _that command_.

> Your proposal is to merge a feature of help-fns+.el in help-fns.el.  This
> feature adds a link in *Help* buffers, and when the user clicks on that
> link the indexes of a (user chosen) list of manuals are checked to see if
> they contain pointers to the subject of the *Help* buffer.  Doing this is,
> as you said yourself, inefficient.  The result of this scan is presented
> in another buffer as a list of links, and when the user clicks on these
> links the place where the subject of the *Help* buffer is documented in
> the manual is displayed.
> 
> These are two very different proposals.

They're different, yes, but not profoundly different.

And the inefficiency I referred to is likely from my
insufficient knowledge of using `info-lookup'.

With my code EITHER you can quickly get a direct link
to one of the manuals (that's what `info-lookup-symbols'
gives you), OR you can get a link that when clicked
looks up the symbol in each of the manuals and gives
you an Index list of links, as described above.  It's
a user choice.

The former is immediate, but it doesn't give you
links to each of the relevant manuals.  The latter
takes the time to perform index lookups.

But I'm sure that someone more familiar with the
`info-lookup' code can do better than I, providing
links to multiple manuals quickly.  And if that
possibility isn't yet available from info-lookup,
it can likely be coded.

My point is not that we need to use the `help-fns+.el'
code.  And it's not to exclude the addition of links
manually.

My point is that we can and should provide links to
the manuals from *Help*, and we can start doing that
today.  Improvements are always possible.

RE: master 2a7488d: Add support for displaying short documentation for function groups

[Gregory Heytings via Emacs development discussions.]

>
> But you also said that you think we cannot provide such links 
> automatically.  And my response to that is that we can.  And I have.
>

We can in theory, but it would be too inefficient, as you said yourself. 
I think that checking the indexes of the sixty info files whenever a 
*Help* buffer is opened is not feasible.

>
> So far, we have _VERY_ few manually provided links. Nothing is stopping 
> someone from proposing adding this or that link manually.  Still, we 
> have very few, so far.
>

It was the meaning of my proposal.  Now it has to be done, of course. 
But for this there needs to be an agreement that it's a good thing to do.

>> For example, the docstring of kill-buffer would have two links, one to 
>> (info "(emacs)Buffers") and another one to (info "(elisp)Buffers"), 
>> with some explanation.  For example:
>>
>> See also the following manual chapters: for interactive use, see 
>> `(emacs) Buffers'; for Emacs Lisp programming use, see `(elisp) 
>> Buffers'.
>
> And for `kill-buffer' the `manuals' link gives you an Info Index buffer 
> with these two links:
>
> * kill-buffer [elisp]:   (elisp)Killing Buffers. (line 31)
> * kill-buffer [emacs]:   (emacs)Kill Buffer. (line 22)
>
> I think those are more appropriate targets than your `Buffers' nodes.
>

I do not think so.  Remember that what triggered my proposal was a 
question by RMS: how to make manuals easier to access by newcomers.  If 
you provide these newcomers with three similar versions of the same 
information (the docstring of kill-buffer, the documentation of 
kill-buffer in the Emacs manual, the documentation of kill-buffer in the 
Emacs Lisp manual), they will not see the point of reading the manuals. 
If you point them to the beginning of a chapter, they will see something 
different, in which they can expect to (and will) find information about 
the context of the command or function, for example, what the related 
concepts are, and what other related functions can do.  A manual is a 
manual, not a dictionary.

>
> They're different, yes, but not profoundly different.
>

It depends how you define profound ;-)

>
> And the inefficiency I referred to is likely from my insufficient 
> knowledge of using `info-lookup'.
>

I do not think so, but I would be happy to be proven wrong.  It seems to 
me that searching the indexes of sixty info files takes time.

RE: master 2a7488d: Add support for displaying short documentation for function groups

[Drew Adams]

> > But you also said that you think we cannot provide such links
> > automatically.  And my response to that is that we can.  And I have.
> 
> We can in theory, but it would be too inefficient, as you said yourself.
> I think that checking the indexes of the sixty info files whenever a
> *Help* buffer is opened is not feasible.

That's not what happens.

The default behavior is to use `info-lookup-symbol'.
That's immediate.  It produces the link in *Help*
immediately, and when you click the link it
immediately goes to one of the manuals.

An alternative behavior also immediately produces
the link in *Help*.  But when you click the link
it accesses the Indexes of the manuals and takes
you to an Info Index with links to the manuals.
This alternative can give you a link to more than
one manual.  That's its advantage, but at the cost
of index lookups when you click the link.

Again, that's not the default behavior.

> >> See also the following manual chapters: for interactive use, see
> >> `(emacs) Buffers'; for Emacs Lisp programming use, see `(elisp)
> >> Buffers'.
> >
> > the `manuals' link gives you an Info Index buffer
> > with these two links:
> >
> > * kill-buffer [elisp]:   (elisp)Killing Buffers. (line 31)
> > * kill-buffer [emacs]:   (emacs)Kill Buffer. (line 22)
> >
> > I think those are more appropriate targets than your `Buffers' nodes.
> 
> I do not think so.  Remember that what triggered my proposal was a
> question by RMS: how to make manuals easier to access by newcomers.  If
> you provide these newcomers with three similar versions of the same
> information (the docstring of kill-buffer, the documentation of
> kill-buffer in the Emacs manual, the documentation of kill-buffer in the
> Emacs Lisp manual), they will not see the point of reading the manuals.
> If you point them to the beginning of a chapter, they will see something
> different, in which they can expect to (and will) find information about
> the context of the command or function, for example, what the related
> concepts are, and what other related functions can do.  A manual is a
> manual, not a dictionary.

We disagree about what manual pages the *Help* on
a command should link to.  And so far, at least,
the manual Indexes agree with me about this.  And
if the Indexes are ever changed to take you to the
chapter and not the more specific node, then the
same solution I proposed will do what you want.

IOW, the link should reflect our indexing.

> > And the inefficiency I referred to is likely from my insufficient
> > knowledge of using `info-lookup'.
> 
> I do not think so, but I would be happy to be proven wrong.  It seems to
> me that searching the indexes of sixty info files takes time.

With `help-fns+.el' users can control which manuals
to use.  And so can any library code: pick the
manuals to use according to some context etc.

`info-lookup-symbol' is _very_ quick.  Assuming it
can be made to work well with additional manuals,
which some have said is the case, and assuming it
can be made to return links to multiple manuals,
there would presumably be no naive index-lookup
such as what my code currently does.

Re: master 2a7488d: Add support for displaying short documentation for function groups

[Juri Linkov]

>>     Add support for displaying short documentation for function groups
>
> After tinkering with this for a while on a branch, I've now merged the
> shortdoc stuff into the trunk.  The main idea is taken from what is,
> according to the entire internet, the Platonic ideal in documentation:
>
>   https://github.com/magnars/s.el
>
> So it's a list of functions and examples.
>
> It could probably do with a bit more tinkering, looks-wise.
>
> The easiest way to experience it is to say `C-h f string-trim RET' and
> then clicking on the button.

I have pondered a year ago about doing something like this,
but based on Info and/or HTML, i.e. to generate Info nodes with
functions listed by groups in separate nodes (possibly using HTML format),
so e.g. going to (info "(shortdoc) Buffer")
could display an Info node with a menu of related functions,
where nodes could be navigated using Info keys.
Does this make sense?

RE: master 2a7488d: Add support for displaying short documentation for function groups

[Drew Adams]

> I have pondered a year ago about doing something like this,
> but based on Info and/or HTML, i.e. to generate Info nodes with
> functions listed by groups in separate nodes (possibly using HTML format),
> so e.g. going to (info "(shortdoc) Buffer")
> could display an Info node with a menu of related functions,
> where nodes could be navigated using Info keys.
> Does this make sense?

Doesn't `Info-virtual-index' already do that?
E.g. `I buffer' gives you an index with just
the index entries that match "buffer".

Maybe you can state the difference between that
command and what you have in mind, to clarify.

Re: master 2a7488d: Add support for displaying short documentation for function groups

[T.V Raman]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain; charset=gb18030, Size: 300 bytes --]

Keep the format (html, texinfo etc) separate from any UI mechanisms we
want to try, otherwise it becomes all to easy to build things that  are
format-specific. HTML is a particularly slippery slope, once you add
Javascript to the mix,
-- 

Thanks,

--Raman
7©4 Id: kg:/m/0285kf1  •0Ü8

Re: master 2a7488d: Add support for displaying short documentation for function groups

[Lars Ingebrigtsen]

Juri Linkov <juri@linkov.net> writes:

> I have pondered a year ago about doing something like this,
> but based on Info and/or HTML, i.e. to generate Info nodes with
> functions listed by groups in separate nodes (possibly using HTML format),
> so e.g. going to (info "(shortdoc) Buffer")
> could display an Info node with a menu of related functions,
> where nodes could be navigated using Info keys.
> Does this make sense?

I don't immediately see anything to be gained by using Info mode here --
it just seems like a complication.  What would the advantages be?

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: master 2a7488d: Add support for displaying short documentation for function groups

[Juri Linkov]

>> I have pondered a year ago about doing something like this,
>> but based on Info and/or HTML, i.e. to generate Info nodes with
>> functions listed by groups in separate nodes (possibly using HTML format),
>> so e.g. going to (info "(shortdoc) Buffer")
>> could display an Info node with a menu of related functions,
>> where nodes could be navigated using Info keys.
>> Does this make sense?
>
> Doesn't `Info-virtual-index' already do that?
> E.g. `I buffer' gives you an index with just
> the index entries that match "buffer".

Yes, I meant to implement this by using `Info-virtual-index'.

Re: master 2a7488d: Add support for displaying short documentation for function groups

[Juri Linkov]

> Keep the format (html, texinfo etc) separate from any UI mechanisms we
> want to try, otherwise it becomes all to easy to build things that  are
> format-specific. HTML is a particularly slippery slope, once you add
> Javascript to the mix,

Actually, for implementation I intended to use not HTML as text,
but an s-expression tree that represents HTML elements in Lisp syntax.
And instead of Javascript to use Emacs Lisp.

Re: master 2a7488d: Add support for displaying short documentation for function groups

[Juri Linkov]

>> I have pondered a year ago about doing something like this,
>> but based on Info and/or HTML, i.e. to generate Info nodes with
>> functions listed by groups in separate nodes (possibly using HTML format),
>> so e.g. going to (info "(shortdoc) Buffer")
>> could display an Info node with a menu of related functions,
>> where nodes could be navigated using Info keys.
>> Does this make sense?
>
> I don't immediately see anything to be gained by using Info mode here --
> it just seems like a complication.  What would the advantages be?

Some advantages of using Info mode:

1. Info navigation keys and commands are available for navigation:
   Info-next, Info-prev, Info-up, Info-top-node, Info-follow-nearest-node, ...

2. Info addressing scheme, so e.g. such reference (info "(shortdoc) Buffer")
   could link documents, or be sent by mail, and like URL could be visited,
   Info-goto-node does the right thing to visit such generated Info nodes;

3. Info searching and indexing capabilities all should work with generated nodes;

Re: master 2a7488d: Add support for displaying short documentation for function groups

[T.V Raman]

that sounds perfect, apologies for the false alarm.Juri Linkov writes:
 > > Keep the format (html, texinfo etc) separate from any UI mechanisms we
 > > want to try, otherwise it becomes all to easy to build things that  are
 > > format-specific. HTML is a particularly slippery slope, once you add
 > > Javascript to the mix,
 > 
 > Actually, for implementation I intended to use not HTML as text,
 > but an s-expression tree that represents HTML elements in Lisp syntax.
 > And instead of Javascript to use Emacs Lisp.

-- 
♉Id: kg:/m/0285kf1  🦮♉

--
♉Id: kg:/m/0285kf1  🦮♉

Re: master 2a7488d: Add support for displaying short documentation for function groups

[Lars Ingebrigtsen]

Juri Linkov <juri@linkov.net> writes:

> Some advantages of using Info mode:
>
> 1. Info navigation keys and commands are available for navigation:
>    Info-next, Info-prev, Info-up, Info-top-node, Info-follow-nearest-node, ...

None of those are relevant for the shortdoc function, I think.  It's
just a list of functions.

> 2. Info addressing scheme, so e.g. such reference (info "(shortdoc) Buffer")
>    could link documents, or be sent by mail, and like URL could be visited,
>    Info-goto-node does the right thing to visit such generated Info nodes;

That doesn't sound like something somebody would do.

> 3. Info searching and indexing capabilities all should work with
> generated nodes;

An index into a shortdoc list sounds counter-productive: It is its own
index.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: master 2a7488d: Add support for displaying short documentation for function groups

[Stefan Monnier]

>> Some advantages of using Info mode:

The new shortdoc thingy is split into two parts: the actual data and
the UI.  So nothing prevents you or anyone else from implementing an
Info UI for it.


        Stefan

Re: master 2a7488d: Add support for displaying short documentation for function groups

[Juri Linkov]

> The new shortdoc thingy is split into two parts: the actual data and
> the UI.  So nothing prevents you or anyone else from implementing an
> Info UI for it.

My original intention was to implement such a documentation browser
using Web UI in eww, but I already agreed that was a bad idea.

However, I'm not sure about Info UI.  The only thing that stops me from
implementing this in Info is a doubt that the users of the standalone
Info reader might expect the same virtual Info manuals be available for them.

For example, with a dynamically generated Info manual with groups of functions
and the addressing scheme such as (info "(shortdoc) regexp functions"),
would the users of the standalone Info reader expect that visiting
the same Info location should produce the same documentation to them
in the standalone Info reader?

Re: master 2a7488d: Add support for displaying short documentation for function groups

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > For example, with a dynamically generated Info manual with groups of functions
  > and the addressing scheme such as (info "(shortdoc) regexp functions"),
  > would the users of the standalone Info reader expect that visiting
  > the same Info location should produce the same documentation to them
  > in the standalone Info reader?

I think it ought to work for that if possible.

Why can't the dynamically generated manual be written into Info files
which are then accessible in all the usual ways?

-- 
Dr Richard Stallman
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: master 2a7488d: Add support for displaying short documentation for function groups

[Juri Linkov]

>   > For example, with a dynamically generated Info manual with groups of functions
>   > and the addressing scheme such as (info "(shortdoc) regexp functions"),
>   > would the users of the standalone Info reader expect that visiting
>   > the same Info location should produce the same documentation to them
>   > in the standalone Info reader?
>
> I think it ought to work for that if possible.
>
> Why can't the dynamically generated manual be written into Info files
> which are then accessible in all the usual ways?

It would require an additional step of running 'make' to update
the generated manuals, whereas most Help commands have the advantage
of immediately displaying the most recent information.

However, the Emacs Info reader could display the most recent information,
but for the users of the standalone Info read we could write that
into Info files.

Re: master 2a7488d: Add support for displaying short documentation for function groups

[Stefan Kangas]

[-- Attachment #1: Type: text/plain, Size: 435 bytes --]

Lars Ingebrigtsen <larsi@gnus.org> writes:

>>     Add support for displaying short documentation for function groups
>
> After tinkering with this for a while on a branch, I've now merged the
> shortdoc stuff into the trunk.

This is great, thank you.

The attached patch adds a group for hash-table.  WDYT?

Two other useful groups to add could be alist and plist.

Also, `replace-match' should perhaps be added to the regexp group.

[-- Attachment #2: shortdoc-hash-table.diff --]
[-- Type: text/x-diff, Size: 1158 bytes --]

diff --git a/lisp/emacs-lisp/shortdoc.el b/lisp/emacs-lisp/shortdoc.el
index 7ae6d53a21..9ab046f94e 100644
--- a/lisp/emacs-lisp/shortdoc.el
+++ b/lisp/emacs-lisp/shortdoc.el
@@ -381,6 +381,39 @@ file
    :eg-result t))
 
 
+(define-short-documentation-group hash-table
+  "Hash Table Basics"
+  (make-hash-table
+   :no-eval (make-hash-table)
+   :result-string "#s(hash-table ...)")
+  (puthash
+   :no-eval (puthash 'key "value" table))
+  (gethash
+   :no-eval (gethash 'key table)
+   :eg-result "value")
+  (remhash
+   :no-eval (remhash 'key table)
+   :result nil)
+  (clrhash
+   :no-eval (clrhash table)
+   :result-string "#s(hash-table ...)")
+  (maphash
+   :no-eval (maphash (lambda (key value) (message value)) table)
+   :result nil)
+  "Other Hash Table Functions"
+  (hash-table-p
+   :eval (hash-table-p 123))
+  (copy-hash-table
+   :no-eval (copy-hash-table table)
+   :result-string "#s(hash-table ...)")
+  (hash-table-count
+   :no-eval (hash-table-count table)
+   :eg-result 15)
+  (hash-table-size
+   :no-eval (hash-table-size table)
+   :eg-result 65))
+
+
 (define-short-documentation-group list
   "Making Lists"
   (make-list

Re: master 2a7488d: Add support for displaying short documentation for function groups

[Lars Ingebrigtsen]

Stefan Kangas <stefankangas@gmail.com> writes:

> The attached patch adds a group for hash-table.  WDYT?

Looks good to me; go ahead and push.

> Two other useful groups to add could be alist and plist.
>
> Also, `replace-match' should perhaps be added to the regexp group.

Yup and yup.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: master 2a7488d: Add support for displaying short documentation for function groups

[Stefan Kangas]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> Stefan Kangas <stefankangas@gmail.com> writes:
>
>> The attached patch adds a group for hash-table.  WDYT?
>
> Looks good to me; go ahead and push.

Done.

>> Two other useful groups to add could be alist and plist.
>>
>> Also, `replace-match' should perhaps be added to the regexp group.
>
> Yup and yup.

I took the liberty of pushing a new shortdoc group for alists.  Please
take a look and make any changes you deem necessary.

Re: master 2a7488d: Add support for displaying short documentation for function groups

[Lars Ingebrigtsen]

Stefan Kangas <stefankangas@gmail.com> writes:

> I took the liberty of pushing a new shortdoc group for alists.  Please
> take a look and make any changes you deem necessary.

Looks good to me.  :-)

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: master 2a7488d: Add support for displaying short documentation for function groups

[Basil L. Contovounesios]

Stefan Kangas <stefankangas@gmail.com> writes:

> Also, `replace-match' should perhaps be added to the regexp group.

Perhaps rx, too?

Thanks,

-- 
Basil

Re: master 2a7488d: Add support for displaying short documentation for function groups

[Stefan Kangas]

Basil L. Contovounesios <contovob@tcd.ie> writes:

> > Also, `replace-match' should perhaps be added to the regexp group.
>
> Perhaps rx, too?

I think so.  What about save-match-data?

Re: master 2a7488d: Add support for displaying short documentation for function groups

[Basil L. Contovounesios]

Stefan Kangas <stefankangas@gmail.com> writes:

> Basil L. Contovounesios <contovob@tcd.ie> writes:
>
>> > Also, `replace-match' should perhaps be added to the regexp group.
>>
>> Perhaps rx, too?
>
> I think so.  What about save-match-data?

Perhaps under a "match data" subgroup?

-- 
Basil

Re: master 2a7488d: Add support for displaying short documentation for function groups

[Lars Ingebrigtsen]

"Basil L. Contovounesios" <contovob@tcd.ie> writes:

>> I think so.  What about save-match-data?
>
> Perhaps under a "match data" subgroup?

Makes sense.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: master 2a7488d: Add support for displaying short documentation for function groups

[Stefan Kangas]

[-- Attachment #1: Type: text/plain, Size: 546 bytes --]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> "Basil L. Contovounesios" <contovob@tcd.ie> writes:
>
>>> I think so.  What about save-match-data?
>>
>> Perhaps under a "match data" subgroup?
>
> Makes sense.

How about the attached?

- I moved match-beginning and match-end to the new section "Match Data",
  and moved it below "Looking in Buffers".

- I added rx to the "Utilities" group.

Perhaps I went a bit overboard with the rx example, but it's useful to
just show off a bunch of syntax at a glance.  Let me know if it's too
much though...

[-- Attachment #2: 0001-Add-save-match-data-and-rx-to-regexp-shortdoc-group.patch --]
[-- Type: text/x-diff, Size: 1728 bytes --]

From cf0f47acf5fbd96c7e1f0c40f6efd075fb624481 Mon Sep 17 00:00:00 2001
From: Stefan Kangas <stefan@marxist.se>
Date: Tue, 27 Oct 2020 22:50:20 +0100
Subject: [PATCH] Add save-match-data and rx to regexp shortdoc group

* lisp/emacs-lisp/shortdoc.el (regexp): Add save-match-data and rx
to group.  New section "Match Data".
---
 lisp/emacs-lisp/shortdoc.el | 19 ++++++++++++-------
 1 file changed, 12 insertions(+), 7 deletions(-)

diff --git a/lisp/emacs-lisp/shortdoc.el b/lisp/emacs-lisp/shortdoc.el
index a2e5ce6e29..98994ed501 100644
--- a/lisp/emacs-lisp/shortdoc.el
+++ b/lisp/emacs-lisp/shortdoc.el
@@ -628,12 +628,6 @@ regexp
   (match-string
    :eval (and (string-match "^\\([fo]+\\)b" "foobar")
               (match-string 0 "foobar")))
-  (match-beginning
-   :no-eval (match-beginning 1)
-   :eg-result 0)
-  (match-end
-   :no-eval (match-end 1)
-   :eg-result 3)
   "Looking in Buffers"
   (re-search-forward
    :no-eval (re-search-forward "^foo$" nil t)
@@ -644,6 +638,15 @@ regexp
   (looking-at-p
    :no-eval (looking-at "f[0-9]")
    :eg-result t)
+  "Match Data"
+  (match-beginning
+   :no-eval (match-beginning 1)
+   :eg-result 0)
+  (match-end
+   :no-eval (match-end 1)
+   :eg-result 3)
+  (save-match-data
+    :no-eval (save-match-data ...))
   "Replacing Match"
   (replace-match
    :no-eval (replace-match "new")
@@ -659,7 +662,9 @@ regexp
   (regexp-opt-depth
    :eval (regexp-opt-depth "\\(a\\(b\\)\\)"))
   (regexp-opt-charset
-   :eval (regexp-opt-charset '(?a ?b ?c ?d ?e))))
+   :eval (regexp-opt-charset '(?a ?b ?c ?d ?e)))
+  (rx
+   :eval (rx (| (* "f") (+ "o") (? "o")) (any "bar") (group "baz"))))
 
 (define-short-documentation-group sequence
   "Sequence Predicates"
-- 
2.28.0

Re: master 2a7488d: Add support for displaying short documentation for function groups

[Mattias Engdegård]

27 okt. 2020 kl. 23.02 skrev Stefan Kangas <stefankangas@gmail.com>:

> - I moved match-beginning and match-end to the new section "Match Data",
>  and moved it below "Looking in Buffers".

Perhaps 'match-string' belongs there too.

> - I added rx to the "Utilities" group.
> 
> Perhaps I went a bit overboard with the rx example, but it's useful to
> just show off a bunch of syntax at a glance.  Let me know if it's too
> much though...

+   :eval (rx (| (* "f") (+ "o") (? "o")) (any "bar") (group "baz"))))

(any "bar") may be misleading since it looks like "bar" is a string to be matched, but it is just the characters {a,b,r}.

(If you want to be complete, the rx family also includes rx-to-string, rx-define, rx-let and rx-let-eval.)

Re: master 2a7488d: Add support for displaying short documentation for function groups

[Lars Ingebrigtsen]

Stefan Kangas <stefankangas@gmail.com> writes:

> How about the attached?
>
> - I moved match-beginning and match-end to the new section "Match Data",
>   and moved it below "Looking in Buffers".
>
> - I added rx to the "Utilities" group.

Looks good to me.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: master 2a7488d: Add support for displaying short documentation for function groups

[Stefan Kangas]

Mattias Engdegård <mattiase@acm.org> writes:

>> - I moved match-beginning and match-end to the new section "Match Data",
>>  and moved it below "Looking in Buffers".
>
> Perhaps 'match-string' belongs there too.

Indeed, so I fixed that.

> +   :eval (rx (| (* "f") (+ "o") (? "o")) (any "bar") (group "baz"))))
>
> (any "bar") may be misleading since it looks like "bar" is a string to be matched, but it is just the characters {a,b,r}.

I changed that.

Though, to be honest, perhaps we should replace this entire example with
something that actually demonstrates _why_ one would want to use `rx'.
I just couldn't think of a good example right now.  There is time to
improve the example before Emacs 28.1, I guess.

> (If you want to be complete, the rx family also includes rx-to-string, rx-define, rx-let and rx-let-eval.)

I added all of them into a new section and pushed this to master.

Thanks.

Re: master 2a7488d: Add support for displaying short documentation for function groups

[Stefan Kangas]

[-- Attachment #1: Type: text/plain, Size: 853 bytes --]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> Stefan Kangas <stefankangas@gmail.com> writes:
>
>> I'm seeing some possibly incorrect behavior with
>> `text-property-search-backward'.  See the FIXMEs in my patch.  The
>> documentation says "if a matching region is found, moves point to its
>> beginning", but in practice that doesn't happen (at least not in this
>> case).  Is this a bug or am I just missing something?
>
> I think it's probably a copy/paste error in the doc string?  Or just
> unclear.  It seems to be behaving like it should -- which is to leave
> point at the, er, end of the matching region (but it's the beginning if
> you're counting from the end of the buffer :-) ).

I tried clarifying this in the attached patch.  WDYT?

>> Subject: [PATCH] Add shortdoc navigation commands
>
> This look good to me.

Thanks, pushed to master.

[-- Attachment #2: 0001-Clarify-point-position-after-text-property-search.patch --]
[-- Type: text/x-diff, Size: 3396 bytes --]

From 41ea9828061da6e60a9581c458c3b4702dbe5697 Mon Sep 17 00:00:00 2001
From: Stefan Kangas <stefan@marxist.se>
Date: Fri, 30 Oct 2020 12:48:30 +0100
Subject: [PATCH] Clarify point position after text-property-search

* lisp/emacs-lisp/text-property-search.el
(text-property-search-forward, text-property-search-backward): Doc fix
to clarify placement of point after search.
* test/lisp/emacs-lisp/text-property-search-tests.el
(text-property-search--pos-test): New defun.
(text-property-search-forward-point-at-beginning)
(text-property-search-backward-point-at-end): New test.
---
 lisp/emacs-lisp/text-property-search.el        | 12 ++++++------
 .../emacs-lisp/text-property-search-tests.el   | 18 ++++++++++++++++++
 2 files changed, 24 insertions(+), 6 deletions(-)

diff --git a/lisp/emacs-lisp/text-property-search.el b/lisp/emacs-lisp/text-property-search.el
index 61bd98d3cf..d7dc7da7c1 100644
--- a/lisp/emacs-lisp/text-property-search.el
+++ b/lisp/emacs-lisp/text-property-search.el
@@ -34,11 +34,11 @@ text-property-search-forward
   "Search for the next region of text whose PROPERTY matches VALUE.
 
 If not found, return nil and don't move point.
-If found, move point to end of the region and return a `prop-match'
-object describing the match.  To access the details of the match,
-use `prop-match-beginning' and `prop-match-end' for the buffer
-positions that limit the region, and `prop-match-value' for the
-value of PROPERTY in the region.
+If found, move point to the start of the region and return a
+`prop-match' object describing the match.  To access the details
+of the match, use `prop-match-beginning' and `prop-match-end' for
+the buffer positions that limit the region, and
+`prop-match-value' for the value of PROPERTY in the region.
 
 PREDICATE is used to decide whether a value of PROPERTY should be
 considered as matching VALUE.
@@ -125,7 +125,7 @@ text-property-search-backward
   "Search for the previous region of text whose PROPERTY matches VALUE.
 
 Like `text-property-search-forward', which see, but searches backward,
-and if a matching region is found, moves point to its beginning."
+and if a matching region is found, place point at its end."
   (interactive
    (list
     (let ((string (completing-read "Search for property: " obarray)))
diff --git a/test/lisp/emacs-lisp/text-property-search-tests.el b/test/lisp/emacs-lisp/text-property-search-tests.el
index 83d4b95b76..278155006c 100644
--- a/test/lisp/emacs-lisp/text-property-search-tests.el
+++ b/test/lisp/emacs-lisp/text-property-search-tests.el
@@ -153,6 +153,24 @@ text-property-search-backward-prop-match-match-face-italic-nil
    46 57 nil
    (point-max)))
 
+\f
+;;;; Position after search.
+
+(defun text-property-search--pos-test (fun pos &optional reverse)
+  (with-temp-buffer (:name "position")
+    (insert (concat "foo "
+                  (propertize "bar" 'x t)
+                  " baz"))
+    (goto-char (if reverse (point-max) (point-min)))
+    (funcall fun 'x t)
+    (should (= (point) pos))))
+
+(ert-deftest text-property-search-forward-point-at-beginning ()
+  (text-property-search--pos-test #'text-property-search-forward 5))
+
+(ert-deftest text-property-search-backward-point-at-end ()
+  (text-property-search--pos-test #'text-property-search-backward 8 t))
+
 (provide 'text-property-search-tests)
 
 ;;; text-property-search-tests.el ends here
-- 
2.28.0

Re: master 2a7488d: Add support for displaying short documentation for function groups

[Lars Ingebrigtsen]

Stefan Kangas <stefankangas@gmail.com> writes:

> I tried clarifying this in the attached patch.  WDYT?

Looks good to me.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: master 2a7488d: Add support for displaying short documentation for function groups

[Stefan Kangas]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> Looks good to me.

Thanks, pushed to master.