Hi Ingo, > > 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/).
I agree that the mandoc rendering is way 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. Would you please kindly bring it up on the groff list, if you think groff should address this too? (I can do it, but it would get more momentum comming from you.) > > 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. Yes. > 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. Ah, so is this being "outside of the display" (meaning "outside of the kind-of-D1-line" here) that introduces the line breaks? > 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/: (). It would also be semantically wrong, right? The parentheses surely are not part of the link. > 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/). Ugh. > 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. I was probably wrong in my original impression that it is a Pq problem - it's the Lk that' the issue here, right? > 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. This looks better to me. Thanks, Jan > 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 . >
