latex3 / latex3/hyperref

Proposal: split up hyperref.dtx and let it be build only as part of the publish process

Open
#173 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
TeX
Stars
205
Forks
41
PR merge metrics
No merged PRs in 30d

Description

Currently one can not do git log --follow puenc.def because it is embedded into massive titanosaur hyperref.dtx. For ease of maintenance and comfort of eavesdropper owning a local clone, it would be nice if all files were actually existing in the repo, and their combination into hyperref.dtx only done as part of the publish process. I do understand that this refactoring is a bit complicated. And that there will be difference between puenc.def in repo without the docstrip commented header but inclusive of the code comments, and the puenc.def extracted from hyperref.dtx ending up in people's texmf which has a header and is stripped of code comments.

Probably a ready-made solution has been integrated into l3build? I am not familiar with it; all I can say is that I have such an organization for xint. My repo's xintexpr.sty for example contains all code comments (and even private ones which never make it to the dtx, but here on a public repo this of course would make no sense); when pushing a new release to CTAN, a script assembles the xint.dtx. The CTAN-based TeX distros can then extract user xintexpr.sty with no code comments; actually I submit it in tds.zip form so my build ctan script does the docstrip phase itself (all of this happens in sub-directory which is added to .gitignore). The user manual is itself a separate file not using inconvenient doc format, so I can work on it as a perfectly standard latex file, but this is other matter unrelated.

I find this useful, and I have often used git log --follow in this context. Now hyperref has at least 64 extracted files (half of them about being ".drv" files), and I think in the long term such a refactoring will make maintenance easier.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reviewing hyperref.dtx and the extracted puenc.def and .drv files, then compare the proposed organization with l3build and the xint example described in the issue. Define how the repository files and publish process should relate, including the differing headers and code comments. Done means the extracted files are maintainable individually while the publish process still produces hyperref.dtx and usable distribution files.

Written by the indexing model from the issue text.

Assessment

Tech stack
latex
Domain
build-system
Issue type
Refactor
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.