Metadata-Version: 2.4
Name: jargon-file
Version: 0.1.0
Summary: Small utility to convert the Jargon File DocBook XML and print random entries.
Project-URL: Homepage, https://github.com/rdubar/jargon
Project-URL: Repository, https://github.com/rdubar/jargon
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: lxml>=4.9
Description-Content-Type: text/markdown

# Jargon utility

Small CLI for browsing the Jargon File from your terminal — random entries, term lookups, colored output. Supports both the classic ESR edition and the actively maintained community edition.

> "The Jargon File is a glossary and usage dictionary of slang used by computer programmers. The original Jargon File was a collection of terms from technical cultures such as the MIT AI Lab, the Stanford AI Lab (SAIL) and others of the old ARPANET AI/LISP/PDP-10 communities, including Bolt, Beranek and Newman (BBN), Carnegie Mellon University, and Worcester Polytechnic Institute. It was published in paperback form in 1983 as The Hacker's Dictionary (edited by Guy Steele) and revised in 1991 as The New Hacker's Dictionary (ed. Eric S. Raymond; third edition published 1996)." — [Wikipedia](https://en.wikipedia.org/wiki/Jargon_File)

## Data sources

- **Classic edition** — Jargon File 4.1.0 (DocBook XML), last updated 2003 by Eric S. Raymond. Bundled with this repo.
- **Community edition** — [agiacalone/jargonfile](https://github.com/agiacalone/jargonfile), actively maintained. Downloaded on demand with `jargon fetch`.

## Install

### Quick (no clone)
```bash
uv tool install 'git+https://github.com/rdubar/jargon.git'
# or:
pipx install 'git+https://github.com/rdubar/jargon.git'
```

### From a clone
```bash
gh repo clone rdubar/jargon && cd jargon
uv venv && source .venv/bin/activate
uv pip install -e .
```

## Usage

**Classic edition (default)**
```bash
jargon                  # random entry
jargon endian           # look up a term (case-insensitive, partial match ok)
jargon --all            # show all senses for the entry
jargon build            # rebuild JSON from bundled XML
```

**Community edition**
```bash
jargon fetch            # download & parse community data (~2300 entries)
jargon -c               # random entry from community data
jargon -c ABEND         # look up a term in community data
jargon -c --all         # show all senses
```

## Commands

| Command | What it does |
|---------|-------------|
| `jargon [term]` | Random entry, or look up a term in the classic edition |
| `jargon build` | Rebuild JSON from bundled DocBook XML |
| `jargon fetch` | Download community edition and build local JSON cache |
| `jargon -c [term]` | Random entry or lookup from community edition |

**Flags:** `--all` / `-a` show all senses · `--rebuild` / `-r` force JSON regeneration · `--xml` / `--json` override data paths

## Data files

- `data/jargon.xml` — bundled classic DocBook source
- `data/jargon.json` — generated from XML (auto-built on first run)
- `data/community.json` — generated by `jargon fetch` (gitignored, local only)

## Notes

- Requires Python 3.10+.
- If the console script isn't on your PATH, run `python jargon_tool.py --help`.

## License

The utility code is MIT licensed — see [LICENSE](LICENSE).

The bundled Jargon File data (`data/jargon.xml`) is copyright 1993 Eric S. Raymond, all rights reserved, and is included here for personal and educational use only.

## Author

**Roger Dubar** — [rdubar@gmail.com](mailto:rdubar@gmail.com) — [github.com/rdubar](https://github.com/rdubar)

## Credits

Jargon File 4.1.0 by Eric S. Raymond <esr@snark.thyrsus.com> — https://catb.org/jargon/

The actively maintained community edition of the Jargon File is at [agiacalone/jargonfile](https://github.com/agiacalone/jargonfile) — submissions and corrections welcome there.
