GNU bug report logs - #39215
Hyperlinks to man pages in doc strings

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 39215 in the body.
You can then email your comments to 39215 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefan <at> marxist.se>
To: bug-gnu-emacs <at> gnu.org
Subject: Hyperlinks to man pages in doc strings
Date: Tue, 21 Jan 2020 09:55:42 +0100

Severity: wishlist

Please add the possibility to write in doc strings:

    man page `find'

and have it automatically converted into a hyperlink which will open
up M-x man and visit the specified man page.

The proposed feature complements the already existing functionality
with hyperlinks to info pages.[1]

For an example of where this would be useful, please see the doc
string of `dired-do-chmod'.

Best regards,
Stefan Kangas

Footnotes:
[1]  See (info "(elisp)Documentation Tips")

Message #8 received at 39215 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: 39215 <at> debbugs.gnu.org
Subject: Re: bug#39215: Hyperlinks to man pages in doc strings
Date: Tue, 21 Jan 2020 17:36:43 +0200

> From: Stefan Kangas <stefan <at> marxist.se>
> Date: Tue, 21 Jan 2020 09:55:42 +0100
> 
> Severity: wishlist
> 
> Please add the possibility to write in doc strings:
> 
>     man page `find'
> 
> and have it automatically converted into a hyperlink which will open
> up M-x man and visit the specified man page.

'find' has an Info manual: find.info.  Why not use a hyperlink to that
instead, something we already support?  Many utilities have similar
Info manuals, and the glibc has an Info manual as well.

> The proposed feature complements the already existing functionality
> with hyperlinks to info pages.[1]

Nitpicking: let's not call Info manuals "pages".  They are not like
"man pages", which are a collection of short concise usage
descriptions.

Message #11 received at 39215 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefan <at> marxist.se>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 39215 <at> debbugs.gnu.org
Subject: Re: bug#39215: Hyperlinks to man pages in doc strings
Date: Tue, 21 Jan 2020 17:32:35 +0100

Eli Zaretskii <eliz <at> gnu.org> writes:

> 'find' has an Info manual: find.info.  Why not use a hyperlink to that
> instead, something we already support?  Many utilities have similar
> Info manuals, and the glibc has an Info manual as well.

I was looking for something which would work also with BSD find (or
indeed any find not from GNU findutils).  My idea was to specify both.

But that's just one example.  Most non-GNU software don't use texinfo.
They often have man pages.  It would be useful to be able to add links
to them.

> Nitpicking: let's not call Info manuals "pages".  They are not like
> "man pages", which are a collection of short concise usage
> descriptions.

Sure, I'll try to remember to say "info manuals" in our documentation
and sources.

(FWIW, I think getting people to stop using that vocabulary is going
to be an uphill battle, since it is so ubiquitous.  We even use this
nomenclature in some places in Emacs itself.  Try grepping for "info
pages" in our sources.)

Best regards,
Stefan Kangas

Message #14 received at 39215 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: 39215 <at> debbugs.gnu.org
Subject: Re: bug#39215: Hyperlinks to man pages in doc strings
Date: Tue, 21 Jan 2020 18:56:50 +0200

> From: Stefan Kangas <stefan <at> marxist.se>
> Date: Tue, 21 Jan 2020 17:32:35 +0100
> Cc: 39215 <at> debbugs.gnu.org
> 
> Eli Zaretskii <eliz <at> gnu.org> writes:
> 
> > 'find' has an Info manual: find.info.  Why not use a hyperlink to that
> > instead, something we already support?  Many utilities have similar
> > Info manuals, and the glibc has an Info manual as well.
> 
> I was looking for something which would work also with BSD find (or
> indeed any find not from GNU findutils).  My idea was to specify both.

Why should we cater so much to non-GNU systems?  The users of BSD can
install the Info manual as well, can they not?

> But that's just one example.  Most non-GNU software don't use texinfo.
> They often have man pages.  It would be useful to be able to add links
> to them.

Maybe we should teach info.el to display man pages.  The stand-alone
Info reader that is part of the Texinfo package does that since time
immemoriam.

> Try grepping for "info pages" in our sources.

Those places should be corrected.

Message #17 received at 39215 <at> debbugs.gnu.org (full text, mbox):

From: Glenn Morris <rgm <at> gnu.org>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: Stefan Kangas <stefan <at> marxist.se>, 39215 <at> debbugs.gnu.org
Subject: Re: bug#39215: Hyperlinks to man pages in doc strings
Date: Tue, 21 Jan 2020 23:03:01 -0500

Eli Zaretskii wrote:

> Maybe we should teach info.el to display man pages.  The stand-alone
> Info reader that is part of the Texinfo package does that since time
> immemoriam.

(This seems unrelated to the, IMO totally reasonable, feature request.)

The info reader does a worse job of rendering man pages than the 'man'
program does. I hope Emacs doesn't implement a second (on top of M-x
woman) partial replacement for the man program, when one can just use
M-x man.

Message #20 received at 39215 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Glenn Morris <rgm <at> gnu.org>
Cc: stefan <at> marxist.se, 39215 <at> debbugs.gnu.org
Subject: Re: bug#39215: Hyperlinks to man pages in doc strings
Date: Wed, 22 Jan 2020 17:45:04 +0200

> From: Glenn Morris <rgm <at> gnu.org>
> Cc: Stefan Kangas <stefan <at> marxist.se>,  39215 <at> debbugs.gnu.org
> Date: Tue, 21 Jan 2020 23:03:01 -0500
> 
> Eli Zaretskii wrote:
> 
> > Maybe we should teach info.el to display man pages.  The stand-alone
> > Info reader that is part of the Texinfo package does that since time
> > immemoriam.
> 
> (This seems unrelated to the, IMO totally reasonable, feature request.)

My reasoning was that if info.el could do that, then a hyperlink like
`(find)' would "just work", without a need to invent yet another magic
sequence of characters.

