Re: CVS commit: src

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

hi,

> yamt%mwd.biglobe.ne.jp@localhost (YAMAMOTO Takashi) wrote:
>> > Log Message:
>> > Unify kmem_alloc/zalloc/free under kmem(9).  Links preserved.
>> 
>> i intentionally made them separate pages because
>> it's easier to read for me.  (ie. no need to search in a man page.)
> 
> I think we should have a manual per-subsystem:
> 
> - 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. :)

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

> 
> - On the other hand, uvm(9) is an example where manual page is too heavy.
>   Each part is complicated enough and could be taken as a separate system.

i agree uvm(9) is too big.

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

for example?

> 
> Therefore, attempting to get some consistent and readable structure.

i agree being consistent is a good thing.

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.

YAMAMOTO Takashi

> 
>> YAMAMOTO Takashi
> 
> -- 
> Mindaugas