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.