I completely disagree on that topic. The primitive cludge is using links in the file system to annotate man page aliases. .Nm by itself is a much, much cleaner approach and something man(1) should learn to use at a later point of this project.You may disagree on technical grounds, but I doubt you can deny that .Nm's spanning multiple lines are just plain ugly from a typographic stance. These hide the .Nd and have largely no value for a reader as the prototypes are always listed in SYNOPSIS (same goes for other sections). From this point, one could use .XX macro that is not rendered. Also: try "apropos power": PCI, pci_activate, pci_chipset_tag_create, pci_chipset_tag_destroy, pci_conf_read, pci_conf_write, pci_conf_print, pci_conf_capture, pci_conf_restore, pci_find_device, pci_get_capability, pci_mapreg_type, pci_mapreg_map, pci_mapreg_info, pci_intr_map, pci_intr_string, pci_intr_evcnt, pci_intr_establish, pci_intr_disestablish, pci_get_powerstate, pci_set_powerstate, pci_vpd_read, pci_vpd_write, pci_make_tag, pci_decompose_tag, pci_findvendor, pci_devinfo, PCI_VENDOR, PCI_PRODUCT, PCI_REVISION (9) - Peripheral Component Interconnect PMF, pmf_device_register, pmf_device_register1, pmf_device_deregister, pmf_device_suspend, pmf_device_resume, pmf_device_recursive_suspend, pmf_device_recursive_resume, pmf_device_resume_subtree, pmf_class_network_register, pmf_class_input_register, pmf_class_display_register, pmf_system_suspend, pmf_system_resume, pmf_system_shutdown, pmf_event_register, pmf_event_deregister, pmf_event_inject, pmf_set_platform, pmf_get_platform (9) - power management and inter-driver messaging framework How does that parse for a human user?(a) apropos doesn't have to show all of them. In fact, it should just give the name of the man page. That works even better if all the links go away and only the authoritive copy of the man page remains. (b) If you have too many .Nm entries, it's a sign that you should consider splitting your man page. (c) It's not used just for section 3/9 man pages nor is one set part consistently a subset of the other.
Hi, shameless plug here, and maybe a bit of competition for neat manual stuff. mandoc's nascent apropos tool,
http://mdocml.bsd.lv/mandoc-tools/index.htmldoes exactly point (a). It differs from the GSoC apropos (which, in looking at the code, seems based on an old version of mandoc's makewhatis.c) in doing semantic instead of free-form searches, so `power' is queried in things like the `Nm' names (or -man NAME section names), description (`Nd' and -man NAME descriptions), variable names, utility names, and so forth---but not in standalone text.
% ./apropos power ACPICPU(4) - ACPI processor power and performance state ACPIPWRRES(4) - ACPI power resources ACPITIMER(4) - ACPI power management timer APM(4/MacPPC) - advanced power management device interface APM(4/Loongson) - advanced power management device interface APM(4/Zaurus) - advanced power management device interface APM(4/i386) - advanced power management device interface APM(4/AMD64) - power management interface DOPOWERHOOKS(9) - run all power hooks EXP(3) - exponential, logarithm, power functions LDEXP(3) - multiply floating-point number by integral power of 2 MACEBUS(4/SGI) - Multimedia, Audio and Communications Engine I/O ASIC PCI_CONF_READ(9) - PCI config space manipulation functions PCI_INTR_MAP(9) - PCI interrupts PMC(4/SPARC64) - power management controller POWER(4/HPPA) - power button and power fail support POWER(4/SPARC64) - power button POWER(4/SGI) - power button POWER(4/LANDISK) - power switch POWERHOOK_ESTABLISH(9) - add or remove a power hook % ./apropos -a AMD64 power APM(4/AMD64) - power management interfaceNote that this is initial output. You can see the full capabilities, such as the matching semantic region and links to formatted output, as currently used by the CGI. Both have the same backend.
http://mdocml.bsd.lv/cgi-bin/mandoc.cgi?key=powerNote these are for makewhatis databases generated on an OpenBSD box by the CVS version of "makewhatis" tool in mandoc. All of these tools should work on any architecture.
Thanks, Kristaps