Documentation overhaul

[Bruce Miller]

On 10/12/2016 11:03 AM, Lawrence Velázquez wrote:
>> On Oct 12, 2016, at 10:30 AM, Bruce Miller <bruce.miller at nist.gov> wrote:
>>
>> On 10/09/2016 09:53 AM, Marcel Bischoff wrote:
>>> Hi all.
>>>
>>> As Ryan has identified that the online documentation needs work,
>>
>> I would applaud this, while acknowledging that it will be a lot
>> of work.
>>
>> To pick up on a comment from another thread:
>> Although I tend to program Perl like lisp, I might
>> program Tcl like fortran, since it seems to
>> me very much like fortran, or even cobol.
>
> That's interesting. I've found Tcl to have interesting functional
> properties, so I tend to write it pretty Lisp-y, for better or worse.
>
> Not sure what this says about Tcl. Nothing good, I expect.

Probably my lack of familiarity does injustice to Tcl;
I have certainly competent colleagues that use it.

But still, many aren't familiar with it, so while
the MacPorts documentation shouldn't take on teaching
Tcl, it ought to provide plenty of examples of Tcl
"Done Right".

>> There's a *lot* of stuff in MacPorts, but much
>> isn't documented well, or at all. If I find example
>> portfiles doing similar things, they use magic that
>> I can't find explained anywhere.  An Index of commands
>> would be very useful.  And also PortGroups are very
>> powerful I think, I had particular needs from the
>> Perl & TeX groups. But: even reading the code, it
>> wasn't completely clear what functionality they
>> provided and what they didn't, and how best to use them.
>
> I agree that our portgroup documentation is especially weak.
>
> vq
>