MP manpages (was: Migrating the guide to AsciiDoc)

[Jan Stary]

On Apr 23 16:26:13, raimue at macports.org wrote:
> On 2018-04-23 14:27, Jan Stary wrote:
> >> 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?
> 
> No, I really do not care about these workarounds. Why should I care
> about workarounds in intermediate formats?
> I do not see anything of this in my terminal.

The asciidoc is what you don't see on you terminal.
The resulting man(7) page is what you see, rendered
by either groff (typically) or mandoc.

> Again, this is added to every man page produced by DocBook and not
> specific to the man pages generated for MacPorts. We are not maintaining
> the XSLT stylesheets that produce this output. If you think these
> workarounds are not necessary, the DocBook project is the right address
> for complaints.

I have no desire to "fix docbook", overengineered beyond absurdity.
My point is why do you want to use something like docbook
to produce the manpages?

> >>>> 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)?
> 
> mdoc(7).
> 
> You seem to count both the input and the output files. Also, some of the
> old files, such as portfile.7 and porthier.7, still have not been
> converted. The real progress was even slower than that.
> 
> > How did you write the mdoc(7) manpages then?
> 
> Those had been written before I even joined the project. Apparently
> someone wrote the original man pages, then left the project and no
> longer contributed. Nobody updated the man pages because they were
> written in a format nobody wanted to learn.

Are you sure _that_ was the reason? It's pretty damn trivial to
update an _existing_ mdoc(7) manpage (such as: add an option, etc).

> Therefore the plan came up
> to replace that format with something else that is easier to pick up for
> new contributors.

Honest question: how much did people start contributing documentation,
after the switch from mdoc(7) to asciidoc?

> Although there was already some work to use DocBook XML for the man
> pages, I proposed to use AsciiDoc in the NewHelpSystem. This format was
> already used by other projects to write man pages. Just to name popular
> examples, git and mercurial still use it. I do not think that the HTML
> version of their man pages is missing semantics. I do not think that our
> HTML version [1] is missing semantics, either.

What?

(> [1] https://man.macports.org/port-diagnose.1.html
has almost no content; let's take port.1.html as an example:)

<pre class="content"><strong>port</strong>
[<strong>-bcdfknNopqRstuvy</strong>] [<strong>-D</strong>
<em>portdir</em>] [<strong>-F</strong> <em>cmdfile</em>]
[<em>action</em>] [<em>actionflags</em>]
     [[<em>portname</em> | <em>pseudo-portname</em>
     | <em>port-expressions</em> | <em>port-url</em>]]
          [[<em>@version</em>] [+/-variant …] …
	  [option=value …]]</pre>

There is _no_ semantics in here. Or what denotes an option here?
Or its (optional) argument? Nothing. This is purely presentational:
"put this in bold, type a bracket here".

> Back then, I did not even know there was a difference between man(7) and
> mdoc(7). And even today, neither looks like a syntax new contributors
> without previous knowledge want to write in my opinion.

I do. I am willing to write it.
Please just say you simply don't want it.

> I see you are strongly attached to mdoc(7), but take a look around:
> except some *BSD projects nobody uses mdoc(7) to write man pages.

All of OpenBSD, FreeBSD and NetBSD, in fact. And MacOS of course.
(I love how you try to make it sound as something negligible.
Remember how everyone except some BSD projects was using ssh.com
before OpenSSH was started in some BSD project?)

$ vi `man -w ls`

> Most
> projects use lightweight markup languages such as AsciiDoc, Markdown, or
> restructuredText, or even pod2man for this task.

No, most project don't. and even if they did,
is that a reason to do it too?

> $ find /opt/local/share/man | wc -l
>    15591
> $ find /opt/local/share/man -exec zgrep -l '^.Dt' {} + | wc -l
>      588

Well, that differs by user of course:

$ find /opt/local/share/man -type f | wc -l
    3493
$ find /opt/local/share/man -type f | xargs -n1 zgrep ^.TH | wc -l
    2574
$ find /opt/local/share/man -type f | xargs -n1 zgrep ^.Dt | wc -l
     537

Also, this just greps for man(7) manpages;
that does not mean they are produced by asciidoc (or whatever).
In fact, we know that asciidoc-produced manpages contain this:

$ find /opt/local/share/man -type f \
| xargs -n1 zgrep -F "http://bugs.debian.org/507673" | wc -l
      57

Jan