| 1 |
# Texdoc ― Find and view documentation in TeX Live |
| 2 |
|
| 3 |
[](https://github.com/TeX-Live/texdoc/actions/workflows/ci.yml) |
| 4 |
[](https://www.ctan.org/pkg/texdoc) |
| 5 |
|
| 6 |
## General Information |
| 7 |
|
| 8 |
* Website: <https://www.tug.org/texdoc/> |
| 9 |
* Repository: <https://github.com/TeX-Live/texdoc/> |
| 10 |
* Mailing list: <[email protected]> |
| 11 |
|
| 12 |
## Using Texdoc |
| 13 |
|
| 14 |
Texdoc is part of the TeX Live distribution. Generally, you don't have to install it yourself. |
| 15 |
|
| 16 |
If you want to try/test the develop version, please see below. |
| 17 |
|
| 18 |
## How to Install the Develop Version |
| 19 |
|
| 20 |
### Using Bundler |
| 21 |
|
| 22 |
The easiest way to install the develop version of Texdoc is using [Bundler](https://bundler.io/) and [Rake](https://github.com/ruby/rake): |
| 23 |
|
| 24 |
```shell |
| 25 |
bundle install |
| 26 |
rake install |
| 27 |
``` |
| 28 |
|
| 29 |
If you want to uninstall the develop version (to use the TeX Live version), just try: |
| 30 |
|
| 31 |
```shell |
| 32 |
rake uninstall |
| 33 |
``` |
| 34 |
|
| 35 |
### Installing manually |
| 36 |
|
| 37 |
Here, `$TEXDOC` means the path to the texdoc dev sources you cloned (or downloaded), and `$TEXMFHOME` denotes your personal TEXMF tree (you can get its location with `kpsewhich --var-value TEXMFHOME`). |
| 38 |
|
| 39 |
* **The command.** Symlink or copy `$TEXDOC/script` as `$TEXMFHOME/scripts/texdoc`. |
| 40 |
* **The configuration file.** Symlink or copy `$TEXDOC/texdoc.cnf` as `$TEXMFHOME/texdoc/texdoc-dist.cnf` (notice the `-dist` part). It will completely override the other configuration files except `$TEXMFHOME/texdoc/texdoc.cnf` which you can still use for you personal settings. |
| 41 |
|
| 42 |
You can make sure that the right files are used by running `texdoc --files`: the first line contains the full path to the version of used `texdoclib.tlu`, and the rest lists the configuration files in use. |
| 43 |
|
| 44 |
## Files in This Repository |
| 45 |
|
| 46 |
- `doc/` contains the documentation, |
| 47 |
- `script/` contains the source code, |
| 48 |
- `spec/` is a directory for testing scripts, and |
| 49 |
- `texdoc.cnf` is the default configuration file. |
| 50 |
|
| 51 |
## Building and Testing |
| 52 |
|
| 53 |
Many building tasks are defined as [Rake](https://github.com/ruby/rake) tasks. |
| 54 |
|
| 55 |
### Generating all documentation |
| 56 |
|
| 57 |
The following will generate both the PDF and the manpage in `doc/` directory. |
| 58 |
|
| 59 |
```shell |
| 60 |
rake doc |
| 61 |
``` |
| 62 |
|
| 63 |
### Generating a pre-hashed cache file |
| 64 |
|
| 65 |
The following will generate a pre-hashed cache file `script/Data.tlpdb.lua`. This task have to be done under a TeX Live setup with tlpdb. |
| 66 |
|
| 67 |
```shell |
| 68 |
rake gen_datafile |
| 69 |
``` |
| 70 |
|
| 71 |
### Running tests |
| 72 |
|
| 73 |
The following will run all tests in `spec/` directory. |
| 74 |
|
| 75 |
```shell |
| 76 |
rake test |
| 77 |
``` |
| 78 |
|
| 79 |
Alternatively, you can give spec names with the `--list` (`-l`) option for this task. E.g., following will run only `spec/action/help_spec.rb` and `spec/mode/list_spec.rb`: |
| 80 |
|
| 81 |
```shell |
| 82 |
rake test -- -l action/help,mode/list |
| 83 |
``` |
| 84 |
|
| 85 |
### Showing all available tasks |
| 86 |
|
| 87 |
Following will show all available tasks with a short description. |
| 88 |
|
| 89 |
```shell |
| 90 |
rake -T |
| 91 |
``` |
| 92 |
|
| 93 |
In addition to that, for options available tasks, e.g., `rake test` and `rake run_texdoc`, you can get options information with `-h` option for each task: |
| 94 |
|
| 95 |
```shell |
| 96 |
rake test -- -h |
| 97 |
``` |
| 98 |
|
| 99 |
## Further Information |
| 100 |
|
| 101 |
More specific information, such as the TODO list of this project and some information for distributors, can be found in the Wiki of our GitHub repository. Please visit: |
| 102 |
|
| 103 |
* <https://github.com/TeX-Live/texdoc/wiki> |
| 104 |
|
| 105 |
## Copyright and License |
| 106 |
|
| 107 |
Copyright 2008-2025 Manuel Pégourié-Gonnard, Takuto Asakura, the TeX Live Team. |
| 108 |
|
| 109 |
This package is distributed under the terms of the GNU General Public License as published by the Free Software Foundation, either [version 3](./COPYING) of the License, or (at your option) any later version. |
| 110 |
|
| 111 |
Previous work (texdoc program) in the public domain: |
| 112 |
|
| 113 |
* Contributions from Reinhard Kotucha (2008). |
| 114 |
* First texlua versions by Frank Küster (2007). |
| 115 |
* Original shell script by Thomas Esser, David Aspinall, and Simon Wilkinson. |