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
