Groff difference: punctuation following Lk

Groff difference: punctuation following Lk

[Anthony J. Bentley]

Hi,

Consider the following mdoc(7) source:

    .Lk https://www.example.com/ .

In mandoc(1), this gets rendered as:
    https://www.example.com/.

Doing the same with groff-1.22.3's nroff(1) yields:

    .: https://www.example.com/

It (unexpectedly, to me at least) treats the period as the text of the
link, rather than punctuation that trails the macro.

I guess mandoc's behavior is wrong, even though it makes more sense...

-- 
Anthony J. Bentley
--
 To unsubscribe send an email to tech+unsubscribe@mdocml.bsd.lv

Re: Groff difference: punctuation following Lk

[Ingo Schwarze]

Hi Anthony,

Anthony J. Bentley wrote on Sat, Apr 01, 2017 at 03:29:52AM -0600:

> Consider the following mdoc(7) source:
> 
>     .Lk https://www.example.com/ .
> 
> In mandoc(1), this gets rendered as:
>     https://www.example.com/.
> 
> Doing the same with groff-1.22.3's nroff(1) yields:
> 
>     .: https://www.example.com/

That's an obvious bug in groff.

> It (unexpectedly, to me at least) treats the period as the text of the
> link, rather than punctuation that trails the macro.
> 
> I guess mandoc's behavior is wrong, even though it makes more sense...

I guess not.

How do you like the following patch?

The way the .Lk macro is implemented in groff indicates that mandoc's
behaviour is intendet.  Why would you do an explicit check against
punctuation (the \n[doc-arg-type] < 3) unless you want to handle
punctuation specially?  Given the non-obvious calling conventions
of doc-get-arg-type, it is prone to forgetting the necessary setup
of doc-width, which seems to be what happened here...

By the way, this improves the formatting of sendbug(1), whois(1),
SSL_CTX_get_max_cert_list(3), acx(4), oce(4), and isakmpd.conf(5)
with groff.

If you like it, tell me and i'll submit a patch to the groff
bugtracker and prepare a patch for the OpenBSD ports tree.

Yours,
  Ingo


