Documentation overhaul

[Rainer Müller]

Hello Marcel,

On 2016-10-09 15:53, Marcel Bischoff wrote:
> As Ryan has identified that the online documentation needs work, I'm
> hereby volunteering to give it a go. Since there appear to be quite
> specific views on how everthing here needs to be, I'm asking in advance:
> 
> - Is that in everyone's interest?

Of course! :-)

> - Is there already someone working on it?

We have a new help system on trunk. Each command has a separate man page
that can be reached with 'port help install' and similar. Eventually
these should also end up on on the web, for example at man.macports.org.

https://trac.macports.org/wiki/NewHelpSystem

The source of the new man pages can be found in base/doc/*.txt in
AsciiDoc format:

https://trac.macports.org/browser/trunk/base/doc

> - Where should the final documentation be located: separate website,
>  GitHub wiki, GitHub pages, readthedocs.org, something else?

The best would be to overhaul/replace https:///guide.macports.org with
something new and better structure.

The existing guide can be found here:
https://trac.macports.org/browser/trunk/doc-new

Hosting the site should be the least concern, we have resources for that
now.

> - In what format should the documentation be written: HTML, Markdown,
>  TeX, whatever? I prefer Markdown.

I think one of the main reasons why nobody likes updating the guide is
the DocBook XML syntax.

Back in 2009 (sic!), I started the new help system in AsciiDoc, inspired
by the git help system. AsciiDoc is more complex than Markdown, but
supports syntax elements such as includes and macros, that are very
helpful in reusing the some content in multiple pages and keeping the
layout consistent. Also, macros can be defined per output device,
expanding to specific syntax in roff/html/pdf/etc.

I am fine with using Markdown, as it is the dominant markup syntax
today. However, it is also very limited, but that might just be enough
for the guide.

Rainer