[illumos-Developer] Illumos ARC 2010/001 BSD man page support for Illumos

[Garrett D'Amore]

  On 8/5/2010 2:01 PM, Joerg Schilling wrote:
> This is our first architecture review case...

Heh.  I think I'm not sure that we're going to have a formal ARC as 
such.  At least not initially.  Rather I'd like to have contentious 
issues reviewed and discussed, but lets not get too caught up in the 
process.  And now onward.
>
> Illumos is going to adopt code from *BSD and we of course don't just need
> code but also documentation.
>
> The FreeBSD guys unfortunately did throw away the UNIX man macros in 1992
> while they have been sued by AT&T and replaced the man macros by "doc" macros.
>
> As there are currently only groff macros to support the "doc" macro system,
> many people believe that GNU troff under a restrictive license is needed to
> support BSD man pages.
>
> There are however doc macros that work with the standard troff implementaion.
> I fetched the most recent standard troff macro implementation for
>
> 	troff -mandoc
>
> and added some bug-fixes such as Y2k fixes and others that are needed today.
>
>
> I I hereby propose to add the following files:
>
> /usr/lib/tmac/doc
> /usr/lib/tmac/mandoc
>
> and to change the man(1) command to call "nroff -mandoc" instead of
> "nroff -man".

I must say I'm of a mixed mind.  While I don't mind seeing fixes to 
bugs, I worry that if we create documentation in a format that is not 
acceptable to the upstream it will create undue barriers to upstream 
integration.

In fact, ON currently lacks *any* manual pages, and this is probably the 
case for a level 0 type question (in ARC parlance) -- that is what are 
we going to do about manual pages?  I have some thoughts here, but the 
challenge of balancing the need for updated docs against unnecessary 
divergence from upstream needs to be balanced.

Can we defer this question for just a wee bit longer?  I really want to 
work on closing the functional gaps before we start trying to solve this 
particular problem....   (And I suspect a "documentation" project will 
need to be started.)

     - Garrett

>
> Jörg
>