• Bug#1072354: Manpage copied without updating title

    From Kamil Ignacak@21:1/5 to All on Sun May 4 20:30:01 2025
    Hi!

    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.

    Kamil

    --- SoupGate-Win32 v1.05
    * Origin: fsxNet Usenet Gateway (21:1/5)
  • From Guillem Jover@21:1/5 to Kamil Ignacak on Tue Jun 10 23:50:01 2025
    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

    --- SoupGate-Win32 v1.05
    * Origin: fsxNet Usenet Gateway (21:1/5)