Re: CVS commit: src

[yamt%mwd.biglobe.ne.jp@localhost (YAMAMOTO Takashi)]

hi,

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

they are hard to read, at least for me.  is it a good thing? :-)

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

yes.

> 
>> > - 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? :)

it can be improved.

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

it's a good reason to have an overview page.
it isn't a good reason to unify pages.

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

ditto.

> 
> -- 
> Mindaugas

honestly speaking, it seems that it's a matter of taste.
you have your preference and i have mine.

if the project decided to have a preference (like KNF), i think it should
be documented in somewhere before performing changes like this.
otherwise someone might change it in a different way, for his valid reasons.

YAMAMOTO Takashi