bugGNU roff - Bugs: bug #65102, [mdoc] objection to title heading...

 
 

bug #65102: [mdoc] objection to title heading rendering in 1.23.0

Submitter:  None
Submitted:  Sun 31 Dec 2023 10:29:56 PM UTC
   
 
Category:  Macro package mdoc Severity:  2 - Minor
Item Group:  Rendering/Cosmetics Status:  Unreproducible
Privacy:  Public Assigned to:  gbranden
Open/Closed:  Closed Planned Release:  None
* Mandatory Fields

Post a Comment

Add a New Comment Rich Markup
   

Discussion

Jump to the original submission

Sat 13 Dec 2025 01:58:33 PM UTC, comment #8: 

Migrating to "Unreproducible" status, now defined more clearly as:

"Developers could not re-create the problem, or were not provided with information necessary to resolve it."

G. Branden Robinson <gbranden>
Group administrator
Wed 03 Dec 2025 05:22:26 AM UTC, comment #7: 

comment #3:

> I've been waiting on feedback to this ticket for 19 months.
>
> Can you follow-up, please?


comment #6:

> I should probably have made clear here that I was seeking feedback from наб, who is, I believe, the anonymous submitter of this ticket.


No feedback after an additional 6 months.

Closing as Invalid, which seems the least wrong status for a ticket where we solicited feedback but didn't get it.

G. Branden Robinson <gbranden>
Group administrator
Sun 04 May 2025 10:32:54 AM UTC, comment #6: 

comment #3:

> I've been waiting on feedback to this ticket for 19 months.
>
> Can you follow-up, please?


I should probably have made clear here that I was seeking feedback from наб, who is, I believe, the anonymous submitter of this ticket.

But I do appreciate Ingo's feedback in comment #4.  if groff and mandoc are to have minor differences in rendering, it's good to have the discussion on record as well as the conciliatory attitudes thereto of the relevant maintainers.

I trust Ingo to let me know if he thinks I'm doing something objectively wrong, and he can rely on me to do likewise.  :)

G. Branden Robinson <gbranden>
Group administrator
Sun 04 May 2025 10:27:59 AM UTC, comment #5: 

At 2025-05-03T12:40:03-0400, Ingo Schwarze wrote:

> Follow-up Comment #4, bug #65102 (group groff):
>
> I don't think mandoc(1) will ever follow the new practice of setting
> the .Dt and .TH arguments in italic.  There is no benefit, the header
> and footer line stand out just fine without any markup.  Besides, i
> consider italic as logically wrong for strings that have to be typed
> verbatim - i know that Branden disagrees and thinks it is just fine to
> use italic sometimes for keywords, sometimes for placeholders.  We can
> agree to disagree in that respect.


Yes, I see where you're coming from, and would not characterize your
preferences or mandoc(1)'s approach as "wrong".

> That will likely require patching the italic font out in the OpenBSD
> groff port as well, because otherwise, this would be a massive
> regression introducing universial failure into every test in the test
> suite.


Such a patch should be straightforward, but if you have any trouble with
it, please ping me and I'll help construct one.

> The OP's concern might be that an underlined underscore is hard to
> distinguished from an underscore that is not underlined - but that
> font-dependent (potential) issue is not specific to .Dd, so if that is
> what they meant, it's not such a big deal.


Yes--I can't speak for наб here, but I think you're right that such a
problem is not confined to rendering of `Dd`'s argument, and I'd add
that it's device-specific, too.  Some output devices are capable of
true italics and they should probably be used when available.

> Getting rid of the anachronistic ALL CAPS convention for .Dt and .TH
> is fine.  In particular, it's good for accessibility and precision.


And of course I still agree with this.  :)

G. Branden Robinson <gbranden>
Group administrator
Sat 03 May 2025 04:39:53 PM UTC, comment #4: 

I don't think mandoc(1) will ever follow the new practice of setting the .Dt and .TH arguments in italic.  There is no benefit, the header and footer line stand out just fine without any markup.  Besides, i consider italic as logically wrong for strings that have to be typed verbatim - i know that Branden disagrees and thinks it is just fine to use italic sometimes for keywords, sometimes for placeholders.  We can agree to disagree in that respect.

That will likely require patching the italic font out in the OpenBSD groff port as well, because otherwise, this would be a massive regression introducing universial failure into every test in the test suite.

The OP's concern might be that an underlined underscore is hard to distinguished from an underscore that is not underlined - but that font-dependent (potential) issue is not specific to .Dd, so if that is what they meant, it's not such a big deal.

Getting rid of the anachronistic ALL CAPS convention for .Dt and .TH is fine.  In particular, it's good for accessibility and precision.

Ingo Schwarze <schwarze>
Group Member
Sat 03 May 2025 03:43:22 AM UTC, comment #3: 

I've been waiting on feedback to this ticket for 19 months.

Can you follow-up, please?

