### Texdoc Zsh Shell Completion Setup

Source: https://context7.com/tex-live/texdoc/llms.txt

Provides instructions for setting up shell completion for the texdoc command in zsh. It shows how to generate the completion script and install it either by evaluating it in the zshrc file or by placing it in the fpath directory. Examples of usage with tab completion are also included.

```bash
# Generate zsh completion script
texdoc --print-completion zsh > _texdoc

# Install completion (Option 1: eval in .zshrc)
echo 'eval "$(texdoc --print-completion zsh)"' >> ~/.zshrc

# Install completion (Option 2: file in fpath)
texdoc --print-completion zsh > ~/.zsh/completions/_texdoc
# Ensure fpath includes ~/.zsh/completions

# Usage after installation:
texdoc hyp<TAB>         # Completes to hyperref, hyph-utf8, etc.
texdoc --<TAB>          # Shows --help, --version, --list, etc.
texdoc -d <TAB>         # Shows debug categories

```

--------------------------------

### Texdoc Alias System Examples

Source: https://context7.com/tex-live/texdoc/llms.txt

Demonstrates the use of aliases in `texdoc.cnf` to map search terms to specific documentation files or commands. Includes examples of basic aliases, aliasing with custom scores, and language-specific aliases.

```ini
# texdoc.cnf - Alias examples

# Basic alias: searching "td" finds texdoc documentation
alias td = texdoc

# Alias with custom score (default is 10)
alias(20) fontenc = encguide
alias(5) metapost = mpgraph

# Multiple aliases for same keyword
alias latex3 = ltx3info
alias l3 = interface3
alias(9) l3 = source3

# Language-specific aliases
alias lshort-de = l2kurz
alias lshort-ja = jlshort
alias koma-de = scrguide-de

# TeX engine references
alias pdftex = pdftex-a
alias xetex = xetex-reference
alias luatex = luatex.man1
```

--------------------------------

### Texdoc Configuration File Format (texdoc.cnf)

Source: https://context7.com/tex-live/texdoc/llms.txt

Provides an example of the `texdoc.cnf` file format, detailing how to set default modes, viewers, search parameters, and document extensions. Supports comments and line continuation.

```ini
# texdoc.cnf - Personal configuration example
# Place in: $TEXMFHOME/texdoc/texdoc.cnf

# Set default mode to list
mode = list

# Enable interactive menus
interact_switch = true

# Set maximum results before prompting
max_lines = 15

# Set verbosity (0=nothing, 1=errors, 2=warnings, 3=info)
verbosity_level = 2

# Custom viewers (platform-specific)
viewer_pdf = evince %s &
viewer_html = firefox %s &
viewer_txt = less

# Document extensions to recognize (comma-separated, empty = no extension)
ext_list = pdf, html, htm, txt, md, ps, dvi,

# Bad extensions (get lower scores)
badext_list = txt, dat,

# Known suffixes for documentation naming patterns
suffix_list = doc, -doc, _doc, manual, -manual, guide

# Fuzzy search tolerance (Levenshtein distance, 0=disabled)
fuzzy_level = 3

# Online documentation URL (PKGNAME is replaced)
online_url = https://texdoc.org/serve/PKGNAME/0

# Line continuation with backslash
suffix_list = doc, -doc, _doc, .doc, /doc, manual, /manual, -manual, \
              userguide, /user_guide, -guide, -user, man, -man
```

--------------------------------

### Invoking Texdoc from a Custom TEXMF Tree (Shell)

Source: https://github.com/tex-live/texdoc/wiki/Invoking-Texdoc-without-switching-the-TEXMF-trees

This snippet demonstrates how to execute the Texdoc program when it's installed in a custom TEXMF tree. It requires the `texlua` interpreter and specifies the path to the `texdoc.tlu` script. The arguments passed will be processed by Texdoc.

```shell
texlua <YOUR TEXMF>/scripts/texdoc/texdoc.tlu <arguments>
```

--------------------------------

### Rake Build Tasks for Texdoc

Source: https://context7.com/tex-live/texdoc/llms.txt

Lists common Rake tasks used for building, testing, and managing the texdoc project. This includes installing dependencies, installing/uninstalling the development version, generating documentation, creating data files, running tests, and viewing available tasks or task help.

```bash
# Install development dependencies
bundle install

# Install development version to TEXMFHOME
rake install

# Uninstall development version
rake uninstall

# Generate documentation (PDF manual and man page)
rake doc

# Generate pre-hashed TLPDB cache file
rake gen_datafile

# Run all tests
rake test

# Run specific test files
rake test -- -l action/help,mode/list

# Show all available tasks
rake -T

# Get help for a specific task
rake test -- -h

```

--------------------------------

### Texdoc Exit Codes for Scripting

Source: https://context7.com/tex-live/texdoc/llms.txt

Explains the different exit codes returned by the texdoc command, which are useful for scripting and automation. It covers success (0), usage errors (2), and cases where no documentation is found (3), along with a script example demonstrating how to check these exit codes.

