NetBSD-Docs archive

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

Re: how to identify that manpage is only for certain platforms?

Jeremy C. Reed wrote:
> But what about few manpages that refer to asc(4)? But asc.4 is for a few
> ports like: acorn32, alpha, pmax, and vax.
> How should those be handled when refering to them? List it four times 
> (with "port/")? Have some comment about the ports? Or just ignore it -- 
> causing frustration for those trying to get more details?

Ignoring missingness is just wrong.  

The man pages should be tailored per-port: asc.4 distributed only with
each port it belongs to, and referring pages mentioning it only if it
exists.  You can think of it as referential integrity for man pages, or no
broken links.  

That's the right way to do it.  Nothing extraneous is mentioned and
nothing pertinent is lost.  But it means some work: a database of ports
and pages, and some way to generate the SEE ALSO sections.  

The other alternatives are less work:

1.  Just include everything.  One set of identical man pages for all
ports.  (Except stuff like intro(4).) 
2.  Indicate port-specificity on the referring page ("SEE ALSO i386/isa").
3.  Indicate port-applicability on the device page. 

#2 won't work.  At first glance, it would seem the best: on the referring
#page, mention the port-specific informtion, because the reader knows what
#not to chase down.  But this leads to a lot of ugliness: i386/this and
#vax/that on every referring page.  And of course many devices are
#supported on several ports.  

That leaves 1 and 3, but I like DTRT best.  


Home | Main Index | Thread Index | Old Index