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

[Roland Mainz]

On Thu, Aug 5, 2010 at 11:07 PM, Garrett D'Amore <garrett at nexenta.com> wrote:
>  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.

Erm... technically I think we should choose neither format for our
_own_ docmentation. Sun originally started with SolBook/SGML and is
now moving todwards DocBook/XML and IMO new docmentation should be (if
not provided by an upstream) in DocBook/XML because it can be
converted into all known other formats used on Unix/Linux etc. (like
man, ASCII plain text, Unicode plain text, HTML, PDF etc.) and allows
some advanched stuff (like MathML) to be used quite easily. And it
helps a lot with things like localisation of manpages, too.

----

Bye,
Roland

-- 
  __ .  . __
 (o.\ \/ /.o) roland.mainz at nrubsig.org
  \__\/\/__/  MPEG specialist, C&&JAVA&&Sun&&Unix programmer
  /O /==\ O\  TEL +49 641 3992797
 (;O/ \/ \O;)