```bash
# Success (documentation found and displayed)
texdoc hyperref
echo $?  # 0

# Usage error (invalid options)
texdoc --invalid-option
echo $?  # 2

# No documentation found
texdoc nonexistent-package-xyz
echo $?  # 3

# Script example checking exit codes
#!/bin/bash
if texdoc --nointeract "$1" 2>/dev/null; then
    echo "Documentation found for $1"
else
    case $? in
        1) echo "Internal error" ;; # Note: Exit code 1 is not explicitly defined in the text but is a common convention for internal errors.
        2) echo "Usage error" ;; 
        3) echo "No documentation found for $1" ;; 
    esac
fi

```

--------------------------------

### Check Aliases in texdoc.cnf

Source: https://github.com/tex-live/texdoc/wiki/Maintenance-note

Executes a rake task to verify all aliases within the distributed `texdoc.cnf` file. This task requires the latest version of TeX Live to be installed.

```shell
rake check_aliases

```

--------------------------------

### Basic Texdoc Command-Line Usage

Source: https://context7.com/tex-live/texdoc/llms.txt

Demonstrates fundamental ways to use the `texdoc` command to search for and view documentation. Includes basic search, listing results, and viewing specific files.

```bash
# Basic usage - view documentation for a package
texdoc hyperref

# List mode - show all matching results interactively
texdoc --list tikz

# Mixed mode - view if single result, list if multiple
texdoc --mixed beamer

# Show all results including low-scoring matches
texdoc --showall latex

# Non-interactive mode for scripting
texdoc --nointeract --list pgf

# Machine-readable output (tab-separated)
texdoc --machine koma-script
# Output: koma-script	10	/path/to/scrguide-en.pdf	en	KOMA-Script guide

# View a specific file directly (no searching)
texdoc --just-view /usr/local/texlive/2024/texmf-dist/doc/latex/hyperref/hyperref.pdf

# Show version information
texdoc --version
# Output: Texdoc 4.1.1 (2025-02-11)

# Display configuration files in use
texdoc --files
# Output:
# /path/to/texdoclib.tlu 4.1.1
# Configuration file(s):
#     active	/usr/local/texlive/2024/texmf-dist/texdoc/texdoc.cnf

# Search multiple packages at once
texdoc amsmath amssymb amsthm
```

--------------------------------

### Texdoc Configuration and Debugging Options

Source: https://context7.com/tex-live/texdoc/llms.txt

Illustrates how to configure Texdoc's behavior using command-line flags and environment variables. Includes options for setting modes, verbosity, debugging, and specifying custom viewers.

```bash
# Set configuration item from command-line
texdoc -c mode=list latex
texdoc -c verbosity_level=3 -c max_lines=20 pgf

# Debug output for troubleshooting
texdoc --debug=search,score hyperref
# Available debug categories: config, files, search, docfile, score, texdocs, tlpdb, version, view, all

# Quiet mode (suppress warnings)
texdoc --quiet latex

# Verbose mode (show viewer commands)
texdoc --verbose tikz
# Output includes: Info: View command: (xdg-open "/path/to/pgfmanual.pdf") &

# Environment variables for viewers
export PDFVIEWER_texdoc="evince"
export BROWSER_texdoc="firefox"
export PAGER_texdoc="less"
texdoc hyperref  # Uses evince for PDF viewing

# Language preference via environment
export LANGUAGE_texdoc=de
texdoc koma-script  # Prioritizes German documentation
```

--------------------------------

### Texdoc Lua Library API Usage

Source: https://context7.com/tex-live/texdoc/llms.txt

Demonstrates how to use the texdoclib Lua library programmatically. It covers accessing version information, initializing databases, searching for documentation, iterating through results, viewing files, retrieving configuration values, and performing fuzzy searches with Levenshtein distance calculations.

```lua
-- texdoclib usage example (requires texlua environment)
local texdoc = require('texdoclib')

-- Access version information
print(texdoc.const.progname)      -- "Texdoc"
print(texdoc.const.version)       -- "4.1.1"
print(texdoc.const.release_date)  -- "2025-02-11"

-- Initialize databases (required before searching)
texdoc.search.init_databases()

-- Search for documentation
local doclist = texdoc.search.get_doclist("hyperref")

-- Iterate through results
for i, doc in ipairs(doclist) do
    print(string.format("%d. %s (score: %s)",
        i,
        doc.realpath,   -- Full path to file
        doc.score       -- Numeric score
    ))
    -- Additional docfile properties:
    -- doc.basename    - Filename without path
    -- doc.normname    - Normalized path
    -- doc.lang        - Language code (if available)
    -- doc.details     - Description from CTAN catalogue
    -- doc.quality     - "good", "bad", or "killed"
end

-- View a file directly
texdoc.view.view_file("/path/to/document.pdf")

-- Get configuration values
local mode = texdoc.config.get_value("mode")
local max_lines = texdoc.config.get_value("max_lines")

-- Fuzzy search for closest package name
local closest, distance = texdoc.search.fuzzy_search("hyprref")
print(closest)    -- "hyperref"
print(distance)   -- 1 (Levenshtein distance)

-- Levenshtein distance calculation
local dist = texdoc.search.levenshtein("latex", "laetx")
print(dist)  -- 2

```

