Hi Dirk,

comment #2:

> Sorry that I forgot to mention it: groff-1.23.0 is what I am using
> here.

Thanks for confirming that.  The problem you describe goes way back. :-O

> Because I wondered why man(1) has no problems in formatting the
> attached lsp-help.1 whereas
>

> $ nroff -t -man lsp-help.broken.1

>
> has, I had a closer look and here on my system (Gentoo) nroff(1) is
> called with -mandoc.  Depending on the current size of the terminal
> more options are used, e.g.:
>

> nroff -mandoc -c -rLL=143n -rLT=143n -Tutf8

>
> I now noticed that for some sizes everything is OK and for others the
> problems arise.
>
> I mention this, because I had a look at the discussion in bug #65190
> mentioning a patch for an.tmac but not andoc.tmac.

The "-mandoc" argument is a red herring in this case; what matters is
configuration of the terminal width, something man-db man(1) does
automatically.

"andoc.tmac" is an unlikely site to patch for this problem.

See the "Files" section of groff_man(7):

       /usr/share/groff/1.23.0/tmac/andoc.tmac
              This brief groff program detects whether the man or mdoc
              macro package is being used by a document and loads the
              correct macro definitions, taking advantage of the fact
              that pages using them must call .TH or .Dd, respectively,
              before any other macros.  A man program or user typing,
              for example, “groff -mandoc page.1”, need not know which
              package the file page.1 uses.  Multiple man pages, in
              either format, can be handled; andoc reloads each macro
              package as necessary.

> I tried your suggested workaround and it works here.

Glad to hear it!

> I will try to follow all the discussions, because at least I learn a
> lot from it.

If you have any questions about anything to do with groff, please feel
free to post them to the groff at gnu dot org mailing list.

Regards,
Branden

Hi Dirk,

Thanks for the report.

And thank you very much for trimming the page down to make a simpler reproducing case!

I note that the `-s` and `-Tutf8` options don't seem to matter.  (One has to select some terminal output device, but `-Tascii` works--or fails--just as well.)

You could therefore simplify your command-line recipe.

$ nroff -t -man lsp-help.broken.1
-verabtim-

...in case you aim to write a regression test around this.

I can further verify that this problem affects _groff_ 1.22.3, 1.22.4, 1.23.0, and Git HEAD.

This appears to be the same bug that afflicts the _ascii_(7) document in the Linux man-pages project; in other words, I've seen it before.

I also observe that while the "non-broken" lsp-help.1 specimen does not provoke a warning from _grotty_, it doesn't format correctly, either.[1]

+verbatim+
$ groff -rLL=65n -Tascii -t -man lsp-help.1
lsp-help(1)              lsp online help              lsp-help(1)

General Information
     lsp  lists  file content in pages; the content can come from
     files on disk and from standard input, e.g. manual pages.

