Debian Codegraph @

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

raw
1 # Texdoc ― Find and view documentation in TeX Live
2
3 [![CI](https://github.com/TeX-Live/texdoc/actions/workflows/ci.yml/badge.svg)](https://github.com/TeX-Live/texdoc/actions/workflows/ci.yml)
4 [![CTAN](https://img.shields.io/ctan/v/texdoc?color=FC02FF&label=CTAN&style=flat)](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.