LinuxQuestions.org - [SOLVED] xman and section "9" manpages

- Linux - General (https://www.linuxquestions.org/questions/linux-general-1/)

- - xman and section "9" manpages (https://www.linuxquestions.org/questions/linux-general-1/xman-and-section-9-manpages-4175503362/)

xman and section "9" manpages

I have been using xman while working on a systems with a GUI for years. (It's nice to have the xman icon sitting up there on the panel in case I need to look something up.) Earlier I ran across something odd. While using the "apropos" option in xman to search for a topic, it listed a slew of pages that are in section "9". I'd never heard of that section before. It appears to have topics that I would have thought should be in section "8" (system administration) or "2" or "3" (system calls and subroutines). Even though the output of the "apropos" search option listed pages in section "9", the xman ""Sections" drop down menu doesn't show a section "9". The pages are out there under /usr/share/man but they're only accessible via the CLI.

Q1: What is the general category you'd place the section 9 pages in? It looks like a lot of the topics are for hardware configuration, low-level device programming, etc. The file /etc/manpath.config lists a whole lot of sections that but there's no section names to associate with each numbered section.

Q2: Is there a way to get xman to recognize the pages under "man9"? "/usr/share/man" seems to be specified in /etc/manpath.config but only sections up to "8" are being listed. (Then it skips to "n".)

Q3: If the answer to Q2 is "no", is there another tool like xman that I can use instead?

TIA...

--
Rick

Hi,

In your profile it shows Solaris. Is this the OS that you are querying about man(9)? If so then man(9) references kernel interfaces. I believe most Unix-like Gnu/Linux use pages 1-8 unless modified by the maintainer. UNIX Sys V does use (9) for kernel routines.

It would be nice to know which distribution you are working with so we can specify properly.

'man man';

Quote:

man - format and display the on-line manual pages

SYNOPSIS
man [-acdfFhkKtwW] [--path] [-m system] [-p string] [-C config_file] [-M pathlist] [-P pager] [-B browser] [-H htmlpager] [-S section_list] [section]
name ...

DESCRIPTION
man formats and displays the on-line manual pages. If you specify section, man only looks in that section of the manual. name is normally the name
of the manual page, which is typically the name of a command, function, or file. However, if name contains a slash (/) then man interprets it as a
file specification, so that you can do man ./foo.5 or even man /cd/foo/bar.1.gz.

See below for a description of where man looks for the manual page files.

MANUAL SECTIONS
The standard sections of the manual include:

1 User Commands

2 System Calls

3 C Library Functions

4 Devices and Special Files

5 File Formats and Conventions

6 Games et. Al.

7 Miscellanea

8 System Administration tools and Deamons

Distributions customize the manual section to their specifics, which often include additional sections.

Please note the underlined information above.

'man xman';

Quote:

xman - Manual page display program for the X Window System

SYNOPSIS
xman [ -options ... ]

DESCRIPTION
Xman is a manual page browser. The default size of the initial xman window is small so that you can leave it running throughout your entire login
session. In the initial window there are three options: Help will pop up a window with on-line help, Quit will exit, and Manual Page will pop up a
window with a manual page browser in it. Typing Control-S will pop up a window prompting for a specific manual page to display. You may display
more than one manual page browser window at a time from a single execution of xman.

For further information on using xman, please read the on-line help information. Most of this manual will discuss customization of xman.

OPTIONS
Xman supports all standard Toolkit command line arguments (see X(7)). The following additional arguments are supported.

-helpfile filename
Specifies a helpfile to use other than the default.

-bothshown
Allows both the manual page and manual directory to be on the screen at the same time.

-notopbox
Starts without the Top Menu with the three buttons in it.

-geometry WxH+X+Y
Sets the size and location of the Top Menu with the three buttons in it.

-pagesize WxH+X+Y
Sets the size and location of all the Manual Pages.

CUSTOMIZING XMAN
Xman allows customization of both the directories to be searched for manual pages, and the name that each directory will map to in the Sections menu.
Xman determines which directories it will search by reading the MANPATH environment variable. If no MANPATH is found then the directory is /usr/man
is searched on POSIX systems. This environment is expected to be a colon-separated list of directories for xman to search.

setenv MANPATH /mit/kit/man:/usr/man

By default, xman will search each of the following directories (in each of the directories specified in the users MANPATH) for manual pages. If man-
ual pages exist in that directory then they are added to list of manual pages for the corresponding menu item. A menu item is only displayed for
those sections that actually contain manual pages.

Directory Section Name
--------- ------------
man1 (1) User Commands
man2 (2) System Calls
man3 (3) Subroutines
man4 (4) Devices
man5 (5) File Formats
man6 (6) Games
man7 (7) Miscellaneous
man8 (8) Sys. Administration
manl (l) Local
mann (n) New
mano (o) Old

For instance, a user has three directories in her manual path and each contain a directory called man3. All these manual pages will appear alphabet-
ically sorted when the user selects the menu item called (3) Subroutines. If there is no directory called mano in any of the directories in her MAN-
PATH, or there are no manual pages in any of the directories called mano then no menu item will be displayed for the section called (o) Old.

BSD AND LINUX SYSTEMS
In newer BSD and Linux systems, Xman will search for a file named /etc/man.conf which will contain the list of directories containing manual pages.
See man.conf(5) for a complete description of the file format.

THE MANDESC FILE
By using the mandesc file a user or system manager is able to more closely control which manual pages will appear in each of the sections represented
by menu items in the Sections menu. This functionality is only available on a section by section basis, and individual manual pages may not be han-
dled in this manner. (Although generous use of symbolic links -- see ln(1) -- will allow almost any configuration you can imagine.)

The format of the mandesc file is a character followed by a label. The character determines which of the sections will be added under this label.
For instance suppose that you would like to create an extra menu item that contains all programmer subroutines. This label should contain all manual
pages in both sections two and three. The mandesc file would look like this:

2Programmer Subroutines
3Programmer Subroutines

This will add a menu item to the Sections menu that would bring up a listing of all manual pages in sections two and three of the Programmers Manual.
Since the label names are exactly the same they will be added to the same section. Note, however, that the original sections still exist.

If you want to completely ignore the default sections in a manual directory then add the line:

no default sections

anywhere in your mandesc file. This keeps xman from searching the default manual sections In that directory only. As an example, suppose you want
to do the same thing as above, but you don't think that it is useful to have the System Calls or Subroutines sections any longer. You would need to
duplicate the default entries, as well as adding your new one.

no default sections
1(1) User Commands
2Programmer Subroutines
3Programmer Subroutines
4(4) Devices
5(5) File Formats
6(6) Games
7(7) Miscellaneous
8(8) Sys. Administration
l(l) Local
n(n) New
o(o) Old

Xman will read any section that is of the from man<character>, where <character> is an upper or lower case letter (they are treated distinctly) or a
numeral (0-9). Be warned, however, that man(1) and catman(8) will not search directories that are non-standard.

From the above 'MANPATH' would be a good start to see what is available for 'xman' on the system in question.

Hope this helps.
:hattip:

Quote:

Originally Posted by onebuck (Post 5161911)

Hi,

In your profile it shows Solaris. Is this the OS that you are querying about man(9)?

Arrggh! [banging head on desk] I never mentioned that this was on OpenSUSE. :D

I could fire up my old Ultra60 and see what xman shows on that system but I'd have to haul the thing out of the back room and get it reconnected to the LAN. For now I'll take your word that section 9 shows up on Solaris's xman.

I've fixed the missing Section "9" entry though it took some doing. (Caution: long-winded description of the fix process follows. If it feels a little disjointed, I blame that on constant interruptions from phone calls, folks asking me questions, etc.)

There is a manpath.config file under /etc but as far as I can tell, it appears to be OK. It appears to set up the man subsystem for all of the section 1-8 manpages and for a slew of other sections as well.

Code:

 .

 .

 .

SECTION        0 1 n l 8 3 2 5 4 9 6 7 1x 3x 4x 5x 6x 8x 1bind 3bind 5bind 7bind 8bind 1cn 8cn 1m 1mh 5mh 8mh 1netpbm 3netpbm 5netpbm 0p 1p 3p 3posix 1pgsql 3pgsql 5pgsql 3C++ 8C++ 3blt 3curses 3ncurses 3form 3menu 3db 3gdbm 3f 3gk 3paper 3mm 5mm 3perl 3pm 3pq 3qt 3pub 3readline 1ssl 3ssl 5ssl 7ssl 3t 3tk 3tcl 3tclx 3tix 7l 7nr 8c Cg g s m

 .

 .

 .

I decided not to touch this file as the syntax is pretty complex and not well described. I ran across some mention of "man.conf" but there isn't any information on the system about that file -- especially in section 5 where the format should be described -- even though it's referenced in the xman manpage.

I tried manually adding the "man[1-9]" directories to MANPATH, exported it, and fired up xman. Only the numbered sections 1-8 appear in the 'Section' drop down menu; "9" did not show up. (I didn't really expect this to work as I've never seen a MANPATH specify anything deeper than a "man" directory on any Unix system.)

Just for fun, I ran

Code:

strace -v xman 2>&1 | tee /tmp/xman.trace

for various settings of MANPATH and grepped through the resulting log file for instances of file opens -- especially those that did not fail (i.e. did not have an exit status of "ENOENT") -- and found no cases of a successful open of "manpath.conf", "man.conf", or anything like that. Funny thing, though, is that xman is accessing the contents of MANPATH because I saw an open() call looking for the PostgreSQL manpages out under "/opt/app/postgresql/share/man" that is specified in my MANPATH variable (part of the directory tree where Pg is installed on my system). When I had manually added the "man[1-9]" directories xman was looking in those as well. But all these opens were for a file "mandesc" under each MANPATH entry and they were all failing. Hmm...

Everything I've read says that MANPATH controls what directories xman will display but that's not exactly true as I saw with the strace output. Information over at the Xorg web site indicates that /etc/man.conf is used but I saw no evidence that xman was even trying to open that file -- I didn't see an attempt to access it in my strace log -- and, as I expected, when I created one, it had no effect on the menus. (Outdated documentation?)

Recalling all the open() fails I saw in the strace output for "mandesc" files, I found a description of the format for that file on the X.org web site. (It was basically a prettier version of what you posted.) The docs mention that a "mandesc" file may also be used to control xman. I created one -- using an example shown on the Xorg/Xman pages -- and that is -- so far -- the only thing that has made the section "9" pages show up. My version of the mandesc page is:

Code:

no default sections

1(1) User Commands

2(2) System Calls

3(3) Subroutines

4(4) Devices

5(5) File Formats

6(6) Games

7(7) Miscellaneous

8(8) Sys. Administration

9(9) Kernel Routines

l(l) Local

n(n) New

o(o) Old

A variation on the example on the X.org site and your previous reply. I'll try something like:

Code:

9(9) Kernel Routines

and see if the default sections are automagically filled in so I don't have to explicitly specify those. For good measure I copied this file to each entry in MANPATH -- probably overkill and I'll fix it later after testing if I find they're extraneous -- but now the xman Section drop-down menu shows the section 9 pages.

Now on to figuring out what those manpages under the "man0p" directory are all about and getting those added to the menu. (Looks like descriptions of POSIX header files.) I suspect I'll have to get creative if I try and add menu entries for the manpages for many of the sections that are listed in the entries in that SECTION variable in manpath.config. Xman's mandesc doesn't use more than one character to define a section entry.

Anyway... thanks for the hint. Well, maybe not a hint exactly but faced with the prospect of schlepping 50+ pounds of Sparcstation around and reconnecting it to the network just to see how Solaris had things set up and perhaps copying that, I found I'd rather scour the Internet for whatever information I could find on xman. And I got to use a few tools I hadn't touched for a while, too.

Later...

--
Rick