Bug 274343 - man(1) fails to render manpages that work correctly both with gnroff and mdocml
Summary: man(1) fails to render manpages that work correctly both with gnroff and mdocml
Status: Open
Alias: None
Product: Documentation
Classification: Unclassified
Component: Manual Pages (show other bugs)
Version: Latest
Hardware: Any Any
: --- Affects Some People
Assignee: freebsd-bugs (Nobody)
URL:
Keywords:
Depends on:
Blocks: 273903
  Show dependency treegraph
 
Reported: 2023-10-07 20:44 UTC by mirabilos
Modified: 2023-12-28 15:42 UTC (History)
2 users (show)

See Also:


Attachments

Note You need to log in before you can comment on or make changes to this bug.
Description mirabilos 2023-10-07 20:44:04 UTC
Hi again,

still the ports/shells/mksh upstream with bugreports directed my way by my users.

The user is on 13.2-RELEASE and reports that the mksh(1) manpage does not display correctly:

  $ man mksh | head -5

  is  a command interpreter intended for both interactive and shell
  script use.  Its command language is a superset of the shell lan-
  guage and largely compatible to  the  original  Korn  shell.   At
  times, this manual page may give scripting advice; while it some-

However, invoking not only GNU groff directly (I told him to use “nroff -mdoc -c mksh.1 | less”) works, but it also works if he invokes mdocml directly:

$ mandoc mksh.1 | head -10
MKSH(1)                 FreeBSD General Commands Manual                MKSH(1)

NAME
     mksh, sh – MirBSD Korn shell

SYNOPSIS
     mksh [-+abCefhiklmnprUuvXx] [-T [!]tty | -] [-+o option] [-c string |
          -s | file [argument ...]]
     builtin-name [argument ...]
[…]

I *was* suspecting the mdocml version at first because older mdocml releases failed to render manpages with *roff commands/macros in them at all, but that has been fixed at some point, and apparently, he’s carrying a version that does.

At this point, and without access to a FreeBSD system myself, my triage ends and I have to defer to whomever maintains the man/groff/mdocml subsystems at your site.
Comment 1 Graham Perrin 2023-10-07 21:39:27 UTC
Tentatively: blocked by bug 273903.
Comment 2 mirabilos 2023-10-07 22:42:13 UTC
Hmm, I don’t follow.

On a Debian system (unstable/sid chroot) with GNU groff 1.23 the manpage *also* renders okay, even with -mandoc:

$ nroff -c -mandoc mksh.1 | head -10
MKSH(1)                     General Commands Manual                    MKSH(1)

NAME
       mksh, sh — MirBSD Korn shell

SYNOPSIS
       mksh  [-+abCefhiklmnprUuvXx]  [-T [!]tty | -] [-+o option] [-c string |
            -s | file [argument ...]]
       builtin‐name [argument ...]

So it’s not a GNU groff issue.
Comment 3 G. Branden Robinson 2023-12-24 05:56:50 UTC
I can reproduce the problem on my Debian system with the following.

$ zcat /usr/share/man/man1/mksh.1.gz | groff -man -Tutf8 | head

is  a command interpreter intended for both interactive and shell
script use.  Its command language is a superset of the shell lan‐
guage and largely compatible to  the  original  Korn  shell.   At
times, this manual page may give scripting advice; while it some‐
times  does  take  portable  shell scripting or various standards
into account all information is first and foremost presented with
in mind and should be taken  as  such.   Please  refer  to:  Most
builtins  can  be  called  directly, for example if a link points
from its name to the shell; not all make sense, have been  tested

In other words, all I had to do was say "-man" instead of "-mandoc".

That would make this a duplicate of bug #273245 (and bug #273565).
Comment 4 mirabilos 2023-12-24 17:06:29 UTC
(In reply to G. Branden Robinson from comment #3)

No, that’s wrong.

For normal manpages, you *must* use -mandoc because you can’t know ahead of time whether they want -man or -mdoc (-mandoc is a “switch”: it checks from the first macro the manpage calls whether it’s a -man or a -mdoc page and loads the correct one).
Comment 5 G. Branden Robinson 2023-12-24 17:15:25 UTC
You're saying the same thing I am.

I described how I was able to reproduce the problem--by using the "wrong" macro package selection.

Please see comment #3 in bug #273245.

Also, I am familiar with the operation of andoc.tmac.

https://git.savannah.gnu.org/cgit/groff.git/log/tmac/andoc.tmac