etcman.conf


/etc/man.conf

The man.conf file tells man(1) how to find and present manual pages. If you install software in nonstandard locations, this file will be quite helpful to let you access documentation transparently. For example, in some environments add-on software is installed under /usr/pkg or /opt. By editing /etc/man.conf, you can access the manual pages in that directory tree just as you can base system documentation. The file has several sorts of entries, each set off by keywords or section names.

Search Index

The "_whatdb" keyword gives the full path to a whatis(1) database, as used by whatis(1) and apropos(1), allowing users to easily search and cross-index the manual. These databases can be created by makewhatis(8). Here, we tell the manual system to check the file /usr/pkg/man/whatis.db when you run apropos(1) or whatis(1):

 _whatdb      /usr/pkg/man/whatis.db 

Manual Page Location

Manual pages are scattered in directories all over the system. To tell man(1) which directories to check by default, use the "_default" keyword. You can group directories by using brackets.

For example, here's the standard default directory listing:

 _default    /usr/{share,X11R6,X11,contrib,gnu,local}/{man,man/old} 1 / 

We have a massive group of directories here. The brackets are used to combine multiple directories associatively — for example, this entry means that we check /usr/share/man, /usr/share/man/old, /usr/X11R6/man, /usr/X11R6/man/ old, and so on. Note that this entry ends with a 1 slash; this indicates that this entry has subdirectories. To add /usr/pkg/man to the default locations, just add "pkg" in amongst the directories like so:

 _default    /usr/{share,X11R6,X11,contrib,gnu,local, 1 pkg}/{man,man/old}/ 

By adding in the 1 pkg directory name here, we've added the directories /usr/pkg/man and /usr/pkg/man/old to the directory list.

The "_subdir" keyword contains a list of subdirectories to be searched under other directories. Only use one _subdir entry. These directories will be searched in order.

 _subdir           1 cat1 2 man1 cat8 man8 cat6 man6 cat2 man2 cat3 man3 cat5 man5 cat7 man7 cat3f man3f cat4 man4 cat9 man9 cat3p man3p 

For example, our search starts in /usr/share/man, as defined by our _default list. Man(1) will check in 1 /usr/share/man/cat1 for a manual page of the desired name, and then proceed to 2 /usr/share/man/man1, and go on down the list. The user will see the first matching manual page.

Displaying Manual Pages

Manual pages are distributed in a wide variety of formats, depending on the software distributor's preferred format. Each different format must be displayed using a different command. Fortunately, each different format also has a different filename suffix, which can be used to determine how to display the file. The "_build" keyword defines a filename suffix and the command used to display that file. Here are a couple simple examples:

 _suffix        1 .0 _build         2 .0.Z            3 /usr/bin/zcat 4 %s ... 

Our first examples, files ending in 1 .0, do not need any special formatting command; the file is simply dumped directly to the pager. Our second entry, files ending in 2 .0.gz, need to be processed by 3 zcat first. The 4 %s is a macro for the file containing the manual page.

Section Names

The final function handled by man.conf is dividing the manual into sections. We saw in Chapter 1 that you can search the manual by particular sections to get certain man pages. These sections are nothing more than directories identified in /etc/man.conf. For example, here's where we define the manual pages included in section 1:

 1          /usr/{share,X11R6,X11,contrib,local}/{man/,man/old/}{cat,man}1 

There is no trailing slash, because we are not searching any subdirectories; these are the actual directories containing section 1 man pages. You can define arbitrary section names in /etc/man.conf. While it's a good idea to stay away from section names beginning with an underscore, to avoid confusion with man.conf's keywords, you could do just about anything else. The default man.conf has a few section names defined, much like this one for the "local" section.

 local          /usr/local/man/ 

If you only want to search the man pages for locally installed software for the command "test," you could run "man local test." You could easily add a local section name for your developer manual pages.




Absolute Openbsd(c) Unix for the Practical Paranoid
Absolute OpenBSD: Unix for the Practical Paranoid
ISBN: 1886411999
EAN: 2147483647
Year: 2005
Pages: 298

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net