diff --git a/tmac/doc.tmac-u b/tmac/doc.tmac-u
index 8f9f90fb..71c68466 100644
--- a/tmac/doc.tmac-u
+++ b/tmac/doc.tmac-u
@@ -6454,6 +6454,7 @@
 .  ds doc-str-Lk Sy \$@
 .
 .  ie (\n[.$] > 1) \{\
+.    doc-get-width "\$2"
 .    doc-get-arg-type \$2
 .    ie (\n[doc-arg-type] < 3) \{\
 .      Em \)\$2:
--
 To unsubscribe send an email to tech+unsubscribe@mdocml.bsd.lv

Re: Groff difference: punctuation following Lk

[Anthony J. Bentley]

Ingo Schwarze writes:
> > It (unexpectedly, to me at least) treats the period as the text of the
> > link, rather than punctuation that trails the macro.
> > 
> > I guess mandoc's behavior is wrong, even though it makes more sense...
> 
> I guess not.

Glad to hear it!

> How do you like the following patch?

I like it very much.

Groff's output still differs in two ways that I can see. The first is
that it doesn't handle multiple arguments well:

.Lk https://www.example.com/ a b c

becomes "a: https://www.example.com/ b c" in groff (b and c bolded),
instead of "a b c: https://example.com/" in mandoc.

The other is that URLs of a certain size (I think that's the criteria?)
get indented in groff. You can see this in sendbug(1), for example:

     The status of bug reports can be followed by checking the
     bugs@openbsd.org mailing list archive available at
           http://marc.info/?l=openbsd-bugs.

Reducing the URL to 25 characters removes the indent:

     The status of bug reports can be followed by checking the
     bugs@openbsd.org mailing list archive available at
     http://marc.info/?l=openb.

Mandoc doesn't indent in either case.

-- 
Anthony J. Bentley
--
 To unsubscribe send an email to tech+unsubscribe@mdocml.bsd.lv

Re: Groff difference: punctuation following Lk

[Ingo Schwarze]

Hi Anthony,

Anthony J. Bentley wrote on Sun, Apr 09, 2017 at 03:47:23PM -0600:

> I like it very much.

Good, thanks for having a look, submitted to groff.

> Groff's output still differs in two ways that I can see.

Yes, i'm aware of these two differences, but followed the
concept of "one change at a time".

> The first is that it doesn't handle multiple arguments well:
> 
> .Lk https://www.example.com/ a b c
> 
> becomes "a: https://www.example.com/ b c" in groff (b and c bolded),
> instead of "a b c: https://example.com/" in mandoc.

I agree that the mandoc behaviour is useful and the groff behaviour
is useless, confusing, and likely unintentional.  I'll probably
look whether groff can be improved.  I can't believe anybody relies
on the current behaviour.

> The other is that URLs of a certain size (I think that's the criteria?)
> get indented in groff. You can see this in sendbug(1), for example:
> 
>      The status of bug reports can be followed by checking the
>      bugs@openbsd.org mailing list archive available at
>            http://marc.info/?l=openbsd-bugs.
> 
> Reducing the URL to 25 characters removes the indent:
> 
>      The status of bug reports can be followed by checking the
>      bugs@openbsd.org mailing list archive available at
>      http://marc.info/?l=openb.

Yes, doc.tmac-u hardcodes a limit for inserting a virtual .D1 macro
of >= 26\(en for nroff, but 38 for troff.  That is weird, but the
end-result usually looks OK, ...

> Mandoc doesn't indent in either case.

 ... so probably mandoc should follow.

Yours,
  Ingo
--
 To unsubscribe send an email to tech+unsubscribe@mdocml.bsd.lv

Re: Groff difference: punctuation following Lk

[Ingo Schwarze]

Hi Anthony,

Ingo Schwarze wrote on Mon, Apr 10, 2017 at 02:49:24AM +0200:
> Anthony J. Bentley wrote on Sun, Apr 09, 2017 at 03:47:23PM -0600:

>> I like it very much.

> Good, thanks for having a look, submitted to groff.

Today, it was committed to groff.
Carsten Kunze is doing good work over there.

>> Groff's output still differs in two ways that I can see.

> Yes, i'm aware of these two differences, but followed the
> concept of "one change at a time".

So, here is the next proposed change, considerably more intrusive
than the first.

>> The first is that it doesn't handle multiple arguments well:
>> 
>> .Lk https://www.example.com/ a b c
>> 
>> becomes "a: https://www.example.com/ b c" in groff (b and c bolded),
>> instead of "a b c: https://example.com/" in mandoc.

> I agree that the mandoc behaviour is useful and the groff behaviour
> is useless, confusing, and likely unintentional.  I'll probably
> look whether groff can be improved.  I can't believe anybody relies
> on the current behaviour.

The following patch does the following:

 * Use the second and following arguments as the link text.
 * Do not mark up the following colon with \fI.
 * Handle any number of trailing delimiters.

What do you think?
If you like it, i'll propose it for groff.

Yours,
  Ingo


diff --git a/tmac/doc.tmac-u b/tmac/doc.tmac-u
index 71c68466..eab0b95f 100644
--- a/tmac/doc.tmac-u
+++ b/tmac/doc.tmac-u
@@ -6447,37 +6447,53 @@
 .\" NS   link (for conversion to HTML)
 .\" NS
 .\" NS local variables:
+.\" NS   doc-delim-Lk
 .\" NS   doc-reg-Lk
-.\" NS   doc-str-Lk
+.\" NS   doc-target-Lk
+.\" NS   doc-text-Lk
 .
 .de Lk
-.  ds doc-str-Lk Sy \$@
-.
-.  ie (\n[.$] > 1) \{\
-.    doc-get-width "\$2"
-.    doc-get-arg-type \$2
-.    ie (\n[doc-arg-type] < 3) \{\
-.      Em \)\$2:
-.      ds doc-str-Lk Sy "\$1"
-.      doc-get-width "\$1"
-.      shift 2
-.      if \n[.$] \
-.        as doc-str-Lk " \$@
+.  \" The first argument is the target URI.
+.  ds doc-target-Lk \$1
+.  shift
+.
+.  \" Split the remaining arguments into link text and delimiters.
+.  ds doc-text-Lk
+.  ds doc-delim-Lk
+.  while \n[.$] \{\
+.    doc-get-width "\$1"
+.    doc-get-arg-type \$1
+.    ie (\n[doc-arg-type] > 2) \
+.      as doc-delim-Lk \$1
+.    el \{\
+.      if !'\*[doc-delim-Lk]'' \{\
+.        \" More text follows delimiter(s); go back to text mode.
+.        as doc-text-Lk \*[doc-delim-Lk]
+.        ds doc-delim-Lk
+.      \}
+.      ie '\*[doc-text-Lk]'' \
+.        ds doc-text-Lk \$1
+.      el \
+.        as doc-text-Lk " \$1
 .    \}
-.    el \
-.      doc-get-width "\$1"
+.    shift
 .  \}
-.  el \
-.    doc-get-width "\$1"
 .
+.  \" Print the link text, if any.
+.  if !'\*[doc-text-Lk]'' \
+.      Em \*[doc-text-Lk] Ns :
+.
+.  \" Print link target.
 .  ie n \
 .    nr doc-reg-Lk 26
 .  el \
 .    nr doc-reg-Lk 38
+.  doc-get-width "\*[doc-target-Lk]"
 .  ie (\n[doc-width] >= \n[doc-reg-Lk]) \
-.    D1 \*[doc-str-Lk]
-.  el \
-.    \*[doc-str-Lk]
+.    D1 Sy \*[doc-target-Lk] Ns \*[doc-delim-Lk]\&
+.  el .ie \n[doc-width] \
+.    Sy \*[doc-target-Lk] Ns \*[doc-delim-Lk]\&
+.  el \*[doc-delim-Lk]\&
 ..
 .
 .


P.S.
This is still open, but a separate issue:

> Yes, doc.tmac-u hardcodes a limit for inserting a virtual .D1 macro
> of >= 26\(en for nroff, but 38 for troff.  That is weird, but the
> end-result usually looks OK, ...
 
>> Mandoc doesn't indent in either case.

>  ... so probably mandoc should follow.
--
 To unsubscribe send an email to tech+unsubscribe@mdocml.bsd.lv

Re: Groff difference: punctuation following Lk

[Anthony J. Bentley]

Hi Ingo,

Ingo Schwarze writes:
> The following patch does the following:
> 
>  * Use the second and following arguments as the link text.
>  * Do not mark up the following colon with \fI.
>  * Handle any number of trailing delimiters.
> 
> What do you think?
> If you like it, i'll propose it for groff.

Yes, this behavior seems like a big improvement. Thanks.

-- 
Anthony J. Bentley
--
 To unsubscribe send an email to tech+unsubscribe@mdocml.bsd.lv