Categories Each man page may have a .SH CATEGORY <category> entry. If it does, then an entry is added to the <category>.c command listing. Whether it does or does not have a .SH CATEGORY entry, an entry is added to the section listing (eg 1.c, 8.c, etc). Each category may have a man page itself in the source tree, as <category>.c. If it does, then the autogenerated portion of the category man page is prefixed with the existing man page. Namespaces A category man page is <category>.c and the category namespace must be unique. The "Categories" and "Alphabetical" categories are reserved for system use; you must pick a different name. It’s a requirement that the entire namespace is unique, when including the section name/number. Helptool Inside helptool, we index things by <name>.<section> which explains the namespace requirement. It looks like this when you start up helptool on a bunch of man pages in sections 1, 5, 8 with some which had .SH CATEGORY Category1, Category2: Categories All Category1 Category2 1 7 8 Alphabetical abort.1 … … foo.1 foo.8 … zebra.8 Autogeneration of information We generate a temporary listing of command synopsis in _<category>.c as we work through the list of files. At the end, we sort these, add the roff commands to turn it into a listing, and create <category>.c, either prepended with the man page <category>.c or we provide a default header (the standard BitMover .TH stuff). The complete list of autogenerated pages are All.c A.c B.c C.c where A, B, C are .SH CATEGORY entries 1.c 8.c where 1, 8 are man page suffices. Lookups bk help/helptool will now take lookups of the form <name> or <name>.<section>. If there is a foo.1 and a foo.8 and you say bk helptool foo, you get foo.1. This has implications for the helptopiclist command.