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?

On Wed, 26 Mar 2008, James K. Lowden wrote:

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

Coming back to old thread as I forgot to commit something, but now I see 
may have been wrong in first place.

So also architecture specific man pages should go into own directories:

I was planning to commit:

--- share/man/man4/mc.4 26 Sep 2003 19:53:50 -0000      1.1
+++ share/man/man4/mc.4 10 Sep 2008 18:31:39 -0000
@@ -67,7 +67,7 @@
 Ethernet address of the adapter.
-.Xr ae 4 ,
+.Xr \&mac68k/ae 4 ,

But now I realize that share/man/man4/mc.4 should really be at 
share/man/man4/man4.mac68k/mc.4 instead.

tx:src$ grep 'Dt MC' /usr/src/share/man/man4/*
/usr/src/share/man/man4/mc.4:.Dt MC 4 mac68k
/usr/src/share/man/man4/mca.4:.Dt MCA 4
/usr/src/share/man/man4/mcclock.4:.Dt MCCLOCK 4
/usr/src/share/man/man4/mcd.4:.Dt MCD 4

To me it looks like mc.4 is in wrong place.

Okay if I move that?

Home | Main Index | Thread Index | Old Index