Re: [TCLCORE] gsoc ideas

[Brian G. <bri...@ea...>]

On Mar 8, 2012, at 8:59 AM, Lars Hellström wrote:

> Larry McVoy skrev 2012-03-08 16.45:
>>> 1. Tcl has a very good documentation, both on the C and the script side.
>>>    AFAIK the sources are still in nroff format. And there is also a very
>>>    good description on top of each C-function and Tcl-proc.
>> 
>> I don't understand the desire to move away from nroff.  It's not broken,
>> why fix it?
> 
> One reason could be that the number of developers who can maintain 
> documentation written in nroff is dwindling. It doesn't help that something 
> isn't broken if hardly anyone understands how to modify it anymore; what 
> used to be editable source is then effectively becoming an unmodifiable 
> binary instead.
> 
> My experience, coming late to the traditional Unix tools, is:
> 1. I find it very difficult to read nroff source (despite having mastered 
> several obscure file formats in my life).
> 2. I have been unable to find any significant documentation of the format.
> 3. The only practical way I know of generating working nroff is to use 
> doctools, converting from .man.
> Hence, if someone asked me to modify an nroff manpage in some way, I most 
> likely wouldn't be able to help. And I suspect I am far from the only one.
> 
> Lars Hellström

What he said summarized in a one word answer to the question "what's broken?":  Authoring.

-Brian