Migrating the guide to AsciiDoc

[Rainer Müller]

On 2018-04-23 10:12, Jan Stary 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

I do not care about the raw input, I read man pages in rendered form
with man(1).

These quirks are added by DocBook XSLT and are apparently required to
make the output compatible. If you disagree with that, talk to DocBook
why they added them.

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

We moved away from mdoc(7) with the NewHelpSystem [1]. It took us about
five years to write all man pages, including conversion of the old man
pages.

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

I really cannot see the benefits of this. To me, writing this by hand
would be even more terrible than writing XML. I have no idea what any of
these two-character commands mean. This syntax is far from being intuitive.

Yes, it seems to be possible to encode more semantics than with
AsciiDoc. But do we really need that in a man page? At least for
terminal output, almost everything of that is lost with rendering anyway.

If you really care that much about the non-rendered file on disk,
I would recommend to rewrite the DocBook XSLT to use the mdoc(7) format
or contribute a native backend for it to AsciiDoctor.

Rainer

[1] https://trac.macports.org/wiki/NewHelpSystem