Skip to content

getopts --nroff: nested lists not properly formatted #1055

Open

Description

@stephane-chazelas

In 1.0.10, man -l <(getopts --nroff 2>&1) shows the group list as:

[...]
     There are several group types:
       1.
         A  group of the form [-[version][flag[number]]...[?text]] appearing as
         the first group enables the extended interface. version specifies  the
         interface  version, currently 1. The latest version is assumed if ver‐
         sion is omitted. Future enhancements may increment  version,  but  all
         versions  will  be  supported. text typically specifies an SCCS or CVS
         identification string. Zero or more flags with optional number  values
         may be specified to control option parsing. The flags are:
       +
         Arguments beginning with + are considered options.
       c
         Cache  this  optstring  for multiple passes. Used to optimize builtins
         that may be called many times within the same process.
       i
         Ignore this optstring when generating help. Used when  combining  opt‐
         string values from multiple passes.
[...]

While with --man (or --html), that's properly rendered as nested lists:

  There are several group types:
    1.    A group of the form [-[version][flag[number]]...[?text]] appearing as
          the first group enables the extended interface. version specifies the
          interface version, currently 1. The latest version is assumed if
          version is omitted. Future enhancements may increment version, but
          all versions will be supported. text typically specifies an SCCS or
          CVS identification string. Zero or more flags with optional number
          values may be specified to control option parsing. The flags are:
            +     Arguments beginning with + are considered options.
            c     Cache this optstring for multiple passes. Used to optimize
                  builtins that may be called many times within the same
                  process.
            i     Ignore this optstring when generating help. Used when
                  combining optstring values from multiple passes.

Raw nroff indeed shows no distinction, using .H1 custom macro for all list items at both levels:

.H1 1\&.
A group of the form
[\-[\fIversion\fP][\fIflag\fP[\fInumber\fP]]\&.\&.\&.[?\fItext\fP]] appearing
as the first group enables the extended interface\&. \fIversion\fP specifies
the interface version, currently \fB1\fP\&. The latest version is assumed if
\fIversion\fP is omitted\&. Future enhancements may increment \fIversion\fP,
but all versions will be supported\&. \fItext\fP typically specifies an SCCS or
CVS identification string\&. Zero or more \fIflags\fP with optional
\fInumber\fP values may be specified to control option parsing\&. The flags
are:
.H1 +
Arguments beginning with + are considered options\&.
.H1 c
Cache this \fIoptstring\fP for multiple passes\&. Used to optimize builtins
that may be called many times within the same process\&.
.H1 i
Ignore this \fIoptstring\fP when generating help\&. Used when combining
\fIoptstring\fP values from multiple passes\&.

If I revert this hunk from ksh93/ksh93-history@6a8dad6#diff-6ce302972762b6070a35e8cd1ca0fd9c20a0cc43af3d06d88bb6076a713d5a7bL4644-R4679

diff --git a/src/lib/libast/misc/optget.c b/src/lib/libast/misc/optget.c
index 82ad101b..56823629 100644
--- a/src/lib/libast/misc/optget.c
+++ b/src/lib/libast/misc/optget.c
@@ -1461,7 +1468,7 @@ item(Sfio_t* sp, char* s, int level, int style, Sfio_t* ip, int version, char* c
                if (level)
                {
                        if (style >= STYLE_nroff)
-                               sfprintf(sp, ".H%d ", (level + 1) / 2);
+                               sfprintf(sp, ".H%d ", (level - (level > 2)) / 2);
                        else
                                for (n = 0; n < level; n++)
                                        sfputc(sp, '\t');

Then, that particular man page renders OK again:

     There are several group types:
       1.
         A  group of the form [-[version][flag[number]]...[?text]] appearing as
         the first group enables the extended interface. version specifies  the
         interface  version, currently 1. The latest version is assumed if ver‐
         sion is omitted. Future enhancements may increment  version,  but  all
         versions  will  be  supported. text typically specifies an SCCS or CVS
         identification string. Zero or more flags with optional number  values
         may be specified to control option parsing. The flags are:
           +
             Arguments beginning with + are considered options.
           c
             Cache  this  optstring  for  multiple  passes.  Used  to  optimize
             builtins that may be called many times within the same process.
           i
             Ignore this optstring when generating help.  Used  when  combining
             optstring values from multiple passes.

But I don't know whether that would break other man pages assuming there was a reason for that change back in 2008.

Activity

  1. McDutchie commented on Oct 13, 2026

    @McDutchie

    If I revert this hunk from ksh93/ksh93-history@6a8dad6#diff-6ce302972762b6070a35e8cd1ca0fd9c20a0cc43af3d06d88bb6076a713d5a7bL4644-R4679
    [...]
    Then, that particular man page renders OK again:

    Potentially relevant src/lib/libast/RELEASE entries from that commit are:

    08-04-14 misc/optget.c: clean up nroff output
    08-03-30 misc/optget.c: [-n]... to enable -number & +number options
    08-03-06 misc/optget.c: ---* and +++* are now operands
    

    The relevant entry is probably the first one, "clean up nroff output". Not very informative. The change could quite simply be wrong.

    By the way, that third entry suggests #1053 is a feature, not a bug.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething is not working

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions