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

[Garrett D'Amore]

On 08/06/10 04:44, ken mays wrote:
>
> --- 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
>    

Here's my opinion on the matter:

a) I think we can use a great deal of the upstream man pages.  We should 
use what we can, and the format of those pages should be supported as a 
"source format".

b) I'm not sure that doc is so widely used as Joerg implies.  In any 
case, its trivial to convert from doc to man or other formats just by 
adding markup to the generated output.

c) I believe that troff -man should be considered a "destination" format 
rather than just a "source" format.  (Although I think it *may* be a 
reasonable "source" format too.)

d) I only think we need to "install" the "destination" format.  In this 
case, -man, on the system.  There is no need to install other macro 
packages IMO.

e) The people working on and creating the documentation should decide 
what the "source" format is to be, modulo the fact that there must be 
tools to convert from the "source" to the "destination".

So, with the above thoughts in hand, I think we need to continue to 
support -man.  Its unclear whether SGML is needed in the long run.  I 
think XML *is* needed -- at least in the documenter's and translator's 
tool kits; I am however willing to wait until someone steps forward to 
start a major documentation effort to decide the toolkits of choice.   I 
do not want the few utilities we import from FreeBSD to drive the 
choices that we make for the rest of the system -- that would be like 
the tail wagging the dog.

Hopefully that all makes sense.

     -- Garrett