bugGNU roff - Bugs: bug #67456, [doc,man] improve closing brace...

 
 

bug #67456: [doc,man] improve closing brace escape sequence clustering advice

Submitter:  Bjarni Ingi Gislason <bjarniig>
Submitted:  Sun 24 Aug 2025 09:57:33 PM UTC
   
 
Category:  Core Severity:  2 - Minor
Item Group:  Documentation Status:  Confirmed
Privacy:  Public Assigned to:  None
Open/Closed:  Open Planned Release:  None
* Mandatory Fields

Post a Comment

Add a New Comment Rich Markup
   

Discussion

Sun 24 Aug 2025 10:17:38 PM UTC, comment #1: 

At 2025-08-24T17:57:36-0400, Bjarni Ingi Gislason wrote:

> File: man/groff.7.man
>
> In chapter "Control structures", fourth paragraph:
>
> "\} should appear on a line with other occurrences of itself as necessary
> to match \{ sequences."
>
>   With '\}\}..." the end of a structure (with indentation) is not clearly
> visible.
>
>   A better practice is to have each "end of a block" on its own line,
> like:
>
> .    \}
> .  \}
> .\}
>
> matching the beginning of each corresponding block of text.


I believe the intention of the language here was to prevent people from
supposing that they could mix close-brace escape sequences with
arbitrary tokens on an input line.

Historically, this was done in AT&T/DWB troff and can still be seen in
Plan 9 from User Space today.  Here's a modest sample.


src/cmd/mpm/tmac.pm:68:.sp \\$1\}
src/cmd/mpm/tmac.pm:143:.       fp 4 PX\}
src/cmd/mpm/tmac.pm:149:.               fp 4 NX CentBI\}
src/cmd/mpm/tmac.pm:154:.               fp 4 NX\}\}


As noted elsewhere in the manual, such aggressive economy does not work
well with the `while` request.

At the same time, I don't want to be overprescriptive; the manual should
document what is allowed, and suggest best practices where known and
of sufficient merit.

G. Branden Robinson <gbranden>
Group administrator
Sun 24 Aug 2025 09:57:33 PM UTC, original submission:  

Subject: [groff(7)] Bad advice for grouping of '\}'

File: man/groff.7.man

In chapter "Control structures", fourth paragraph:

"\} should appear on a line with other occurrences of itself as necessary
to match \{ sequences."

  With '\}\}..." the end of a structure (with indentation) is not clearly
visible.

  A better practice is to have each "end of a block" on its own line,
like:

.    \}
.  \}
.\}

matching the beginning of each corresponding block of text.

  With

grep -n -F -e '\{\' -e '\}' <file>

  the structure is made visible to check for mismatched delimiters.

N.B.

  Counting the number of "delimiters" (grep -c -F ...) is a first measure
to check for a possible mismatch.

Bjarni Ingi Gislason <bjarniig>

 

Attached Files

This item currently has no 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 gbranden (Posted a comment)
  • -email is unavailable- added by bjarniig (Submitted the item)
  •  

    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 4 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2025-08-24 gbranden CategoryGeneral Core
        Severity3 - Normal 2 - Minor
        StatusNone Confirmed
        Summary[groff(7)] Bad advice for grouping of '\}' [doc,man] improve closing brace escape sequence clustering advice

    Back to the top

    Powered by Savane 3.16-a7ba.
    Corresponding source code