bugGNU roff - Bugs: bug #52849, mdoc(7) .Lk: complete rewrite of...

 
 

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

Submitter:  Ingo Schwarze <schwarze>
Submitted:  Tue 09 Jan 2018 11:57:51 PM UTC
   
 
Category:  Macro mdoc Severity:  3 - Normal
Item Group:  Feature change Status:  Fixed
Privacy:  Public Assigned to:  schwarze
Open/Closed:  Closed Planned Release:  1.22.4
* Mandatory Fields

Add a New Comment Rich Markup
   

Sat 13 Jan 2018 03:01:22 AM UTC, comment #2: 

commit e53dff356d43f358133138d2f99eca7b0a7fda32

Ingo Schwarze <schwarze>
Group Member
Wed 10 Jan 2018 08:37:01 AM UTC, comment #1: 

Ingo, you now have commit rights.  Please proceed in case there are no objections!

Werner LEMBERG <wl>
Group administrator
Tue 09 Jan 2018 11:57:51 PM UTC, original submission:  

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 <wl@gnu.org>
  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.

Ingo Schwarze <schwarze>
Group Member

 

(Note: upload size limit is set to 16384 kB, after insertion of the required escape characters.)

Attach Files:
   
   
Comment:
   

Attached Files
file #42878:  Lk.patch added by schwarze (3KiB - text/x-patch)
file #42879:  test-Lk.mdoc added by schwarze (753B - application/octet-stream)

 

Depends on the following items: None found

Items that depend on this one: None found

 

Carbon-Copy List
  • -email is unavailable- added by wl (Posted a comment)
  • -email is unavailable- added by schwarze (Submitted the item)
  •  

    There are 0 votes so far. Votes easily highlight which items people would like to see resolved in priority, independently of the priority of the item set by tracker managers.

    Only logged-in users can vote.

     

    Follow 7 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2018-01-13 schwarze StatusIn Progress Fixed
        Open/ClosedOpen Closed
        Planned ReleaseNone 1.22.4
    2018-01-10 wl StatusNone In Progress
        Assigned toNone schwarze
    2018-01-09 schwarze Attached File- Added Lk.patch, #42878
        Attached File- Added test-Lk.mdoc, #42879

    Back to the top

    Powered by Savane 3.13-02a9.
    Corresponding source code