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

[ken mays]

--- On Fri, 8/6/10, Joerg Schilling <Joerg.Schilling at fokus.fraunhofer.de> wrote:

> From: Joerg Schilling <Joerg.Schilling at fokus.fraunhofer.de>
> Subject: Re: [illumos-Developer] Illumos ARC 2010/001 BSD man page support for Illumos
> To: roland.mainz at nrubsig.org, garrett at nexenta.com
> Cc: developer at lists.illumos.org
> Date: Friday, August 6, 2010, 4:38 AM
> 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

Hi Jörg,

I thought about the way FreeBSD is curently doing their documentation
as well as the document team starting with HTML as that way we can build
a web repository just for the man pages. Then, run existing scripts to create the man pages from there to other formats (like PDF).

Think: HTML <-> man pages

This will help create a faster adoption rate and keep things multi-platform in scope - as far as documentation editing is concern.

Just a thought.

~ Ken