Script: HTML `_static/` gets 225 macOS AppleDouble files (`._*`) from the Runestone Services archive

Open Beginner friendly
#3,249 3 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
72/100
Issue type
Bug
Clarity
Clearly specified
Activity status
Active
Tech stack
python
Domain
build-system

Research direction

The extraction happens in _place_runestone_services in pretext/lib/pretext.py (around lines 3958-3959), where tarfile.extractall(build_dir) unpacks every member. Reproduce by running an HTML build with the default static files and counting ._* entries in _static/, which should be 225. The fix is to filter out members whose basename starts with ._ before extracting; done means no ._* files appear in the output and the other static files are unchanged.

Written by the indexing model from the issue text.

Description

Summary

Every HTML build that places Runestone Services in its own output (the default; not portable
HTML, nor resources from the CDN) ends up with 225 macOS AppleDouble
files in _static/, one beside each real file:

_static/._139.6404c46752b3e634.js
_static/._139.6404c46752b3e634.js.gz
_static/._139.6404c46752b3e634.js.map
...

Each is 163 bytes of Finder metadata (file reports "AppleDouble encoded Macintosh
file"), used by nothing. They are harmless in a browser, but they double the file count
of _static/ (450 files where 225 are wanted), and they travel with every site that is
uploaded or zipped from the output.

Cause

They are in the archive itself. dist-8.3.2.tgz from https://runestone.academy/cdn/runestone/
has 450 entries, 225 of them ._*, all owned by bmiller/staff; dist-8.2.13.tgz is the
same. This is what macOS tar does by default: it writes each file's extended
attributes as a ._ companion. The archive also carries LIBARCHIVE.xattr.com.apple.provenance
headers, which GNU tar reports as "Ignoring unknown extended header keyword" on every
entry; Python's tarfile passes over those silently.

_place_runestone_services (pretext/lib/pretext.py, lines 3958–3959 at 20d10545)
unpacks everything:

            services_file = tarfile.open(services_build_path)
            services_file.extractall(build_dir)

Suggested fix

Either end would do, and both would be best.

In the script, skip the AppleDouble members when extracting:

            services_file = tarfile.open(services_build_path)
            members = [m for m in services_file.getmembers()
                       if not os.path.basename(m.name).startswith("._")]
            services_file.extractall(build_dir, members=members)

Tried on dist-8.3.2.tgz: 225 files come out, none of them ._*, and they are exactly
the files a build places now, less the AppleDouble ones.

In the Runestone packaging, make the archive without the macOS metadata, for example
COPYFILE_DISABLE=1 tar --no-xattrs -czf dist-<version>.tgz ..., which also removes the
provenance headers. That fix belongs to the Runestone side.

Reproduce

Any HTML build with the default static files, at 20d10545:

pretext -c doc -f html -p publication.ptx -d out main.ptx
ls -A out/_static | grep -c '^\._'        # 225
Dominant language
XSLT
Stars
466
Forks
251
Avg merge
4m
Merged PRs (30d)
13

Getting set up

This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.

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.

More from PreTeXtBook/pretext

All issues in PreTeXtBook/pretext

Similar issues

More Build System issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.