[bug #52849] mdoc(7) .Lk: complete rewrite of the macro

[Ingo Schwarze]

URL:
  <http://savannah.gnu.org/bugs/?52849>

                 Summary: mdoc(7) .Lk: complete rewrite of the macro
                 Project: GNU troff
            Submitted by: schwarze
            Submitted on: Tue 09 Jan 2018 11:57:51 PM UTC
                Category: Macro - mdoc
                Severity: 3 - Normal
              Item Group: Wishlist
                  Status: None
                 Privacy: Public
             Assigned to: None
             Open/Closed: Open
         Discussion Lock: Any
         Planned Release: None

    _______________________________________________________

Details:

The mdoc(7) .Lk macro is a very useful macro introduced by groff to the mdoc
language.  The implementation is essentially unchanged since

  commit 30079e0e0b872d8e575c46d5c32a6e3271d94494
  Author: Werner LEMBERG <address@hidden>
  Date:   Mon Sep 25 13:49:25 2000 +0000

except that i fixed two bugs in April 2017
(2464569cae9e21a7bff31fa78b563f2502bec94f,
24904c378090cdb17f8e2390829ad41b7fee3ec0).

This macro was introduced shortly before the big mdoc rewrite for groff-1.17,
and many of the significant improvements that were applied to almost all other
macros were never implemented here.  For example, .Lk is neither callable nor
parsed and only partially handles trailing punctuation.

Apart from the somewhat old-fashioned implementation, an independent issue is
caused by the built-in semantics to display short URIs in-line and long URIs
using an implicit display, somewhat similar to what .D1 does.  While it is
true that it often makes sense to render short URIs in-line and to display
long URIs, the automatic has several downsides:

 - The length threshold varies among output devices, and the outcome is
impossible to predict by the document author.
 - All the same, knowing the outcome is imperative because the surrounding
text must be worded accordingly.
 - In real-word manual pages, the display layout often occurs even though the
author clearly expected in-line layout, making them look very ugly.
 - In case in-line layout is desired for a slightly longer URI, which is not
even a very rare situation, there is no way to achieve it.

For these reasons, i propose to completely remove the implicit display feature
and show all URIs in-line.  This will improve the rendering of more existing
manual pages than it will harm, and when a display is really desired, it is
trivial to achieve with ".D1 Lk" with this patch.

The attached patch is a complete re-implementation of the .Lk macro which

 - makes .Lk callable, such that ".Pq Lk" and similar constructions work: they
already occur in practice;
 - make trailing punctuation work in all situations
 - makes the style of the implementation consistent with other macros
 - allows making .Lk parsed later on if we want to; but that's optional and
not very pressing, in practice, you can usually put the following macro on the
next input line without any adverse effect.

I'm also attaching a demo file to help you visualize how various constructions
involving .Lk will render with the patch.



    _______________________________________________________

File Attachments:


-------------------------------------------------------
Date: Tue 09 Jan 2018 11:57:51 PM UTC  Name: Lk.patch  Size: 3KiB   By:
schwarze

<http://savannah.gnu.org/bugs/download.php?file_id=42878>
-------------------------------------------------------
Date: Tue 09 Jan 2018 11:57:51 PM UTC  Name: test-Lk.mdoc  Size: 753B   By:
schwarze

<http://savannah.gnu.org/bugs/download.php?file_id=42879>

    _______________________________________________________

Reply to this item at:

  <http://savannah.gnu.org/bugs/?52849>

_______________________________________________
  Message sent via/by Savannah
  http://savannah.gnu.org/