Hi Jan, Jan Stary wrote on Mon, Jul 10, 2017 at 05:57:08PM +0200:
> This is how ports.7 is rendered on my 6.1-current: > > For more information about using ports, see The OpenBSD Ports System ( > https://www.openbsd.org/faq/faq15.html#Ports > ). For information about creating new ports, see the OpenBSD > Porter's > Handbook ( > https://www.openbsd.org/faq/ports/ > ). That is much better than what groff renders, which is: For more information about using ports, see The OpenBSD Ports System ( For information about creating new ports, see the OpenBSD https://www.openbsd.org/faq/faq15.html#Ports). Porter's Handbook ( For a detailed description of the build process, see https://www.openbsd.org/faq/ports/). The groff rendering is completely broken, the mandoc rendering is much better... > The code snippet is > > .Pp > For more information about using ports, see > The > .Ox > Ports System > .Pq Lk https://www.openbsd.org/faq/faq15.html#Ports . > For information about creating new ports, see > the > .Ox > Porter's Handbook > .Pq Lk https://www.openbsd.org/faq/ports/ . ... so that mdoc(7) source code is not portable. Maybe mandoc should warn about the portability issue? Possibly, but i would have to understand what exactly is broken in groff, so what the permissible syntax is. Or even better, we should fix groff? That may be hard. > The Pq rendering doesn't seem right: in the first case, > the whole "( http:/// )" would fit nicely on the second line; > in the second case, it would in fact fit nicely on the same line > - the breaks after the '(' and before the ')' seem superfluous. In groff, there is a length threshold. Shorter links are rendered inline, longer ones in what resembles a .D1 display. That is not completely unreasonable, so mandoc should follow. I recently did quite some work on .Lk rendering, and most valid constructs - i.e. those rendering reasonably with groff - now render identically with groff and mandoc. There may still be bugs, of course. At some point, i got tired of how complicated this macro is to implement and stopped digging for more edge cases. Note that the .Pq is *outside* the .Lk, so it is logical that the parentheses appear *outside* the display. If you want the parentheses inside the display, you might feel tempted to write something like For more information about using ports, see The .Ox Ports System .Lk ( https://www.openbsd.org/faq/faq15.html#Ports ) . For information about creating new ports, see the .Ox Porter's Handbook .Lk ( https://www.openbsd.org/faq/ports/ ) . But that also breaks with groff: For more information about using ports, see The OpenBSD Ports System https://www.openbsd.org/faq/faq15.html#Ports: (). For information about creating new ports, see the OpenBSD Porter's Handbook https://www.openbsd.org/faq/ports/: (). Since leading opening delimiters fail with groff, i was lazy and did not implement keeping them in scope in mandoc either, but the mandoc rendering is still better than the groff rendering: For more information about using ports, see The OpenBSD Ports System ( https://www.openbsd.org/faq/faq15.html#Ports). For information about creating new ports, see the OpenBSD Porter's Handbook ( https://www.openbsd.org/faq/ports/). The .Lk macro is relatively young. If i read the source history correctly, it was added as part of the big groff-1.17 mdoc rewrite in 2000. Lk is more fragile than most other mdoc(7) macros. Probably, some work should be done to make the implementation more robust or at least to document the valid syntax more strictly. The current groff implementation looks rather sloppy to me. I already got two improvements committed to groff back in April 2017, but the situation with .Lk is still far from satisfactory. All that said, see below for what i just committed to improve the quality and in particular the portability of the manual, using the standard idiom rather than some hand-rolled approach. Yours, Ingo CVSROOT: /cvs Module name: src Changes by: schwa...@cvs.openbsd.org 2017/07/10 16:48:00 Modified files: share/man/man7 : ports.7 Log message: Fix non-portable .Lk usage that results in complete garbage with groff and looks better, but still not good with mandoc. Issue pointed out by Jan Stary <hans at stare dot cz>. Index: ports.7 =================================================================== RCS file: /cvs/src/share/man/man7/ports.7,v retrieving revision 1.112 diff -u -r1.112 ports.7 --- ports.7 28 Jun 2017 10:24:23 -0000 1.112 +++ ports.7 10 Jul 2017 22:43:40 -0000 @@ -60,15 +60,9 @@ to install the application. .Pp For more information about using ports, see -The -.Ox -Ports System -.Pq Lk https://www.openbsd.org/faq/faq15.html#Ports . +.Lk https://www.openbsd.org/faq/faq15.html#Ports "The OpenBSD Ports System" . For information about creating new ports, see -the -.Ox -Porter's Handbook -.Pq Lk https://www.openbsd.org/faq/ports/ . +.Lk https://www.openbsd.org/faq/ports/ "The OpenBSD Porter's Handbook" . .Pp For a detailed description of the build process, see .Xr bsd.port.mk 5 .
