groff `Lk' badness

groff `Lk' badness

[Kristaps Dzonsons]

Hi,

By way of a note by Aldis Berzoja, it seems that `Lk' has some 
mysterious behaviour we should clarify.

Input:

.Lk foo bar baz xyzzy

groff Output:

      bar: foo baz xyzzy

Where "bar:" is underlined and the rest is in bold.

So it looks like "bar" is the link, as underlined things make us think 
of links.  That would make "foo" be the link name (bold text) and damned 
if I know why "baz" and "xyzzy" are also in bold.

This is confusing, because in fact `Lk' is documented as being link 
first, link-name second (cutting off at two arguments and continuing the 
formatting is probably a groff bug).

mandoc formats its output as "foo: bar baz xyzzy", but I think this is 
misleading because the ":" is a reserved token in the URI spec.

Can we come to an agreement as to how this should be formatted?  I don't 
want to be bug-compatible with groff in this case.  I like the "link: 
link-name" output, but due to the colon being a URI reserved token, 
"link-name: link" makes more sense, with link-name being bold and link 
being underlined.

Thoughts?

Kristaps
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv

Re: groff `Lk' badness

[Ingo Schwarze]

Hi Kristaps,

> By way of a note by Aldis Berzoja, it seems that `Lk' has some
> mysterious behaviour we should clarify.

Thanks to Aldis for reporting!

> Input:
> 
> .Lk foo bar baz xyzzy
> 
> groff Output:
> 
>      bar: foo baz xyzzy
> 
> Where "bar:" is underlined and the rest is in bold.
> 
> So it looks like "bar" is the link, as underlined things make us
> think of links.

I think here is the source of the confusion.

> That would make "foo" be the link name (bold text)
> and damned if I know why "baz" and "xyzzy" are also in bold.
> This is confusing, because in fact `Lk' is documented as being link
> first, link-name second (cutting off at two arguments and continuing
> the formatting is probably a groff bug).

Right, the latter (in parantheses) is what i think, too.

> mandoc formats its output as "foo: bar baz xyzzy",

I think this is wrong, and

  "bar baz xyzzy: foo"

would be better.

> but I think this is misleading because the ":" is a reserved
> token in the URI spec.

Yes.

And think of it the following way:

  Here are some web sites of BSD operating systems:
  .br
  .Lk http://www.dragonflybsd.org/ "DragonFly BSD"
  .br
  .Lk http://www.freebsd.org/ FreeBSD
  .br
  .Lk http://www.netbsd.org/ NetBSD
  .br
  .Lk http://www.openbsd.org/ OpenBSD

Rendering that as

  Here are some web sites of BSD operating systems:
  DragonFly BSD:
        http://www.dragonflybsd.org/
  FreeBSD: http://www.freebsd.org/
  NetBSD: http://www.netbsd.org/
  OpenBSD: http://www.openbsd.org/

seems quite natural, doesn't it?
I wouldn't expect the URI to precede its description.

> Can we come to an agreement as to how this should be formatted?  I
> don't want to be bug-compatible with groff in this case.  I like the
> "link: link-name" output, but due to the colon being a URI reserved
> token, "link-name: link" makes more sense,

Definitely.

> with link-name being bold and link being underlined.

Well, normally, you click on the link *name*, so underlining that
makes sense.  Besides, diverging from what groff does seems
gratuitous in this particular respect.

> Thoughts?

The real mess is here:

  schwarze@rhea $ /usr/local/bin/groff --version | head -n1
  GNU groff version 1.20.1
  schwarze@rhea $ /usr/local/bin/groff -mdoc -Thtml link.in
  [...]
  NetBSD:</i> <b>http://www.netbsd.org/</b> <i><br>
  OpenBSD:</i> <b>http://www.openbsd.org/</b></p>

Groff doesn't even attempt to produce real hyperlinks
in -Thtml mode.  Is this true?

I think we should have something similar to:

  <a href="http://www.netbsd.org/">NetBSD</a>:
  <b>http://www.netbsd.org/</b>

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

Re: groff `Lk' badness

[Kristaps Dzonsons]

>> mandoc formats its output as "foo: bar baz xyzzy",
> 
> I think this is wrong, and
> 
>   "bar baz xyzzy: foo"
> 
> would be better.

I just committed a fix for this.  Thanks!

> The real mess is here:
> 
>   schwarze@rhea $ /usr/local/bin/groff --version | head -n1
>   GNU groff version 1.20.1
>   schwarze@rhea $ /usr/local/bin/groff -mdoc -Thtml link.in
>   [...]
>   NetBSD:</i> <b>http://www.netbsd.org/</b> <i><br>
>   OpenBSD:</i> <b>http://www.openbsd.org/</b></p>
> 
> Groff doesn't even attempt to produce real hyperlinks
> in -Thtml mode.  Is this true?

groff passes only style bits via groff_out(7).  So it can't by design do 
anything more.  Run groff -Z -mandoc to see for yourself.

grohtml in general is pretty useless (even Werner has said so).  Another 
part of the design of troff: it was never built for hierarchical output.

> I think we should have something similar to:
> 
>   <a href="http://www.netbsd.org/">NetBSD</a>:
>   <b>http://www.netbsd.org/</b>

Ours simply formats as <a href="LINK">LINK-NAME</a> if a link name is 
specified, else just <a href="LINK">LINK</A>.  I generally think that 
writing an entire URI in a browser is superfluous as it usually shows up 
someplace, e.g., the status bar.  I'm not married to this behaviour, I 
guess.  If anybody else also thinks this should be changed, I'll do it.

Kristaps

--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv

Re: groff `Lk' badness

[Ingo Schwarze]

Hi Kristaps,

> grohtml in general is pretty useless (even Werner has said so).
> Another part of the design of troff: it was never built for
> hierarchical output.

Ah, OK, so no need to worry about that.

>>I think we should have something similar to:
>>  <a href="http://www.netbsd.org/">NetBSD</a>:
>>  <b>http://www.netbsd.org/</b>

> Ours simply formats as <a href="LINK">LINK-NAME</a> if a link name
> is specified, else just <a href="LINK">LINK</A>.  I generally think
> that writing an entire URI in a browser is superfluous as it usually
> shows up someplace, e.g., the status bar.

Yes, i think you are right, that is completely sufficient.
Actually, my proposal would result in rather ugly WWW manuals,
which we certainly don't want.

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