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