Interacting with lsp
                             General keys
   -----------------+-----------------------------------------------
   Keyboard / Mouse | Action
   -----------------+-----------------------------------------------
          q         | - Quit lsp.
                    | - Quit TOC mode.
                    | - Close this help.
   -----------------+-----------------------------------------------
          h         | Show this online help.
   -----------------+-----------------------------------------------
                        Handling manual pages
   -----------------+-----------------------------------------------
   Keyboard / Mouse | Action
   -----------------+-----------------------------------------------
         TAB        | go to next valid reference in the manual page
   -----------------+-----------------------------------------------
      Shift-TAB     | go to previous valid reference
   -----------------+-----------------------------------------------
        ENTER       | open current reference
   -----------------+-----------------------------------------------
          a         | show apropos(1) buffer of all manual pages on
                    | the system
                    | (The above commands can then be used to visit
                    | those references.)
   -----------------+-----------------------------------------------
          m         | open another manual page
   -----------------+-----------------------------------------------
          T         | TOC mode: toggle through three  levels  of  a
                    | TOC (or folding) mode:
                    | 1)  Only  content  starting  in  column  1 is
                    | shown.
                    | 2) Additionaly, content starting in column  4
                    | is shown.
                    | 3) Add content starting in column 8, but only
                    | if  it  is followed by a line with deeper in-
                    | dentation.
                    | This mode is left by pressing 'q' or ENTER to
                    | jump to the highlighted entry.
   -----------------+-----------------------------------------------
                          Movement in files
   -----------------------------------------------------------------
   Keyboard / Mouse   Action
   -----------------------------------------------------------------
          b
       Page up        backward one page
   -----------------------------------------------------------------
        Key up        backward one line
   -----------------------------------------------------------------
        ENTER
       Key down       forward one line
   -----------------------------------------------------------------
          f
      Page down
        SPACE         forward one page
   -----------------------------------------------------------------
          <           backward to first page
   -----------------------------------------------------------------
          >           forward to last page
   -----------------------------------------------------------------
         C-l          In a search: bring the current match  to  the
                      top of the page
   -----------------+-----------------------------------------------
                    |     Searching in files
   -----------------+-----------------------------------------------
   Keyboard / Mouse | Action
   -----------------+-----------------------------------------------
          /         | search forward for regular expression
   -----------------+-----------------------------------------------
          ?         | search backward for regular expression
   -----------------+-----------------------------------------------
          n         | find next match
   -----------------+-----------------------------------------------
          p         | find previous match
   -----------------+-----------------------------------------------
                    |    Switching open files
   -----------------+-----------------------------------------------
   Keyboard / Mouse | Action
   -----------------+-----------------------------------------------
          B         | show list of open files for selection
   -----------------+-----------------------------------------------
        ENTER       | switch to selected file
   -----------------+-----------------------------------------------
          c         | kill (close) active file
   -----------------+-----------------------------------------------
                    |      Toggling options
   -----------------+-----------------------------------------------
   Keyboard / Mouse | Action
   -----------------+-----------------------------------------------
          -c        | toggle  chopping of lines that do not fit the
                    | current width of the screen.
   -----------------+-----------------------------------------------
        <ESC>       |
          -h        | toggle highlighting of search matches
   -----------------+-----------------------------------------------
          -i        | toggle case sensitivity in searches
   -----------------+-----------------------------------------------
          -n        | toggle line numbering
   -----------------+-----------------------------------------------
          -V        | toggle verification of references
   -----------------+-----------------------------------------------
                    |
                    |       03/24/2023                lsp-help(1)
                    |
                    |
                    |
                    |
                    |
                    |
                    |

1.  The vertical rule that should lie between the columns in the "Movement in files" section of the table is missing; and
2.  the vertical rule in the final section of the table is senselessly overdrawn below.

I believe, but am not certain because I haven't proven the fix I have in mind yet, that these both arise from the same underlying issue, that being the trick that groff's man and mdoc macro packages employ to implement "continuous rendering mode".  I observe that if I add the line

.pl 99999v

after the `TH` macro call in either page, both problems go away.

If you'd like to assume I'll get the problem fixed for groff 1.24.0 (and I would), you can add the following workaround after the `TH` line in your production page.

.if \n(.g \{\
.  \" Work around Savannah #65189.
.  if n .do if \n[cR] .do if ((\n[.x] = 1) & (\n[.y] < 24)) .pl 99999v
.\}

What this does is set the page length to 99,999 "vees" or lines...but only if:

1. groff (or an implementation claiming compatibility with it) is the formatter;
2. the formatter is in "_nroff_ mode" (preparing output for a terminal);
3. continuous rendering mode is enabled (the default in _nroff mode, but can be changed); and
4. the version number of groff is less than 1.24.

The foregoing assumes your man page will not grow beyond 100,000 lines.  Let me know if you expect that to be a problem, and I can prescribe something more complicated to achieve the same goal.

Regards,
Branden

[1] I have made the man page artificially narrow for ergonomic purposes in this Savannah ticket.  That in turn provokes a legitimate warning from the document.

lsp-help.1:29: warning: table wider than line length minus indentation

You can ignore this unless you want your page to be portable to nroff output on System V Unix, where the default line length for man pages was 65n (65 characters)--but from what I've seen, that line of tbl development had pretty awful problems with tables on terminal devices anyway.

On GNU/Linux systems, historically a line length of 78n was used--no one ever seemed to document why, but my surmise is that this was a convention developed to work around undocumented/unreported bugs in GNU tbl.  In groff 1.23.0, some of those bugs were fixed and you can use 79n.  In groff 1.24.0, you will be able use the full 80n of quasi-standard terminals.  Of course you can always overset a line on purpose by turning off fill mode and not breaking a long line yourself.  But GNU tbl will warn about overlong table lines.