bugGNU roff - Bugs: bug #43532, [man] abbreviate titles when too...

 
 

bug #43532: [man] abbreviate titles when too wide, instead of overlapping them

Submitter:  Osamu Sayama <sayama>
Submitted:  Wed 05 Nov 2014 06:09:18 AM UTC
   
 
Category:  Macro man Severity:  1 - Wish
Item Group:  Feature change Status:  Fixed
Privacy:  Public Assigned to:  gbranden
Open/Closed:  Closed Planned Release:  1.23.0
* Mandatory Fields

Add a New Comment Rich Markup
   

Jump to the original submission

Thu 03 Jun 2021 03:05:52 PM UTC, comment #7: 


commit b7f38e8a1d698e1078d7c215d08fde57d8e919b9
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
Date:   Fri Jun 4 00:41:20 2021 +1000

    tmac/an-old.tmac: Fix Savannah #43532.

    * tmac/an-old.tmac (an-abbreviate-title): Add new internal macro to
      reduce the length of a man page title (i.e., the "ls" in "ls(1)", if
      it is too wide to fit in the page header (and would overwrite the
      center header material, usually the title of the manual section).
      Since the beginning and end of the title might be important for
      disambiguation, truncation at either end would be unwise; replace the
      middle of the title with an ellipsis.  Define new an-pageref and
      an-title-abbv strings for use by other macros and user-defined PT and
      BT traps.

      (PT, an-footer): Use new an-pageref string for economy.

      (an-header): Call an-abbreviate-title after setting the title length.

    Fixes <https://savannah.gnu.org/bugs/index.php?43532>.


G. Branden Robinson <gbranden>
Group administrator
Mon 31 May 2021 08:32:20 AM UTC, comment #6: 

Proposed patch.  Tested, seems to work.


diff --git a/tmac/an-old.tmac b/tmac/an-old.tmac
index 0eb568cb..45a97a10 100644
--- a/tmac/an-old.tmac
+++ b/tmac/an-old.tmac
@@ -306,8 +306,7 @@
 .\" Redefine these to customize the header & footer
 .
 .de1 PT
-.  tl '\\*[an-title](\\*[an-section])'\\*[an-extra3]'\
-\\*[an-title](\\*[an-section])'
+.  tl '\\*[an-pageref]'\\*[an-extra3]'\\*[an-pageref]'
 ..
 .
 .de1 BT
@@ -321,11 +320,57 @@
 .    tl '\\*[an-extra2]'\\*[an-extra1]'\\*[an-outer-footer-text]'
 ..
 .
+.\" Abbreviate the page title if it's too long for the header.  Leaves
+.\" string an-pageref defined for use in .PT and .an-footer.  Also
+.\" leaves an-title-abbv for possible use by .PT and .BT re-definers.
+.de1 an-abbreviate-title
+.  ds an-title-abbv \\*[an-title]\"
+.  ds an-title-string \\*[an-title]\"
+.  ds an-ellipsis \|.\|.\|.\|\"
+.  ds an-pageref \\*[an-title-abbv](\\*[an-section])\"
+.  nr an-header-width \\w'\\*[an-pageref]\\*[an-extra3]\\*[an-pageref]'
+.  while (\\n[an-header-width] >= \\n[.lt]) \{\
+.    \" The page title is too long; trim some bits out of the middle.
+.    length an-title-length \\*[an-title-string]
+.    \" roff division rounds integers toward zero.  Remove an additional
+.    \" character on each side of the midpoint to account for the
+.    \" ellipsis we add later.
+.    nr an-mark1 (\\n[an-title-length] / 2 - 2)
+.    nr an-mark2 (\\n[an-title-length] / 2 + 2)
+.    ds an-prefix \\*[an-title-string]\"
+.    ds an-suffix \\*[an-title-string]\"
+.    \" Use extremum operators to ensure that the first and last
+.    \" characters of the title remain intact (in cases of pathological
+.    \" shortening).
+.    substring an-prefix 0 (\\n[an-mark1] >? 1)
+.    substring an-suffix (\\n[an-mark2] <? (\\n[an-title-length] - 1) -1
+.    ds an-title-string \\*[an-prefix]\\*[an-suffix]\"
+.    ds an-title-abbv \\*[an-prefix]\\*[an-ellipsis]\\*[an-suffix]\"
+.    \" Measure the string again and give up if we made no progress.
+.    length an-title-new-length \\*[an-title-string]
+.    ie (\\n[an-title-new-length] >= \\n[an-title-length]) \
+.      break
+.    ds an-pageref \\*[an-title-abbv](\\*[an-section])\"
+.    nr an-header-width \
+       \\w'\\*[an-pageref]\\*[an-extra3]\\*[an-pageref]'
+.  \}
+.  rr an-title-length-prev
+.  rr an-mark1
+.  rr an-mark2
+.  rm an-prefix
+.  rm an-suffix
+.  rm an-title-string
+.  rr an-title-length
+.  rr an-header-width
+.  rm an-ellipsis
+..
+.
 .de1 an-header
 .  ev an-env
 .  ps \\n[PS]u
 .  vs \\n[VS]u
 .  lt \\n[LT]u
+.  an-abbreviate-title
 .  if !\\n[an-is-output-html] \{\
 .    if !\\n[cR] \
 .      sp .5i
@@ -356,7 +401,7 @@
 .  lt \\n[LT]u
 .  if !\\n[an-is-output-html] \{\
 .    ie \\n[cR] \
-.      ds an-outer-footer-text "\\*[an-title](\\*[an-section])\"
+.      ds an-outer-footer-text "\\*[an-pageref]\"
 .    el \{\
 .      ds an-outer-footer-text \\n[%]\"
 .      if r X \{\


G. Branden Robinson <gbranden>
Group administrator
Mon 31 May 2021 03:29:23 AM UTC, comment #5: 

Un-postponing.  Turns out I need to gnaw on this to scratch a different itch.

G. Branden Robinson <gbranden>
Group administrator
Wed 19 May 2021 09:13:05 AM UTC, comment #4: 

I'm uneasy with applying this patch because (1) I think the result looks bad (though not as bad as the status quo, and it was never going to be beautiful with such obnoxiously long identifiers--what were the Erlang people thinking?) but more importantly (2) the man package makes some assumptions that the footer line in particular is going to be only one output line in length.

groff's man(7) package also supports hooks in the form of the PT and BT macros to let users alter the presentation of the header and footer lines, respectively.  The assumption here is pretty much that all the user needs to do is write a .tl request as the macro definition[1].

I think the better thing to do is to shorten the components of the header line if they overrun, as groff's mdoc(7) does (and as recently bug-fixed to avoid an infinite loop[2].

I am taking responsibility for this bug and postponing it.  If there's no discussion about it I expect to resolve it as "Wont Fix" in the future.

[1] It's slightly more complicated than that if they want different titles for recto and verso pages, but not much.
[2] https://lists.gnu.org/archive/html/groff-commit/2020-11/msg00167.html

G. Branden Robinson <gbranden>
Group administrator
Sat 25 Jul 2020 11:22:09 AM UTC, comment #3: 

For comparison, here is what mandoc does:


 $ mandoc
.TH CosNotifyChannelAdmin_StructuredProxyPushSupplier 3erl "cosNotification 1.1.18" "Ericsson AB" "Erlang Module Definition"
CosNotifyChannelAdmin_StructuredProxyPushSupplier(3erl)
                                                      Erlang Module Definition



Ericsson AB                 cosNotification 1.1.18
                       CosNotifyChannelAdmin_StructuredProxyPushSupplier(3erl)
 $


Note that

  • CosNotify... is left justified on line 1
  • Erlang Module Definition   is right justified on line 2
  • Ericsson AB   is left justified
  • cosNotification 1.1.18   is centered
  • CosNotify... is right justified on the last line


I did not inspect the patch yet.

Ingo Schwarze <schwarze>
Group Member
Mon 01 Dec 2014 08:51:38 AM UTC, comment #2: 

Yes, I modified the patch to work with -rLT (and -rLL) by
using .lt and it worked ok for me.
I uploaded revised one as an-old.tmac-long-TH.patch2.


(file #32577)

Osamu Sayama <sayama>
Wed 05 Nov 2014 12:26:18 PM UTC, comment #1: 

I noticed this patch fixes the space at 4.3 inches, but groff_man specifies that the title line length can be changed by setting -rLT (or -rLL) to a different width, so should not this patch take this into account. (NB I have not actually tested the patch yet).

Deri James <deri>
Group Member
Wed 05 Nov 2014 06:09:18 AM UTC, original submission:  

For example, erlang has many long .TH man pages.
---
% grep '^.TH' /usr/share/man/man3erl/CosNotifyChannelAdmin_StructuredProxyPushSu
pplier.3erl
.TH CosNotifyChannelAdmin_StructuredProxyPushSupplier 3erl "cosNotification 1.1.
18" "Ericsson AB" "Erlang Module Definition"
---
If such a long .TH file is processed by groff, header and
fooder are displayed by overlapping.
---
% grep '^.TH' /usr/share/man/man3erl/CosNotifyChannelAdmin_StructuredProxyPushSu
pplier.3erl | gtroff -man -T ascii|grotty -c
CosNotifyChannelAdmin_SCosNotifyChannelAdmin_StructuredProxyPushSupplier(3erl)



Ericsson AB            CosNotifyChannelAdmin_StructuredProxyPushSupplier(3erl)
---
I created a patch for an-old.tmac to be displayed by two lines
if it is long.
---
% grep '^.TH' /usr/share/man/man3erl/CosNotifyChannelAdmin_StructuredProxyPushSu
pplier.3erl | gtroff -man -T ascii|grotty -c
Erlang Module Definition
                       CosNotifyChannelAdmin_StructuredProxyPushSupplier(3erl)


Ericsson AB                 cosNotification 1.1.18
                       CosNotifyChannelAdmin_StructuredProxyPushSupplier(3erl)
---
It would be great if long .TH is handled by two lines like this.

Osamu Sayama <sayama>

 

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

Attach Files:
   
   
Comment:
   

Attached Files
file #32577:  an-old.tmac-long-TH.patch2 added by sayama (4KiB - application/octet-stream)
file #32370:  an-old.tmac-long-TH.patch added by sayama (2KiB - text/x-diff)

 

Depends on the following items: None found

Items that depend on this one: None found

 

Carbon-Copy List
  • -email is unavailable- added by gbranden (Updated the item)
  • -email is unavailable- added by schwarze (Updated the item)
  • -email is unavailable- added by deri (Posted a comment)
  • -email is unavailable- added by sayama (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 17 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2021-06-03 gbranden StatusIn Progress Fixed
        Open/ClosedOpen Closed
        Planned ReleaseNone 1.23.0
        Summary[man] put titles on separate lines when parts too wide, instead of overlapping them [man] abbreviate titles when too wide, instead of overlapping them
    2021-05-31 gbranden Summaryman: put titles on separate lines when parts too wide, instead of overlapping them [man] put titles on separate lines when parts too wide, instead of overlapping them
    2021-05-31 gbranden Summary[PATCH] man: put titles on separate lines when parts too wide, instead of overlapping them man: put titles on separate lines when parts too wide, instead of overlapping them
    2021-05-31 gbranden StatusPostponed In Progress
    2021-05-19 gbranden StatusConfirmed Postponed
        Assigned toNone gbranden
    2020-07-25 gbranden Severity2 - Minor 1 - Wish
        Summarygroff handles long .TH as overlaping in header and footer [PATCH] man: put titles on separate lines when parts too wide, instead of overlapping them
    2018-02-16 schwarze CategoryNone Macro man
        Severity3 - Normal 2 - Minor
        Item GroupNone Feature change
        StatusNone Confirmed
    2014-12-01 sayama Attached File- Added an-old.tmac-long-TH.patch2, #32577
    2014-11-05 sayama Attached File- Added an-old.tmac-long-TH.patch, #32370

    Back to the top

    Powered by Savane 3.13-4448.
    Corresponding source code