Re: CVS commit: src

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

hi,

what's the status of this?
in case it was not clear, i want you revert the changes.

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