The manpage ipbt(1) in its-playback-time.deb in sid is mangled,
lacking NAME etc.:

https://manpages.debian.org/unstable/its-playback-time/ipbt.1.en.html
https://manpages.debian.org/trixie/its-playback-time/ipbt.1.en.html

This seems to have changed in 104f8226cb00 "Update to state of current
PuTTY code base." which completely redid the build system.

In 104f8226cb00~, upstream build (./autogen.sh, configure, make)
runs
    halibut --man=ipbt.1 ipbt.but
and the output looks right in `man -l ipbt.1`

In 104f8226cb00, upstream build (mkdir obj; cd obj; cmake ..; make VERBOSE=1)
runs
    cd /home/ian/things/Debian/Its-playback-time/its-playback-time/obj/doc && /bin/halibut --man=ipbt.1 /home/ian/things/Debian/Its-playback-time/its-playback-time/doc/mancfg.but /home/ian/things/Debian/Its-playback-time/its-playback-time/doc/man-ipbt.but
and the output looks wrong in `man -l ./doc/ipbt.1`

Simon, do you know what's wrong here?

(This bug was spotted by lintian in Debian QA infrastructure.)

Ian.

Ian Jackson <ijackson@chiark.greenend.org.uk> wrote:

Yes – mancfg.but is the culprit. If you just give Halibut the single
input file man-ipbt.but, it generates a correct man page with headings.
With mancfg.but on the command line too, the headings are discarded,
because mancfg.but contains the Halibut directive \cfg{man-mindepth}{2},
and the \U headings are at depth 1.

mancfg.but comes from the parent PuTTY code base, and its purpose is to
arrange that the PuTTY man pages can appear as subsections of an
appendix in the main manual (where each man page's internal headings are
at depth 2) _and_ be built standalone to go in /usr/share/man. For the
latter, mancfg.but provides a dummy depth-1 chapter heading to make the
depth-2 headings in each man page not cause errors, and a directive to
omit it from the output.

This works for the PuTTY man pages because their internal sections are
defined using the \H directive, which means a second-level heading
within a chapter. The Halibut one uses \U, which is a top-level heading,
because it wasn't written with the same requirement to be part of a
chapter.

I don't exactly recall, but it seems likely that when I last merged
updates from PuTTY into IPBT, I must have tried to make the docs build
more like the PuTTY one, to reduce downstream diff and future merge
conflicts. And since the build didn't _fail_, I probably just failed to
notice that its output was subtly wrong.

An interim fix is to remove mancfg.but from the build command:

diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt
index f4117e71..d721950f 100644
--- a/doc/CMakeLists.txt
+++ b/doc/CMakeLists.txt
@@ -38,10 +38,9 @@ macro(manpage title section)
   if(HALIBUT)
     add_custom_command(OUTPUT ${title}.${section}
       COMMAND ${HALIBUT} --man=${title}.${section}
-        ${CMAKE_CURRENT_SOURCE_DIR}/mancfg.but
         ${CMAKE_CURRENT_SOURCE_DIR}/man-${title}.but
       DEPENDS
-        mancfg.but man-${title}.but)
+        man-${title}.but)
     register_manpage(${title} ${section})
   elseif(EXISTS ${CMAKE_CURRENT_SOURCE_DIR}/${title}.${section})
     # Our tarballs include prebuilt man pages in the source tree, so

But probably a better permanent fix from a "minimal downstream diff"
perspective is to change the heading level in man-ipbt.but so that the
same build command _will_ work the same way between the two projects.
I'll probably do that fix upstream when I get a chance.

Cheers,
Simon

Simon Tatham <simon@tartarus.org> wrote:
[...]
depth 1. Each PuTTY man page has a \H (level 1) heading reading "Man
page for foo", and the internal NAME, SYNOPSIS etc are \S (level 2), so
that the whole lot can be collected under a single level-0 appendix
heading.

I'll update man-ipbt.but to have the same structure, so that it can be
built with the same doc/CMakeLists.txt.
mean this should be done (and I will do it) in _my_ ipbt repository,
i.e. upstream from Debian's POV, but downstream from my POV in the sense
that ipbt is a downstream of PuTTY.

Cheers,
Simon

Thanks for the quick reply and analysis.

Simon Tatham writes ("Bug#1137644: ipbt manpage no longer in proper man format"):

Right.

Given that currently only the ipbt in Debian testing is affected, I am
inclined (with my Debian maintainer hat on) to wait for the upstream
fix, rather than carry a change in Debian testing until it's fixed
upstream.  Doing the latter risks the build system delta persisting
beyond its usefulness.

Please let me know if you disagree.

(By "minimal downstream diff" I think you mean to minimise the delta
between putty and ipbt.)

Ian.

Simon Tatham writes ("Bug#1137644: ipbt manpage no longer in proper man format"):

And:

You presumably need to update man-ipbt-dump.but too?

Ian.

Ian Jackson <ijackson@chiark.greenend.org.uk> wrote:

Yes, good point. Thanks.

Now pushed fdcd2b0ad60f74ffa6a695c992d56c6a3ae20e4a which should fix all
of this.

Cheers,
Simon

Simon Tatham writes ("Bug#1137644: ipbt manpage no longer in proper man format"):

Thanks.

In your commit message:
                                         ^^^^^^^
I think this should have read "IPBT's man page".  (Another occurrence
below.)  It's too late to fix this now obviously.

FTR, I think I would instead have added an affordance to the upstream
PuTTY build systtem to allow use of mancfg.but to be suppressed by a
make variable or environment varisble or something.  But maybe you
don't want to many *any* changes to PuTTY to benefit this weird ipbt
thing.

