MAN - and colours...

[Dariusz Piatkowski]

OK, so the whole MAN page thing is a handy system...but oh boy, the colours my configuration uses today leave some room for improvement => see attached 'man pdftocairo' output.

Therefore, off I went digging into this realizing that since my MAN setup uses the default LESS pager I most likely need to start looking at LESS colour configuration as well.

Indeed, it would appear that 'SET TERM=ansi-color-3' (my current setup) only controls the framework MAN display colours and not the actual content itself.

...but where do we (OS/2) set/configure this?

More details, my CONFIG.SYS contains the following MAN section:

REM ******************************
REM ***   MAN PAGES - START    ***
REM ******************************
SET CAWFLIB=g:\usr\local\cawf
SET TERMCAP=g:\util\misc\termcap.dat
rem set TERM, valid values are: os2, ansi, ansi-color-3, etc.
SET TERM=ansi-color-3
rem Set the pager to OS/2 MORE command, otherwise uses LESS
rem SET PAGER=MORE
rem SET MANPATH=G:\usr\share\man
REM ******************************
REM ***   MAN PAGES - END      ***
REM ******************************

I've experimented with the various 'SET TERM=' options, but as noted above those do not impact the actual man page content colours.

The strange (to me lol) part is that all LESS documentation states that LESS does in fact use TERM and references TERMCAP, which on my machine appear to be in-sync, and yet even when I set it to 'mono' the colour still appear, so clearly something's off somewhere.

Searching on-line produces a bunch of Linux specific information which typically goes along the lines of something like this:

Code: [Select]

