typo in 'getopts --man' about ksh HOT 7 CLOSED

in this context, one further remark/question:

anyCommand --man 2>&1 | anyThing looses tty size info and text markup (bold, italics -- those \b...\b and \a...\a constructs of getopts). the usual use case is piping long manpages into the pager (less, mostly) in order to be able to easily scroll, read, search. while I understand that tty size is lost when using the pipe and some default line length needs to be used, the stripping of ansi escapes (I guess?) that are doing the text annotation (bold, italics) seems not desirable:
compare, e.g. man ksh vs. man ksh|less vs. ksh --man vs. ksh --man 2>&1|less. man (or groff --man) does not stripe the ansi escapes and I think this is more reasonable since saving the output of --man to a file seems a rare demand.

I also note that ksh now at least hints at the necessity to redirect stderr to stdout of --man output, but is it really out of the question to send the output directly to stdout? typing the redirect stuff too often is a minor pain in the back frequently :). what is the reason for keeping it this way? backward compatibility?

from ksh.

Thanks for the report. The typo will be fixed.

anyCommand --man 2>&1 | anyThing looses tty size info and text markup (bold, italics -- those \b...\b and \a...\a constructs of getopts).

Export the COLUMNS and LINES variables to preserve tty size info. Export ERROR_OPTIONS=emphasis to force emphasis markup.

typing the redirect stuff too often is a minor pain in the back frequently :). what is the reason for keeping it this way? backward compatibility?

Yes.

It's very hard to change without breaking other things. The design is that --man output is treated as if it is an error message. Error messages and --man output are printed using the exact same errormsg function call.

Issues like these are why I wrote an autoloadable man function, which is now part of the ksh 93u+m distribution. The workarounds for these inconveniences are hidden in the function. Just type man anyCommand and it will show the built-in manual page with your configured pager. If no built-in page is found (or if there is more than one argument to man) then the function simply hands off to the system's man command. End result is that, barring any bugs, you can just use man for everything.

from ksh.

thanks for explaining. I now see that all this could have been found in the ksh93u+m manpage (I have not installed the manpage so only ever see the system manpage of ksh which is ... suboptimal). this (exporting COLUMNS etc.) essentially solves the issue except:

by default I have less enumerate its output and this makes the $COLUMN wide --man output too wide so it wraps around and one has to switch off line numbering to get it right. there probably is not much that can be done about this I guess (and it is not a big deal anyway).

also thanks for the pointer to your autoloadable man function. maybe this is the way to go. the only glitch I see is that it drops through to system man immediately if any options are given to the man call. personally I have/need a man alias setting the -C configfile option (to fix groff issues) and this prevents the man function from ever kicking in, really.

maybe the function could just ignore any options if a built-in manpage is found in the last arg and only dispatch to system man (including the options...) otherwise?

from ksh.

also thanks for the pointer to your autoloadable man function. maybe this is the way to go. the only glitch I see is that it drops through to system man immediately if any options are given to the man call. personally I have/need a man alias setting the -C configfile option (to fix groff issues) and this prevents the man function from ever kicking in, really.

Try this patch. It allows you to set .sh.manopts='-C configfile'.

If that works for you, I'll commit it.

diff --git a/src/cmd/ksh93/fun/man b/src/cmd/ksh93/fun/man
index 538b484a9..234f9a55b 100755
--- a/src/cmd/ksh93/fun/man
+++ b/src/cmd/ksh93/fun/man
@@ -102,9 +102,7 @@ namespace man
 
 	pager()
 	{
-		typeset IFS		# local default split...
-		set -o noglob		# ...and no pathname expansion...
-		${PAGER:-less -R}	# ...so we can safely split $PAGER
+		${PAGER:-less -R}
 	}
 
 	# Try if a system manual page in a section exists. Unfortunately, we
@@ -115,7 +113,7 @@ namespace man
 
 	try_os_man()
 	{
-		[[ $2 != */* && $(command man -s "$1" "$2" 2>/dev/null) == *$'\n'*$'\n'*$'\n'* ]]
+		[[ $2 != */* && $(command man ${.sh.manopts-} -s "$1" "$2" 2>/dev/null) == *$'\n'*$'\n'*$'\n'* ]]
 	}
 
 	# The main function puts it all together. When given a single argument,
