Re: GSoC Project Status Update: Apropos Replacement

[Joerg Sonnenberger <joerg%britannica.bec.de@localhost>]

On Tue, Jun 21, 2011 at 02:37:13PM +0300, Jukka Ruohonen wrote:
> On Tue, Jun 21, 2011 at 01:25:03PM +0200, Joerg Sonnenberger wrote:
> > 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.

Joerg