Message #23 received at 39215 <at> debbugs.gnu.org (full text, mbox):

From: Richard Stallman <rms <at> gnu.org>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: stefan <at> marxist.se, 39215 <at> debbugs.gnu.org
Subject: Re: bug#39215: Hyperlinks to man pages in doc strings
Date: Wed, 22 Jan 2020 20:39:53 -0500

[[[ 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. ]]]

  > Why should we cater so much to non-GNU systems?  The users of BSD can
  > install the Info manual as well, can they not?

That is the right approach.  Let's focus our work on improvements that
are beneficial in the GNU system (as well as, possibly, elsewhere).

-- 
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)

Message #26 received at 39215 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefan <at> marxist.se>
To: Richard Stallman <rms <at> gnu.org>
Cc: Eli Zaretskii <eliz <at> gnu.org>, 39215 <at> debbugs.gnu.org
Subject: Re: bug#39215: Hyperlinks to man pages in doc strings
Date: Thu, 23 Jan 2020 04:14:39 +0100

Richard Stallman <rms <at> gnu.org> writes:

>   > Why should we cater so much to non-GNU systems?  The users of BSD can
>   > install the Info manual as well, can they not?
>
> That is the right approach.  Let's focus our work on improvements that
> are beneficial in the GNU system (as well as, possibly, elsewhere).

This would benefit GNU just as much as non-GNU systems.

There is a lot of free software out there that I would like to use on
GNU, but that is not GNU software.  Non-GNU software more often than
not does not have an Info manual.  So I would like to be able to link
their man page instead.

Best regards,
Stefan Kangas

Message #29 received at 39215 <at> debbugs.gnu.org (full text, mbox):

From: Richard Stallman <rms <at> gnu.org>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: eliz <at> gnu.org, 39215 <at> debbugs.gnu.org
Subject: Re: bug#39215: Hyperlinks to man pages in doc strings
Date: Thu, 23 Jan 2020 21:58:00 -0500

[[[ 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. ]]]

  > There is a lot of free software out there that I would like to use on
  > GNU, but that is not GNU software.  Non-GNU software more often than
  > not does not have an Info manual.  So I would like to be able to link
  > their man page instead.

Ok, you've convinced me.

-- 
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)

Message #32 received at 39215 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefan <at> marxist.se>
To: Richard Stallman <rms <at> gnu.org>
Cc: eliz <at> gnu.org, 39215 <at> debbugs.gnu.org
Subject: Re: bug#39215: Hyperlinks to man pages in doc strings
Date: Fri, 24 Sep 2021 18:07:43 -0700

[Message part 1 (text/plain, inline)]

tags 39215 + patch
thanks

Richard Stallman <rms <at> gnu.org> writes:

