y...@mwd.biglobe.ne.jp (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
