• Removing manpages from libpam-modules to improve multi-arch

    From Sam Hartman@21:1/5 to All on Wed Jan 15 17:50:01 2025
    TL;DR: I propose move man pages out of a multi-arch: same package into a
    arch all package. Asking for any downsides and usrmerge review.

    I'm in the process of packaging pam 1.7.0. Upstream has moved from
    autotools to meson and in the process has streamlined their release
    tarballs to remove all or almost all build artifacts such as generated
    man pages.

    Today, we include man pages for all the pam modules in libpam-modules. Libpam-modules is multi-arch: Same, so all these man pages need to be bit-for-bit identical across all architectures.
    Originally that was easy: we just included unmodified upstream man
    pages.
    But various Debian patches change the man pages.
    For a while we just built the man pages but if any of the docbook tools
    changed between one arch build and another, we'd end up with m-a
    uninstallable packages.

    So, we ended up including patches to the man pages as well as their
    source.
    This was a real pain to maintain under the old build system, but it's
    even more annoying now.

    My proposal is to move the man pages into libpam-doc.
    I'm not actually convinced that normal Debian users need man pages for
    all the pam modules on all Debian systems, and a suggests relationship
    should be sufficient.
    If people really want to maintain the current level of man page
    presence, we could move the manpages into libpam-modules-bin which is
    M-A: foreign.

    I think there are no usrmerge implications. While libpam-modules did
    move files from /lib/multiarch_tripple/security to /usr/lib/multiarch_tripple/security, the man pages have always been in /usr/share/man, which lives on /usr.

    Thoughts on this proposed action?

    -----BEGIN PGP SIGNATURE-----

    iHUEARYIAB0WIQSj2jRwbAdKzGY/4uAsbEw8qDeGdAUCZ4fluAAKCRAsbEw8qDeG dIzhAQDYM3wHwugUZdB2wlAOsBhM9KnpTwlT6TriqZNL9hbX7wEAs5ewcWHZ6lZQ 1MQNamYxDJ2e6KxEca6YPhxBsPYftgw=
    =jyZi
    -----END PGP SIGNATURE-----

    --- SoupGate-Win32 v1.05
    * Origin: fsxNet Usenet Gateway (21:1/5)
  • From Marvin Renich@21:1/5 to All on Wed Jan 15 19:30:01 2025
    * Sam Hartman <hartmans@debian.org> [250115 11:44]:

    TL;DR: I propose move man pages out of a multi-arch: same package into a
    arch all package. Asking for any downsides and usrmerge review.

    My proposal is to move the man pages into libpam-doc.
    I'm not actually convinced that normal Debian users need man pages for
    all the pam modules on all Debian systems, and a suggests relationship
    should be sufficient.
    If people really want to maintain the current level of man page
    presence, we could move the manpages into libpam-modules-bin which is
    M-A: foreign.

    I have on a number of occasions used these man pages, and having them
    installed locally is very helpful. I would rather have the man pages
    installed without the additional documentation in libpam-doc. Why not
    (other than a trip through NEW) put them in a new binary package libpam-manpages (arch:all)? I would prefer recommends rather than
    suggests.

    ...Marvin

    --- SoupGate-Win32 v1.05
    * Origin: fsxNet Usenet Gateway (21:1/5)
  • From Sam Hartman@21:1/5 to All on Wed Jan 15 20:50:01 2025
    "Marvin" == Marvin Renich <mrvn@renich.org> writes:


    Marvin> I have on a number of occasions used these man pages, and
    Marvin> having them installed locally is very helpful. I would
    Marvin> rather have the man pages installed without the additional
    Marvin> documentation in libpam-doc. Why not (other than a trip
    Marvin> through NEW) put them in a new binary package
    Marvin> libpam-manpages (arch:all)? I would prefer recommends
    Marvin> rather than suggests.

    Do you actually have a system on which you want these man pages and on
    which the extra space of libpam-doc would be a problem?

    Unless there's a compelling need, my answer is that I don't understand
    why manpages should be separated from other documentation in this instance.

    --Sam

    --- SoupGate-Win32 v1.05
    * Origin: fsxNet Usenet Gateway (21:1/5)
  • From Russ Allbery@21:1/5 to Sam Hartman on Wed Jan 15 22:20:01 2025
    Sam Hartman <hartmans@debian.org> writes:

    My proposal is to move the man pages into libpam-doc. I'm not actually convinced that normal Debian users need man pages for all the pam
    modules on all Debian systems, and a suggests relationship should be sufficient. If people really want to maintain the current level of man
    page presence, we could move the manpages into libpam-modules-bin which
    is M-A: foreign.

    I am in favor of moving the man pages out of the multiarch library package
    and into either libpam-doc or libpam-modules-bin. I don't have any strong opinions between that choice of packages.

    Putting anything other than the minimum required and ideally all multiarch-aware files into the packages intended to be coinstalled in a multiarch situation is asking for trouble, IMO. Those packages should be
    as minimal as possible to deliver their functionality, for exactly the
    reasons you describe.

    --
    Russ Allbery (rra@debian.org) <https://www.eyrie.org/~eagle/>

    --- SoupGate-Win32 v1.05
    * Origin: fsxNet Usenet Gateway (21:1/5)
  • From Sam Hartman@21:1/5 to All on Wed Jan 15 22:20:01 2025
    "G" == G Branden Robinson <g.branden.robinson@gmail.com> writes:

    G> At 2025-01-15T12:45:22-0700, Sam Hartman wrote:
    Marvin> I have on a number of occasions used these man pages, and
    Marvin> having them installed locally is very helpful. I would
    Marvin> rather have the man pages installed without the additional
    Marvin> documentation in libpam-doc. Why not (other than a trip
    Marvin> through NEW) put them in a new binary package
    Marvin> libpam-manpages (arch:all)? I would prefer recommends
    Marvin> rather than suggests.
    >>
    >> Do you actually have a system on which you want these man pages
    >> and on which the extra space of libpam-doc would be a problem?
    >>
    >> Unless there's a compelling need, my answer is that I don't
    >> understand why manpages should be separated from other
    >> documentation in this instance.

    G> Don't we have dpkg filters for this sort of use case?

    I honestly can't tell from your message which position you are
    supporting, which I do find somewhat frustrating when I'm trying to get feedback to make a change.

    I think that yes, because we have dpkg filters, there's not a compelling argument to separate the man pages from the rest of the docs.

    I think that given the multi-arch issues it still makes sense to
    separate the man pages from the m-a: same binaries.
    Were it not for multi-arch, I could see an argument that dpkg filters
    were sufficient and the man pages could stay in libpam-modules.
    But I could also see an argument for minimizing the essential set even
    if someone does not use dpkg filters.

    --- SoupGate-Win32 v1.05
    * Origin: fsxNet Usenet Gateway (21:1/5)
  • From Simon Richter@21:1/5 to Sam Hartman on Thu Jan 16 05:20:01 2025
    Hi,

    On 1/16/25 01:43, Sam Hartman wrote:

    For a while we just built the man pages but if any of the docbook tools changed between one arch build and another, we'd end up with m-a uninstallable packages.

    Can this be fixed by removing the "Generator:" comment in the generated manpage, and possibly clamping the included date to SOURCE_DATE_EPOCH?

    Simon

    --- SoupGate-Win32 v1.05
    * Origin: fsxNet Usenet Gateway (21:1/5)
  • From Russ Allbery@21:1/5 to Simon Richter on Thu Jan 16 05:30:01 2025
    Simon Richter <sjr@debian.org> writes:
    On 1/16/25 01:43, Sam Hartman wrote:

    For a while we just built the man pages but if any of the docbook tools
    changed between one arch build and another, we'd end up with m-a
    uninstallable packages.

    Can this be fixed by removing the "Generator:" comment in the generated manpage, and possibly clamping the included date to SOURCE_DATE_EPOCH?

    There are various things one can do to try to make the output of a man
    page generator like that more consistent, but they don't fix the problem,
    just reduce its frequency, unless Debian sets up to do a fully
    reproducible build with pinned versions of everything (which I don't think
    we want to do).

    Otherwise, the problem is that the documentation generation tools may have changed versions, and therefore changed output in a way that's not really avoidable, between the time the source package was uploaded and built and
    the time a binNMU was scheduled for one of the architectures.

    --
    Russ Allbery (rra@debian.org) <https://www.eyrie.org/~eagle/>

    --- SoupGate-Win32 v1.05
    * Origin: fsxNet Usenet Gateway (21:1/5)
  • From Simon Richter@21:1/5 to Russ Allbery on Thu Jan 16 08:20:01 2025
    Hi,

    On 1/16/25 13:22, Russ Allbery wrote:

    There are various things one can do to try to make the output of a man
    page generator like that more consistent, but they don't fix the problem, just reduce its frequency, unless Debian sets up to do a fully
    reproducible build with pinned versions of everything (which I don't think
    we want to do).

    Agreed, it's not a complete fix, but I'd expect the frequency of changes
    in the output besides the version number to be low enough for this to be
    the least-effort solution.

    If it means we need to trigger a rebuild of a few packages every few
    years, then this thread has already used more time.

    Simon

    --- SoupGate-Win32 v1.05
    * Origin: fsxNet Usenet Gateway (21:1/5)
  • From Helmut Grohne@21:1/5 to Sam Hartman on Thu Jan 16 11:00:01 2025
    Hi Sam,

    On Wed, Jan 15, 2025 at 09:43:36AM -0700, Sam Hartman wrote:
    My proposal is to move the man pages into libpam-doc.
    I'm not actually convinced that normal Debian users need man pages for
    all the pam modules on all Debian systems, and a suggests relationship
    should be sufficient.

    I've actually used those pages more than once and appreciated their
    presence by default, but I also appreciate the ability to not install
    them. Sounds like I'll end up installing libpam-doc where I need them.

    From a package building pov, I'd appreciate if you could also move the
    tools for building the manual pages to Build-Depends-Indep while you
    move them.

    I think there are no usrmerge implications. While libpam-modules did
    move files from /lib/multiarch_tripple/security to /usr/lib/multiarch_tripple/security, the man pages have always been in /usr/share/man, which lives on /usr.

    I confirm. Their presence inside the /usr/share hierarchy makes them
    fully independent of any /usr-merge or /usr-move concerns.

    Helmut

    --- SoupGate-Win32 v1.05
    * Origin: fsxNet Usenet Gateway (21:1/5)
  • From =?UTF-8?B?QsOhbGludCBSw6ljemV5?=@21:1/5 to Simon Richter on Thu Jan 16 13:40:02 2025
    Hi,

    On 2025. Jan 16., Thu at 8:17, Simon Richter <sjr@debian.org> wrote:

    Hi,

    On 1/16/25 13:22, Russ Allbery wrote:

    There are various things one can do to try to make the output of a man
    page generator like that more consistent, but they don't fix the problem, just reduce its frequency, unless Debian sets up to do a fully
    reproducible build with pinned versions of everything (which I don't
    think
    we want to do).

    Agreed, it's not a complete fix, but I'd expect the frequency of changes
    in the output besides the version number to be low enough for this to be
    the least-effort solution.

    If it means we need to trigger a rebuild of a few packages every few
    years, then this thread has already used more time.


    I agree. It is very easy to detect file differences between multiarch
    packages and scheduling binNMUs.

    Since the described problem potentially affects all packages shipping man
    pages with the binaries - which is the best practice - splitting man pages
    from a single package to solve that particular problem sounds misdirected effort.

    Cheers,
    Balint



    Simon



    <div><div dir="auto">Hi,</div><div><br><div class="gmail_quote"></div></div></div><div><div dir="ltr" class="gmail_attr">On 2025. Jan 16., Thu at 8:17, Simon Richter &lt;<a href="mailto:sjr@debian.org" target="_blank">sjr@debian.org</a>&gt; wrote:<br></
    <blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-style:solid;padding-left:1ex;border-left-color:rgb(204,204,204)">Hi,<br>

    On 1/16/25 13:22, Russ Allbery wrote:<br>

    &gt; There are various things one can do to try to make the output of a man<br> &gt; page generator like that more consistent, but they don&#39;t fix the problem,<br>
    &gt; just reduce its frequency, unless Debian sets up to do a fully<br>
    &gt; reproducible build with pinned versions of everything (which I don&#39;t think<br>
    &gt; we want to do).<br>

    Agreed, it&#39;s not a complete fix, but I&#39;d expect the frequency of changes <br>
    in the output besides the version number to be low enough for this to be <br> the least-effort solution.<br>

    If it means we need to trigger a rebuild of a few packages every few <br> years, then this thread has already used more time.</blockquote><div dir="auto"><br></div></div><div><div dir="auto">I agree. It is very easy to detect file differences between multiarch packages and scheduling binNMUs.</div><div dir="auto"><br></div><
    div dir="auto">Since the described problem potentially affects all packages shipping man pages with the binaries - which is the best practice - splitting man pages from a single package to solve that particular problem sounds misdirected effort.</div><
    div dir="auto"><br></div><div dir="auto">Cheers,</div><div dir="auto">Balint</div><div dir="auto"><br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-style:solid;padding-left:1ex;border-left-color:
    rgb(204,204,204)" dir="auto"><br>

        Simon<br>

    </blockquote>
    </div>

    --- SoupGate-Win32 v1.05
    * Origin: fsxNet Usenet Gateway (21:1/5)
  • From Guillem Jover@21:1/5 to Sam Hartman on Thu Jan 16 13:40:02 2025
    Hi!

    On Wed, 2025-01-15 at 09:43:36 -0700, Sam Hartman wrote:
    My proposal is to move the man pages into libpam-doc.
    I'm not actually convinced that normal Debian users need man pages for
    all the pam modules on all Debian systems, and a suggests relationship
    should be sufficient.
    If people really want to maintain the current level of man page
    presence, we could move the manpages into libpam-modules-bin which is
    M-A: foreign.

    ISTM that moving them to libpam-modules-bin would be the better
    path forward, as it would not regress with missing man pages. I
    think having no man pages by default when installing programs,
    config or other such content, that previously had them would be
    rather unexpected (I certainly miss them when packages have no man
    pages at all or even provide no man pages by default). I don't think
    size should be considered an issue here given that the man pages were
    already shipped (and we expect them to be installed as per policy),
    and as mentioned in the thread people can filter them out if desired.

    (Perhaps if you are shuffling files around you could also consider
    whether moving /etc/security and /usr/share/pam-configs into
    libpam-modules-bin as well also makes sense, to avoid potentially
    weird semantics with refcounted conffiles and M-A:same? Not a blocker
    though, just a thought, while checking the contents.)

    Thanks,
    Guillem

    --- SoupGate-Win32 v1.05
    * Origin: fsxNet Usenet Gateway (21:1/5)
  • From Marvin Renich@21:1/5 to All on Thu Jan 16 14:40:02 2025
    [Please don't CC me]

    * Sam Hartman <hartmans@debian.org> [250115 14:45]:
    Do you actually have a system on which you want these man pages and on
    which the extra space of libpam-doc would be a problem?

    No.

    Unless there's a compelling need, my answer is that I don't understand
    why manpages should be separated from other documentation in this instance.

    I have a strong aversion to the mantras "disk space is cheap", "memory
    is cheap", "network bandwidth is cheap", or any other denigration of
    seemingly abundant resources. They are the enemy of good programming principles.

    In this particular case, I don't think putting the man pages in with the
    other docs is a problem. But if every package did this, the bloat would
    be significant. I think it sets a bad precedent.

    My original message was really responding to:

    * Sam Hartman <hartmans@debian.org> [250115 11:44]:
    I'm not actually convinced that normal Debian users need man pages for
    all the pam modules on all Debian systems, and a suggests relationship
    should be sufficient.

    I think you underestimate the amount these man pages are used and their
    value.

    The suggestion to create a new libpam-manpages was really just one way
    to keep the status quo without bringing in the additional doc'n. With a Recommends relationship, it would allow installing libpam-modules
    without the man pages, if desired, but would include them by default
    (except where the user had opted out of installing Recommends by
    default).

    I am fine with putting the man pages in with libpam-modules-bin.

    ...Marvin

    --- SoupGate-Win32 v1.05
    * Origin: fsxNet Usenet Gateway (21:1/5)
  • From Sam Hartman@21:1/5 to All on Thu Jan 16 17:50:02 2025
    "Guillem" == Guillem Jover <guillem@debian.org> writes:

    Guillem> Hi!
    Guillem> On Wed, 2025-01-15 at 09:43:36 -0700, Sam Hartman wrote:
    >> My proposal is to move the man pages into libpam-doc. I'm not
    >> actually convinced that normal Debian users need man pages for
    >> all the pam modules on all Debian systems, and a suggests
    >> relationship should be sufficient. If people really want to
    >> maintain the current level of man page presence, we could move
    >> the manpages into libpam-modules-bin which is M-A: foreign.

    Guillem> ISTM that moving them to libpam-modules-bin would be the
    Guillem> better path forward, as it would not regress with missing
    Guillem> man pages. I think having no man pages by default when
    Guillem> installing programs, config or other such content, that
    Guillem> previously had them would be rather unexpected (I certainly
    Guillem> miss them when packages have no man pages at all or even
    Guillem> provide no man pages by default). I don't think size should
    Guillem> be considered an issue here given that the man pages were
    Guillem> already shipped (and we expect them to be installed as per
    Guillem> policy), and as mentioned in the thread people can filter
    Guillem> them out if desired.

    Helmut has argued for moving the docs into arch: all packages to
    hopefully be able to reduce arch all build dependencies.
    That sounds like a good argument to me.
    (We'd also need to do something about libpam0g-dev man pages).

    Guillem> (Perhaps if you are shuffling files around you could also
    Guillem> consider whether moving /etc/security and
    Guillem> /usr/share/pam-configs into libpam-modules-bin as well also
    Guillem> makes sense, to avoid potentially weird semantics with
    Guillem> refcounted conffiles and M-A:same? Not a blocker though,
    Guillem> just a thought, while checking the contents.)

    Will moving conffiles around like /etc/security just work even if they
    are modified, or will that trigger a bunch of what to do about modified conffile at install time warnings?

    -----BEGIN PGP SIGNATURE-----

    iHUEARYIAB0WIQSj2jRwbAdKzGY/4uAsbEw8qDeGdAUCZ4k2zwAKCRAsbEw8qDeG dAuXAQCpXOO3ET9TmdfF5kue/EKc8Xe8gcISIalLEGu6/RbjDwD9GVsulnDi6cyI Tou0fWP1xk829axYdQ+eNG7l98dF8wA=
    =OUYK
    -----END PGP SIGNATURE-----

    --- SoupGate-Win32 v1.05
    * Origin: fsxNet Usenet Gateway (21:1/5)
  • From Simon McVittie@21:1/5 to Sam Hartman on Thu Jan 16 18:40:01 2025
    On Thu, 16 Jan 2025 at 09:41:51 -0700, Sam Hartman wrote:
    (We'd also need to do something about libpam0g-dev man pages).

    Moving user-facing documentation from libpam0g into either
    libpam-modules-bin or libpam-doc (depending how often you expect users to
    need it), and developer documentation from libpam0g-dev into libpam-doc,
    seems like it would make sense to me?

    API reference material for C libraries is often in a -doc package, whether
    its format is HTML, PDF or man pages.

    smcv

    --- SoupGate-Win32 v1.05
    * Origin: fsxNet Usenet Gateway (21:1/5)
  • From Russ Allbery@21:1/5 to balint@balintreczey.hu on Thu Jan 16 19:50:01 2025
    Bálint Réczey <balint@balintreczey.hu> writes:
    On 2025. Jan 16., Thu at 8:17, Simon Richter <sjr@debian.org> wrote:

    Agreed, it's not a complete fix, but I'd expect the frequency of
    changes in the output besides the version number to be low enough for
    this to be the least-effort solution.

    If it means we need to trigger a rebuild of a few packages every few
    years, then this thread has already used more time.

    I agree. It is very easy to detect file differences between multiarch packages and scheduling binNMUs.

    Since the described problem potentially affects all packages shipping
    man pages with the binaries - which is the best practice - splitting man pages from a single package to solve that particular problem sounds misdirected effort.

    Hm, I would say that the energy put into finding workarounds for varying content in multiarch packages and scheduling binNMUs would be the more
    wasted effort in the long run. I would advise every multiarch package
    shipping man pages to move them into a separate package, which is a
    one-time fix that makes the problem go away for that package.

    To me, this is an extension of the long-standing advice that every shared library should be isolated in its own package and not include other files.
    It's for a somewhat similar reason, too: for shared libraries, this is to
    avoid conflicts on SONAME bumps, and in this case, it's to avoid conflicts
    on binNMUs.

    There has never been a best-practice requirement that the man pages be in
    the same binary package, only that they be installed when the package is installed, so putting them in a dependency has always been fine. I think
    the concern here may just be that the effective dependency on libpam-doc
    is Suggests and people would rather it be something stronger. That's an argument for putting them in libpam-runtime, even though it's not a
    perfect semantic fit, because that package is Priority: required.

    --
    Russ Allbery (rra@debian.org) <https://www.eyrie.org/~eagle/>

    --- SoupGate-Win32 v1.05
    * Origin: fsxNet Usenet Gateway (21:1/5)
  • From Sam Hartman@21:1/5 to All on Thu Jan 16 20:30:01 2025
    "Simon" == Simon Richter <sjr@debian.org> writes:

    Simon> Hi,
    Simon> On 1/16/25 01:43, Sam Hartman wrote:

    >> For a while we just built the man pages but if any of the docbook
    >> tools changed between one arch build and another, we'd end up
    >> with m-a uninstallable packages.

    Simon> Can this be fixed by removing the "Generator:" comment in the
    Simon> generated manpage, and possibly clamping the included date to
    Simon> SOURCE_DATE_EPOCH?

    Patches welcome for clamping the included date if that's not already
    being done by something.
    I agree with Russ that I want to move the man pages out of multi-arch:
    same packages, but would welcome patches to make the build more
    reproducible.

    You raised the issue that we want man pages to accompany their binary.
    It's fairly rare for binaries in /usr/bin or /usr/sbin to be in m-a:
    same packages.
    I think for libraries, we want the man page to be in the -dev package,
    and that's where I think we really start running into trouble.
    Cross building encourages us to make those -dev packages M-A: same.
    I think that I might generally agree with you that scheduling bin NMUs
    when -dev packages get out of sync might be sufficient.
    If you can give me clean patches to make libpam0g-dev's man pages
    reproducible (or spend the effort to confirm they already are), I'll
    leave the dev man pages there even though it is M-A: same.

    pages

    --=-=-Content-Type: application/pgp-signature; name="signature.asc"

    -----BEGIN PGP SIGNATURE-----

    iHUEARYIAB0WIQSj2jRwbAdKzGY/4uAsbEw8qDeGdAUCZ4lcAQAKCRAsbEw8qDeG dEqYAP9oGn+ujMJ6SCJbTBwJCPccx7xRaaoaBa0czEIbGzGgJAEAyeUS/sfz25X9 8ZU4/Kig382Id3cS28T5EXtBIJltggg=KPmg
    -----END PGP SIGNATURE-----

    --- SoupGate-Win32 v1.05
    * Origin: fsxNet Usenet Gateway (21:1/5)
  • From Sam Hartman@21:1/5 to All on Thu Jan 16 21:20:01 2025
    "Simon" == Simon McVittie <smcv@debian.org> writes:

    Simon> On Thu, 16 Jan 2025 at 09:41:51 -0700, Sam Hartman wrote:
    >> (We'd also need to do something about libpam0g-dev man pages).

    Simon> Moving user-facing documentation from libpam0g into either
    Simon> libpam-modules-bin or libpam-doc (depending how often you
    Simon> expect users to need it), and developer documentation from
    Simon> libpam0g-dev into libpam-doc, seems like it would make sense
    Simon> to me?

    I got enough requests from people who want the sysadmin-facing
    documentation installed by default (including a mild preference from
    Helmut who I generally align with on issues like this).

    I got a request from Helmut to minimize build dependencies.

    With the exception of Simon Richter, we appear to be agreed that
    avoiding man pages in m-a: same packages is good.

    So what I'm going to do is move the developer man pages into libpam-doc
    and the sysadmin man pages into libpam-runtime.
    I'll be open to requests from people who want to minimize essential set
    to move the sysadmin man pages to libpam-doc, but so far I'm not seeing
    that.

    I think this means:

    * build-arch will not need the doc tools

    * nodoc alone isn't enough to avoid the doc tools because of
    libpam-runtime

    * bootstrapping can reuse libpam-runtime so pam at least won't bring
    the xml docbook stack into bootstrapping essential.

    * I will recommend libpam-doc from libpam0g-dev

    --- SoupGate-Win32 v1.05
    * Origin: fsxNet Usenet Gateway (21:1/5)
  • From Simon Richter@21:1/5 to Sam Hartman on Fri Jan 17 03:00:01 2025
    Hi,

    On 1/17/25 05:14, Sam Hartman wrote:

    With the exception of Simon Richter, we appear to be agreed that
    avoiding man pages in m-a: same packages is good.

    I mean, this is specifically about the manpages included in
    libpam-modules, which are at the intersection of

    - likely to be useful when the full -doc package is not installed
    - in a m-a:same package
    - built with a tool that insists on inserting a comment with its own
    version number into output files

    So generalizing this to a rule to not ship manpages in m-a:same packages
    is overly broad -- basically we'd have to give every -dev package
    containing manual pages a -doc package, which is not really economical, especially when it's only a problem for generated manpages, and the
    differences between versions of the file are in comment lines.

    For libpam-modules itself, because there is a -runtime package already,
    moving the manpages there is a good solution, but it's not something I
    believe should become a general rule, because there absolutely are use
    cases for user facing documentation shipped with library packages.

    Simon

    --- SoupGate-Win32 v1.05
    * Origin: fsxNet Usenet Gateway (21:1/5)
  • From Simon McVittie@21:1/5 to Simon Richter on Fri Jan 17 10:30:02 2025
    On Fri, 17 Jan 2025 at 10:56:39 +0900, Simon Richter wrote:
    basically we'd have to give every -dev package containing
    manual pages a -doc package

    In many cases I think this is best-practice anyway, because it takes
    the documentation generation toolchain out of the critical path for bootstrapping, cross-compiling, and slow architectures. Many libraries
    have their API reference as HTML or even PDF, generated via something
    like Doxygen, gtk-doc or Pandoc, and kicking out that documentation into
    a separate package significantly reduces what needs to be built to get
    a minimal version of the library that is enough to continue to build
    dependent packages. For existing libraries that have not done this,
    I can see the argument for not introducing a -doc package to avoid NEW,
    but when packaging a new library or doing a SONAME bump I would nearly
    always split out the API reference into a -doc package.

    The nodoc build option and build profile go some way towards resolving
    this, but need to be invoked explicitly every time and alter the
    contents of built binary packages (not reproducible), whereas a separate Architecture: all documentation package "just works" and is easy to acceptance-test (if it builds successfully on the official buildds and
    has the desired contents, then you have succeeded).

    I can see that if the library of interest only has man pages (no HTML)
    and they're hand-written *roff (not generated from a more author-friendly source format with some tool) this might be considered unnecessary,
    because in that case there is no documentation toolchain, but that's
    uncommon in the ecosystems I usually work with.

    Similarly if a library has manual or automated as-installed tests, I've
    taken to always splitting them into an -examples or -tests package to
    avoid multiarch issues (and if it doesn't have even a manual smoke-test,
    I've started considering that to be an upstream bug that should be resolved before packaging, because that's how we get packages that nobody wants to
    NMU or team-upload because we don't know how to test them).

    smcv

    --- SoupGate-Win32 v1.05
    * Origin: fsxNet Usenet Gateway (21:1/5)
  • From Jonas Smedegaard@21:1/5 to All on Mon Jan 20 11:30:01 2025
    Quoting Simon McVittie (2025-01-17 10:19:47)
    Many libraries have their API reference as HTML or even PDF, generated
    via something like Doxygen, gtk-doc or Pandoc,

    Those packages currently using pandoc are recommended to check if either
    of the much lighter cmark or cmark-gfm is sufficient.

    - Jonas

    --
    * Jonas Smedegaard - idealist & Internet-arkitekt
    * Tlf.: +45 40843136 Website: http://dr.jones.dk/
    * Sponsorship: https://ko-fi.com/drjones

    [x] quote me freely [ ] ask before reusing [ ] keep private --==============S81526679360569016=MIME-Version: 1.0
    Content-Transfer-Encoding: 7bit
    Content-Description: signature
    Content-Type: application/pgp-signature; name="signature.asc"; charset="us-ascii"

    -----BEGIN PGP SIGNATURE-----

    wsG7BAABCgBvBYJnjiR+CRAsfDFGwaABIUcUAAAAAAAeACBzYWx0QG5vdGF0aW9u cy5zZXF1b2lhLXBncC5vcmfYHXqVAqPe/W4FoOvCbWDrQGR+Cn1mhReJEbJBdYaz TBYhBJ/j6cNmkaaf9TzGhCx8MUbBoAEhAAB9sg//flkj9gJ46mKnIASoiG3EcjRQ pV5LrYE3/7B1aTMCVgePEbKAQkhaWfqaqLarexyTQGtAHExn29mf/UZzhoM42fUN 35n3igGJ41hEWatcW+m4i7cm+bA256Kh5yfYyQMXdzRuHzATNKPNNvXT/YNf4A2h rE+y3xDJwBzTZ4O8vj2+8gQ9EBRpK5HYCutHQKkLv2/6uKFK5smazO5IKOimqQhn yGdmSV05mqsIxmgi0bObBn0p5h08PaCWvo1XC4avOjjTV9sPEsLVMs6oz4o0ZTbW vaopeVxTifFXDQa1tSL01CabBEJIi/Aqwu7nDfvoooys34/AsJ1X5xM2QqGed+Bt sRGJbvbikkDMUNSPMvW6BzZOvI8KlDNAD4FMb0nH