Re: documentation in TeX Live collections

[Nicolas Goaziou <mail@nicolasgoaziou.fr>]

Hello,

Thanks for that detailed report!

Emmanuel Beffara <manu@beffara.org> writes:

> There has been a lot of movement around TeX Live recently and it is very nice
> to see. We now have a usable modular installation and a great number of
> available packages and collections. However, I don't understand what is the
> proper way to reach documentation in the current system.
>
> I installed `texlive-scheme-medium` in my home profile managed by `guix home`,
> everything works including `texdoc` (although it always says « Info: Running
> Texdoc not installed in the current TEXMFMAIN. » for some reason), but there
> is essentially no documentation installed:
>
>     $ texdoc inputenc
>     Info: Running Texdoc not installed in the current TEXMFMAIN.
>     You don't appear to have any local documentation installed.
>
>     There may be online documentation available for "inputenc" at
> 	https://texdoc.org/serve/inputenc/0
>     This documentation may be for a different version than you have installed.
>
>     Would you like to search online? (y/N)
>
> Indeed the `doc` folder is nearly empty:
>
>     $ ls $GUIX_TEXMF/doc
>     bibtex8/  bibtexu/  chktex/
>
> Apparently, all individual packages have a specific "doc" output but
> collections and schemes do not and they don't have them as inputs either. So
> we end up with an installation with no documentation

It sounds like a good default to me. I doubt anyone reads all
documentation for every TeX Live package they install.

> (apart from the three above, which is surprising).

They are brought by `texlive-bin', which has no "doc" output.

> I tried to explicity include documentation in a sub-shell but this changes
> nothing:
>
>     $ guix shell texlive-latex:doc -- texdoc inputenc

Note that you also need to install texlive-texdoc (or some collection/scheme including it).

>     Info: Running Texdoc not installed in the current TEXMFMAIN.
>     You don't appear to have any local documentation installed.
>
>     There may be online documentation available for "inputenc" at
> 	https://texdoc.org/serve/inputenc/0
>     This documentation may be for a different version than you have installed.
>
>     Would you like to search online? (y/N)
>
> Including the TeX Live scheme in the same shell makes things worse:
>
>     $ guix shell texlive-scheme-medium texlive-latex:doc -- texdoc inputenc
>     Info: Running Texdoc not installed in the current TEXMFMAIN.
>     texdoc error: No texlive.tlpdb nor shipped tlpdb data found.
>
> Inspecting GUIX_TEXMF in this shell reveals that it now contains two paths,
> one of which does contain the right documentation:
>
>     $ guix shell texlive-scheme-medium texlive-latex:doc
>     $ env | grep TEX
>     GUIX_TEXMF=/gnu/store/fg1z0jgkj0r4v8i3rmpg0c1vfirbg1ac-profile/share/texmf-dist:/home/manu/.guix-home/profile/share/texmf-dist
>     $ ls /gnu/store/fg1z0jgkj0r4v8i3rmpg0c1vfirbg1ac-profile/share/texmf-dist/doc
>     bibtex8  bibtexu  chktex  latex
>     $ export GUIX_TEXMF=${GUIX_TEXMF%:*}
>     $ texdoc inputenc
>     ... inputenc.pdf is displayed! ...
>
> Apparently the fact that this GUIX_TEXMF variable contains several paths is
> problematic for texdoc.

Would the following definition for texlive-texdoc solve both issues
mentioned above? (the warning and the error.)

--8<---------------cut here---------------start------------->8---
(define-public texlive-texdoc
  (package
    (name "texlive-texdoc")
    (version (number->string %texlive-revision))
    (source (texlive-origin
             name version
             (list "doc/man/man1/texdoc.1"
                   "doc/man/man1/texdoc.man1.pdf"
                   "doc/support/texdoc/" "scripts/texdoc/"
                   "texdoc/")
             (base32
              "19mvh7pm2332f6c8nzgcbscm9vcz0apwfgm0m55ycibssc2fb3ww")))
    (outputs '("out" "doc"))
    (build-system texlive-build-system)
    (arguments
     (list #:link-scripts #~(list "texdoc.tlu")
           #:phases
           #~(modify-phases %standard-phases
               ;; Prevent "Info: Running Texdoc not installed in the current
               ;; TEXMFMAIN" warning by skipping an unnecessary test.
               (add-after 'unpack 'fix-script
                 (lambda _
                   (substitute* "scripts/texdoc/texdoc.tlu"
                     (("if texmf ~= nil") "if false"))))
               ;; Teach `texdoc' how to handle multiple directories in
               ;; GUIX_TEXMF environment variable.
               (add-after 'link-scripts 'wrap-programs
                 (lambda _
                   (wrap-program (string-append #$output "/bin/texdoc")
                     '("GUIX_TEXMF" = ("${GUIX_TEXMF%:*}"))))))))
    (propagated-inputs (list texlive-kpathsea))
    (home-page "https://ctan.org/pkg/texdoc")
    (synopsis "Documentation access for TeX Live")
    (description
     "@command{texdoc} is a Lua script providing easy access to the
documentation in TeX Live: PDF, DVI, plain text files, and more.  Viewing and
other configuration can be extensively customized.")
    (license license:gpl3+)))
--8<---------------cut here---------------end--------------->8---

> As an attempt to work around this, I tried to add texlive-latex:doc to my home
> profile definition and it did make that documentation available to texdoc.
> Moreover, for some reason, ALL documentation was downloaded:
>
>     $ guix home reconfigure home.scm
>     ...
>      texlive-cm-66594-doc  2KiB
>      texlive-etex-66594-doc  189KiB
>      texlive-hyphen-complete-66594-doc  783KiB
>      texlive-kpathsea-66594-doc  1022KiB
>      texlive-pdftex-66594  4.2MiB
>     ...
>     $ ls -d /gnu/store/*-texlive-*-doc/ | wc
>        1105    1105   82506
>
> Apparently something has triggered the download of documentation for all
> packages `texlive-scheme-medium` depends on but only the one I explicitly
> requested is made available in the profile (which is expected). All these
> other documentation were downloaded but not used and `guix gc` actually
> deletes them all!

I noticed that, too, but I don't have any explanation for it at the
moment.

For example,

  ./pre-inst-env guix shell texlive-scheme-basic texlive-texdoc texlive-babel:doc

is enough to trigger a massive download of "doc" outputs.

> So what would be the proper way to install `texlive-scheme-medium` in a home
> profile with the documentation of the packages it includes ?

If that's a common request, we could add a `texlive-collection-foo-doc'
package that would propagate all "doc" outputs from all packages
included in `texlive-collection-foo'.

However, I'm a bit reluctant to add more artificial packages (i.e., not
known to TeX Live distribution). Also, it might be as simple to do it in
one's own manifest.

I'm Cc'ing guix-devel ML.

Regards,
-- 
Nicolas Goaziou