Anyway, thanks.  I'll merge your fix into the Debian branch.

Ian.

We believe that the bug you reported is fixed in the latest version of
its-playback-time, which is due to be installed in the Debian FTP archive.

A summary of the changes between this version and the previous one is
attached.

Thank you for reporting the bug, which will now be closed.  If you
have further comments please address them to 1137644@bugs.debian.org,
and the maintainer will reopen the bug report if appropriate.

Debian distribution maintenance software
pp.
Ian Jackson <ijackson@chiark.greenend.org.uk> (supplier of updated its-playback-time package)

(This message was generated automatically at their request; if you
believe that there is a problem with it please contact the archive
administrators by mailing ftpmaster@ftp-master.debian.org)
Format: 1.8
Date: Thu, 28 May 2026 22:30:53 +0100
Source: its-playback-time
Architecture: source
Version: 0.2026-05-26.fdcd2b0-1
Distribution: unstable
Urgency: medium
Maintainer: Ian Jackson <ijackson@chiark.greenend.org.uk>
Changed-By: Ian Jackson <ijackson@chiark.greenend.org.uk>
Closes: 1137644
Changes:
 its-playback-time (0.2026-05-26.fdcd2b0-1) unstable; urgency=medium
 .
   * Update to latest upstream.  Closes: #1137644.
Checksums-Sha1:
 0759a2cc6482b44d72b73889162e172a58f683a6 2051 its-playback-time_0.2026-05-26.fdcd2b0-1.dsc
 18f1b4677b0795c9440926779842c3fa84efb19f 266532 its-playback-time_0.2026-05-26.fdcd2b0-1.tar.xz
 6dce1cea5053a97db33501832f241ac642370244 463460 its-playback-time_0.2026-05-26.fdcd2b0-1.git.tar.xz
 da3de85784a860eb22baa5416394f7842b02de1c 17585 its-playback-time_0.2026-05-26.fdcd2b0-1_source.buildinfo
Checksums-Sha256:
 414d41b050035f1351ae9878ca86f59e4fed78fe2ffcd023de573a30151a691d 2051 its-playback-time_0.2026-05-26.fdcd2b0-1.dsc
 a541fda49573ef0702d486d8f7812920656b437f9aa60706285374234ebc6861 266532 its-playback-time_0.2026-05-26.fdcd2b0-1.tar.xz
 18b4d12409ecfa927775bbcb2e046b506925662d7da2dd380e3b8b40dce6b944 463460 its-playback-time_0.2026-05-26.fdcd2b0-1.git.tar.xz
 7bd8f20266e05af7d590b7c154fd0fa415e13896ef53b3c665c2411bdff40d2f 17585 its-playback-time_0.2026-05-26.fdcd2b0-1_source.buildinfo
Files:
 11a95308d3a88d346190c5e95e2bbf5b 2051 misc optional its-playback-time_0.2026-05-26.fdcd2b0-1.dsc
 af16cf2692ed37d18fe5a2c94f1fc3c6 266532 misc optional its-playback-time_0.2026-05-26.fdcd2b0-1.tar.xz
 ba3f71676b0264264b401ecffafc8803 463460 misc None its-playback-time_0.2026-05-26.fdcd2b0-1.git.tar.xz
 b6a70d135576f640c9bd84447a5811ff 17585 misc optional its-playback-time_0.2026-05-26.fdcd2b0-1_source.buildinfo
Git-Tag-Info: tag=db3ba6fbba52f74250f111708a2612b9ad96ca98 fp=41638114d132883b25a20ddd47515757d8002456
Git-Tag-Tagger: Ian Jackson <iwj@xenproject.org>
-----BEGIN PGP SIGNATURE-----

iQIzBAEBCgAdFiEEN02M5NuW6cvUwJcqYG0ITkaDwHkFAmoYuA0ACgkQYG0ITkaD
wHmRFhAAzNs+J/Ja4lPAHCfip5LT3nbWkIy6ARh2XhDxxVbeIMmblyW2ks8Krlo7
gbxJ+zxltusOyrgsgsM3x2aEAUPUS/cDgqSZZy6FY7DLhrMI8iyYU3UpYyckljJI
Zi228A2F53D7SJElQuKd+MMAzYBXPQUCkz8TdmZPL2/AfPjAX6nw7MSa/huDE1vf
KzG0prfezLvM2rbicnCHUW6ud9pslk+o1zMhg2NYa/G5tVaXykJvmwdDxJgFMgfE
TDXh6OvE2eC0lUNNy5QTHp2zKm80CPbiD32ieoxVP2w9Vw+o0smPt+ztWP0AvwyA
hav+GPak/Q/hbDK06BIdfFsRtEEKMIl3oJw7ijlQeMbyd7ahvzLXEj5B0dxsSMTo
myuISTTBOsy2/1tamHCvi3moyySmq/gcJ3ZQwd24u65VkY2cLA/q9OUARwxQFL7M
RWu49E4TwmpAqtrSIonZJ2EU1kI6ucO8j8gCG2X0HqB9H0UMz9QAWbhOrbxxiQWo
Xnq6GfF9c76mZ0CVzfA+SjxqdTYLHTD8Onhjto/6GuvWhtmoZ+nh+aoswlCWAeu9
ODo3gHo8BAaROCRX7MYPIDomURAuQfGTtoLcSIBykNamfo3t0YWGKtPXStqeZOj9
cv7JvIGSxviEULYBeRxe/dRSun/nCSwmvg/uOffon/iiM3dvpto=
=yn2h
-----END PGP SIGNATURE-----