Hi Yavor, Yavor Doganov <ya...@gnu.org> writes:
> 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
>
This looks like an epic effort to get the info page reference the images
in another directory correctly, and hence my kudos!
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.
For now I guess putting the images under /usr/share/info may be the
simplest and supported by most info clients. And if this is acceptable
(e.g. documented in the Maintainer's guide), we may implement this in
lintian to be less noisy.
Want to see what debhelper and lintian maintainers think. Thanks again
in advance.
--
Regards,
Xiyue Deng
signature.asc
Description: PGP signature
