akiomik / akiomik/bela-rs

Links out of the package dangle on crates.io, and the rule for them is stated but not followed

Đang mở
#159 0 bình luận 0 reaction 0 người được giao Xem trên GitHub
documentation
Ngôn ngữ chính
Rust
Star
1
Fork
0
Merge trung bình
5 giờ 19 phút
Pull request đã merge (30 ngày)
26

Mô tả

`bela-sys/Cargo.toml` and `bela/Cargo.toml` both set `readme = "README.md"`, so both files are rendered on crates.io with no repository around them. A link that walks out of the package directory has nothing to walk to there.

`bela/README.md` knows this and says so, at its `docs/fft.md` link:

> Both links are absolute because this file is read on crates.io, where the repository around it is not there.

Neither file follows it. Counted on `docs/scope-inventory` (`grep -n '](\.\./' bela/README.md bela-sys/README.md`), **fourteen links leave a package directory**: nine in `bela-sys/README.md` — `docs/fft.md`, `docs/board-facts.md`, `docs/midi.md`, `docs/scope.md`, `bela/README.md`, and `docs/cross-compile.md` four times — and five in `bela/README.md`, the file that states the rule: `bela-sys`, `docs/multithreaded-rendering.md`, the repository `README.md`, and `docs/cross-compile.md` twice.

Nothing here is broken in the repository — every one resolves on GitHub. It is only the published rendering that loses them, which is why it has gone unnoticed.

## Why this is not a "make them all absolute" one-liner

An absolute link pins a branch. `https://github.com/akiomik/bela-rs/blob/main/...` follows `main`, so a crates.io page for 0.8.1 sends its reader to whatever the file says now. That is fine for `cross-compile.md`, which describes a procedure, and less fine for anything describing what a version has. The two absolute links already in `bela/README.md` accept that trade; a sweep should decide it deliberately rather than inherit it fourteen more times.

The alternative is to stop linking out of the package and name the path in prose, which is what `bela`'s rustdoc does with `docs/`: 43 of its 44 mentions are prose and exactly one is a link. That reads worse in a README and never dangles.

A third answer is to package the files — `include = [...]` in each `Cargo.toml` — which would make the relative links correct where they are read. That has its own cost: `docs/` is 3400 lines and would ship with both crates.

Any of the three is fine. What is not fine is the current state, where the rule is written down in one file and followed in neither.

Found while reviewing #157, which added a fifteenth such link, made it absolute, and then took the absolute form back out rather than widen a documentation pull request into this.

Hướng dẫn đóng góp

Mở hướng dẫn đóng góp

Đánh giá

Issue này chưa được đánh giá.

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.