Skip to content

docs(const,vendor): six :rfc:959#section-4.1 citations name an anchor RFC 959 does not have #944

Closed

Description

@JarryShaw

Describe the bug

Six :rfc: citations name 959#section-4.1. The fragment is well-formed but the anchor does not exist, so each renders a live link to nothing — the same user-visible defect as #942's secion-3, reached a different way. #943's new shape invariant cannot catch this class, by design: it checks that a fragment looks like an anchor, never that the anchor is real.

RFC 959 predates per-subsection anchors. Its rendered HTML carries only eight section- ids — section-1 through section-8 — on both mirrors:

$ curl -s -A 'Mozilla/5.0' -L https://www.rfc-editor.org/rfc/rfc959.html | grep -o 'id="section-[0-9.]*"' | sort -u
id="section-1" id="section-2" id="section-3" id="section-4" id="section-5" id="section-6" id="section-7" id="section-8"
$ ... | grep -c 'id="section-4\.1"'
0

Identical result from https://datatracker.ietf.org/doc/html/rfc959.

Reproduction

$ grep -rn '959#section-4\.1' pcapkit/ | grep -v __pycache__
pcapkit/const/ftp/command.py:187        pcapkit/vendor/ftp/command.py:199
pcapkit/const/ftp/command.py:261        pcapkit/vendor/ftp/command.py:273
pcapkit/const/http/method.py:268        pcapkit/vendor/http/method.py:173

Three template/generated pairs. The string is a literal in each vendor/ template, not synthesised, so both halves are hand-editable — no regeneration or IANA crawl is needed.

Expected behavior

A fragment that resolves. This needs a judgement rather than a spelling fix, which is why it is its own issue:

  • #section-4 — resolves, and §4 "FILE TRANSFER FUNCTIONS" does contain §4.1 "FTP COMMANDS". Loses precision.
  • #page-N — page- is a real anchor form (id="page-5" verified present) and Sphinx titles it, per sphinx.roles._format_rfc_target, whose known set is {'appendix', 'page', 'section'}. Precise but brittle against re-pagination.
  • Drop the fragment and cite :rfc:959`` plainly.

My lean is #section-4, but the call is the maintainer's.

Notes

System information

  • pcapkit commit 9ea0d6a5a, Python 3.14.7, CPython, Linux.

Activity

  1. added
    bugIssues reporting a defect (set by the bug report template; a default, not an assessment)
    docsPull requests that change documentation only (docs: subject prefix)
    constRegenerated IANA or vendor constant tables; members keep their numeric values
    needs: decisionWaiting on the maintainer to decide — not blocked by other work
    on Sep 30, 2026
  2. JarryShaw commented on Sep 30, 2026

    @JarryShaw
    OwnerAuthor

    Sure section-4 is good.

  3. JarryShaw commented on Sep 30, 2026

    @JarryShaw
    OwnerAuthor

    Ruling from the maintainer — #section-4 it is. Verbatim:

    Sure section-4 is good.

    So all six sites become ``:rfc:959#section-4```. #page-N` and the bare-`:rfc:` option are both declined.

    Re-verified on current main (d7489c61c, after #943 and #945 merged) — all six are still present and the count is unchanged:

    pcapkit/const/ftp/command.py:187    pcapkit/vendor/ftp/command.py:199
    pcapkit/const/ftp/command.py:261    pcapkit/vendor/ftp/command.py:273
    pcapkit/const/http/method.py:268    pcapkit/vendor/http/method.py:173
    

    Three template/generated pairs, each a literal in the vendor/ template, so both halves are hand-edited and no crawl or regeneration is needed. #943's shape invariant already accepts section-4, so the fix is inside the existing test's grammar.

    Labels: needs: decision off, wip on. A worker is on it.

  4. added
    wipWork in flight - a covering PR is open or an agent is actively on it
    and removed
    needs: decisionWaiting on the maintainer to decide — not blocked by other work
    on Sep 30, 2026
  5. removed
    wipWork in flight - a covering PR is open or an agent is actively on it
    on Sep 30, 2026
  6. added this to the 1.5 milestone on Oct 6, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugIssues reporting a defect (set by the bug report template; a default, not an assessment)constRegenerated IANA or vendor constant tables; members keep their numeric valuesdocsPull requests that change documentation only (docs: subject prefix)

    Projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions