NetBSD Problem Report #54715

From martin@aprisoft.de  Sun Nov 24 09:34:46 2019
Return-Path: <martin@aprisoft.de>
Received: from mail.netbsd.org (mail.netbsd.org [199.233.217.200])
	(using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits))
	(Client CN "mail.NetBSD.org", Issuer "mail.NetBSD.org CA" (not verified))
	by mollari.NetBSD.org (Postfix) with ESMTPS id B91237A152
	for <gnats-bugs@gnats.NetBSD.org>; Sun, 24 Nov 2019 09:34:46 +0000 (UTC)
Message-Id: <20191124093436.C17425CC7A2@emmas.aprisoft.de>
Date: Sun, 24 Nov 2019 10:34:36 +0100 (CET)
From: martin@NetBSD.org
Reply-To: martin@NetBSD.org
To: gnats-bugs@NetBSD.org
Subject: Support a two args Lk tmac directive with optimized html output
X-Send-Pr-Version: 3.95

>Number:         54715
>Category:       toolchain
>Synopsis:       Support a two args Lk tmac directive with optimized html output
>Confidential:   no
>Severity:       non-critical
>Priority:       medium
>Responsible:    toolchain-manager
>State:          closed
>Class:          change-request
>Submitter-Id:   net
>Arrival-Date:   Sun Nov 24 09:35:00 +0000 2019
>Closed-Date:    Tue Nov 26 09:06:20 +0000 2019
>Last-Modified:  Tue Nov 26 09:06:20 +0000 2019
>Originator:     Martin Husemann
>Release:        NetBSD 9.99.18
>Organization:
The NetBSD Foundation, Inc.
>Environment:
System: NetBSD seven-days-to-the-wolves.aprisoft.de 9.99.18 NetBSD 9.99.18 (GENERIC) #318: Fri Nov 22 11:38:50 CET 2019 martin@seven-days-to-the-wolves.aprisoft.de:/work/src/sys/arch/amd64/compile/GENERIC amd64
Architecture: x86_64
Machine: amd64
>Description:

To improve the quality of our release notes, especially in the HTML version,
it would be great to have a variant of the Lk (link) macro that could
generate short links for html output but still create readable ascii/more
output.

Example current code:

Check the list of
.Nx
mirrors at
.Lk https://www.NetBSD.org/mirrors
for details.
.Pp

This creates:

  Check the list of
  NetBSD
  mirrrors at
  <a href="https://www.NetBSD.org/mirrors">https://www.NetBSD.org/mirrors</a>
  for details.

which (in a browser) is unpleasant to read. Better would be somethink like:


Check the list of
.Nx
.Lk https://www.NetBSD.org/mirrors mirrors
for details.
.Pp

that could generate in html:

  Check the list of
  NetBSD
  <a href="https://www.NetBSD.org/mirrors">mirrors</a>
  for details.

