Documentation overhaul

[Lawrence Velázquez]

> 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.

> 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