bug#46979: Allow setting Man-default-entry via Local Variables

bug#46979: Allow setting Man-default-entry via Local Variables

[積丹尼 Dan Jacobson]

M-x man says e.g.,
  Manual entry (default CAT(1)):

Well wouldn't it be great if one could do e.g.,

# Local Variables:
# Man-default-entry: "crontab(5)"
# End:

in one's .crontab file.

Or a

# Local Variables:
# Man-default-entry: "bash"
# End:

that one could put in their .bashrc file.

bug#46979: Allow setting Man-default-entry via Local Variables

[Eli Zaretskii]

> From: 積丹尼 Dan Jacobson
>  <jidanni@jidanni.org>
> Date: Sun, 07 Mar 2021 07:18:12 +0800
> 
> Well wouldn't it be great if one could do e.g.,
> 
> # Local Variables:
> # Man-default-entry: "crontab(5)"
> # End:
> 
> in one's .crontab file.
> 
> Or a
> 
> # Local Variables:
> # Man-default-entry: "bash"
> # End:
> 
> that one could put in their .bashrc file.

IMO, it would make much more sense to derive that from the current
major-mode (in Man-default-man-entry).  Patches welcome.

bug#46979: Allow setting Man-default-entry via Local Variables

[積丹尼 Dan Jacobson]

>>>>> "EZ" == Eli Zaretskii <eliz@gnu.org> writes:
>> From: 積丹尼 Dan Jacobson
>> <jidanni@jidanni.org>
>> Date: Sun, 07 Mar 2021 07:18:12 +0800
>> 
>> Well wouldn't it be great if one could do e.g.,
>> 
>> # Local Variables:
>> # Man-default-entry: "crontab(5)"
>> # End:
>> 
>> in one's .crontab file...

EZ> IMO, it would make much more sense to derive that from the current
EZ> major-mode (in Man-default-man-entry).  Patches welcome.

OK, sounds good. But sometimes e.g., crontab mode is not in emacs
officially yet, so supplementing that should still be an option.

bug#46979: Allow setting Man-default-entry via Local Variables

[Daniel Martín via Bug reports for GNU Emacs, the Swiss army knife of text editors]

積丹尼 Dan Jacobson <jidanni@jidanni.org> writes:
>
> EZ> IMO, it would make much more sense to derive that from the current
> EZ> major-mode (in Man-default-man-entry).  Patches welcome.
>
> OK, sounds good. But sometimes e.g., crontab mode is not in emacs
> officially yet, so supplementing that should still be an option.

The major mode approach would work great for Bash configuration files,
for example, but, as you mention, it may not work so well for Cron files
or other .rc/.conf files that share Fundamental or Conf mode, in the
abscence of a more specific mode.  The local variable would require
users to add them to existing files, only for Emacs.

Do you have a more complete list of potential use cases, ie. common
program configuration files with corresponding man pages? I don't know
if there are plenty of them, and with that information we could think of
the best and simplest way to implement the feature, if it's worth it.
Thanks.

bug#46979: Allow setting Man-default-entry via Local Variables

[積丹尼 Dan Jacobson]

Let's see, one would usually want "make" man and INFO pages when
browsing a makefile. (Ah, we see we want to make a hint about what INFO
page we want too!)

Nobody knows what man pages when browsing a .txt or .html file.

Too many pages when browsing a perl file. OK maybe e.g., Math::Trig if
that is the only "use" used.

Probably no especial page when browsing (oops, I mean editing. Same
above too) a .kml file.

So yes, some alists might be possible. But still... there should be a
way of letting the user use Local Variables per file...

My main use case example is getting


              # field          allowed values
              # -----          --------------
              # minute         0–59
              # hour           0–23
              # day of month   1–31
              # month          1–12 (or names, see below)
              # day of week    0–7 (0 or 7 is Sun, or use names)

reminders that I put in out of my crontab files.

And

# man Mail::SpamAssassin::Conf
# man spamassassin-run

out of my spamassassin files... (which are meant for me to put the
cursor on and do M-x man.) (so we see here we want to put two items on a
list of man page defaults!)

>>>>> "DM" == Daniel Martín <mardani29@yahoo.es> writes:
DM> Do you have a more complete list of potential use cases...

bug#46979: Allow setting Man-default-entry via Local Variables

[Eli Zaretskii]

> From: 積丹尼 Dan Jacobson <jidanni@jidanni.org>
> Cc: Eli Zaretskii <eliz@gnu.org>,  46979@debbugs.gnu.org
> Date: Mon, 08 Mar 2021 21:46:13 +0800
> 
> So yes, some alists might be possible. But still... there should be a
> way of letting the user use Local Variables per file...

Our solution to this is "C-h S".  Did you try it?  You can extend its
database if the default lacks something you need.

bug#46979: Allow setting Man-default-entry via Local Variables

