Re: CVS commit: src

[Mindaugas Rasiukevicius <rmind%netbsd.org@localhost>]

yamt%mwd.biglobe.ne.jp@localhost (YAMAMOTO Takashi) wrote:
> > - We already have some practices of writing documentation is such way,
> >   like mutex(9), rwlock(9), softint(9), vnode(9) and bunch of others.
> >   And I would like to keep such consistent structure.
> 
> vnode(9) and sysctl(9) are good examples which i don't want to read. :)

I found their structure as quite good.

Do you think it would be better to split vnode(9) into 27 (!) man-pages?
It is the amount of functions in that page.

> > - Reading bit-by-bit, via "see also" links and creating an overall image
> >   of subsystem in such way is quite disturbing, in my opinion.
> 
> it's the reason to have an "overview" page like
> vmem(9) (the one before your change, i mean).

DESCRIPTION
     The vmem is a general purpose resource allocator.  Despite its name, it
     can be used for arbitrary resources other than virtual memory.

That was it. Does not really overview much, does it? :)

> > - Single man pages for each function are getting generally messy. They get
> >   "lost" by reader and are often outdated.
> 
> for example?

For example cpu_*(9) manual pages are scattered and do not demonstrate any
structure of MD or CPU-related subsystems. Although the actual contents can
be good, e.g. cpu_switchto(9).

> i disagree what's a readable structure.
> i consider a unified page unstructured.  ie. you need to read the
> contents to know where something you want to read is.

It is important to have a good introduction to subsystem / interface, with
which reader is probably new. Whole image is essential here.

-- 
Mindaugas