>   > There is a lot of free software out there that I would like to use on
>   > GNU, but that is not GNU software.  Non-GNU software more often than
>   > not does not have an Info manual.  So I would like to be able to link
>   > their man page instead.
>
> Ok, you've convinced me.

Thanks.  How about the attached patch?

[0001-Add-support-for-man-page-hyperlinks-in-doc-strings.patch (text/x-diff, attachment)]

Message #37 received at 39215 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: Richard Stallman <rms <at> gnu.org>, 39215 <at> debbugs.gnu.org
Subject: Re: bug#39215: Hyperlinks to man pages in doc strings
Date: Sat, 25 Sep 2021 03:13:03 +0200

Stefan Kangas <stefan <at> marxist.se> writes:

> Thanks.  How about the attached patch?

[...]

> * lisp/help-mode.el (help-man): New button type.
> (help-xref-man-regexp): New const.
> (help-make-xrefs): Use them to allow making man page buttons.
> * doc/lispref/tips.texi (Documentation Tips): Document the new
> hyperlink type.  (Bug#39215)

I think that's a really good idea.  I haven't tried the patch, but
skimming it, it looks good to me, so go ahead and push.

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

Message #40 received at 39215 <at> debbugs.gnu.org (full text, mbox):

From: Phil Sainty <psainty <at> orcon.net.nz>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: Richard Stallman <rms <at> gnu.org>, 39215 <at> debbugs.gnu.org
Subject: Re: bug#39215: Hyperlinks to man pages in doc strings
Date: Sat, 25 Sep 2021 13:32:04 +1200

On 2021-09-25 13:07, Stefan Kangas wrote:
> "\\<[Mm]an[ \t\n]+\\(?:page\\)[ \t\n]+\\(?:for[ 
> \t\n]\\)?['`‘\"]\\([^'’\"]+\\)['’\"]"

Was "\\(?:page\\)[ \t\n]+" meant to be "\\(?:page[ \t\n]+\\)?" ?

That would be almost the same as "for" except I note that there's
no allowance for more than one whitespace char after "for", so
maybe that needs changing as well?


-Phil

Message #43 received at 39215 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefan <at> marxist.se>
To: Phil Sainty <psainty <at> orcon.net.nz>
Cc: Richard Stallman <rms <at> gnu.org>, 39215 <at> debbugs.gnu.org
Subject: Re: bug#39215: Hyperlinks to man pages in doc strings
Date: Fri, 24 Sep 2021 19:10:09 -0700

Phil Sainty <psainty <at> orcon.net.nz> writes:

> On 2021-09-25 13:07, Stefan Kangas wrote:
>> "\\<[Mm]an[ \t\n]+\\(?:page\\)[ \t\n]+\\(?:for[
>> \t\n]\\)?['`‘\"]\\([^'’\"]+\\)['’\"]"
>
> Was "\\(?:page\\)[ \t\n]+" meant to be "\\(?:page[ \t\n]+\\)?" ?
>
> That would be almost the same as "for" except I note that there's
> no allowance for more than one whitespace char after "for", so
> maybe that needs changing as well?

Thanks for this attentive reading.

The intention was actually this, which should fix the issues you
mention:

"\\<[Mm]an[ \t\n]+page[ \t\n]+\\(?:for[ \t\n]+\\)?['`‘\"]\\([^'’\"]+\\)['’\"]")

Message #46 received at 39215 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefan <at> marxist.se>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: Richard Stallman <rms <at> gnu.org>, 39215 <at> debbugs.gnu.org
Subject: Re: bug#39215: Hyperlinks to man pages in doc strings
Date: Fri, 24 Sep 2021 19:10:21 -0700

tags 39215 fixed
close 39215 28.1
thanks

Lars Ingebrigtsen <larsi <at> gnus.org> writes:

> Stefan Kangas <stefan <at> marxist.se> writes:
>
>> Thanks.  How about the attached patch?
>
> [...]
>
>> * lisp/help-mode.el (help-man): New button type.
>> (help-xref-man-regexp): New const.
>> (help-make-xrefs): Use them to allow making man page buttons.
>> * doc/lispref/tips.texi (Documentation Tips): Document the new
>> hyperlink type.  (Bug#39215)
>
> I think that's a really good idea.  I haven't tried the patch, but
> skimming it, it looks good to me, so go ahead and push.

Thanks.  I fixed the issue pointed out by Phil and have now pushed it to
master as commit 0917919337.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.