[積丹尼 Dan Jacobson]

C-h S, powerful as it may be, only seems to help with 5% of the points I
have made.

bug#46979: Allow setting Man-default-entry via Local Variables

[Eli Zaretskii]

> From: 積丹尼 Dan Jacobson <jidanni@jidanni.org>
> Cc: mardani29@yahoo.es,  46979@debbugs.gnu.org
> Date: Mon, 08 Mar 2021 22:48:51 +0800
> 
> C-h S, powerful as it may be, only seems to help with 5% of the points I
> have made.

That's enough to close the bug report from my POV.  But why only 5?
what real problems does it not handle, pray-say?

bug#46979: Allow setting Man-default-entry via Local Variables

[積丹尼 Dan Jacobson]

>>>>> "EZ" == Eli Zaretskii <eliz@gnu.org> writes:
>> 
>> C-h S, powerful as it may be, only seems to help with 5% of the points I
>> have made.

EZ> That's enough to close the bug report from my POV.  But why only 5?
EZ> what real problems does it not handle, pray-say?

95% needed before closing.

E.g., we are editing our crontab file, and do M-x man
we don't want to have to type in c r o n t a b ( 5 ) each time.

bug#46979: Allow setting Man-default-entry via Local Variables

[Eli Zaretskii]

> From: 積丹尼 Dan Jacobson <jidanni@jidanni.org>
> Cc: mardani29@yahoo.es,  46979@debbugs.gnu.org
> Date: Mon, 08 Mar 2021 23:51:03 +0800
> 
> E.g., we are editing our crontab file, and do M-x man
> we don't want to have to type in c r o n t a b ( 5 ) each time.

Who on earth needs to read the man page of crontab(5)?

Any other examples?

bug#46979: Allow setting Man-default-entry via Local Variables

[積丹尼 Dan Jacobson]

>>>>> "EZ" == Eli Zaretskii <eliz@gnu.org> writes:
EZ> Who on earth needs to read the man page of crontab(5)?

How then, do you remember the order of the five numbers on each line?
Is the first the minute, or the hour, etc.

Also crontab doesn't have an Info manual.

Anyway, if someone wrote the crontab(5) man page, that probably means it
exists for a reason.

Same say for fstab(5).

bug#46979: Allow setting Man-default-entry via Local Variables

[Eli Zaretskii]

> From: 積丹尼 Dan Jacobson <jidanni@jidanni.org>
> Cc: mardani29@yahoo.es,  46979@debbugs.gnu.org
> Date: Tue, 09 Mar 2021 01:06:32 +0800
> 
> >>>>> "EZ" == Eli Zaretskii <eliz@gnu.org> writes:
> EZ> Who on earth needs to read the man page of crontab(5)?
> 
> How then, do you remember the order of the five numbers on each line?
> Is the first the minute, or the hour, etc.
> 
> Also crontab doesn't have an Info manual.
> 
> Anyway, if someone wrote the crontab(5) man page, that probably means it
> exists for a reason.
> 
> Same say for fstab(5).

OK, but why do you insist on doing this via file-local variables?

bug#46979: Allow setting Man-default-entry via Local Variables

[積丹尼 Dan Jacobson]

>>>>> "EZ" == Eli Zaretskii <eliz@gnu.org> writes:

EZ> OK, but why do you insist on doing this via file-local variables?

Because certainly the people who make the alists will probably think
that crontab(1) is the man page people editing crontabs want to see,
but individual programmer Williams wants to see crontab(5) usually.
But wait! Not always. For his other cron page he more often wants to see
cron(8), and even crontab(1posix). So you never know. And then again for
his Nurdenburg project he often wants to see the flippant(1) man page,
except for his flursburg file, where he often needs to check the
fartsburg(7) man page. I.e., Local Variables are the only way to cater
to all his needs. Sure, he could make lists of what filenames should
match what man pages. But he also wants the flexibility of Local Variables.

bug#46979: Allow setting Man-default-entry via Local Variables

[Eli Zaretskii]

> From: 積丹尼 Dan Jacobson <jidanni@jidanni.org>
> Cc: mardani29@yahoo.es,  46979@debbugs.gnu.org
> Date: Tue, 09 Mar 2021 22:24:20 +0800
> 
> >>>>> "EZ" == Eli Zaretskii <eliz@gnu.org> writes:
> 
> EZ> OK, but why do you insist on doing this via file-local variables?
> 
> Because certainly the people who make the alists will probably think
> that crontab(1) is the man page people editing crontabs want to see,
> but individual programmer Williams wants to see crontab(5) usually.
> But wait! Not always. For his other cron page he more often wants to see
> cron(8), and even crontab(1posix). So you never know.

But Mr Williams does know!  And the alist can be modified exactly like
the local-vars section in a file.

