MP manpages (was: Migrating the guide to AsciiDoc)

[Ryan Schmidt]

On Apr 23, 2018, at 14:46, Jan Stary wrote:

Man, you sure love to argue about stuff.


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

Asciidoc is what we see in an editor when we edit the manual. The output of groff is what we see in the Terminal. All the intermediate stuff isn't particularly interesting to me as long as the input is easy enough to write and the output is legible.


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

As Rainer already explained:

> On Apr 23, 2018, at 06:17, Rainer Müller wrote:
> 
>> That is correct, DocBook XML is used because AsciiDoc has no native
>> backend to produce man pages.
>> 
>> However, AsciiDoctor has a native backend for man pages [1], which does
>> not require the additional step through DocBook XML. If you, or anyone
>> else, wants to look into switching the man page generation in base from
>> AsciiDoc to AsciiDoctor, that would be appreciated.


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

Ok, then what was the reason, since you don't believe us when we tell you what we think it was?


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

I don't recall seeing a lot of substantial changes to the asciidoc after the conversion. But, the conversion included a complete modern rewrite of the manpages, such that additional contributions weren't immediately necessary. I think if we had not allowed the manpages to be converted to asciidoc, the person who did the rewrite would not have wanted to do so.


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

Does that matter?


>> 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 think that, having spent a very long time on rewriting the manpages in asciidoc--a process which is not yet 100% complete--we're now unclear on why we would want to convert to yet another different format now.