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

From: "Drew Adams" <[email-masked]>
Date: Thu, 29 Oct 2009 14:51:36 -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.

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.