Package: texlive-base Version: 2022.20230122-3 Severity: minor X-Debbugs-Cc: debbug.texlive-b...@sideload.33mail.com
I tried to start using tlmgr for the first time. It was pleasing to find that “texdoc tlmgr” presented a PDF manual. There is a natural expectation with linux tools that a PDF guide would be comprehensive and complete to some extent, while the man page would typically just serve as a complete but concise reference. In the case of tlmgr the reality is an inversion of that. The PDF is titled “Basic Usage…”, which tries to clarify the coverage is /basic/ but I simply still expected the PDF to be more complete than a man page. I figured the man page must be even more basic. The intro gave an overview which reinforced that expectation. So I expected to learn everything I needed from that PDF. My first command failed: ===8<---------------------------------------- $ tlmgr info acro (running on Debian, switching to user mode!) (see /usr/share/doc/texlive-base/README.tlmgr-on-Debian.md) TLPDB: Cannot determine type of tlpdb from ~/.local/share/texmf! tlmgr: user mode not initialized, please read the documentation! ===8<---------------------------------------- The last line was discouraging because I read what I thought was the comprehensive documentation. The PDF makes no mention of user mode, not even mention of the existence of the --usermode parameter. It is covered in the man page though. I was surprised that I would need a user-maintained database to simply query for the version of the acro package. Adding --usermode eliminated the warning but still made no progress: ===8<---------------------------------------- $ tlmgr --usermode info acro TLPDB: Cannot determine type of tlpdb from /home/blee/.local/share/texmf! tlmgr: user mode not initialized, please read the documentation! ===8<---------------------------------------- I also expected a list of what’s installed to not require a user-maintained database, so I tried that as well: ===8<---------------------------------------- $ tlmgr --usermode list TLPDB: Cannot determine type of tlpdb from /home/blee/.local/share/texmf! tlmgr: user mode not initialized, please read the documentation! ===8<---------------------------------------- >From the man page: manpg> "tlmgr" is switched into user mode with the command line option manpg> "--usermode". It does not switch automatically, nor is there any manpg> configuration file setting for it. Thus, this option has to be manpg> explicitly given every time user mode is to be activated. The claim that tlmgr does not switch to user mode automatically is apparently inaccurate assuming the output is accurate. manpg> This mode of "tlmgr" works on a user tree, by default the value of the manpg> "TEXMFHOME" variable. This can be overridden with the command line manpg> option "--usertree". In the following when we speak of the user tree we manpg> mean either "TEXMFHOME" or the one given on the command line. There is no mention of what happens if --usertree is not supplied and TEXMFHOME is unset. Users would rather not guess and experiment. But I was forced to experiment because at the same time I did not want to select a unconventional custom location. So I took a risk and ran the init-usertree command without feeding it a location. init-usertree printed no output. So it was unclear if it did any work. And if it did, it was unclear where the database was put. I happened to have had stuff in ~/.local/share/texmf/ and so I guessed that the db would be created there. So I ran “find ~/.local/share/texmf/” before and after init-usertree, which luckily revealed that was the default. Novices will not know about that path. The “ENVIRONMENT VARIABLES” section does not include $TEXMFHOME. This might also be a good place to mention the default dir if $TEXMFHOME is unset. manpg> Before using "tlmgr" in user mode, you have to set up the user tree with manpg> the "init-usertree" action. This creates *usertree*"/web2c" and manpg> *usertree*"/tlpkg/tlpobj", and a minimal manpg> *usertree*"/tlpkg/texlive.tlpdb". At that point, you can tell "tlmgr" to manpg> do the (supported) actions by adding the "--usermode" command line manpg> option. I was alienated by the use of “*usertree*”. It was indeed mentioned that “when we speak of the user tree we mean either "TEXMFHOME" or the one given on the command line” but that is easily overlooked by speed readers and the asterisks imply a wildcard which confuses things. The convention for a variable token in BNF would be angle brackets and the double quotes are not needed; thus I think <user tree>/tlpkg/tlpobj would be more clear to more readers. BTW, a “tree” is normally thought to be the whole heiarchy of directories, not the root or home. I would change the wording to <tlmgr home> or <tlmgr root> or perhaps <tlmgr tree root>. manpg> Some "tlmgr" actions don't need any write permissions and thus work the manpg> same in user mode and normal mode. Currently these are: "check", "help", manpg> "list", "print-platform", "print-platform-info", "search", "show", manpg> "version". I would also naturally expect the “info” action to not need permissions but it’s not listed as needing write perms and not listed as not needing write perms. -- System Information: Debian Release: 12.5 APT prefers stable-updates APT policy: (990, 'stable-updates'), (990, 'stable-security'), (990, 'stable'), (500, 'oldstable') Architecture: amd64 (x86_64) Foreign Architectures: i386 Kernel: Linux 5.10.0-28-amd64 (SMP w/2 CPU threads) Kernel taint flags: TAINT_OOT_MODULE, TAINT_UNSIGNED_MODULE Locale: LANG=en_US.UTF-8, LC_CTYPE=en_US.UTF-8 (charmap=UTF-8), LANGUAGE not set Shell: /bin/sh linked to /usr/bin/dash Init: systemd (via /run/systemd/system) LSM: AppArmor: enabled Versions of packages texlive-base depends on: ii debconf [debconf-2.0] 1.5.82 ii libpaper-utils 1.1.29 ii sensible-utils 0.0.17+nmu1 ii tex-common 6.18 ii texlive-binaries 2022.20220321.62855-5.1+deb12u1 ii ucf 3.0043+nmu1 ii xdg-utils 1.1.3-4.1 Versions of packages texlive-base recommends: ii lmodern 2.005-1 Versions of packages texlive-base suggests: ii evince [postscript-viewer] 43.1-2+b1 ii ghostscript [postscript-viewer] 10.0.0~dfsg-11+deb12u3 ii mupdf [pdf-viewer] 1.21.1+ds2-1+b4 ii okular [postscript-viewer] 4:22.12.3-1 pn perl-tk <none> ii qpdfview [pdf-viewer] 0.5.0+ds-2 ii qpdfview-ps-plugin [postscript-viewer] 0.5.0+ds-2 ii xpdf [pdf-viewer] 3.04+git20220601-1+b2 pn xzdec <none> Versions of packages tex-common depends on: ii ucf 3.0043+nmu1 Versions of packages tex-common suggests: ii debhelper 13.11.4 Versions of packages texlive-base is related to: ii tex-common 6.18 ii texlive-binaries 2022.20220321.62855-5.1+deb12u1 -- debconf information excluded
