reference Debian package of multiple binaries sharing one man page

[Norwid Behrnd <nbehrnd@yahoo.com>]

Hello,

I seek a maintained Debian package which provides multiple binaries sharing one
man page in common -- do you know an example?

Recently, I started to upgrade the Debian package about `markdownlint`,[1] a
syntax checker.  The initially packaged version 0.12.0 provided a binary of
name `ruby-mdl` which now becomes a transition dummy package in favour of the
functionally updated `markdownlint`.

I wonder how to properly prepare an adjusted man page for both binaries, because
lintian warns about the absence for `usr/bin/mdl`.[2]  After passing section
12.1 of the Debian Policy Manual, Jens Schweikhart's manual[3] appeared suitable
here because of the following section 4:

---8>< ---
Here is how to do it: If you want to have your man page available under the
names `foo' and `bar' in section 1, then put the man page in foo.1 and have
bar.1 look like this:

.so man1/foo.1

It is important to specify the man1/ directory part as well as the file name
`foo.1' because when groff is run by the browser it will have the manual base
directory as its current working directory (cwd) and groff interprets .so
arguments relative to the cwd.
---8>< ---

However, there still is some detail I did not understand well enough; the
additional line

```
.so man1/mdl.1
```

in my file `/debian/markdownlint.1`[4] and followed by the call of

```shell
sbuild -A -d unstable --source
```

yields for example the following warning

```shell
...
Processing triggers for libc-bin (2.37-12) ...
Running lintian...
W: markdownlint: groff-message -:7: warning: failed .so request [usr/share/man/man1/markdownlint.1.gz:2]
W: markdownlint: groff-message can't open man1/mdl.1: No such file or directory [usr/share/man/man1/markdownlint.1.gz:1]
W: markdownlint: groff-message troff:<standard input>:7: error: can't open 'man1/mdl.1': No such file or directory [usr/share/man/man1/markdownlint.1.gz:3]
W: markdownlint: no-manual-page [usr/bin/mdl]

I: Lintian run was successful.

+------------------------------------------------------------------------------+
| Post Build                                                                   |
+------------------------------------------------------------------------------+

...
```

Regards,

Norwid

[1] https://tracker.debian.org/pkg/ruby-mdl
[2] https://udd.debian.org/lintian/?packages=ruby-mdl
[3] http://www.schweikhardt.net/man_page_howto.html#q4
[4] https://salsa.debian.org/nbehrnd/markdownlint_test/-/blob/master/debian/markdownlint.1