Re: [Monotone-devel] Please review nvm.man-page

[Stephen Leake]

Thomas Keller <address@hidden> writes:

> Am 19.08.2010 14:05, schrieb Stephen Leake:
>> Thomas Keller <address@hidden> writes:
>> 
>>> Please have a final look at nvm.man-page. 
>> 
>> Compilation fails because 'isatty' is not defined in Windows MinGW.
>> 
>> Neither is troff or less, on a typical MinGW system.
>
> Weird, we use isatty in win32/terminal.cc - 

Ah. I guess I didn't look hard enough.

> could you test and see if this fixes the issue for you?
>
> #
> # old_revision [64367890e4f081f62c6495359dc74ded12d33a13]
> #
> # patch "cmd.cc"
> #  from [b0c21243f7f344006c05aebb2b4f5c9f9ee6ccfd]
> #    to [581f15da8b3300ba057c6ed006dde65a84be679b]
> #
> ============================================================
> --- cmd.cc      b0c21243f7f344006c05aebb2b4f5c9f9ee6ccfd
> +++ cmd.cc      581f15da8b3300ba057c6ed006dde65a84be679b
> @@ -24,6 +24,7 @@
>  #ifndef _WIN32
>  #include <signal.h>
>  #include <errno.h>
> +#include <io.h>
>  #endif
>
>  #include <iostream>

Not quite; that's 'ifndef _WIN32'; we need 'ifdef WIN32'. Then it
compiles. 

In bash under emacs, 'isatty' is apparently false, as this outputs the
nroff source. So we need an option to force the interactive behavior.

In a Cygwin window, it gives the same complaint about not finding nroff
(more in other thread). 

>> Another solution is to dump a plain text version of the man page by
>> default, and the formatted version when a new option --formatted is
>> given; the Makefile will use the option. We could reuse the existing
>> option --non-interactive for this.
>
> The reason why the "manpage" command is not hidden and has this
> interactivity functionality at all is that you cannot create localized
> man pages on build time, since you cannot enforce which message
> catalogue should be used unless the application is installed. So I
> thought it might be a good idea to install the plain text english one
> (available via `man mtn`) and have the localized one when `mtn manpage`
> is called.

Ah, that makes sense. 

That should go in monotone.texi (which doesn't have manpage yet?).

>> At the very least, there needs to be an option to override the default
>> interactive behavior, so we can generate the troff source from a command
>> line (for including user commands, for example).
>
> User commands are already included, as they're part of the overall
> command tree. 

Not in the installed manpage.

> This is btw. another reason for `mtn manpage` which is told to ignore
> any user commands specifically on build time via --norc since they are
> of course only locally available and subject to change. 

But some systems (like mine at work) will have system wide user
commands, and they will want to install the manpage for them. So there
needs to be a simple way to do that.

> Using the command from scripts is also not a problem because as soon
> as STDOUT is not a tty, the plain troff output is echoed anyways, so I
> see no reason why there should be an option for that.

That's a magic behavior that would better be explicit.

For example, if I'm testing a shell script by executing commands
directly in a bash shell, I need the same behavior.

>> If people don't have privs to install the man page, they can view it
>> this way:
>> 
>> mtn man > mtn.1; MANPAGE=.:$MANPAGE man mtn
>> 
>> This could go in the manual.
>
> This and the originally anticipated `mtn man | nroff -man -Tutf8 | less
> -R` is a bit cumbersome and exactly the reason why I build this
> interactivity into the command at all. I was kind of inspired of what
> happens when you e.g. call `git add --help`.

Now that 'isatty' is not a problem, I don't really have a problem with
this interactive feature.

But since it is not reliable on Windows, there needs to be a clear
mechanism for producing and using the localized manpage (both for LANG
and for user commands).

And it would be nice if the error message didn't talk about bugs in
monotone, since it's not.

>> I tried various combinations of 'mtn man | troff | less'; none seemed to
>> work well, I didn't spend much time trying to figure out why.
>
> See the above command - this is also the default one which is configured
> by the hook. If this doesn't work on mingw, we might want to find a
> different call path and distinguish them in the hook.

Obviously I tried that first. I'll give it another go.

>> However, the Cygwin mtn doesn't think bash running under MinGW Emacs is
>> a tty, so it dumps the raw troff source there. 'man mtn' in bash under
>> Emacs does a much better job; 'M-x man mtn' does an even better job. 
>
> I don't know much of emacs, if you have a solution for this let me
> know.

The simplest solution is to provide an option to force
formatted/interactive output. In general, running interactive programs
under Emacs is something of a black art, and it differs between Windows
and Linux (and I assume Mac).

Automagically deducing what the user wants from the detected stdio type
is problematic (under Emacs especially, but also in any other
environment). It's a nice heuristic, but there needs to be a definitive
way for the user to get the behavior they want.

For example, 'mtn sync' guesses whether to use dot or counted progress
style based on the stdout type, and often gets it wrong for me. But the
--ticker option fixes it.

-- 
-- Stephe