> > 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 ksamm...@macports.org
