Re: reference Debian package of multiple binaries sharing one man page

[Norwid Behrnd]

On Mon, 13 Nov 2023 09:41:12 -0800
Russ Allbery  wrote:

> 
> Oh, indeed, you're right and I misread that.  So I think you can just use
> symlinks, period, and not worry about .so (although you have to handle
> nodoc builds correctly).
> 

Well, one file with a list like

```debian/markdownlint.manpages
debian/markdownlint.1
debian/mdl.1
debian/ruby-mdl.1
```

where the first one is the complete manpage, and the later files only contain
two line note of

```debian/mdl.1
.\"relay to markdownlint.1
.so man1/markdownlint.1
```

to indicate the complete manpage in the same folder might be equally acceptable
for a small package.  At least it was both considered good enough by lintian
after compiling the .deb as well as a subsequent local installation now
providing the functionality missed earlier.  Good enough for an upload to
mentors and a RFS.[1]

[1] https://mentors.debian.net/package/ruby-mdl/

Re: reference Debian package of multiple binaries sharing one man page

[Russ Allbery]

Andrey Rakhmatullin  writes:
> On Fri, Nov 10, 2023 at 11:44:06AM -0800, Russ Allbery wrote:

>> The good news is that if you're using debhelper, you don't have to care
>> about how man handles these indirections and can just use a symlink.
>> Install the man page into usr/share/man/man1 under whatever name is
>> canonical (possibly by using dh_installman), and then create a symlink
>> in usr/share/man/man1 from the other man page name to that file.

>> dh_installman will then clean this all up for you and create proper .so
>> links and you don't have to care about the proper syntax.

> Isn't it the other way around? The whole idea of using .so is to tell
> dh_installman(1) to create symlinks.

Oh, indeed, you're right and I misread that.  So I think you can just use
symlinks, period, and not worry about .so (although you have to handle
nodoc builds correctly).

-- 
Russ Allbery (r...@debian.org)  

Re: reference Debian package of multiple binaries sharing one man page

[Andrey Rakhmatullin]

On Fri, Nov 10, 2023 at 11:44:06AM -0800, Russ Allbery wrote:
> The good news is that if you're using debhelper, you don't have to care
> about how man handles these indirections and can just use a symlink.
> Install the man page into usr/share/man/man1 under whatever name is
> canonical (possibly by using dh_installman), and then create a symlink in
> usr/share/man/man1 from the other man page name to that file.
> 
> dh_installman will then clean this all up for you and create proper .so
> links and you don't have to care about the proper syntax.
Isn't it the other way around? The whole idea of using .so is to tell
dh_installman(1) to create symlinks.

Re: reference Debian package of multiple binaries sharing one man page

[Russ Allbery]

Norwid Behrnd  writes:

> 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]

I think the problem is that you put the .so line in the wrong file.  It
should be the entire contents of the file corresponding to the deprecated
binary name, not a line in the file that represents the current binary
name.

The good news is that if you're using debhelper, you don't have to care
about how man handles these indirections and can just use a symlink.
Install the man page into usr/share/man/man1 under whatever name is
canonical (possibly by using dh_installman), and then create a symlink in
usr/share/man/man1 from the other man page name to that file.

dh_installman will then clean this all up for you and create proper .so
links and you don't have to care about the proper syntax.

-- 
Russ Allbery (r...@debian.org)  

Re: reference Debian package of multiple binaries sharing one man page

[Norwid Behrnd]

Hello,

On Sat, 11 Nov 2023 14:08:49 +0100
Alexander Sulfrian  wrote:

> 
> You will need a file mdl.1 with the following content:
> 
> .so man1/markdownlint.1
> 
> and markdownlint.1 should be the normal manpage without a .so line.
> 

This logic provides exactly the relay I sought out.  Thanks a lot, the problem
is resolved fully.

Norwid

Re: reference Debian package of multiple binaries sharing one man page

[Alexander Sulfrian]

Hello,

On Fri, Nov 10, 2023 at 08:20:35PM +0100, Norwid Behrnd wrote:
> 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

I think you missunderstodd the instructions:

> 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

You will need a file mdl.1 with the following content:

.so man1/markdownlint.1

and markdownlint.1 should be the normal manpage without a .so line.


Alex

Re: reference Debian package of multiple binaries sharing one man page

[Xinhui Yang]

Hi,

On 2023/11/11 3:20, Norwid Behrnd wrote:

Hello,

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



Vim is an example of this, if I recalled it right - Vim has multiple 
frontends, there is a CLI one and a GTK one, which is in vim-gtk3 
package. Both frontends has its corresponding manual pages, but they are 
identical.


However, vim(1) is packaged into vim-common, gvim(1) is packaged into 
vim-gui-common. Since one copy of the manual is packages two times 
separately, I don't see any issue like this will come to Vim.


Regards,
Xinhui

Re: reference Debian package of multiple binaries sharing one man page

[Gioele Barabucci]

On 11/11/23 08:12, Tobias Frost wrote:

On Fri, Nov 10, 2023 at 08:20:35PM +0100, Norwid Behrnd wrote:

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


devscripts - it links debchange.1 to dch.1 via debian/links  (dh_link)

$grep -r dch debian/links
/usr/bin/debchange  /usr/bin/dch


Please note that using d/links for manpages breaks building packages 
with , unless dh-exec is used and the manpages links are marked 
with .


Regards,

--
Gioele Barabucci

Re: reference Debian package of multiple binaries sharing one man page

[Tobias Frost]

On Fri, Nov 10, 2023 at 08:20:35PM +0100, Norwid Behrnd wrote:
> Hello,
> 
> I seek a maintained Debian package which provides multiple binaries sharing 
> one
> man page in common -- do you know an example?

devscripts - it links debchange.1 to dch.1 via debian/links  (dh_link)

$grep -r dch debian/links
/usr/bin/debchange  /usr/bin/dch

-- 
tobi

Re: reference Debian package of multiple binaries sharing one man page

[IOhannes m zmölnig]

Am 10. November 2023 20:20:35 MEZ schrieb Norwid Behrnd :
>Hello,
>
>I seek a maintained Debian package which provides multiple binaries sharing one
>man page in common -- do you know an example?
>

faust


mfh.her.fsr
IOhannes

reference Debian package of multiple binaries sharing one man page

[Norwid Behrnd]

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::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