tech-userlevel archive

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index][Old Index]

Re: GSoC Project Status Update: Apropos Replacement

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,

does 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 interface

Note 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.

Note 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.



Home | Main Index | Thread Index | Old Index