@@ -129,17 +127,17 @@ namespace man
 	main()
 	{
 		if (($# != 1)); then
-			command man "$@"
+			command man ${.sh.manopts-} "$@"
 		elif builtin_has_selfdoc "$1"; then
 			show_selfdoc "$1" | pager
 		elif try_os_man 1 "$1"; then
-			command man -s 1 "$1"
+			command man ${.sh.manopts-} -s 1 "$1"
 		elif try_os_man 8 "$1"; then
-			command man -s 8 "$1"
+			command man ${.sh.manopts-} -s 8 "$1"
 		elif extcmd_has_selfdoc "$1"; then
 			show_selfdoc "$1" | pager
 		else
-			command man "$1"
+			command man ${.sh.manopts-} "$1"
 		fi
 	}
 }
@@ -160,6 +158,8 @@ namespace man
 
 function man
 {
+	typeset IFS	# local default split...
+	set -o noglob	# ...and no pathname expansion, for safe field splitting
 	.man.main "$@"
 }
 

from ksh.

thanks for bothering :).

and yes, this helps. it still does not tolerate the presence of the so-far used alias

alias man='man -C configfile

but setting instead .sh.manopts='-C configfile' (and removing the alias) seems to make it work flawlessly, both, for system commands and ksh buitlins (and scripts using getopts).

I tested it just sourceing your man function. what did not work in this setup, was trying to use man from within the directory where the man function was stored. issuing man system_command from there was not showing anything (but man builtin or man my_script did work). no big deal but of course not desirable. is this behaviour expected?

from ksh.

I tested it just sourceing your man function. what did not work in this setup, was trying to use man from within the directory where the man function was stored. issuing man system_command from there was not showing anything (but man builtin or man my_script did work). no big deal but of course not desirable. is this behaviour expected?

No, and I cannot reproduce it:

$ (unset FPATH; ENV=/./dev/null ksh)      
$ cd /usr/local/src/ksh93/ksh/src/cmd/ksh93/fun                                                                                    
$ source ./man
$ man ls
(ls(1) man page shown as normal)

from ksh.

No, and I cannot reproduce it:
too bad, since I can... I tried a few things to understand it, but to no avail. to be specific about the situation here:

• I am currently using Version AJM 93u+m/1.1.0-alpha+d33c64a7 2023-06-05 and if that might be the cause, I of course will update (but I would not expect this: man even seems to mostly work just fine with ksh93u (although complaining about missing whence -t option)...).

• I have put the man function into $HOME/bin/kshfun from where it is sourced in my .kshrc (FPATH not used)

• I have put .sh.manopts='-C my_configfile' into .kshrc

• a new shell then can use man as intended, both, for system commands (by dispatching correctly to system man including the -C option (I believe, need to check again) as well as for builtins and getopts based scripts

• this works especially in $HOME and $HOME/bin but dispatch to system man stops working in $HOME/bin/kshfun (where man resides). by putting some print -u2 into main() it transpires that the else clause is triggered for system commands at this point (command man ${.sh.manopts-} "$1") -- and this just returns silently and immediately to the command prompt. when called elsewhere on a system command the elif try_os_man 1 "$1"; then clause is triggered instead (executing command man ${.sh.manopts-} -s 1 "$1")

• I furthermore have noted that (as mentioned) man seems mostly to work identically with ksh93u while complaining about whence -t missing. and I do not see the WARNING: this man wrapper function requires ksh 93u+m 2021-12-27 or later message except if I issue man from within said directory where man is stored (and it only appears after susbantial (1-2 secs) latency).

• UPDATE: in case this is relevant: actually my login shell (OSX) is set to ksh93u. I only start+use ksh93u+m as a subshell but I cannot see how that would interfere?

I so far really have no idea what is going wrong. let me know if you want me to provide further information

from ksh.