...
# Have less display colours
# from: https://wiki.archlinux.org/index.php/Color_output_in_console#man
export LESS_TERMCAP_mb=$'\e[1;31m'     # begin bold
export LESS_TERMCAP_md=$'\e[1;33m'     # begin blink
export LESS_TERMCAP_so=$'\e[01;44;37m' # begin reverse video
export LESS_TERMCAP_us=$'\e[01;37m'    # begin underline
export LESS_TERMCAP_me=$'\e[0m'        # reset bold/blink
export LESS_TERMCAP_se=$'\e[0m'        # reset reverse video
export LESS_TERMCAP_ue=$'\e[0m'        # reset underline
export GROFF_NO_SGR=1                  # for konsole and gnome-terminal
....
Add the following in your `~.bashrc':
...
Soooo...where the heck do I need to make the change for these darn dark BLUEs to show up without me practically having to poke my nose up against the screen as I attempt to read the text??? 

[Dave Yeo]

It's not less introducing the colours. Try man 7z for an example of a man page with no colours.
The ANSI control characters seem to be right in the man files, along with other control characters.
You can turn off ANSI,

Code: [Select]

ANSI offand the control characters get printed.
I think the problem is our terminal simply handles ANSI slightly differently then other systems, or perhaps using so many colours (video settings, 32 bit colors) screws things up. be interesting to try with less colours, 64k or even 256. My guess the man pages would be more readable
If you open a full screen, a man page is also much more readable.
If you open EPM, do Run-->Create command shell and display a man page there, the colours are displayed differently and are quite readable.
Looking quickly, eg "man man" I can't see an option to turn off the colours.
IIRC, besides an alternate terminal such as EPM, there are other man viewers floating around which might work better for displaying the man pages

[Bogdan]

From the seven or eight different ways to display manual pages under OS/2 only one will work satisfactorily. The picture shows not only problems with the colours but also heavy problems with the codepage. The 'Á' should be rendered to an '*' or '■'.

[Dave Yeo]

Hmm, the  only options are,

Code: [Select]

-E encoding, --encoding=encoding
              Generate output for a character encoding other than the default.
              For backward compatibility, encoding may be an nroff device such
              as ascii, latin1, or utf8 as well as a true  character  encoding
              such as UTF-8.

Whereas I guess we need CP850. The nroff man page states,

Code: [Select]

The nroff script emulates the nroff command using groff.   Only  ascii,
       latin1,  utf8,  and  cp1047 are devices accepted by nroff to select the
       output encoding emitted by grotty, groff's TTY output device.  If  nei-
       ther  the GROFF_TYPESETTER environment variable nor the -T command line
       option (which overrides the environment variable) specifies  a  (valid)
       device,  nroff  checks  the  current  locale to select a default output
       device.  It first tries the locale program, then the environment  vari-
       ables  LC_ALL, LC_CTYPE, and LANG, and finally the LESSCHARSET environ-
       ment variable.
Should also note that it seems often the colours are shown instead of bold, italic and such that don't work on our VIO window.
Bogdan, any recommendations for a better man viewer?

[Dave Yeo]

Found http://hobbes.os-2.in/files/os2/apps/docviewer-4/SimplifiedMAN_1-0.zip from Alex, seems to do the job. Needs some environment variables such as MANPATH set.

[Dariusz Piatkowski]

Hello Dave!

Found http://hobbes.os-2.in/files/os2/apps/docviewer-4/SimplifiedMAN_1-0.zip from Alex, seems to do the job. Needs some environment variables such as MANPATH set.

This is a great point, in fact I had deployed Alex's version a few years back however I was never able to get the page sizing/offsets correct, and never figured out what actually controls this.

Take a look at the attached screenshots:

1) the 1st one shows how SimplifiedMAN leaves a few lines up top on the 1st page, this causes all other pages to be offset

2) the 2nd one shows how the remaining pages show the '^L' character where a page-brake should happen (I believe)

[Dariusz Piatkowski]

Hello Bogdan,

From the seven or eight different ways to display manual pages under OS/2 only one will work satisfactorily. The picture shows not only problems with the colours but also heavy problems with the codepage. The 'Á' should be rendered to an '*' or '■'.

I don't disagree with what you stated above...but is there a recommendation you have as far as how to actually remedy the issue?

[David McKenna]

Hi Dariusz,

 Never had a MAN reader setup before, so tried installing CAWF and Alex's MAN script (and added CAWFLIB, TERM, and MANPATH paths to CONFIG.SYS) but I can't get an actual 100% working display. In a command prompt, the first page displays with a message at the bottom 'Waiting for data...' and cannot continue beyond that (space-bar, enter, esc, etc. don't do anything). I suspect it has to do with the VAST majority of MAN pages on my system are *.gz files. They fully display in the EPM shell, but with weird formatting that makes them unreadable (maybe an EPM configuration issue?) and also MEShell they display the best, but with frequent 'unknown font' errors.

 You mention a 'termcap.dat' file in your setup (I don't recall seeing that in any setup instructions I've read). Don't have that on my system - do you remember where you got it? Maybe that would help on my machine.

Regards,

[Bogdan]

Hmm, the  only options are,

Code: [Select]

-E encoding, --encoding=encoding
              Generate output for a character encoding other than the default.
              For backward compatibility, encoding may be an nroff device such
              as ascii, latin1, or utf8 as well as a true  character  encoding
              such as UTF-8.

Whereas I guess we need CP850. The nroff man page states,

Code: [Select]

The nroff script emulates the nroff command using groff.   Only  ascii,
       latin1,  utf8,  and  cp1047 are devices accepted by nroff to select the
       output encoding emitted by grotty, groff's TTY output device.  If  nei-
       ther  the GROFF_TYPESETTER environment variable nor the -T command line
       option (which overrides the environment variable) specifies  a  (valid)
       device,  nroff  checks  the  current  locale to select a default output
       device.  It first tries the locale program, then the environment  vari-
       ables  LC_ALL, LC_CTYPE, and LANG, and finally the LESSCHARSET environ-
       ment variable.
Should also note that it seems often the colours are shown instead of bold, italic and such that don't work on our VIO window.
Bogdan, any recommendations for a better man viewer?

I dont't know which version of less or any other pager was used causing the reported problems. For the local console utilising Vio calls there are at least 5 different solutions. The Japanese ports of groff & Co. should give the best results. The ports from these RPMs should only be used remotely with terminals capable of ISO/IEC 8859-1. Manual changes to terminfo db are recommended for colour terminals btw. - infocmp can be useful.

For better searching and indexing it's better to use the docview of emacs or other advanced text editors or development environments. Nowadays it would be quite simple to use the UNIX docview facility from a web browser that also can generate PDF files of pages and whole sections.

For users of the C language it should be no problem to use the programs and macros from DWB that were open sourced by AT&T more than 20 years ago.

[Anton Monroe]

I cannot reproduce the problem-- the text that you see in blue, I see in red.
But you might look at the -D switch for less. I can change the color with
    PAGER=less -Ducw$Ddwr
which tells less to show underlined text as cyan on white and bold text as
white on red. I also use "-R -c" for less, but I don't remember exactly why.

My environment has no mention of termcap and I have no termcap.dat file. Maybe
you are using an older version of less? Mine is version 668, dated Feb. 25 2025
and came from the less-668-1.oc00.pentium4 rpm package.

From the CAWFLIB and MANPATH entries in you config.sys, I suspect you are using
Alex Taylor's simplified man.cmd. The man.exe I normally use is from the
man-db-2.7.6.1-3.oc00.pentium4 rpm package. Try installing it with yum or ANPM.
It probably depends on groff and maybe other packages.  Unlike man.cmd,
man.exe expects a Unix-style %manpath with a colon as a path separator, like

    /@unixroot/usr/local/share/man:/@unixroot/usr/share/man

Years ago I hacked the man.cmd to add a few features. See the attached file.
You can experiment with different settings for the pager and term on the
command line without needing to change the environment each time. As in

    man.cmd <manpage> -pager="less -R -c -Ducw" -term=ansi-color-3

Note that it also defaults to using groff because groff seems to produce fewer
error messages than cawf. If you want to keep using your existing cawf you will
need to specify it on the command line like

    man.cmd <manpage> -troff="cawf -man"

It understands either an OS/2 or Unix-style %manpath, so I can have a Unix
%manpath in my environment and let man.cmd convert it.

I keep man.cmd around because I have run into a couple of man pages that seem
to work better with it.

[Bogdan]

Hello Bogdan,

From the seven or eight different ways to display manual pages under OS/2 only one will work satisfactorily. The picture shows not only problems with the colours but also heavy problems with the codepage. The 'Á' should be rendered to an '*' or '■'.

I don't disagree with what you stated above...but is there a recommendation you have as far as how to actually remedy the issue?

I have no idea about the state of the man page system now shipped via RPM. I would try to determine the used macro (man, mdoc, or mandoc) that will be invoked and simply modify the corresponding macro by inserting the control codes. But that would be only a dirty hack for ANSI capable terminals (OS/2 CMD windowed or full screen). NYAOS or 4OS2 can behave differently. Using awk/sed and the OS2_SHELL environment variable in the shell scripts would be the cleaner solution.

[Dave Yeo]

Yes, simplified man does seem broken.
I built this, probably could use some porting. Click the Preferences button for options, click Append and add your path to find man pages. Here so far I've add W:/usr/share/man and W:/usr/local/share/man. Take a few seconds to build an index then use the search bar.
Requires Qt5 and I guess the usual stuff that man requires. It's built to install in /@unixroot/usr/local but seems to work fine without installing.
Edit: Source from https://gitee.com/dyfet/manpager
Patch,

Code: [Select]

diff --git a/Manpager.pro b/Manpager.pro
index a8eb539..e075e15 100644
--- a/Manpager.pro
+++ b/Manpager.pro
@@ -57,6 +57,12 @@ win32 {
     RC_ICONS += "$${TARGET}.ico"
 }

+os2 {
+    CONFIG += DesktopClient
+    PREFIX = /@unixroot/usr/local
+}
+

 !CONFIG(DesktopClient):error(unsupported platform)

 # project layout

And add an icon.
Replace the binary with one with the icon
and replace the binary with one that should automatically find the usual man pages, in /@unixroot/usr/share/man and /@unixroot/usr/local/share/man, even /@unixroot/opt/local/man if it exists.

[Dariusz Piatkowski]

Hi David!

...Never had a MAN reader setup before, so tried installing CAWF and Alex's MAN script (and added CAWFLIB, TERM, and MANPATH paths to CONFIG.SYS) but I can't get an actual 100% working display. In a command prompt, the first page displays with a message at the bottom 'Waiting for data...' and cannot continue beyond that (space-bar, enter, esc, etc. don't do anything). I suspect it has to do with the VAST majority of MAN pages on my system are *.gz files. They fully display in the EPM shell, but with weird formatting that makes them unreadable (maybe an EPM configuration issue?) and also MEShell they display the best, but with frequent 'unknown font' errors.

 You mention a 'termcap.dat' file in your setup (I don't recall seeing that in any setup instructions I've read). Don't have that on my system - do you remember where you got it? Maybe that would help on my machine...

I zipped up what I have, two versions actually, no idea where I picked them up. I will say that the termcap.dat appears to work 'better' than the other one...I only say this b/c trying the other one produced control codes that were visible when they shouldn't have been shown.

To have another 'go' at it I would suggest you take a look at the modified script which Anton shared. I switched to that one having previously modified Alex's script to suit my purposes (I had it reading a separate MANPATH and leaving the RPM MAN to fetch directly from man_db.conf.

[Dariusz Piatkowski]

Hello Anton!

I cannot reproduce the problem-- the text that you see in blue, I see in red.
But you might look at the -D switch for less. I can change the color with
    PAGER=less -Ducw$Ddwr
which tells less to show underlined text as cyan on white and bold text as
white on red. I also use "-R -c" for less, but I don't remember exactly why...

AHA!!! ...thank you for sharing this...I started to look at the colour coding b/c it seemed like nothing else I was trying was making sense and well the MAN page for LESS has a pretty good section on this very topic, so your feedback confirmed that!

...My environment has no mention of termcap and I have no termcap.dat file. Maybe you are using an older version of less? Mine is version 668, dated Feb. 25 2025 and came from the less-668-1.oc00.pentium4 rpm package...

I am not sure (simply do not remember truth be told) why I have TERMCAP set, however seeing as I positioned it within the MAN section of my CONFIG.SYS I can only venture a guess that I deemed it to be needed for that purpose?

...From the CAWFLIB and MANPATH entries in you config.sys, I suspect you are using Alex Taylor's simplified man.cmd. The man.exe I normally use is from the man-db-2.7.6.1-3.oc00.pentium4 rpm package. Try installing it with yum or ANPM.
It probably depends on groff and maybe other packages.  Unlike man.cmd, man.exe expects a Unix-style %manpath with a colon as a path separator, like

    /@unixroot/usr/local/share/man:/@unixroot/usr/share/man

Years ago I hacked the man.cmd to add a few features. See the attached file...

Couple of things here worth noting:
1) Alex's Simplified MAN, yes, I had installed it and actually stopped using it having deployed the RPM man install, so yes, I am using the same version you are
2) The only strange thing is that in my install the RPM man does not need MANPATH to be set, it simply goes to \etc\man_db.conf and reads those contents automatically

...but as I started troubleshooting this issue I did go back to Alex's work to see if I could debug what it's doing and the specific calls it's making. Not a terribly complex piece of REXX, so that was easy enough to do.

...You can experiment with different settings for the pager and term on the command line without needing to change the environment each time. As in

    man.cmd <manpage> -pager="less -R -c -Ducw" -term=ansi-color-3

Note that it also defaults to using groff because groff seems to produce fewer
error messages than cawf. If you want to keep using your existing cawf you will
need to specify it on the command line like

    man.cmd <manpage> -troff="cawf -man"

It understands either an OS/2 or Unix-style %manpath, so I can have a Unix
%manpath in my environment and let man.cmd convert it...

Alright, so I downloaded your version and had a go at it. Thank you very much because the changes you implemented were similar to what I've done with my changes, albeit much more sophisticated - as in the various options to use different PAGERs, etc.

Working with your script also allowed me to notice that I actually had TWO different version of LESS present:

1) RPM
less 668 (POSIX regular expressions)
Copyright (C) 1984-2024  Mark Nudelman

2) OTHER
less 458 (Spencer V8 regular expressions)
Copyright (C) 1984-2012 Mark Nudelman

As it turned out, I was playing with the different colour options and for some strange reason running your script from my utilities directory was producing a different colouring output as compared to me running the very same script from elsewhere...and that's when the bells went off: "yikes...I've got something sitting there that shouldn't be!!!" lol

OK, so one problem addressed.

Seeing as we have this hybrid thing on OS/2 I suppose it is to be expected that some of this requires additional work, I just didn't expect that to be the case with MAN as that is such a core element of Unix help system.

Anyways, alright, so here is what my final version of CONFIG.SYS MAN section looks like:

Code: [Select]

REM ******************************
REM ***   MAN PAGES - START    ***
REM ******************************
rem The below two lines are part of the Simplified MAN setup by Alex Taylor
SET CAWFLIB=g:\usr\local\cawf
SET MANPATH_SIMPLE=G:\usr\share\man;G:\usr\local\share\man

rem MAN uses \etc\man_db.conf by default, but this allows to append other paths AFTER man_db.conf
SET MANPATH=:G:/usr/share/man:G:/usr/local/share/man

rem LESS options to show the % displayed in MAN pages, applies SYSTEM-WIDE
SET LESS="-M +Gg"

SET TERMCAP=g:\util\misc\termcap.dat
rem set TERM, valid values are: os2, ansi, ansi-color-3, etc.
SET TERM=ansi-color-3

rem Set the pager to OS/2 MORE command, otherwise uses LESS by default
rem SET PAGER=MORE
REM ******************************
REM ***   MAN PAGES - END      ***
REM ******************************

Appreciate everyone's input on this...what I now have suits me fine, see attached.

[Dariusz Piatkowski]

Dave!

...I built this, probably could use some porting. Click the Preferences button for options, click Append and add your path to find man pages. Here so far I've add W:/usr/share/man and W:/usr/local/share/man. Take a few seconds to build an index then use the search bar.
Requires Qt5 and I guess the usual stuff that man requires. It's built to install in /@unixroot/usr/local but seems to work fine without installing...

NICE!

Thank you...this is very handy, especially the ability to open up multiple MAN pages at once.