or in ascii:

  Check the list of NetBSD mirrors [https://www.NetBSD.org/mirrors]
  for details.


>How-To-Repeat:
s/a

>Fix:
n/a

>Release-Note:

>Audit-Trail:
From: Ingo Schwarze <schwarze@usta.de>
To: gnats-bugs@netbsd.org
Cc: wiz@netbsd.org, martin@netbsd.org
Subject: Re: toolchain/54715: Support a two args Lk tmac directive with
 optimized html output
Date: Sun, 24 Nov 2019 15:27:47 +0100

 Hello Martin and Thomas,

 i'm not quite sure what you are asking for.  As far as i can see,
 mandoc(1) already does almost exactly what you want:

    $ cat tmp.txt                                                  
   Check the list of
   .Nx
   .Lk https://www.NetBSD.org/mirrors mirrors
   for details.

    $ mandoc -mdoc -Thtml tmp.txt 
   [...]
   <div class="manual-text">Check the list of <span class="Ux">NetBSD</span>
   <a class="Lk" href="https://www.NetBSD.org/mirrors">mirrors</a> for
   details.</div>

    $ mandoc -mdoc -Tascii tmp.txt
   [...]
   Check the list of NetBSD mirrors: https://www.NetBSD.org/mirrors
   for details.

 What exactly is wrong with that?

 Note that for the example given above and for similar examples that
 don't go out of their way to uncover groff or mandoc bugs, mandoc
 and groff -T ascii output is byte-by-byte identical, so what you are
 asking for is even reasonably portable.

 I tested the above on OpenBSD-current and don't have a NetBSD system
 for comparison, but as far as i'm aware (http://mandoc.bsd.lv/ports.html),
 the NetBSD version of mandoc(1) is perfectly up-to-date (not so for
 apropos(1), but that doesn't matter in this case), so it ought to
 work in just the same way.  Does it?

 Yours,
   Ingo

From: Martin Husemann <martin@duskware.de>
To: Ingo Schwarze <schwarze@usta.de>
Cc: gnats-bugs@netbsd.org, wiz@netbsd.org, martin@netbsd.org
Subject: Re: toolchain/54715: Support a two args Lk tmac directive with
 optimized html output
Date: Sun, 24 Nov 2019 15:59:01 +0100

 On Sun, Nov 24, 2019 at 03:27:47PM +0100, Ingo Schwarze wrote:
 > Hello Martin and Thomas,
 > 
 > i'm not quite sure what you are asking for.  As far as i can see,
 > mandoc(1) already does almost exactly what you want:

 Yeah, but we do not use mandoc for our release notes (which is where I'd
 like to use it).

 I expected that kind of output from the 2-args invocation of .Lk, but
 it uses the first arg for the anchor text.

 Martin

From: Ingo Schwarze <schwarze@usta.de>
To: Martin Husemann <martin@duskware.de>
Cc: gnats-bugs@netbsd.org, wiz@netbsd.org
Subject: Re: toolchain/54715: Support a two args Lk tmac directive with
 optimized html output
Date: Sun, 24 Nov 2019 17:01:00 +0100

 Hi Martin,

 Martin Husemann wrote on Sun, Nov 24, 2019 at 03:59:01PM +0100:
 > On Sun, Nov 24, 2019 at 03:27:47PM +0100, Ingo Schwarze wrote:

 >> i'm not quite sure what you are asking for.  As far as i can see,
 >> mandoc(1) already does almost exactly what you want:

 > Yeah, but we do not use mandoc for our release notes

 Why not?  What do you use instead?

 > (which is where I'd like to use it).
 > 
 > I expected that kind of output from the 2-args invocation of .Lk, but
 > it uses the first arg for the anchor text.

 What does "it" in "it uses" refer to?
 Mandoc certainly does not use the first arg for the anchor text:

    $ echo .Lk first second | mandoc -mdoc -Thtml | grep href
   <div class="manual-text"><a class="Lk" href="first">second</a></div>

 Mandoc uses the first arg as the URI and the second as the displayed
 text that the user is supposed to click on.

 I'm trying to figure out what needs to be improved in mandoc(1),
 or what kind of help you need for using or integrating it...

 Yours,
   Ingo

From: "Robert Elz" <kre@netbsd.org>
To: gnats-bugs@gnats.NetBSD.org
Cc: 
Subject: PR/54715 CVS commit: src/share/tmac
Date: Tue, 26 Nov 2019 08:38:19 +0000

 Module Name:	src
 Committed By:	kre
 Date:		Tue Nov 26 08:38:19 UTC 2019

 Modified Files:
 	src/share/tmac: doc2html

 Log Message:
 PR toolchain/54715

 Remove duplicate (incorrect) version of the .Lk macro, so the
 earlier (fancier and functional) definition survives.

 For now simply comment it out.  Sometime later this one should be
 removed - but the two have been present since these macros were
 first imported (1999) so leaving this visible (but removed) a
 little longer shouldn't hurt.

 I (believe) this one is the only duplicate of this form.

 With this change the Lk macro in doc2html should work as it is designed
 (but does not call other macros, and can only have punctuation following
 the URL and (optional) anchor args (2nd arg is the anchor if it isn't
 punctuation).

 Tested by martin@


 To generate a diff of this commit:
 cvs rdiff -u -r1.67 -r1.68 src/share/tmac/doc2html

 Please note that diffs are not public domain; they are subject to the
 copyright notices on the relevant files.

From: "Martin Husemann" <martin@netbsd.org>
To: gnats-bugs@gnats.NetBSD.org
Cc: 
Subject: PR/54715 CVS commit: [netbsd-9] src/share/tmac
Date: Tue, 26 Nov 2019 08:56:52 +0000

 Module Name:	src
 Committed By:	martin
 Date:		Tue Nov 26 08:56:51 UTC 2019

 Modified Files:
 	src/share/tmac [netbsd-9]: doc2html

 Log Message:
 Pull up following revision(s) (requested by kre in ticket #485):

 	share/tmac/doc2html: revision 1.68

 PR toolchain/54715

 Remove duplicate (incorrect) version of the .Lk macro, so the
 earlier (fancier and functional) definition survives.

 For now simply comment it out.  Sometime later this one should be
 removed - but the two have been present since these macros were
 first imported (1999) so leaving this visible (but removed) a
 little longer shouldn't hurt.

 I (believe) this one is the only duplicate of this form.
 With this change the Lk macro in doc2html should work as it is designed
 (but does not call other macros, and can only have punctuation following
 the URL and (optional) anchor args (2nd arg is the anchor if it isn't
 punctuation).

 Tested by martin@


 To generate a diff of this commit:
 cvs rdiff -u -r1.67 -r1.67.16.1 src/share/tmac/doc2html

 Please note that diffs are not public domain; they are subject to the
 copyright notices on the relevant files.

From: "Martin Husemann" <martin@netbsd.org>
To: gnats-bugs@gnats.NetBSD.org
Cc: 
Subject: PR/54715 CVS commit: [netbsd-8] src/share/tmac
Date: Tue, 26 Nov 2019 08:59:41 +0000

 Module Name:	src
 Committed By:	martin
 Date:		Tue Nov 26 08:59:41 UTC 2019

 Modified Files:
 	src/share/tmac [netbsd-8]: doc2html

 Log Message:
 Pull up following revision(s) (requested by kre in ticket #1461):

 	share/tmac/doc2html: revision 1.68

 PR toolchain/54715

 Remove duplicate (incorrect) version of the .Lk macro, so the
 earlier (fancier and functional) definition survives.

 For now simply comment it out.  Sometime later this one should be
 removed - but the two have been present since these macros were
 first imported (1999) so leaving this visible (but removed) a
 little longer shouldn't hurt.

 I (believe) this one is the only duplicate of this form.
 With this change the Lk macro in doc2html should work as it is designed
 (but does not call other macros, and can only have punctuation following
 the URL and (optional) anchor args (2nd arg is the anchor if it isn't
 punctuation).

 Tested by martin@


 To generate a diff of this commit:
 cvs rdiff -u -r1.67 -r1.67.6.1 src/share/tmac/doc2html

 Please note that diffs are not public domain; they are subject to the
 copyright notices on the relevant files.

State-Changed-From-To: open->feedback
State-Changed-By: kre@NetBSD.org
State-Changed-When: Tue, 26 Nov 2019 09:03:56 +0000
State-Changed-Why:
Can you test and confirm that the changes committed handle this issue?


State-Changed-From-To: feedback->closed
State-Changed-By: martin@NetBSD.org
State-Changed-When: Tue, 26 Nov 2019 09:06:20 +0000
State-Changed-Why:
Fixed, thanks!


>Unformatted:

Home	PR Database Search