Migrating the guide to AsciiDoc

[Rainer Müller]

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.

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.

>>>> 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. Therefore the plan came up
to replace that format with something else that is easier to pick up for
new contributors.

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.

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 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. Most
projects use lightweight markup languages such as AsciiDoc, Markdown, or
restructuredText, or even pod2man for this task.

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

Rainer

[1] https://man.macports.org/port-diagnose.1.html