Xiyue Deng wrote:

Recently I am attempting to enable shipping docs of the racket-mode package[1]. However, its info page contains links to image files
(e.g. [2]) using the image syntax[3].

I encountered the same problem for fisicalab.app [1] and solved it
this way in debian/rules (I'm not sure if it would be useful for you):

# Rule to build the documentation because the upstream build system
# doesn't have one. Several things to note:
# 1. All images are installed along with the HTML documentation in
# order not to clutter infodir and to avoid duplicate files.
# 2. For producing Info files with images, texi2any needs to find the
# real image. Because /usr/share/doc/fisicalab.app-doc-*/html
# does not exist at build time, the images are copied in a relative
# directory and the .texinfo files are patched accordingly. Then the
# .info files are patched to add the leading slash.
# 3. The Texinfo manual recommends to install images for Info files in
# infodir/PACKAGE-figures but Emacs cannot load them from there.
# Furthermore, the filenames are the same for English/Spanish but
# with different content.
# 4. Lintian emits file-references-package-build-path for the PDF
# files which probably means that the build is not reproducible.
# There doesn't seem to be a way to remove the PTEX.FileName:
# neither by passing the appropriate --Xopt nor by patching the
# .texinfo files. Postprocessing the PDF files with various tools
# also doesn't have any effect.
define doc-rule
srcdir=Documentation/Manual/$(2); \
mkdir --parents build-$(1)/usr/share/doc/fisicalab.app-doc-$(1)/html \
&& cp $${srcdir}/* build-$(1) \
&& cp build-$(1)/*.{jpg,png} \
build-$(1)/usr/share/doc/fisicalab.app-doc-$(1)/html \
&& sed --in-place \
's/@image{/@image{usr\/share\/doc\/fisicalab.app-doc-$(1)\/html\//g' \
build-$(1)/*.texinfo \
&& texi2any --output=build-$(1) build-$(1)/fisicalab.texinfo \
&& sed --in-place 's/usr\/share/\/usr\/share/g' build-$(1)/*.info* \
&& mkdir build-$(1)/html \
&& cp $${srcdir}/*.{jpg,png} build-$(1)/html \
&& texi2any --output=build-$(1)/html --html $${srcdir}/fisicalab.texinfo \
&& texi2any --output=build-$(1)/fisicalab.pdf --pdf --Xopt=--clean \
$${srcdir}/fisicalab.texinfo
endef

# Build documentation, supporting the "nodoc" profile. execute_after_dh_auto_build-indep:
ifdef docs
$(call doc-rule,en,English)
$(call doc-rule,es,Spanish)
endif

[1] Should appear soon at https://tracker.debian.org/pkg/fisicalab.app

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

Xiyue Deng wrote:

However, I am concerned with the maintainability of such a complex
handling that is not blessed by upstream: when there are updates by
adding more info pages or images, and if the package is team
maintained (like racket-mode), other team members may have a hard
time to figure out what to do.

The rule uses globs so it would (theoretically) work if more
images/texinfo files come in the future, provided that the images are
of the types handled by the rule. It is very far from ideal (and I'm
not proud of it all) but it works for my goal: I wanted to ship Info,
HTML and PDF documentation and to avoid duplicate files in the .debs.

I'm not concerned about the number of team members being able to
understand it as there are only two at the time of writing and our
team is unlikely to grow (the square world of GNUstep is not so
attractive to the masses).

Looking at it again, I could avoid those escapes for slashes in the
sed invocations if I used "|" or something else as a sed separator.

For now I guess putting the images under /usr/share/info may be the
simplest and supported by most info clients.

For manuals only in English and providing only Info variant of the
manual, it will work.

It doesn't work in my case because fisicalab.app has an English and
Spanish manual and the filenames of the images are identical for both languages. It also clutters infodir unnecessarily as info readers
have to crawl over more files (and fisicalab.app-doc-(en|es) contain a
lot of images). It is also possible to cause file conflicts with
images in other manuals having identical names.

Also, the fisicalab.app-doc-* packages provide an HTML variant of the
manual, so if image files are shiped in infodir then they won't appear
in the HTML manual unless specificic patch-work or some sed-fu is
being done there (similar to what my rule does).

And if this is acceptable (e.g. documented in the Maintainer's
guide), we may implement this in lintian to be less noisy.

For something to be acceptable (generally speaking, or in policy,
lintian (lintian follows policy basically), various DEPs, etc.), first
it has to be proven to work in practice. Texinfo wrt localization is
*very* far from it. There's also a big question what to do with the
DIR file in different languages. I had long conversations with the
former Texinfo upstream maintainer Karl Berry (a person well known
within GNU and TeX communities) regarding this. And this was circa 20
years ago, nothing changed since then.

I don't think it's wise to suggest something that will work only for
the English language and only for limited cases when there's no HTML
variant of the manual.

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