lvjr / texfindpkg

Query or install TeX packages and their dependencies

TeXFindPkg tool for querying or installing TeX packages

Description: Query or Install TeX packages and their dependencies
Copyright: 2023 (c) Jianrui Lyu <[email protected]>
Repository: https://github.com/lvjr/texfindpkg
License: GNU General Public License v3.0

1. Introduction

TeXFindPkg makes it easy to query or install TeX packages and their dependencies by file names, command names or environment names. It supports both TeXLive and MiKTeX distributions. At present it focuses mainly on LaTeX packages, but may extend to ConTeXt packages if anyone would like to contribute.

2. Installation

Normally your TeX distribution will copy TeXFindPkg files and create a binary file texfindpkg when you install this package. If a manual installation is needed, you could copy TeXFindPkg files to TEXMF tree as follows:

Package file	Where to install it
texfindpkg.1	TEXMF/doc/man/man1/texfindpkg.1
README.md	TEXMF/doc/support/texfindpkg/README.md
texfindpkg.lua	TEXMF/scripts/texfindpkg/texfindpkg.lua
texfindpkg.json.gz	TEXMF/scripts/texfindpkg/texfindpkg.json.gz
tfpbuild.lua	TEXMF/source/texfindpkg/tfpbuild.lua

Then you could create a symbolic link from /usr/local/bin/texfindpkg to path/to/texfindpkg.lua on Linux or MacOS, or create a batch file texfindpkg.bat in binary folder of the TeX distribution with these lines on Windows:

@echo off
texlua path\to\texfindpkg.lua %*

3. Usage

After installing TeXFindPkg, you can run it by executing

texfindpkg <action> [<option>] [<name>]

The <action> could be query, install, help or version. The leading dashes in any <action> will be removed first.

For query action, you pass -f, -c or -e as <option> to indicate the following <name> is a file name, command name or environment name. For example,

• texfindpkg query -f array.sty means querying package with file array.sty;
• texfindpkg query -c fakeverb means querying package with command \fakeverb;
• texfindpkg query -e frame means querying package with environment {frame}.

The only difference between query and install actions is that with install action TeXFindPkg will install missing TeXLive or MiKTeX packages at the end.

With help action, TeXFindPkg prints help message and exit. With version action, TeXFindPkg prints version information and exit.

4. Building

TeXFindPkg uses completion files of TeXstudio editor which are in completion folder of TeXstudio repository.

After putting completion folder into current folder, you can execute texlua tfpbuild.lua generate to generate texfindpkg.json and texfindpkg.json.gz files.

5. Contributing

Any updates of dependencies, commands or environments for packages should be contributed directly to TeXstudio project.

texfindpkg's Issues

texfindpkg can't recognize commands/envs with special characters

For example

texfindpkg query -e +array

doesn't find tabularraylibraryamsmath.cwl, even if you call it with '+array'.

miktex-installed texfindpkg fails

texfindpkg was recently added to miktex so I installed it through the console on my Windows machine, however there seems to be a packaging error (or some other kind of error). Running

texfindpkg query -f array.sty

in a terminal produces

texfindpkg: security risk: running with elevated privileges
[tfp] you are using miktex
...\Local\Programs\MiKTeX\scripts/texfindpkg\texfindpkg.lua:78: bad argument #1 to 'open' (string expected, got nil)

Not sure if this is a miktex or texfindpkg issue.

Add query action

Hi, thanks for this tool.
Would it be possible to add an option dry to show what would be done without actually doing it?

Only alphabetically first package/class defining a command is found

Thanks for writing this, it has a lot of potential. Right now, however, only the first package or class to define a command is found.

E.g.

texfindpkg query '\chapter' finds amsbook.cls but not book, memoir etc.
texfindpkg query '\Tree' finds logicpuzzles but not qtree, tikz-qtree, xyling etc.

I suspect that for the command finding function, finding dependencies is less important than finding the package(s) that define the command, since most people I suspect have a fairly complete distribution installed anyway.

Usage (or installation) problem

The command texfindpkg query array.sty gives:

[tfp] you are using texlive
[tfp] finding dependencies for array.sty
[tfp] please install texlive package tools

kpsewhich array.sty gives:

/usr/local/texlive/2023/texmf-dist/tex/latex/tools/array.sty

So array.sty is installed.

And texfindpkg install array.sty gives:

[tfp] you are using texlive
[tfp] finding dependencies for array.sty
[tfp] installing package tools
Password:🔑

(Yes, the Mac Terminal really displays a key, not with a emoji but with a custom character, when it ask for a password).

I though that texfindpkg don't want to install a package already installed, but with the query action, it's seems that texfindpkg doesn't see that the array package is already installed.

What do you name "package tools" when you say "[tfp] installing package tools"?

If this can help: there is only the file texfindpkg.lua in the scripts folder (complete path: /usr/local/texlive/2023/texmf-dist/scripts/texfindpkg/texfindpkg.lua).

