Explicitly listing involved standards would be nice if we had the data close to hand. We don't, and collecting it all is a rather enormous task. Many of these APIs are also covered by a large number of standards. For example, strcpy() is covered by every C standard, every C++ standard, every POSIX standard, all the SVID standards, and all the de facto BSD standards. In some cases its much uglier. For example, strftime() and strptime() have complex details where format specifiers were added by different standards at different points in time.
If someone wants to do the huge research and editing task, I'm supportive. My guess is that this is simply too much work and too little gain, and that referencing standards(5) was seen as an escape hatch from having to do this work by the various parties at Sun who were responsible for this entry. On Mon, Jul 14, 2014 at 12:30 PM, Josef 'Jeff' Sipek <[email protected]> wrote: > On Mon, Jul 14, 2014 at 12:05:28PM -0700, Garrett D'Amore via > illumos-developer wrote: > ... > > g) mandoc can format man(5) pages as well. So importing from foreign > > sources should be straight-forward. > ... > > Ideally I'd like to convert all of the pages we have in illumos to mdoc > > semantic markup. > ... > > It's an outstanding question as to whether we do these incrementally or > all > > at once. I'm willing to go either way. Obviously incremental > improvement > > is *easier*, but with less immediate benefit. > > Given the snippets above, I think that integrating the tools should be the > first step. The second step would be to convert a number of man pages to > demonstrate the prefered syntax for the various aspects of man pages. > Finally, let all the thrillseekers out there convert the rest of the > manpages over the coming years. > > > The other item of note is our ATTRIBUTES section and table. I'd really > > like to nuke these tables (they are some of the worst for consistency in > > markup and even content). I'd propose that in order to avoid losing the > > data there, we create the following new sections: ARCHITECTURE, CSI, > > INTERFACE STABILITY, MT-LEVEL, and STANDARD. (Actually I might rename > > these as: ARCHITECTURE, CODE SET INDEPENDENCE, INTERFACE STABILITY, > > MULTITHREADED SAFETY, and STANDARDS. (Possibly STANDARDS could be > omitted > > entirely since almost every reference to it in existing pages simply > points > > users to standards(5) instead of providing any useful content directly in > > the page.) > > While the attributes table is neat when it works, it doesn't work all that > well when the manpage gets complex enough (e.g., string(3c)). So, please > nuke it. As far as the standards are concerned, why not explicitly list > the > involved standards? E.g., POSIX 2008. > > Jeff. > > -- > All science is either physics or stamp collecting. > - Ernest Rutherford > ------------------------------------------- illumos-discuss Archives: https://www.listbox.com/member/archive/182180/=now RSS Feed: https://www.listbox.com/member/archive/rss/182180/21175430-2e6923be Modify Your Subscription: https://www.listbox.com/member/?member_id=21175430&id_secret=21175430-6a77cda4 Powered by Listbox: http://www.listbox.com
