#1075839 swi-prolog-doc: file missing since Debian 10.x ("buster"): /usr/share/doc/swi-prolog-doc/Manual/index.html

Package:
swi-prolog-doc
Source:
swi-prolog-doc
Submitter:
Alan D. Salewski
Date:
2024-07-15 09:45:03 UTC
Severity:
normal
Tags:
#1075839#5
Date:
2024-07-06 05:56:42 UTC
From:
To:
Dear Maintainer,

I encountered the below "all `Format' sections are invalid" error
while installing the 'swi-proglog-doc' package:

    # apt-get -u install swi-prolog{,-doc}
    Reading package lists... Done
    Building dependency tree... Done
    Reading state information... Done
    The following additional packages will be installed:
      swi-prolog-core swi-prolog-core-packages swi-prolog-nox swi-prolog-x
    Suggested packages:
      elpa-ediprolog swi-prolog-java swi-prolog-odbc swi-prolog-bdb
    The following NEW packages will be installed:
      swi-prolog swi-prolog-core swi-prolog-core-packages swi-prolog-nox swi-prolog-x
    The following packages will be upgraded:
      swi-prolog-doc
    1 upgraded, 5 newly installed, 0 to remove and 78 not upgraded.
    Need to get 3,545 kB/6,295 kB of archives.
    After this operation, 24.6 MB of additional disk space will be used.
    Do you want to continue? [Y/n]
    Get:1 https://deb.debian.org/debian bullseye/main amd64 swi-prolog-core-packages amd64 8.2.4+dfsg-1 [1,202 kB]
    Get:2 https://deb.debian.org/debian bullseye/main amd64 swi-prolog-nox amd64 8.2.4+dfsg-1 [172 kB]
    Get:3 https://deb.debian.org/debian bullseye/main amd64 swi-prolog-x amd64 8.2.4+dfsg-1 [2,144 kB]
    Get:4 https://deb.debian.org/debian bullseye/main amd64 swi-prolog amd64 8.2.4+dfsg-1 [27.6 kB]
    ...
    Processing triggers for doc-base (0.11.1) ...
    Processing 2 removed doc-base files, 26 added doc-base files...
=>  Error in `/usr/share/doc-base/swi-prolog-manual', line 10: all `Format' sections are invalid.
=>  Note: `install-docs --verbose --check file_name' may give more details about the above error.
    Processing triggers for libc-bin (2.31-13+deb11u10) ...
    ...

    # echo $?
    0

Following the hint from the 'Note:...' after the error, I ran:

    # /usr/sbin/install-docs --verbose --check /usr/share/doc-base/swi-prolog-manual
    Warning in `/usr/share/doc-base/swi-prolog-manual', line 10: file `/usr/share/doc/swi-prolog-doc/Manual/index.html' does not exist.
    Error in `/usr/share/doc-base/swi-prolog-manual', line 10: all `Format' sections are invalid.
    /usr/share/doc-base/swi-prolog-manual: Fatal error found, the file won't be registered

