MP manpages (was: Migrating the guide to AsciiDoc)

[Andrew Moore]

On Apr 23, 2018, at 3:46 PM, Jan Stary <hans at stare.cz> wrote:
> 
> 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?

Jan,
For what it’s worth, I like  mdoc(7)  and use it for my utilities - I even wrote one 
for the Apple's afconvert(1) utility (see attachment) - but for anything intended for
distribution,  the documentation gets rewritten in at least one other format, e.g., texinfo
and/or markdown.

There is no universal documentation format, e.g., ISO 8000 companies have their
own problem.

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

Actually, if you download FreeBSD project documentation, e.g., https://github.com/freebsd/freebsd-doc,
you’ll find that it’s written in DocBook.

Again, for what it’s worth, while I’m not willing to maintain MacPorts mdoc(7) pages, I am
willing to explore improving conversion from asciidoc to mdoc, because for project-wide
documentation asciidoc seems like a reasonable choice.
-AM


-------------- next part --------------
A non-text attachment was scrubbed...
Name: afconvert.1
Type: application/octet-stream
Size: 7836 bytes
Desc: not available
URL: <http://lists.macports.org/pipermail/macports-dev/attachments/20180423/f730b1a8/attachment-0001.obj>
-------------- next part --------------