[bug #63958] [mdoc] decide how to set up hanging indent in Synopsis sections

[G. Branden Robinson]

URL:
  <https://savannah.gnu.org/bugs/?63958>

                 Summary: [mdoc] decide how to set up hanging indent in
Synopsis sections
                   Group: GNU roff
               Submitter: gbranden
               Submitted: Fri 24 Mar 2023 07:52:56 AM UTC
                Category: Macro mdoc
                Severity: 1 - Wish
              Item Group: Rendering/Cosmetics
                  Status: Need Info
                 Privacy: Public
             Assigned to: gbranden
             Open/Closed: Open
         Discussion Lock: Any
         Planned Release: None


    _______________________________________________________

Follow-up Comments:


-------------------------------------------------------
Date: Fri 24 Mar 2023 07:52:56 AM UTC By: G. Branden Robinson <gbranden>
Input:


.Dd June 6, 1944
.Dt timerdday 3bsd
.Os
.Sh Name
.Nm timerdday
.Nd compute time of launch operation within window
.Sh Synopsis
.Ft void
.Fn timerdday "\%struct-timespec *earliest" \
"\%struct-timespec *latest" "\%struct-timespec *resolution"
.Sh Description
Compute the optimal start time for a desired event to occur between
times
.Va earliest No and Va latest
to within a granularity of
.Va resolution .


mandoc 1.14.6 output (on Debian bullseye):


$ mandoc ../ATTIC/timerdday.mdoc | ul
timerdday(3bsd)                      3bsd                     
timerdday(3bsd)

Name
     timerdday – compute time of launch operation within window

Synopsis
     void timerdday(struct-timespec *earliest, struct-timespec *latest,
     struct-timespec *resolution)

Description
     Compute the optimal start time for a desired event to occur between
times
     earliest and latest to within a granularity of resolution.

Debian                           June 6, 1944                          
Debian


groff Git HEAD (in my working copy with a pending fix for bug #63957):


$ ./test-groff -mandoc -Tascii ../ATTIC/timerdday.mdoc 
timerdday(3bsd)                      LOCAL                    
timerdday(3bsd)

Name
       timerdday -- compute time of launch operation within window

Synopsis
       void
       timerdday(struct-timespec *earliest, struct-timespec *latest,
           struct-timespec *resolution);

Description
       Compute  the  optimal  start  time for a desired event to occur
between
       times earliest and latest to within a granularity of resolution.

GNU                              June 6, 1944                 
timerdday(3bsd)


Several questions occur to me:

1. How is mdoc(7) to know where to place the hanging indent?  man(7) does it
by measuring the width of the first argument to the `SY` macro, which is a GNU
extension.

2. mandoc mdoc(7) doesn't break after `Ft`; groff mdoc(7) does.

3. groff mdoc(7) appears to be computing the hanging indent based on the
argument to `Ft`.

4. What's best practice?  Use a display with `-width`?

I'd like to discuss these points with an mdoc(7) maven at some point.  Ingo's
the most likely candidate.







    _______________________________________________________

Reply to this item at:

  <https://savannah.gnu.org/bugs/?63958>

_______________________________________________
Message sent via Savannah
https://savannah.gnu.org/