When I search for all files which contains the name "texfindpkg" on my computer, I obtain this result:

So there is a file named texfindpkg.json.gz (yes, .gz) in: /usr/local/texlive/2023/texmf-dist/tex/latex/texfindpkg/texfindpkg.json.gz (don't know if this file is expected in /tex/latex/texfindpkg rather than in /scripts/texfindpkg, as explained in issue #2, but definitively, the .gz seems to be an error).

I hope this can help you to debug your new package or the installation of your new package.

inconsistent behavior for special libraries

For some packages with package-specific libraries, texstudio supports special prefixes. In particular there are cwls named <prefix><library>.cwl for prefixes tikz, pgfplots, tcolorbox, and tabularray. Querying commands from tikz and tcolorbox libraries seems to work. For example

texfindpkg query -c calendar

produces

found package file tikzlibrarycalendar.code.tex with command \calendar

and

texfindpkg query -c tcbvignette

produces

found package file tcbvignette.code.tex with command \tcbvignette

But for pgfplots and tabularray libraries, it looks for .sty files with the cwl name:

texfindpkg query -c cellGetText

produces

found package file tabularraylibraryfunctional.sty with command \cellGetText

and builds the dependency tree from the cwl file, but of course one would also like it to recognize that you need tabularry installed for it to work. Similarly for pgfplots:

texfindpkg query -e groupplot

produces

found package file pgfplotslibrarygroupplots.sty with environment {groupplot}

"texlive packages not yet installed in total:" should be complete

I am using texfindpkg query -e itemize

The last line is

[tfp] texlive packages not yet installed in total:

Shouldn't there be a number or something after the :?

cwls contain many duplicates

As the person who wrote most of the cwls that texfindpkg uses, I should warn that there's a LOT of duplicated lines among different cwls, mostly due to the limitations of the cwl format (or rather texstudio's syntax parser). For example if a package loads the T1 option of the package fontenc, there's no way to write something like #includeoption:fontenc/T1. Instead I just copy all the commands from this option, something like

# from T1 option of fontenc
\DH#n
\dh#n
\dj#n
\DJ#n
\guillemetleft#n
\guillemetright#n
\guillemotleft#*n
\guillemotright#*n
\guilsinglleft#n
\guilsinglright#n
\Hwithstroke#n
\hwithstroke#n
\k{arg}#n
\NG#n
\ng#n
\quotedblbase#n
\quotesinglbase#n
\textogonekcentered{arg}#n
\textquotedbl#n
\th#n
\TH#n

Hence calling something like texfindpkg query -c guillemetleft produces a huge list of packages. Not necessarily a major issue, just something I thought you should be aware of.

Installation problem and sudo prefix

I have installed findpkg with TeX Live Utility (Mac GUI for tlmgr).

Result:
In the Terminal, kpsewhich findpkg.lua outputs:
/usr/local/texlive/2023/texmf-dist/tex/latex/findpkg/findpkg.lua.

So the installation seems correct.

But texlua findpkg.lua install array.sty in the Terminal output:
Script file findpkg.lua not found.

As a average user, my working directory is /Users/my_user_name.

As I know nothing about the texlua command, I have tested texlua -help and discovered that it is a alias of luatex (because the answer begins with Usage: luatex ...).

So if I understand correctly, I must use cd command to go in /usr/local/texlive/2023/texmf-dist/tex/latex/findpkg/, and THEN use the command texlua findpkg.lua install array.sty?

I'm wrong or can I not use your command when I'm on my default working directory?

When I try this in Terminal (or use the cd command to go in the LaTeX installation, then the command texlua findpkg.lua install array.sty):
texlua /usr/local/texlive/2023/texmf-dist/tex/latex/findpkg/findpkg.lua install array.sty

I obtain:

[findpkg] you are using texlive
[findpkg] finding dependencies for array.sty
[findpkg] installing package tools
You don't have permission to change the installation in any way,
specifically, the directory /usr/local/texlive/2023/tlpkg/ is not writable.
Please run this program as administrator, or contact your local admin.
tlmgr: An error has occurred. See above messages. Exiting.

(effectively, when I install a new package with TeX Live Utility, a prompt ask for my admin password. By the way, what is the behaviour of your tool when we ask for a package already installed?).

By the way, if I understand correctly the purpose of your package, it is a great idea. Perhaps you can add an option like where, so with texlua findpkg.lua where \command (or {environment}) your tool display the name of the package which contains this command or environment without install it. Moreover, with an option like doc you can directly call texdoc to display the documentation of the package which contains this command or environment.

But please, can you make your tool working on user lever working directory?

And if you have the time, a more detailed documentation is welcome (for the moment, explain that your tool only work in the findpkg directory, which is on /usr/local/texlive/2023/texmf-dist/tex/latex/ after being installed with TeX Live Utility, and that we need prefix the command with sudo if I understand correctly). Thanks.