G. Branden Robinson <gbranden>
Group administrator
Mon 01 Jan 2024 01:35:22 AM UTC, comment #2: 

Here's one more attachment for grins, showing real italics on the terminal.  (I'm using xterm(1).)


G. Branden Robinson <gbranden>
Group administrator
Mon 01 Jan 2024 01:30:27 AM UTC, comment #1: 

I had a lengthy response to this but somehow lost or clobbered in one of my hundreds of browser tabs.  :(

But I did take some screenshots that I can still lay my hands on.

First:

> Dt is misrendered


This is a matter of opinion...

> but only in nroff mode.


...but this is not.  The italics to which you object are applied in both typesetter and terminal output.  See attachments.

> in 1.22.4-10, the top left and right corners were "A_B_C(9)".


Yes.

> In 1.23.0-3 [...] they are "\fIA_B_C\fP(9)",


Yes.

> (a) why would you need this?


For consistency between man(7) and mdoc(7) page renderings, also discussed in bug #65101, and for consistency between mentions of page titles in `MR` and `Xr` cross references and their referents (targets).

> (b) completely breaks manuals with underscores in the name,


Breaks how?  What tool is breaking?  Some output scraper?  There is no specification for such things.

> because "\fIA_B_C\fP(9)" and "A_B_C(9)" and "\fIA B C\fP(9)" are all drawn identically.


This is demonstrably false in both typesetter and terminal output (even without using grotty's `-i` option to obtain "true" italics if the terminal device supports them).  See attachments.

It is possible that your terminal emulator is limited or defective.  In such cases, many elements of the rendered page that should be differentiable will not be.  For instance, on the "ascii" and "latin1" output devices, hyphens and minus signs are visually identical, and on the "utf8", "ps", and "pdf" output devices, they are distinguishable.

> I didn't have the time or the energy to root-cause this.


I know exactly whence it comes, but not what, apart from a reflexive objection to any change, is motivating your bug report.

Setting to "Need Info" status.

Exhibit corresponding to attachments (all font styling is lost in copy-and-paste operations, of course):


##$ cat ATTIC/goofy.mdoc
.Dd 2023-12-31
.Dt A_B_C 9
.Os
.Sh Name
.Nm goofy
.Nd a goofy page
.Sh Description
There is nothing more to say.
##$ ~/groff-stable/bin/groff -rLL=50n -mdoc -Tutf8 ATTIC/goofy.mdoc
A_B_C(9)     Kernel Developer’s Manual    A_B_C(9)

Name
       goofy — a goofy page

Description
       There is nothing more to say.

GNU                 2023‐12‐31            A_B_C(9)
##$ ~/groff-stable/bin/groff -mdoc ATTIC/goofy.mdoc >| goofy.ps
##$ evince goofy.ps





G. Branden Robinson <gbranden>
Group administrator
Sun 31 Dec 2023 10:29:56 PM UTC, original submission:  

Downstream bug: https://bugs.d ... an.org/1059536, part 2.

Dt is misrendered but only in nroff mode.
Given

  .Dt A_B_C 9

In troff mode, and in 1.22.4-10, the top left and right corners were "A_B_C(9)".
In 1.23.0-3 in nroff they are "\fIA_B_C\fP(9)", which:
(a) why would you need this?
(b) completely breaks manuals with underscores in the name,
    because "\fIA_B_C\fP(9)" and "A_B_C(9)" and "\fIA B C\fP(9)"
    are all drawn identically.
I didn't have the time or the energy to root-cause this.

Anonymous

 

Attached Files

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

Attach Files:
   
   
Comment:
   

 

Dependencies

This item does not depend on any other items.

No items depend on this one.

 

Mail Notification Carbon-Copy List

Carbon-Copy List
  • -email is unavailable- added by schwarze (Posted a comment)
  • -email is unavailable- added by gbranden (Updated the item)
  • -email is unavailable- added by gbranden (original reporter)
  •  

    Votes

    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.

     

    Please enter the title of George Orwell's famous dystopian book (it's a date):

    History

    Follow 12 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2025-12-13 gbranden StatusInvalid Unreproducible
    2025-12-03 gbranden StatusNeed Info Invalid
        Open/ClosedOpen Closed
    2024-01-01 gbranden Attached File- Added mdoc-page-with-italic-title-terminal-real-italics.png, #55496
    2024-01-01 gbranden Attached File- Added mdoc-page-with-italic-title-terminal.png, #55494
        Attached File- Added mdoc-page-with-italic-title-ps.png, #55495
        Severity3 - Normal 2 - Minor
        Item GroupIncorrect behaviour Rendering/Cosmetics
        StatusNone Need Info
        Assigned toNone gbranden
        Summarymdoc nroff output for Dt broken since 1.23 [mdoc] objection to title heading rendering in 1.23.0
    2023-12-31 gbranden Carbon-Copy- Added -email is unavailable-

    Back to the top

    Powered by Savane 3.16-a7ba.
    Corresponding source code