| 1 |
# Contributing to `ltx-talk` |
| 2 |
|
| 3 |
## Project goals |
| 4 |
|
| 5 |
To help you focus contributions in areas that are likely to be accepted, there |
| 6 |
are some broad goals that are worth bearing in mind |
| 7 |
|
| 8 |
- The core aim of `ltx-talk` is to create tagged PDFs for presentations |
| 9 |
- As far as possible, `ltx-talk` is self-contained, building on functionality of |
| 10 |
the LaTeX kernel, including the development code in |
| 11 |
[`latex-lab`](https://ctan.org/pkg/latex-lab) |
| 12 |
- At the same time, if there is a well-established third-party method to handle |
| 13 |
_required_ functionality, this should be used in preference to _ad hoc_ code |
| 14 |
in the class |
| 15 |
- As we are building on 'template' ideas being developed in the LaTeX kernel, |
| 16 |
some functionality may have to be deferred until the kernel work is ready |
| 17 |
- Unlike [`beamer`](https://ctan.org/pkg/beamer), the aim is to avoid adding |
| 18 |
'useful' ideas that are not tied to presentations; for example, the |
| 19 |
[`tcolorbox`](https://ctan.org/pkg/tcolorbox) package is capable of making a |
| 20 |
range of 'visually impactful' structures similar to `beamer`'s |
| 21 |
`beamercolorbox` |
| 22 |
- Whilst tagging is important, _fixing_ tagging should be done by package |
| 23 |
maintainers: the only tagging `ltx-talk` sets is that it controls |
| 24 |
- Again in contrast to `beamer`, 'themes' are not part of the `ltx-talk` |
| 25 |
approach: the aim is instead to have general mechansisms for adjustment and |
| 26 |
good examples of how users can use these |
| 27 |
|
| 28 |
## What we accept |
| 29 |
|
| 30 |
- Bug fixes |
| 31 |
- Documentation improvements |
| 32 |
- New or improved exampls (in `examples/`) |
| 33 |
- Enhancements that align with the project's goals |
| 34 |
- Changes that keep the public interface tidy |
| 35 |
|
| 36 |
## What to avoid |
| 37 |
|
| 38 |
- _New_ third-party package dependencies unless there is clear reasons |
| 39 |
- Color themes |
| 40 |
|
| 41 |
## Workflow |
| 42 |
|
| 43 |
1. Open an issue describing the bug or change, with an example showing the |
| 44 |
desired behavior |
| 45 |
2. Submit a PR addressing that issue. Include: change description, a minimal |
| 46 |
example (or updated example in `examples/`), and any test or `l3build` check |
| 47 |
that demonstrates the change |
| 48 |
3. If the change impacts tagging, please check the structure using |
| 49 |
[ngPDF](https://ngpdf.com) and include this information in the PR text |
| 50 |
|
| 51 |
## Final notes |
| 52 |
|
| 53 |
- Keep changes small and focused, prefer conservative and well-documented edits, |
| 54 |
and provide examples that make behaviour easy to verify |
| 55 |
- If you're unsure whether a change fits the project's goals, open an issue |
| 56 |
before spending time writing the code! |
| 57 |
|
| 58 |
Thanks — your contributions make `ltx-talk` better! |