nroff (was Re: gsoc ideas) - tcl-core

The old Google Groups will be going away soon, but your browser is incompatible with the new version.
Message from discussion nroff (was Re: gsoc ideas)
Received-SPF: pass (google.com: domain of tcl-core-boun...@lists.sourceforge.net designates 216.34.181.88 as permitted sender) client-ip=216.34.181.88;
Received-SPF: pass (sog-mx-4.v43.ch3.sourceforge.com: domain of
	activestate.com designates 204.244.102.3 as permitted sender)
	client-ip=204.244.102.3; envelope-from=je...@activestate.com;
	helo=mx.activestate.com;
Message-ID: <4F5904EC.3020...@activestate.com>
Date: Thu, 08 Mar 2012 11:13:48 -0800
From: Jeff Hobbs <je...@activestate.com>
User-Agent: Mozilla/5.0 (Windows NT 6.0; WOW64;
	rv:10.0.2) Gecko/20120216 Thunderbird/10.0.2
MIME-Version: 1.0
To: tcl-c...@lists.sourceforge.net
References: <4F58E576.4060...@residenset.net>
	<201203080945.21762.r.zaums...@freenet.de>
	<20120308154559.GE20...@bitmover.com>
	<E1S5hhG-0007FI...@eurydice.office.flightlab.com>
In-Reply-To: <E1S5hhG-0007FI...@eurydice.office.flightlab.com>
Subject: Re: [TCLCORE] nroff (was Re:  gsoc ideas)
Precedence: list
Content-Type: text/plain; charset="us-ascii"
Content-Transfer-Encoding: 7bit
Errors-To: tcl-core-boun...@lists.sourceforge.net

On 08/03/2012 10:04 AM, Joe English wrote:
> Lars_Hellstrom wrote:
>> Larry McVoy wrote:
>>> 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.
>
> That's historically been a real problem.  (For many years,
> most Unices came equipped with nroff(1), since man(1) uses it,
> but unless you paid big $$$ for the "Documenter's Workbench"
> you didn't get any documentation at all on the file format!)
>
> Fortunately most of the original documentation has been liberated:
> see<URL: http://troff.org/papers.html>.  Joe Ossanna's
> reference manual (CSTR#54) is quite good.
>
> The Heirloom Project has revised and updated documentation
> for the DWB toolchain as well:
>
>      <URL: http://heirloom.sourceforge.net/doctools.html>
>
> Lastly, the groff manual (which, somewhat ironically,
> is in GNU Info format) is also decent (though IMO it
> suffers from the typical GNU problem where it reads like
> it wants to be a novel instead of a reference manual..)
>
> Troff, much like vi, is actually rather straightforward
> and can be pleasant to use once you get the basic principles.
> (And, much like vi, if the basic principles *haven't* been
> explained, it's a nightmare.  Come to think of it, the
> same applies to Tcl...)

I for one never found nroff source docs hard to read or write, but then 
again the autoconf didn't scare me much either (it was more of a 
puzzling challenge ;) ).  However, the one real limitation I found is 
that it can't handle screenshots.  This makes Tk docs much less 
friendly.  In the same manner that adding examples to the Tcl docs was a 
real boon for the user, we've never been able to pictorialize for Tk.

I'd be up for switching to a doc format that could manage that well. 
Maybe the rest format would satisfy?

Jeff

------------------------------------------------------------------------------
Virtualization & Cloud Management Using Capacity Planning
Cloud computing makes use of virtualization - but cloud computing 
also focuses on allowing computing to be delivered as a service.
http://www.accelacomm.com/jaw/sfnl/114/51521223/
_______________________________________________
Tcl-Core mailing list
Tcl-C...@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/tcl-core
Create a group - Google Groups - Google Home - Terms of Service - Privacy Policy
Account Options