With your suggestion, by default Emacs will be none the wiser, because
wizard jidanni didn't visit every Mr Williams out there and offered
them his services of adding the local-vars section to every obscure
file they might have on their disk.  Including flippant(1),
fartsburg(7) and whatnot.

A good tool shines when it does DWIM without any tinkering.  The
"alist solution" has much higher chances of doing a large part of the
job, so insisting on not doing anything and leaving everything to the
user's tinkering makes little sense to me.

bug#46979: Allow setting Man-default-entry via Local Variables

[積丹尼 Dan Jacobson]

EZ> A good tool shines when it does DWIM without any tinkering.  The
EZ> "alist solution" has much higher chances of doing a large part of the
EZ> job, so insisting on not doing anything and leaving everything to the
EZ> user's tinkering makes little sense to me.

Good. Great. Full speed ahead with the alist version!
(But still allow setting via Local Variables for Mom's one time pet cat
project.)

bug#46979: Allow setting Man-default-entry via Local Variables

[Daniel Martín via Bug reports for GNU Emacs, the Swiss army knife of text editors]

Eli Zaretskii <eliz@gnu.org> writes:

>
> Our solution to this is "C-h S".  Did you try it?  You can extend its
> database if the default lacks something you need.

C-h S only searches Info pages.  I think this feature request is more
about improving the default that M-x man offers, to consider more things
than just the text around point.

I can see its usefulness, as a lot of Unix tools provide special man
pages for its configuration files.  Another potential use case is a user
visiting a .gitconfig file, where M-x man could suggest "git-config(1)"
by default.  Similarly for .gitattributes and "gitattributes(5)".

As it's almost impossible to have all that knowledge in Emacs core, I
see it as a new extensibilty point for users.  What are the downsides
you see in the local variable approach?

bug#46979: Allow setting Man-default-entry via Local Variables

[Eli Zaretskii]

> From: Daniel Martín <mardani29@yahoo.es>
> Cc: 積丹尼 Dan Jacobson <jidanni@jidanni.org>,
>   46979@debbugs.gnu.org
> Date: Mon, 08 Mar 2021 16:48:52 +0100
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >
> > Our solution to this is "C-h S".  Did you try it?  You can extend its
> > database if the default lacks something you need.
> 
> C-h S only searches Info pages.  I think this feature request is more
> about improving the default that M-x man offers, to consider more things
> than just the text around point.

That'd be a tough sell to a GNU project, since the GNU project wants
to deprecate the man pages.  (And please don't use "Info pages" when
you are talking about Info manuals: those manuals are not just
collections of random unrelated "pages".)

And besides, which important packages don't have Info manuals?

> I can see its usefulness, as a lot of Unix tools provide special man
> pages for its configuration files.  Another potential use case is a user
> visiting a .gitconfig file, where M-x man could suggest "git-config(1)"
> by default.  Similarly for .gitattributes and "gitattributes(5)".

Git has an Info manual, even though many people don't know and don't
use it.

> As it's almost impossible to have all that knowledge in Emacs core, I
> see it as a new extensibilty point for users.  What are the downsides
> you see in the local variable approach?

The need to add local variables to files is in itself a downside.

bug#46979: Allow setting Man-default-entry via Local Variables

[Daniel Martín via Bug reports for GNU Emacs, the Swiss army knife of text editors]

Eli Zaretskii <eliz@gnu.org> writes:

>
> The need to add local variables to files is in itself a downside.

I'm not too sold on the local variables approach, either.  Perhaps we
could expose a customization point in the form of an alist of filename
patterns vs corresponding manuals.  Emacs would provide a few of them
and users could expand the list with more if
needed. `Man-default-man-entry' would consult this alist first and
fallback to the current behavior of guessing based on the text near
point.

bug#46979: Allow setting Man-default-entry via Local Variables

[Eli Zaretskii]

> From: Daniel Martín <mardani29@yahoo.es>
> Cc: 46979@debbugs.gnu.org,  jidanni@jidanni.org
> Date: Mon, 08 Mar 2021 20:01:31 +0100
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >
> > The need to add local variables to files is in itself a downside.
> 
> I'm not too sold on the local variables approach, either.  Perhaps we
> could expose a customization point in the form of an alist of filename
> patterns vs corresponding manuals.  Emacs would provide a few of them
> and users could expand the list with more if
> needed. `Man-default-man-entry' would consult this alist first and
> fallback to the current behavior of guessing based on the text near
> point.

That'd be better, IMO.

We could also define a trivial major mode for those files, and then
make Man-default-man-entry sensitive to that.

bug#46979: Allow setting Man-default-entry via Local Variables

[Basil L. Contovounesios]

Eli Zaretskii <eliz@gnu.org> writes:

> Git has an Info manual, even though many people don't know and don't
> use it.

If only it were packaged with Git!
(I'm glaring at Debian's git-doc package.)
Thanks for alerting us to this boon, I've now installed it from git.git.

-- 
Basil