Documentation overhaul

[Lawrence Velázquez]

> On Oct 9, 2016, at 7:23 PM, Ryan Schmidt <ryandesign at macports.org> wrote:
> 
> I've been with MacPorts for around 10 years and have thought of
> rewriting the documentation for several years so I feel I might be
> able to do it.

+1

> I'm just not doing it right this second because I'm busy trying to
> move us to new hosting. And also because we don't yet know how how we
> will work on GitHub, so we can't fully document that yet.

A lot of our process will be changing very shortly. It's probably a good
idea to hold off for a bit.

> I like markdown but it is missing a lot of things. There is an opinion
> piece I found online about who you should never try to write
> documentation using markdown for this reason.

One problem with Markdown vis-à-vis documentation is that it was
specifically designed to be transformed into HTML. That is why it
permits inline HTML and does not try to do everything in syntax; the
intention was that complex content be written in raw HTML.

vq