Migrating the guide to AsciiDoc

[Jan Stary]

> > We are already using the AsciiDoc format for our man pages,
> 
> Manpages are supposed to be written in mdoc(7), the language of
> manpages, just like e.g. /usr/share/man/man1/ls.1 is.
> 
> The current port-* manpages are horrible
> (not talking about content, but markup).
> 
> Look at e.g. port-diagnose.1; read it, line by line.
> Note the 2008 workarounds to debian bugs.
> Note the 2009 workarouns to GNU roff.
> Note the pointless low-level roff(7) tweaks.


https://lists.gnu.org/archive/html/groff/2014-02/msg00109.html


> Then read the port-diagnose.1 below, written in mdoc(7).
> Which one is cleaner, simpler, more readable, more writable, shorter?
> 
> I offer to rewrite them.
> 
> 	Jan
> 
> 
> .Dd April 23, 2018
> .Dt PORT-DIAGNOSE 1
> .Os
> .Sh NAME
> .Nm port diagnose
> .Nd detects common issues with macports
> .Sh SYNOPSIS
> .Nm port
> .Ic diagnose
> .Op Fl -quiet
> .Sh DESCRIPTION
> .Nm port
> .Ic diagnose
> will check a list of common issues that could
> affect the user of MacPorts in one way or another.
> If any issues are found, a warning will be
> shown to the user included with a possible fix.
> .Pp
> With the
> .Fl -quiet
> option, only warnings and errors are displayed.
> .Sh SEE ALSO
> .Xr port 1
> .Sh AUTHORS
> .An Kyle Sammons Aq Mt ksammons at macports.org