Hi Jan, Jan Stary wrote on Sat, Jun 29, 2013 at 02:28:55PM +0200:
> Certain ports require groff because that's what > their manpages are written for. Manuals specifically written for groff (as opposed to for roff in general) probably exist, but i don't think that's the majority of manuals requiring groff. Rather, i'd guess that most manuals requiring groff in OpenBSD ports use low-level roff formatting (in addition to man(7) macros) that is supported by most roff implementations, not just by groff. Admittedly, i didn't really check the above. But note that manuals written specifically for groff would hardly be usable e.g. on Solaris clones which typically do not inlude groff but older roff implementations. > If I understand > it correctly, the original manpages get preformated > with groff, installed into the .../cat/ directotries, > and that's what the user sees eventually. Yes, that's what USE_GROFF does, see bsd.port.mk(5). > I haven't found the time yet to look into the internals > of the mdoc(7) vs man(7) markup, but would it make > sense to try to slightly rewrite the original > manpages to get rid of groff? In the ports tree at large: No. That would be a gigantic make-work project, and lots of the work would have to be redone for each update of each affected port. That's completely unrealistic. Also note that the mdoc(7) and man(7) languages are completely distinct, they do not have a single common macro. Well, roff(7) requests can be used in both, but that's bad style in the first place. So, rewriting man(7) to mdoc(7) usually requires to change every single macro, and it usually requires adding several macros to the source code. It's more like rewriting the manual, not just like sprinkling a few changes. In one single port, provided that you cooperate closely with upstream, they like the idea, and you know what you are doing? Yes. However, if upstream wants to provide manuals for Solaris clones, they will need to do automatic mdoc(7) to man(7) conversions using mandoc -mdoc -Tman in the tarball build system, like portable sudo(1) does. That works quite well now, but requires mandoc in the tarball build system, so some upstream projects may not like the idea. > Is that generally > possible? Is an mdoc(7) manpage, when written > with compatibility in mind, acceptable for upstream > that originaly wrote the manpage for groff? That depends on the taste of the upstream developers. I think moving from man(7) to mdoc(7) and using -Tman makes manuals better, but some upstream projects will certainly disagree - or simply not care at all. Yours, Ingo
