bug#4826: 23.1; woman-manpath, woman-man.conf-path on MS Windows with Cygwin

bug#4826: 23.1; woman-manpath, woman-man.conf-path on MS Windows with Cygwin

[Drew Adams]

Seems like the default value of things like `man-path' on MS Windows
should not be ("/usr/man" "/usr/share/man" "/usr/local/man").
 
I have Cygwin installed (but I'm not using Cygwin Emacs), but the
default value does not reflect this. Even the doc string of
`woman-manpath' says this:
 
 Microsoft platforms:
 I recommend including drive letters explicitly, e.g.
 
   ("C:/Cygwin/usr/man/" "C:/Cygwin/usr/local/man").
 
One wonders who "I" is here (that's not helful, for doc), but in any
case, why can't Emacs itself do something like that for the default
value? That default value, even if hard-coded, would be better for
Windows users than the actual default value of ("/usr/man"
"/usr/share/man" "/usr/local/man"). There is more chance that a
Windows user has Cygwin installed than that the Unix directories will
work!
 

In GNU Emacs 23.1.1 (i386-mingw-nt5.1.2600)
 of 2009-07-29 on SOFT-MJASON
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (4.4)'
 

bug#4826: 23.1; woman-manpath, woman-man.conf-path on MS Windows with Cygwin

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Date: Thu, 29 Oct 2009 00:40:45 -0700
> 
> Seems like the default value of things like `man-path' on MS Windows
> should not be ("/usr/man" "/usr/share/man" "/usr/local/man").
>  
> I have Cygwin installed (but I'm not using Cygwin Emacs), but the
> default value does not reflect this. Even the doc string of
> `woman-manpath' says this:
>  
>  Microsoft platforms:
>  I recommend including drive letters explicitly, e.g.
>  
>    ("C:/Cygwin/usr/man/" "C:/Cygwin/usr/local/man").
>  
> One wonders who "I" is here

WoMan's author, I presume.

> why can't Emacs itself do something like that for the default
> value?

There's no standard place on Windows for man pages.  Everybody puts
them where they see fit.  How would Emacs know where to look?

> That default value, even if hard-coded, would be better for
> Windows users than the actual default value of ("/usr/man"
> "/usr/share/man" "/usr/local/man").

How can incorrect default value be better?  The current default
actually works for me (because I happen to have man pages installed in
these two directories on my disk D:).  So for me, changing the default
to something like C:/Cygwin/usr/man would be a step back.

If anything, I would suggest writing some code to look up the
directories in the default value on every drive that is on a local
hard disk, then perhaps do the same under /Cygwin on each drive.  But
that's hardly a simple change of the default to a different static
value.

> There is more chance that a Windows user has Cygwin installed than
> that the Unix directories will work!

I'm not sure this is true.  It's certainly false for me.  I have gobs
of man pages, and no Cygwin.

bug#4826: 23.1; woman-manpath, woman-man.conf-path on MS Windows with Cygwin

[Drew Adams]

> > Seems like the default value of things like `man-path' on MS Windows
> > should not be ("/usr/man" "/usr/share/man" "/usr/local/man").
> >  
> > I have Cygwin installed (but I'm not using Cygwin Emacs), but the
> > default value does not reflect this. Even the doc string of
> > `woman-manpath' says this:
> >  
> >  Microsoft platforms:
> >  I recommend including drive letters explicitly, e.g.
> >  
> >    ("C:/Cygwin/usr/man/" "C:/Cygwin/usr/local/man").
> >  
> > One wonders who "I" is here
> 
> WoMan's author, I presume.

Such text is inappropriate and unhelpful for user doc.
That correction is (a minor) part of this bug report.

If that is what Emacs _recommends_ for Windows users, then that is what Emacs
should provide as default for Windows users. Why recommend apples but provide
oranges?

> > why can't Emacs itself do something like that for the default
> > value?
> 
> There's no standard place on Windows for man pages.  Everybody puts
> them where they see fit.  How would Emacs know where to look?

_Of course_ there is no standard place for _UNIX_ manual pages on Windows.

Where should Emacs look? How about looking to the most common UNIX simulation
for Windows? Look to the commonly used program that actually installs a UNIX
manual on Windows. Where would you have Emacs look for a model - at your
personal directory structure, which you mention as a counter-example?

The more important question is this: Why would Emacs use _UNIX_ directories,
knowing that this is MS Windows?

We can be pretty sure that the UNIX directories are incorrect for Windows, even
if you personally are an exception to this rule. Better to have something that
might be appropriate for at least some number of Windows users > 1.

This is already the approach we take for `woman-man.conf-path'. The default
value for that user option, on Windows (emacs -Q), is ("C:/cygwin/lib"
"C:/cygwin/etc"). Why do we use the Cygwin directories here? Because they
provide a reasonable default behavior on Windows.

And there is already code in woman.el that converts UNIX directories to
Cygwin-Windows directories - see `woman-Cyg-to-Win' and
`woman-parse-colon-path'. That code tries to do a good job of figuring out which
Windows file names to use. Why shouldn't we do something similar for
`woman-manpath'?

> > That default value, even if hard-coded, would be better for
> > Windows users than the actual default value of ("/usr/man"
> > "/usr/share/man" "/usr/local/man").
> 
> How can incorrect default value be better?

It can be better by being incorrect for fewer users and correct for more users,
obviously.

The current default value is incorrect for nearly _all_ Windows users (I would
have said "all", but you are apparently an exception). Using the Cygwin value
instead would at least provide a correct value for some non-neglibible set of
Windows users. And this is the value that we explicitly _recommend_ for Windows
users.

And again, that's the approach we already take elsewhere in woman.el. Why do we
do it there? Why should we try to DTRT wrt Cygwin and Windows elsewhere in
woman.el but not here? It is a reasonable thing to do. Using UNIX directories is
not reasonable at all on Windows.

> The current default
> actually works for me (because I happen to have man pages installed in
> these two directories on my disk D:).  So for me, changing the default
> to something like C:/Cygwin/usr/man would be a step back.

You are surely the exception in this regard. How common do you think it is for
users to have personally set up such UNIX directories on Windows?

Keeping to our own recommendation and catering to a commonly used UNIX
simulation such as Cygwin makes a lot more sense than going against our
recommendation and either ignoring Windows use altogether (using UNIX values) or
catering to the unconventional directory structure of one Windows user.

> If anything, I would suggest writing some code to look up the
> directories in the default value on every drive that is on a local
> hard disk, then perhaps do the same under /Cygwin on each drive.  But
> that's hardly a simple change of the default to a different static
> value.
> 
> > There is more chance that a Windows user has Cygwin installed than
> > that the Unix directories will work!
> 
> I'm not sure this is true.  It's certainly false for me.  I have gobs
> of man pages, and no Cygwin.

You _should_ be sure this is true. I cannot believe that you think there are
more Windows users who have personally set up such UNIX directories on Windows
than there are Windows users who use Cygwin.

To follow your logic, we should remove all of the Cygwin-suppporting code in
woman.el and remove the recommendation to use ("C:/Cygwin/usr/man/"
"C:/Cygwin/usr/local/man") on Windows.

bug#4826: 23.1; woman-manpath, woman-man.conf-path on MS Windows with Cygwin

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Date: Thu, 29 Oct 2009 14:51:36 -0700
> 
> Where should Emacs look? How about looking to the most common UNIX simulation
> for Windows? Look to the commonly used program that actually installs a UNIX
> manual on Windows. Where would you have Emacs look for a model - at your
> personal directory structure, which you mention as a counter-example?

GnuWin32 is the most popular and most up-to-date and actively
maintained collection of GNU utilities to native Windows, and its
archives come with man pages.  I think this qualifies as the
``commonly used program that actually installs a UNIX manual on
Windows''.  But GnuWin32 installs the man pages in the `man'
sub-directory under wherever you unzip the archives.  That doesn't
help to resolve this problem, unfortunately.  (As you might have
guessed, I install them under `D:/usr'.)

You suggest to cater to Cygwin first and foremost, but Cygwin defaults
are better suited to the Cygwin build of Emacs (and I believe there,
the current Unix defaults work out of the box anyway).  Native Windows
build of Emacs does not necessarily need to consider Cygwin as the
best default.

> This is already the approach we take for `woman-man.conf-path'. The default
> value for that user option, on Windows (emacs -Q), is ("C:/cygwin/lib"
> "C:/cygwin/etc"). Why do we use the Cygwin directories here? Because they
> provide a reasonable default behavior on Windows.

No, we use these directories for `woman-man.conf-path' because Cygwin
is about the only Windows collection of tools that brings a port of
`man' program which supports the `man' config files.  Other ports of
`man' don't have and don't support that file.

> And there is already code in woman.el that converts UNIX directories to
> Cygwin-Windows directories - see `woman-Cyg-to-Win' and
> `woman-parse-colon-path'. That code tries to do a good job of figuring out which
> Windows file names to use. Why shouldn't we do something similar for
> `woman-manpath'?

This is again Cygwin-specific, because Cygwin uses Unix-style path
lists where directories are separated by colons rather than by
semi-colons.  Native Windows tools will always use semi-colon
separated lists in MANPATH.

To summarize, I think the solution I suggested is the best:

> > If anything, I would suggest writing some code to look up the
> > directories in the default value on every drive that is on a local
> > hard disk, then perhaps do the same under /Cygwin on each drive.

This should work both for you and for me, and probably for most anyone
else.

Unfortunately, I'm too busy these days to implement it.  Volunteers
are welcome.