Bug#1072354: Manpage copied without updating title

[Guillem Jover <guillem@debian.org>]

Hi!

On Sun, 2025-05-04 at 20:25:19 +0200, Kamil Ignacak wrote:
> > APT-TRANSPORT-HTTP(1)                 APT                APT-TRANSPORT-HTTP(1)
> >                   ^========================== "S" forgotten ===============^
> 
> The source code for the man page in 2.6.1 is here:
> https://salsa.debian.org/apt-team/apt/-/blob/2.6.1/doc/apt-transport-https.1.xml?ref_type=tags
> As you can see, the name of the component (apt-transport-https) is
> present in a non-truncated form throughout document.
> 
> The name of the component, seen in a header of man page, is taken from
> this tag in the document (line 20 of xml):
> <refentrytitle>apt-transport-https</refentrytitle>
> 
> The source file is in DocBook format. The available reference suggests
> that maximal length of a title (TH tag in roff markup language) is 20
> chars:
>  - https://cdn.docbook.org/release/xsl/snapshot/doc/manpages/man.th.title.max.length
>  - /usr/share/xml/docbook/stylesheet/docbook-xsl/manpages/param.xsl -> man.th.title.max.length
> 
> Count of chars in "APT\-TRANSPORT\-HTTPS" (the escape chars are
> necessary in roff document) is 21, which is truncated to 20 chars, and
> the ending "S" letter is lost.
> 
> To sum up: this issue is a result of inevitable truncation, not a result
> of a mistake during copying of files.

But this is not an inevitable truncation, docbook could be told to
leave more room before truncation. The link you provide even states as
much:

  The default value is reasonable but somewhat arbitrary. If you have
  pages with long titles, you may want to experiment with changing the
  value in order to achieve the correct aesthetic results.

Having a truncated title is confusing, and I think it can also mess
with the apropos scanning (?).

Thanks,
Guillem