--------------------------------

### Zsh Shell Completion for Texdoc (Simple Version)

Source: https://github.com/tex-live/texdoc/wiki/Tab-completion

Provides a simpler method for zsh tab completion for texdoc. It uses compctl with awk and kpsewhich to dynamically generate the list of package names from the texlive.tlpdb file. This can be added to the .zshrc file.

```shell
compctl -k "$(($(awk '/^name[^.]*$/ {print $2}' $(kpsewhich -var-value TEXMFROOT)/tlpkg/texlive.tlpdb)))" texdoc
```

--------------------------------

### RSpec Command for Texdoc Tests

Source: https://github.com/tex-live/texdoc/blob/master/spec/README.md

This command directly invokes RSpec to run tests for the Texdoc 'version' action. The '-fd' option specifies the 'documentation' format, which displays detailed output of the tests being executed, including their descriptions and outcomes.

```shell
bundle exec rspec -fd spec/action/version_spec.rb
```

--------------------------------

### Bump Version and Tag Release

Source: https://github.com/tex-live/texdoc/wiki/Maintenance-note

Automates the process of updating the project's version number, committing the changes, and creating a Git tag for the new release. This involves setting a new version variable and executing rake and git commands.

```shell
NEW_TEXDOC_VERSION=<new version>
rake bump_version -- $NEW_TEXDOC_VERSION
git add -A
git commit -m "bump version to $NEW_TEXDOC_VERSION"
git tag v$NEW_TEXDOC_VERSION
git push
git push --tags

```

--------------------------------

### Running Texdoc Tests with Rake

Source: https://github.com/tex-live/texdoc/blob/master/spec/README.md

This command executes Texdoc tests using the 'rake test' task, which automatically generates TEXMF trees in a temporary directory and sets up the testing environment. It also demonstrates passing RSpec options like limiting tests and setting the output format.

```shell
rake test -- -l action/version -o "-fd"
```

--------------------------------

### Create CTAN Archive

Source: https://github.com/tex-live/texdoc/wiki/Maintenance-note

Generates an archive file suitable for distribution on CTAN. This is typically done using a specific rake task after the version has been bumped and tagged.

```shell
rake ctan

```

--------------------------------

### Configure Alias for External Documents in Texdoc

Source: https://github.com/tex-live/texdoc/wiki/TODO

This configuration allows users to specify absolute paths for documents that are not part of the standard TeX Live distribution. By using the `alias*` directive in `texdoc.cnf`, users can map a given name to a specific PDF file, enabling Texdoc to find and open it.

```texdoc.cnf
alias* foo = /path/to/your/foobar.pdf
```

--------------------------------

### Bash Shell Completion for Texdoc

Source: https://github.com/tex-live/texdoc/wiki/Tab-completion

Configures bash to provide tab completion for texdoc. It uses awk and kpsewhich to parse the texlive.tlpdb file and generate a list of package names for completion. This is typically added to the .bashrc file.

```shell
complete -W "$(awk '/^name[^.]*$/ {print $2}' $(kpsewhich -var-value TEXMFROOT)/tlpkg/texlive.tlpdb)" texdoc
```

--------------------------------

### Texdoc Configuration Score Adjustments

Source: https://context7.com/tex-live/texdoc/llms.txt

Defines score adjustments in texdoc.cnf to fine-tune search result rankings. It includes global adjustments for excluding directories or demoting certain file types, and per-keyword adjustments to prioritize or demote specific terms or file patterns. The 'stopalias' and 'noadjscore' directives are also shown for controlling aliasing and score adjustments.

```ini
# texdoc.cnf - Score adjustment examples

# Global adjustments (apply to all searches)
adjscore /Makefile = -1000          # Never show Makefiles
adjscore /src/ = -1000              # Exclude source directories
adjscore /source/ = -1000           # Exclude source directories
adjscore copying = -10              # Demote license files
adjscore license = -10
adjscore example = -1               # Slightly demote examples
adjscore test = -3                  # Demote test files

# Per-keyword adjustments
adjscore(tex) texdoc = -10          # "texdoc" isn't TeX documentation
adjscore(latex) /latex/ = -4        # Too generic for latex query
adjscore(latex) /latex/base/ = +5   # Prioritize official base docs
adjscore(beamer) presentations = -10

# Prioritize specific files
adjscore(inputenc) inputenc.pdf = +5
adjscore(pgf) pgfmanual.pdf = +5

# Reset score adjustment (in personal config)
noadjscore /Makefile

```

--------------------------------

### Save and Compare Search Results

Source: https://github.com/tex-live/texdoc/wiki/Maintenance-note

Saves featured search results to the `output` directory using a rake task. The saved results can then be compared against previous versions using the `diff` utility to identify changes.

```shell
rake save_output

```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.