• 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)
  • From Kamil Ignacak@21:1/5 to guillem@debian.org on Sun Jun 15 19:50:01 2025
    This is a multi-part message in MIME format.
    Control: reopen 1072354
    Control: tags 1072354 patch
    Control: retitle 1072354 apt: man page title limit exceeded for apt-transport-https/mirror


    On Tue, 10 Jun 2025 23:39:32 +0200 Guillem Jover <guillem@debian.org> wrote:
    But this is not an inevitable truncation, docbook could be told to
    leave more room before truncation.

    You are right, I have overlooked this.

    I'm attaching a patch (1072354.patch) that increases the value of
    relevant xsltproc parameter. The new value will lead to not truncating
    of title in apt-transport-https, and in apt-transport-mirror.

    and I think it can also mess
    with the apropos scanning (?).

    This doesn't seem to be the case. It looks like apropos matches searched substrings in something other than a title:

    acerion@debian:~$ apropos apt-transport-http
    apt-transport-http (1) - APT transport for downloading via the Hypertext Transfer Protocol (HTTP)
    apt-transport-https (1) - APT transport for downloading via the HTTP Secure protocol (HTTPS)
    acerion@debian:~$ apropos apt-transport-https
    apt-transport-https (1) - APT transport for downloading via the HTTP Secure protocol (HTTPS)

    Kamil
    ZGlmZiAtLWdpdCBhL0NNYWtlL0RvY3VtZW50YXRpb24uY21ha2UgYi9DTWFrZS9Eb2N1bWVu dGF0aW9uLmNtYWtlCmluZGV4IGQ3ZjEzNjAyMC4uYzBmMGFlN2E2IDEwMDY0NAotLS0gYS9D TWFrZS9Eb2N1bWVudGF0aW9uLmNtYWtlCisrKyBiL0NNYWtlL0RvY3VtZW50YXRpb24uY21h a2UKQEAgLTE0MCw2ICsxNDAsNyBAQCBmdW5jdGlvbih4c2x0cHJvY19vbmUpCiAgICAgICAg IC0teGluY2x1ZGUKICAgICAgICAgLS1zdHJpbmdwYXJhbSBjaHVuay5xdWlldGx5IHllcwog ICAgICAgICAtLXN0cmluZ3BhcmFtIG1hbi5vdXRwdXQucXVpZXRseSB5ZXMKKyAgICAgICAg LS1wYXJhbSBtYW4udGgudGl0bGUubWF4Lmxlbmd0aCAyMgogICAgICAgICAtLXBhdGggJHtQ Uk9KRUNUX1NPVVJDRV9ESVJ9L3ZlbmRvci8ke0NVUlJFTlRfVkVORE9SfS8KICAgICAgICAg LS1wYXRoICR7Q01BS0VfQ1VSUkVOVF9TT1VSQ0VfRElSfS8KICAgICApCg==

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