And sure enough, that 'index.html' file does not exist at that
location:

    $ file /usr/share/doc/swi-prolog-doc/Manual/index.html
    /usr/share/doc/swi-prolog-doc/Manual/index.html: cannot open `/usr/share/doc/swi-prolog-doc/Manual/index.html' (No such file or directory)

I'll note that there does exist the file:

    $ file /usr/share/swi-prolog/doc/Manual/import.html
    /usr/share/swi-prolog/doc/Manual/import.html: HTML document, ASCII text

which was reportedly installed by the 'swi-prolog-doc' package:

    $ dpkg -S /usr/share/swi-prolog/doc/Manual/import.html
    swi-prolog-doc: /usr/share/swi-prolog/doc/Manual/import.html

I'll also note that the 'Manual/' subdirectory is empty here:

    $ tree -axNpugsDF --dirsfirst /usr/share/doc/swi-prolog-doc
    /usr/share/doc/swi-prolog-doc
    ├── [drwxr-xr-x root     root           12288 Jul  4 11:01]  Manual/
    ├── [lrwxrwxrwx root     root              29 Jan 30  2021]  packages -> ../../swi-prolog/doc/packages/
    ├── [-rw-r--r-- root     root             763 Jan 30  2021]  NEWS.Debian.gz
    ├── [-rw-r--r-- root     root           17807 Jan 30  2021]  changelog.Debian.gz
    └── [-rw-r--r-- root     root           22346 Jan 30  2021]  copyright

    2 directories, 3 files

Perhaps it was intended that that directory would have symlinks to
the files under:

    /usr/share/swi-prolog/doc/Manual/
?

Here is the content of the file /usr/share/doc-base/swi-prolog-manual:

    $ cat /usr/share/doc-base/swi-prolog-manual
    Document: swi-prolog-manual
    Title: SWI-Prolog Reference Manual
    Author: SWI-Prolog development team
    Abstract: This document gives an overview of the features, system
     limits and built-in predicates of SWI-Prolog.
    Section: Programming/Prolog

    Format: HTML
    Index: /usr/share/doc/swi-prolog-doc/Manual/index.html
    Files: /usr/share/doc/swi-prolog-doc/Manual/*

Using 'apt-file' to look back through Debian releases, it looks like
maybe the last release to have the
'/usr/share/doc/swi-prolog-doc/Manual/index.html' file at the path
expected by the '/usr/share/doc-base/swi-prolog-manual' file was
Debian 10.x ("buster"):

    $ for onesuite in sid trixie bookworm{,-backports}         \
                      bullseye{,-backports} buster stretch; do \
          printf '%s: %s\n'    \
                 "${onesuite}" \
                 "$(apt-file --filter-suites "${onesuite}" search /usr/share/doc/swi-prolog-doc/Manual/index.html || echo '<none>')" ;\
      done
    sid: <none>
    trixie: <none>
    bookworm: <none>
    bookworm-backports: <none>
    bullseye: <none>
    bullseye-backports: <none>
    buster: swi-prolog-doc: /usr/share/doc/swi-prolog-doc/Manual/index.html
    stretch: swi-prolog-doc: /usr/share/doc/swi-prolog-doc/Manual/index.html

Thanks,
-Al

#1075839#10
Date:
2024-07-12 16:46:06 UTC
From:
To:
Dear Alan,

Thanks for your report.

Unifortunately, I have no idea why you faced the bug you reported.

These two directories /usr/share/doc/swi-prolog-doc/{Manual,packages} is
in fact a symlink to ../../swi-prolog/doc/{Manual,packages}. If you
download, say, swi-prolog-doc_8.2.4+dfsg-1_all.deb and navigate through
it with the help of, say, mc, you'll see that everything is in the
correct place and symlinks are properly created. I'd like to stress that
apt-file doesn't show symlinks properly and so reports
/usr/share/swi-prolog/doc/Manual as an empty directory. My guess is that
you faced a kind of race condition while updating doc-base or improper
work of dpkg/apt/whatever installs packages on your machine.

Regards,
Lev Lamberov

#1075839#17
Date:
2024-07-13 20:58:54 UTC
From:
To:
On 2024-07-12 21:46:06, Lev Lamberov <dogsleg@debian.org> spake thus:
[...]

Hi Lev,

Thanks for looking into it. I've done a little bit more digging and
am able to reproduce it. The problem seems to be in the doc-base
triggers when upgrading from swi-prolog-doc 5.6.59-2 to
8.2.4+dfsq-1.

I sanity-checked those locations on my system, and for some reason
the name 'Manual' was a directory. Interestingly, the timestamp for
it was on 2024-07-04 (the day I ran the command on which my original
bug report was based):

     $ ls -ldh /usr/share/doc/swi-prolog-doc/{Manual,packages}
     drwxr-xr-x 2 root root 12K  2024-07-04 11:01:56 /usr/share/doc/swi-prolog-doc/Manual
     lrwxrwxrwx 1 root root  29  2021-01-30 00:18:30 /usr/share/doc/swi-prolog-doc/packages -> ../../swi-prolog/doc/packages

Yes, that's what I see, too, when I look inside the 8.2.4+dfsg-1 deb
file:

     $ dpkg-deb -c /var/cache/apt/archives/swi-prolog-doc_8.2.4+dfsg-1_all.deb \
       | grep -E -e 'Manual/(index[.]html)?$' \
                 -e '^l' \
     drwxr-xr-x root/root         0 2021-01-30 00:18 ./usr/share/swi-prolog/doc/Manual/
     -rw-r--r-- root/root      6198 2021-01-30 00:18 ./usr/share/swi-prolog/doc/Manual/index.html
     lrwxrwxrwx root/root         0 2021-01-30 00:18 ./usr/share/doc/swi-prolog-doc/Manual -> ../../swi-prolog/doc/Manual
     lrwxrwxrwx root/root         0 2021-01-30 00:18 ./usr/share/doc/swi-prolog-doc/packages -> ../../swi-prolog/doc/packages

However, the earlier version of the package from which I was
upgrading (5.6.59-2) does not have those symlinks, and the actual
location of the files was different:

     $ dpkg-deb -c /var/cache/apt/archives/swi-prolog-doc_5.6.59-2_all.deb \
       | grep -E -e 'Manual/(index[.]html)?$' \
                 -e '^l'
     drwxr-xr-x root/root         0 2008-08-12 08:24 ./usr/share/doc/swi-prolog-doc/Manual/
     -rw-r--r-- root/root      4295 2008-08-12 08:24 ./usr/share/doc/swi-prolog-doc/Manual/index.html

If I start over from a clean slate:

     # apt-get remove --purge 'swi-prolog*'

and then install 'swi-prolog-doc':

     # apt-get -u install --no-install-recommends --verbose-versions swi-prolog-doc=8.2.4+dfsg-1
     Reading package lists... Done
     Building dependency tree... Done
     Reading state information... Done
     The following additional packages will be installed:
        swi-prolog-core (8.2.4+dfsg-1)
     Suggested packages:
        elpa-ediprolog (2.1-1)
        swi-prolog-core-packages (8.2.4+dfsg-1)
        swi-prolog-java (8.2.4+dfsg-1)
        swi-prolog-odbc (8.2.4+dfsg-1)
        swi-prolog-bdb (8.2.4+dfsg-1)
     The following NEW packages will be installed:
        swi-prolog-core (8.2.4+dfsg-1)
        swi-prolog-doc (8.2.4+dfsg-1)
     0 upgraded, 2 newly installed, 0 to remove and 80 not upgraded.
     Need to get 0 B/2,750 kB of archives.
     After this operation, 12.3 MB of additional disk space will be used.
     Do you want to continue? [Y/n]
     Retrieving bug reports... Done
     Parsing Found/Fixed information... Done
     Selecting previously unselected package swi-prolog-core.
     (Reading database ... 1724017 files and directories currently installed.)
     Preparing to unpack .../swi-prolog-core_8.2.4+dfsg-1_amd64.deb ...
     Unpacking swi-prolog-core (8.2.4+dfsg-1) ...
     Selecting previously unselected package swi-prolog-doc.
     Preparing to unpack .../swi-prolog-doc_8.2.4+dfsg-1_all.deb ...
     Unpacking swi-prolog-doc (8.2.4+dfsg-1) ...
     Setting up swi-prolog-core (8.2.4+dfsg-1) ...
     update-alternatives: using /usr/bin/swipl to provide /usr/bin/prolog (prolog) in auto mode
     Processing triggers for man-db (2.9.4-2) ...
     Processing triggers for menu (2.1.48) ...
     Processing triggers for doc-base (0.11.1) ...
     Processing 26 added doc-base files...
     Processing triggers for libc-bin (2.31-13+deb11u10) ...
     Setting up swi-prolog-doc (8.2.4+dfsg-1) ...

then I get the 'Manual' and 'packages' symlinks, as expected:

     $ ls -ldh /usr/share/doc/swi-prolog-doc/{Manual,packages}
     lrwxrwxrwx 1 root root 27  2021-01-30 00:18:30 /usr/share/doc/swi-prolog-doc/Manual -> ../../swi-prolog/doc/Manual
     lrwxrwxrwx 1 root root 29  2021-01-30 00:18:30 /usr/share/doc/swi-prolog-doc/packages -> ../../swi-prolog/doc/packages

Note, too, that the symlink for 'Manual' has a date of '2021-01-30'.

So uninstalling and then re-installing 'swi-prolog-doc' is a
workaround.

However, if I start over from a clean slate:

     # apt-get remove --purge 'swi-prolog*'

and install the older version:

     # apt-get -u install swi-prolog-doc=5.6.59-2
     Reading package lists... Done
     Building dependency tree... Done
     Reading state information... Done
     The following NEW packages will be installed:
       swi-prolog-doc
     0 upgraded, 1 newly installed, 0 to remove and 80 not upgraded.
     Need to get 0 B/3,388 kB of archives.
     After this operation, 7,761 kB of additional disk space will be used.
     Retrieving bug reports... Done
     Parsing Found/Fixed information... Done
     Selecting previously unselected package swi-prolog-doc.
     (Reading database ... 1724017 files and directories currently installed.)
     Preparing to unpack .../swi-prolog-doc_5.6.59-2_all.deb ...
     Unpacking swi-prolog-doc (5.6.59-2) ...
     Setting up swi-prolog-doc (5.6.59-2) ...
     Processing triggers for doc-base (0.11.1) ...
     Processing 2 added doc-base files...

and confirm that the 'Manual' directory is back:

     $ ls -ldh /usr/share/doc/swi-prolog-doc/{Manual,packages}
     ls: cannot access '/usr/share/doc/swi-prolog-doc/packages': No such file or directory
     drwxr-xr-x 2 root root 12K  2024-07-13 16:03:36 /usr/share/doc/swi-prolog-doc/Manual

and then try to upgrade to 8.2.4+dfsg-1:

     # apt-get -u install --no-install-recommends --verbose-versions swi-prolog-doc=8.2.4+dfsg-1
     Reading package lists... Done
     Building dependency tree... Done
     Reading state information... Done
     The following additional packages will be installed:
        swi-prolog-core (8.2.4+dfsg-1)
     Suggested packages:
        elpa-ediprolog (2.1-1)
        swi-prolog-core-packages (8.2.4+dfsg-1)
        swi-prolog-java (8.2.4+dfsg-1)
        swi-prolog-odbc (8.2.4+dfsg-1)
        swi-prolog-bdb (8.2.4+dfsg-1)
     The following NEW packages will be installed:
        swi-prolog-core (8.2.4+dfsg-1)
     The following packages will be upgraded:
=>     swi-prolog-doc (5.6.59-2 => 8.2.4+dfsg-1)
     1 upgraded, 1 newly installed, 0 to remove and 80 not upgraded.
     Need to get 0 B/2,750 kB of archives.
     After this operation, 4,491 kB of additional disk space will be used.
     Do you want to continue? [Y/n]
     Retrieving bug reports... Done
     Parsing Found/Fixed information... Done
     Reading changelogs... Done
     Selecting previously unselected package swi-prolog-core.
     (Reading database ... 1724387 files and directories currently installed.)
     Preparing to unpack .../swi-prolog-core_8.2.4+dfsg-1_amd64.deb ...
     Unpacking swi-prolog-core (8.2.4+dfsg-1) ...
     Preparing to unpack .../swi-prolog-doc_8.2.4+dfsg-1_all.deb ...
     Unpacking swi-prolog-doc (8.2.4+dfsg-1) over (5.6.59-2) ...
     Setting up swi-prolog-core (8.2.4+dfsg-1) ...
     update-alternatives: using /usr/bin/swipl to provide /usr/bin/prolog (prolog) in auto mode
     Processing triggers for man-db (2.9.4-2) ...
     Processing triggers for menu (2.1.48) ...
=>  Processing triggers for doc-base (0.11.1) ...
=>  Processing 2 removed doc-base files, 26 added doc-base files...
=>  Error in `/usr/share/doc-base/swi-prolog-manual', line 10: all `Format' sections are invalid.
=>  Note: `install-docs --verbose --check file_name' may give more details about the above error.
     Processing triggers for libc-bin (2.31-13+deb11u10) ...
     Setting up swi-prolog-doc (8.2.4+dfsg-1) ...

we can see the complaint that appears to be coming from the doc-base
triggers. And afterwards, the 'Manual' directory that was there now
has a new timestamp that reflects the current date and time:

     $ ls -ldh /usr/share/doc/swi-prolog-doc/{Manual,packages}
     drwxr-xr-x 2 root root 12K  2024-07-13 16:06:20 /usr/share/doc/swi-prolog-doc/Manual
     lrwxrwxrwx 1 root root  29  2021-01-30 00:18:30 /usr/share/doc/swi-prolog-doc/packages -> ../../swi-prolog/doc/packages

I also tested what happens if I simply try to reinstall 8.2.4+dfsg-1
over top of itself; it gets the same error:

     # apt-get -u install --reinstall --no-install-recommends --verbose-versions swi-prolog-doc=8.2.4+dfsg-1
     Reading package lists... Done
     Building dependency tree... Done
     Reading state information... Done
     0 upgraded, 0 newly installed, 1 reinstalled, 0 to remove and 80 not upgraded.
     Need to get 0 B/1,394 kB of archives.
     After this operation, 0 B of additional disk space will be used.
     (Reading database ... 1724738 files and directories currently installed.)
     Preparing to unpack .../swi-prolog-doc_8.2.4+dfsg-1_all.deb ...
=>  Unpacking swi-prolog-doc (8.2.4+dfsg-1) over (8.2.4+dfsg-1) ...
     Setting up swi-prolog-doc (8.2.4+dfsg-1) ...
=>  Processing triggers for doc-base (0.11.1) ...
=>  Processing 26 changed doc-base files...
=>  Error in `/usr/share/doc-base/swi-prolog-manual', line 10: all `Format' sections are invalid.
=>  Note: `install-docs --verbose --check file_name' may give more details about the above error.

The 'Manual' directory is still present (it has not been replaced by
the desired symlink), but this time the timestamp is /not/ updated
(FWIW):

     $ ls -ldh /usr/share/doc/swi-prolog-doc/{Manual,packages}
     drwxr-xr-x 2 root root 12K  2024-07-13 16:06:20 /usr/share/doc/swi-prolog-doc/Manual
     lrwxrwxrwx 1 root root  29  2021-01-30 00:18:30 /usr/share/doc/swi-prolog-doc/packages -> ../../swi-prolog/doc/packages

My concern is that somebody upgrading from an older version will
have this situation going forward -- it does not "fix itself" once
on the newer version, even with a reinstall of the pacakge.

Could be; definitely looks like doc-base, or something interfacing
with doc-base. I'm going to see if I can't get more information
about the state of the machine before the doc-base triggers fire and
during their execution.

Thanks, and more soon,
-Al

#1075839#22
Date:
2024-07-15 09:41:30 UTC
From:
To:
Hi Alan,

Сб 13 июл 2024 @ 16:58 "Alan D. Salewski" <ads@salewski.email>:

Thanks for your input.

Hmmm... Probably adding Conflicts and/or Breaks to d/control against
earlier versions of swi-prolog-doc is still required. The swi-prolog-doc
package previously was built from a separate source package, and
previously newer swi-prolog-doc had these fields in d/control. But I
don't think that Debian supports such a huge upgrade jumps through
several stable releases at once. My guess is that the correct way is to
upgrade to each stable release in between swi-prolog-doc 5.6.59-2 and
8.2.4+dfsg-1.

Cheers!
Lev