The HTML documentation installed by dev-libs/libevdev[doc] depends on executing javascript code loaded from external web servers. For example: % grep 'script.*http' /usr/share/doc/libevdev-1.10.0/html/index.html <script type="text/javascript" src="https://code.jquery.com/jquery-2.1.1.min.js"></script> <script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.1/js/bootstrap.min.js"></script> Most if not all other installed files have similar script tags. In particular, without the external jquery script being loaded successfully, the main navigation links are simply not present on any page and as a result the usability of the HTML documentation is significantly crippled. It seems pretty silly for installed documentation to depend on a working internet connection to be useful. The required scripts need to be locally installed too. Portage 3.0.13 (python 3.8.6-final-0, default/linux/amd64/17.1, gcc-9.3.0, glibc-2.32-r5, 5.10.12 x86_64) ================================================================= System Settings ================================================================= System uname: Linux-5.10.12-x86_64-Intel-R-_Core-TM-_i5-5200U_CPU_@_2.20GHz-with-glibc2.2.5 KiB Mem: 8059392 total, 6629820 free KiB Swap: 0 total, 0 free Timestamp of repository gentoo: Tue, 19 Jan 2021 00:45:01 +0000 sh dash 0.5.11.3-r1 ld GNU ld (Gentoo 2.34 p6) 2.34.0 ccache version 4.1 [enabled] app-shells/bash: 5.0_p18::gentoo dev-lang/perl: 5.30.3::gentoo dev-lang/python: 2.7.18-r5::gentoo, 3.7.9-r1::gentoo, 3.8.6-r1::gentoo, 3.9.0-r1::gentoo dev-util/ccache: 4.1::gentoo dev-util/cmake: 3.17.4-r1::gentoo sys-apps/baselayout: 2.7::gentoo sys-apps/openrc: 0.42.1::gentoo sys-apps/sandbox: 2.20::gentoo sys-devel/autoconf: 2.13-r1::gentoo, 2.69-r5::gentoo sys-devel/automake: 1.13.4-r2::gentoo, 1.16.2-r1::gentoo sys-devel/binutils: 2.34-r2::gentoo sys-devel/gcc: 9.3.0-r2::gentoo sys-devel/gcc-config: 2.3.2-r1::gentoo sys-devel/libtool: 2.4.6-r6::gentoo sys-devel/make: 4.3::gentoo sys-kernel/linux-headers: 5.10::gentoo (virtual/os-headers) sys-libs/glibc: 2.32-r5::gentoo Repositories: gentoo location: /srv/repos/gentoo sync-type: squashmirror sync-uri: /srv/gentoo sync-user: root priority: -1000 squash-compression: xz squash-cache-location: /var/cache/portage squash-extra-opts: -e distfiles -e packages -e local gentoo-draconx location: /srv/repos/gentoo-draconx sync-type: null sync-uri: null masters: gentoo gentoo-fixes location: /srv/repos/gentoo-fixes sync-type: null sync-uri: null masters: gentoo ACCEPT_KEYWORDS="amd64" ACCEPT_LICENSE="@FREE @OTHER-FREE" CBUILD="x86_64-pc-linux-gnu" CFLAGS="-O2 -march=broadwell -pipe" CHOST="x86_64-pc-linux-gnu" CONFIG_PROTECT="/etc /usr/share/gnupg/qualified.txt" CONFIG_PROTECT_MASK="/etc/ca-certificates.conf /etc/dconf /etc/env.d /etc/fonts/fonts.conf /etc/gconf /etc/gentoo-release /etc/revdep-rebuild /etc/sandbox.d /etc/terminfo /etc/texmf/language.dat.d /etc/texmf/language.def.d /etc/texmf/updmap.d /etc/texmf/web2c" CXXFLAGS="-O2 -march=broadwell -pipe" DISTDIR="/var/cache/portage/distfiles" EMERGE_DEFAULT_OPTS="-j3 --keep-going --dynamic-deps=n --autounmask --autounmask-write=n --unordered-display --verbose-conflicts --binpkg-respect-use=y --with-bdeps-auto=n" ENV_UNSET="CARGO_HOME DBUS_SESSION_BUS_ADDRESS DISPLAY GOBIN GOPATH PERL5LIB PERL5OPT PERLPREFIX PERL_CORE PERL_MB_OPT PERL_MM_OPT XAUTHORITY XDG_CACHE_HOME XDG_CONFIG_HOME XDG_DATA_HOME XDG_RUNTIME_DIR" FCFLAGS="-O2 -march=broadwell -pipe" FEATURES="assume-digests binpkg-docompress binpkg-dostrip binpkg-logs binpkg-multi-instance ccache config-protect-if-modified distlocks ebuild-locks fixlafiles ipc-sandbox merge-sync multilib-strict network-sandbox news parallel-fetch pid-sandbox preserve-libs protect-owned qa-unresolved-soname-deps sandbox sfperms strict unknown-features-warn unmerge-logs unmerge-orphans userfetch userpriv usersandbox usersync xattr" FFLAGS="-O2 -march=broadwell -pipe" GENTOO_MIRRORS="http://distfiles.gentoo.org" INSTALL_MASK="/usr/share/cursors/xorg-x11/default /usr/share/alsa/alsa.conf.d/*.conf /etc/alsa/conf.d/*.conf /etc/portage/*postsync.d /etc/gssproxy/??-*.conf /etc/profile.d/qtgui4.sh /etc/????.d/wpa_supplicant" LANG="en_CA.UTF-8" LDFLAGS="-Wl,-O1 -Wl,--as-needed" MAKEOPTS="-j4 -l5" PKGDIR="/var/cache/portage/packages" PORTAGE_CONFIGROOT="/" PORTAGE_RSYNC_OPTS="--recursive --links --safe-links --perms --times --omit-dir-times --compress --force --whole-file --delete --stats --human-readable --timeout=180 --exclude=/distfiles --exclude=/local --exclude=/packages --exclude=/.git" PORTAGE_TMPDIR="/var/tmp" USE="X aacs acl alsa amd64 berkdb bluray bs2b bzip2 cairo cdda cjk cli crypt cups dav1d doc dri dts dv exif fbcon flac fontconfig fortran gdbm gpm gtk gtk-doc iconv icu idn ipv6 jpeg jpeg2k kerberos libglvnd libtirpc mp3 multilib ncurses nls nptl ogg opengl openmp opus pam pango pcre perl png python readline seccomp smp split-usr ssl svg tcpd theora threads tiff truetype unicode vaapi vim-syntax vorbis vulkan webp xattr xft xinerama zlib" ABI_X86="64" ADA_TARGET="gnat_2018" ALSA_CARDS="ali5451 als4000 atiixp atiixp-modem bt87x ca0106 cmipci emu10k1x ens1370 ens1371 es1938 es1968 fm801 hda-intel intel8x0 intel8x0m maestro3 trident usb-audio via82xx via82xx-modem ymfpci" APACHE2_MODULES="authn_core authz_core socache_shmcb unixd actions alias auth_basic authn_alias authn_anon authn_dbm authn_default authn_file authz_dbm authz_default authz_groupfile authz_host authz_owner authz_user autoindex cache cgi cgid dav dav_fs dav_lock deflate dir disk_cache env expires ext_filter file_cache filter headers include info log_config logio mem_cache mime mime_magic negotiation rewrite setenvif speling status unique_id userdir usertrack vhost_alias" CALLIGRA_FEATURES="karbon sheets words" COLLECTD_PLUGINS="df interface irq load memory rrdtool swap syslog" CPU_FLAGS_X86="aes avx avx2 fma3 mmx mmxext popcnt sse sse2 sse3 sse4_1 sse4_2 ssse3" ELIBC="glibc" GPSD_PROTOCOLS="ashtech aivdm earthmate evermore fv18 garmin garmintxt gpsclock greis isync itrax mtk3301 nmea ntrip navcom oceanserver oldstyle oncore rtcm104v2 rtcm104v3 sirf skytraq superstar2 timing tsip tripmate tnt ublox ubx" KERNEL="linux" LCD_DEVICES="bayrad cfontz cfontz633 glk hd44780 lb216 lcdm001 mtxorb ncurses text" LIBREOFFICE_EXTENSIONS="presenter-console presenter-minimizer" LUA_SINGLE_TARGET="lua5-1" LUA_TARGETS="lua5-1" OFFICE_IMPLEMENTATION="libreoffice" PHP_TARGETS="php7-3 php7-4" POSTGRES_TARGETS="postgres10 postgres11" PYTHON_SINGLE_TARGET="python3_8" PYTHON_TARGETS="python2_7 python3_8" RUBY_TARGETS="ruby26" USERLAND="GNU" VIDEO_CARDS="intel i965" XTABLES_ADDONS="quota2 psd pknock lscan length2 ipv4options ipset ipp2p iface geoip fuzzy condition tee tarpit sysrq steal rawnat logmark ipmark dhcpmac delude chaos account" Unset: CC, CPPFLAGS, CTARGET, CXX, LC_ALL, LINGUAS, PORTAGE_BINHOST, PORTAGE_BUNZIP2_COMMAND, PORTAGE_COMPRESS, PORTAGE_COMPRESS_FLAGS, PORTAGE_RSYNC_EXTRA_OPTS ================================================================= Package Settings ================================================================= dev-libs/libevdev-1.10.0::gentoo was built with the following: USE="doc -test" ABI_X86="(64) -32 (-x32)" FEATURES="config-protect-if-modified ebuild-locks unmerge-orphans sfperms binpkg-docompress userpriv qa-unresolved-soname-deps merge-sync xattr distlocks unknown-features-warn strict usersandbox ccache binpkg-multi-instance binpkg-logs userfetch network-sandbox preserve-libs multilib-strict news fixlafiles unmerge-logs ipc-sandbox parallel-fetch sandbox usersync assume-digests protect-owned binpkg-dostrip pid-sandbox"
Want to write a patch?
Created attachment 685368 [details, diff] remove external web server references from html docs It seems the "jquery" script is already installed by the package. So it is easy enough to just patch all the files to refer to that instead of the external web server. This seems sufficient. I don't know what the other script does. Everything seems fine without it so I just deleted it. With this applied to libevdev-1.10.0 the installed documentation works much better.
Upstream asks what I think is a very valid question: why do you want libevdev documentation installed by the distro? https://gitlab.freedesktop.org/libevdev/libevdev/-/merge_requests/80#note_866626
(In reply to Matt Turner from comment #3) > why do you want libevdev documentation installed by the distro? I'm a bit puzzled by the question to be honest. Documentation is needed to use this library. Documentation is provided with the package, albeit with this annoying problem... but this problem can be fixed. Typically, Gentoo provides a way to install documentation for packages. What would the alternative be? Not having documentation? Patching and installing it manually?
The MR upstream came about because I was looking into this bug, and realized that the Meson build system doesn't actually support installing the documentation, so the question arose: who actually wants it? I guess the question comes from not really expecting anyone to want the HTML documentation. Personally I think I would git clone libevdev and build the documentation there, for example, rather than using the distro-provided stuff. Basically, the question is: do you actually want the HTML documentation provided by the distro? What are you using it for? Writing something that uses libevdev?
(In reply to Matt Turner from comment #5) > The MR upstream came about because I was looking into this bug, and realized > that the Meson build system doesn't actually support installing the > documentation, so the question arose: who actually wants it? I would assume anyone who wants to use this library in their programs would also want the documentation. > I guess the question comes from not really expecting anyone to want > the HTML documentation. If nobody is expected to want the HTML documentation, why provide it in the first place? No other documentation appears to be supplied with this package...? The man page contains no information. > Personally I think I would git clone libevdev and build the > documentation there, for example, rather than using the > distro-provided stuff. Sure, I imagine this can be done, but it is far from the ideal method. It is much more convenient to have the documentation already installed, and is known to correspond with the specific version of the library that is also already installed, and updated when the installed version of the library is updated. Isn't that the whole point of a GNU/Linux distribution? > Basically, the question is: do you actually want the HTML > documentation provided by the distro? What are you using it for? > Writing something that uses libevdev? Yes, that would be the typical reason to read the documentation for libevdev or, for that matter, any library.
Upstream is not interested in supporting installing documentation locally, sorry. I expect the autotools build system to go away at some future point, at which time we wouldn't be able to install the documentation without patching it in Gentoo which doesn't seem like a particularly valuable thing to do. FWIW, there are versioned docs available here: https://www.freedesktop.org/software/libevdev/doc/
