Migrating the guide to AsciiDoc

[Jan Stary]

On Apr 23 13:17:10, raimue at macports.org wrote:
> 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,

(apparently)

> I read man pages in rendered form with man(1).

I thought we are talking about _producing_ the manpages.
That _is_ the raw input (in whichever markup language).

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

You don't care that a 2008 workaround to a Debian bug
is included in every manpage of a MacPorts package system?
Or a 2009 workaround to a Solaris bug in GNU roff?
Don't you find it a prime example of clutter
that simply does not belong there?

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

$ cd /opt/mports/macports-base/doc
$ wc -l *.txt *.1 *.5 *.7

That would make it about nine lines per day.

BTW, was it mdoc(7) or man(7)?

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

How did you write the mdoc(7) manpages then?

> This syntax is far from being intuitive.

	Nm	name
	Op Fl 	optional flag
	Ar	argument
	Sh	section header

Seriously, it takes about 15 minutes to get going.
http://mandoc.bsd.lv/man/mdoc.7.html


The main point is that mdoc(7) allows for constructs like

	.Op Fl f Ar arg

meaning

	there is an optional 'f' flag
	which takes an 'arg' argument

as opposed to

	switch to italics, type a bracket, a dash, "f",
	then switch to boldface and type "arg"

in the physical roff markup of man(7).
Similarly for other constructs like cross-references,
filenames, author emails, env variables, etc.

> Yes, it seems to be possible to encode more semantics than with
> AsciiDoc. But do we really need that in a man page?

Yes; you can _search_ by those semantics then, such as by
a filename mentioned in FILES; or by AUTHORS; you get html manpages
for free and can do things like http://man.openbsd.org/ls#d
i.e. link to individual options and sections.

> But do we really need that in a man page?

Do we need 2008 workarounds to Debian bugs in a manpage?

> At least for terminal output, almost everything of that
> is lost with rendering anyway.

No it's not. And terminal output is not the only:
you get html, pdf, ps, even mandoc from it, without docbook;
mdoc(7) is a language that has been in UNIX for decades
and is very well supported everywhere.

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

I'm not touching DocBook, obviously.
My main motivation here is to get rid of it entirely.
And asciidoc has no way of even expressing the semantics.

Again, I am willing to do the work.
Please let me know if there is no interest.

	Jan