Migrating the guide to AsciiDoc

[Jan Stary]

On Apr 23 10:12:06, hans at stare.cz wrote:
> > > 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
> 

Also, having manpages written in asciidoc means we need
the abominable docbook to actually produce the man(7) pages, right?
At least that's what it says at the end of install:

	* Warning: Using pre-generated man pages only.
	* asciidoc, xsltproc (port libxslt) and docbook-xsl are required
	  to generate man pages from source.

Jan


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