Documentation overhaul

[Bruce Miller]

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.
I don't particularly like Tcl, but so what?

My point is to tease, not flame, but really:
Tcl isn't the most widely know language these
days, and newbies to MacPorts and/or Tcl need
some help.

In writing the Portfile for LaTeXML, I needed to
do a couple of not-quite-standard things, and it
wasn't at all clear where to start.  I got a lot
of help from Mojca and Rainer, but that clearly
isn't fair to them, and slows the whole process down.
I think in the end the Portfile seems to work, and
is relatively clean & compact, to my eye
(but still needs to be committed; Hint :> )

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.

Respectfully submitted;
bruce