Debian Codegraph @

texmf-dist/doc/support/texfindpkg/README.md

raw
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.