| 1 |
# TeXFindPkg tool for querying or installing TeX packages |
| 2 |
|
| 3 |
``` |
| 4 |
Description: Query or Install TeX packages and their dependencies |
| 5 |
Copyright: 2023-2024 (c) Jianrui Lyu <[email protected]> |
| 6 |
Repository: https://github.com/lvjr/texfindpkg |
| 7 |
License: GNU General Public License v3.0 |
| 8 |
``` |
| 9 |
|
| 10 |
## 1\. Introduction |
| 11 |
|
| 12 |
TeXFindPkg makes it easy to query or install TeX packages and their dependencies by file names, command names or environment names. |
| 13 |
It supports both TeXLive and MiKTeX distributions. At present it focuses mainly on LaTeX packages, |
| 14 |
but may extend to ConTeXt packages if anyone would like to contribute. |
| 15 |
|
| 16 |
## 2\. Installation |
| 17 |
|
| 18 |
Normally your TeX distribution will copy TeXFindPkg files and create a binary file `texfindpkg` when you install this package. |
| 19 |
If a manual installation is needed, you could copy TeXFindPkg files to TEXMF tree as follows: |
| 20 |
|
| 21 |
| Package file | Where to install it | |
| 22 |
| :------ | :------ | |
| 23 |
| texfindpkg.1 | TEXMF/doc/man/man1/texfindpkg.1 | |
| 24 |
| README.md | TEXMF/doc/support/texfindpkg/README.md | |
| 25 |
| texfindpkg.lua | TEXMF/scripts/texfindpkg/texfindpkg.lua | |
| 26 |
| texfindpkg.json.gz | TEXMF/tex/latex/texfindpkg/texfindpkg.json.gz | |
| 27 |
| tfpbuild.lua | TEXMF/source/texfindpkg/tfpbuild.lua | |
| 28 |
|
| 29 |
Then you could create a symbolic link from `/usr/local/bin/texfindpkg` to `path/to/texfindpkg.lua` on Linux or MacOS, |
| 30 |
or create a batch file `texfindpkg.bat` in binary folder of the TeX distribution with these lines on Windows: |
| 31 |
|
| 32 |
``` |
| 33 |
@echo off |
| 34 |
texlua path\to\texfindpkg.lua %* |
| 35 |
``` |
| 36 |
|
| 37 |
## 3\. Usage |
| 38 |
|
| 39 |
After installing TeXFindPkg, you can run it by executing |
| 40 |
|
| 41 |
``` |
| 42 |
texfindpkg <action> [<option>] [<name>] |
| 43 |
``` |
| 44 |
|
| 45 |
The `<action>` could be `query`, `install`, `help` or `version`. |
| 46 |
The leading dashes in any `<action>` will be removed first. |
| 47 |
|
| 48 |
For `query` action, you pass `-c`, `-e`, `-f` or `-p` as `<option>` |
| 49 |
to indicate the following `<name>` is a command name, environment name, file name or package name. |
| 50 |
For example (for `-f` option, you can omit file extension in the name if it is `.sty`), |
| 51 |
- `texfindpkg query -c fakeverb` means querying package with command `\fakeverb`; |
| 52 |
- `texfindpkg query -e frame` means querying package with environment `{frame}`; |
| 53 |
- `texfindpkg query -f array.sty` means querying package with file `array.sty`; |
| 54 |
- `texfindpkg query -p caption` means querying LaTeX packages in TeXLive/MiKTeX package `caption`. |
| 55 |
|
| 56 |
You can query a lot of names in one go. For example, |
| 57 |
``` |
| 58 |
texfindpkg query -c fakeverb -e verbatim tblr -f array longtable -p caption |
| 59 |
``` |
| 60 |
|
| 61 |
When you have a lot of names to query, you may want to list them in a file and use `-i` option to insert them. |
| 62 |
For example, if you have a file `input.txt` of lines (comments starting with `#` characters are ignored in it) |
| 63 |
``` |
| 64 |
-c |
| 65 |
fakeverb |
| 66 |
-e |
| 67 |
verbatim |
| 68 |
tblr |
| 69 |
-f |
| 70 |
array |
| 71 |
longtable |
| 72 |
-p |
| 73 |
caption |
| 74 |
``` |
| 75 |
then the following command produces the same result as the previous one does: |
| 76 |
``` |
| 77 |
texfindpkg query -i input.txt |
| 78 |
``` |
| 79 |
|
| 80 |
Furthermore you can save total dependent list of packages to a file with `-o` option: |
| 81 |
``` |
| 82 |
texfindpkg query -i input.txt -o output.txt |
| 83 |
``` |
| 84 |
|
| 85 |
With `-i` and `-o` options, it is quite easy to install a minimal TeXLive distribution with all dependencies resolved, |
| 86 |
which is useful for you to run regression tests with GitHub Actions if you are a package writer. |
| 87 |
Please see `latex-package.txt` and `texlive-package.txt` in [tabularray](https://github.com/lvjr/tabularray/tree/main/.github/workflows) repository for a practical example. |
| 88 |
|
| 89 |
The only difference between `query` and `install` actions is that |
| 90 |
with `install` action TeXFindPkg will install missing TeXLive or MiKTeX packages at the end. |
| 91 |
|
| 92 |
With `help` action, TeXFindPkg prints help message and exit. |
| 93 |
With `version` action, TeXFindPkg prints version information and exit. |
| 94 |
|
| 95 |
## 4\. Building |
| 96 |
|
| 97 |
TeXFindPkg uses completion files of TeXstudio editor which are in `completion` folder of TeXstudio [repository](https://github.com/texstudio-org/texstudio). |
| 98 |
|
| 99 |
After putting `completion` folder into current folder, you can execute `texlua tfpbuild.lua generate` to generate `texfindpkg.json` and `texfindpkg.json.gz` files. |
| 100 |
|
| 101 |
## 5\. Contributing |
| 102 |
|
| 103 |
Any updates of dependencies, commands or environments for packages should be contributed directly to TeXstudio project. |