hi, what's the status of this? in case it was not clear, i want you revert the changes.
YAMAMOTO Takashi > 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
