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

[Joerg Schilling]

Roland Mainz <roland.mainz at nrubsig.org> wrote:

> > 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.

As mentioned before, the documention provided by Sun/Oracle is in a format that 
does not allow editing and it is even ugly and missformatted.

The commonly accepted format for UNIX documentation is the man macro format.
It can be converted in to other formats and it can be edited by anyone.

In any case, you missed the point, as we need to be able to display the 
upstream man page format and in case is a *BSD upstream, this is usually the 
"doc" macro format.

Jörg

-- 
 EMail:joerg at schily.isdn.cs.tu-berlin.de (home) Jörg Schilling D-13353 Berlin
       js at cs.tu-berlin.de                (uni)  
       joerg.schilling at fokus.fraunhofer.de (work) Blog: http://schily.blogspot.com/
 URL:  http://cdrecord.berlios.de/private/ ftp://ftp.berlios.de/pub/schily