Hi Kyle, Brad Smith wrote on Sun, Sep 15, 2013 at 06:23:25PM -0400: > On 15/09/13 6:22 PM, Kyle Isom wrote:
>> I think I'll scrub the man page, and rewrite it in mdoc, and submit a >> patch for that upstream. Thanks, Ingo, for the patch for this and >> bringing this up. > I would speak with upstream first to see if they will accept such a > change otherwise it is a waste of time; even for the ports tree. I fully agree with Brad. While i do consider mdoc(7) the superior format compared to man(7), last time i checked, some very old-fashioned operating systems, for example recent Solaris, still didn't include any mdoc(7) formatter. So, anybody using mdoc(7) as a documentation format for portable software must have a plan how to support Solaris & friends. One good option is to run "mandoc -Tman" on the manuals while building the distribution tarballs and then use the mdoc(7) versions in the build if mandoc(1) or nroff -mdoc is available on the target system, and use the autogenerated fallback man(7) versions as included in the tarball if neither is available. For example, that's how portable sudo(8) does it. However, that doesn't only require the upstream maintainer to be willing to learn and use mdoc(7), but it also requires them to use mandoc(1) -Tman in their distribution tarball build system. Make sure to admit that additional complication up front, or you risk getting yelled at later, when things suddenly stop working on Slowlaris... Yours, Ingo
