[soloturn]

Alternative to this PR's resolveTargetURL/UrlUtils approach, implementing the design @kelson42 actually asked for:

The topic has been again discussed live in the last days, and here is the clear requirements my sides:

• mini-html redirections are a workaround and as such we are no[t] building anything sustainable around them
• there is in particular no requirement to have a "smart" libzim around mini-html
• since the very beginning of the libzim, an effort has been made to have the libzim pretty agnostic about the type of data save[d] in it. It is important to not build anything related to mini-html in the libzim (for this reason as well)

and, from the linked issue:

• Against any modification of the meaning of # in the path...
• We have a way to store the fragment string in the corresponding dirent parameter and we should use that. Very important is to start a proper/robust (json?) structure in this dirent parameter...
• We should not create a new type or new naming of redirects here. We should just allow to get/set an optional fragment with the current standard redirection related API primitives.

What this does instead

• No path parsing, no #/? component splitting, nothing that gives those characters special meaning in a ZIM path.
• No mini-HTML inspection or "smart" resolution anywhere in libzim.
• The redirect dirent's existing parameter field (present in the format from the start, always empty for redirects until now) optionally carries the fragment, as a minimal tagged record (1-byte tag + 1-byte length + value) rather than pulling in a JSON dependency for one optional string — a tag this version doesn't recognize is skipped, not misread, so a future record type (e.g. Feature request: Add keyword/tag support #317's keywords) can share the field without breaking older readers.
• No new redirect type. Creator::addRedirection() gained one new optional trailing parameter (targetFragment, default ""); Entry gained one new method (getRedirectFragment()) alongside the existing getRedirectEntry()/getRedirectEntryIndex().

A redirect that doesn't use a fragment is byte-for-byte identical to one written before this existed — encodeRedirectParameter("") returns "", the same empty parameter every redirect has always had.

Usage

Writing (scrapers, zimwriterfs, python-libzim/libkiwix bindings): pass the new optional argument to point a redirect at a section of the target, not just the target itself.

creator.addRedirection("shortcut", "Shortcut title", "Article", hints, "Geography");

Reading (kiwix-tools, kiwix-desktop, kiwix-android, libkiwix, or any client walking Entry): ask a redirect entry for its fragment alongside the existing redirect-target accessors.

if (entry.isRedirect()) {
  auto fragment = entry.getRedirectFragment(); // "" if none
  // e.g. append "#" + fragment to a Location header, or jump to the anchor
}

Every existing caller of addRedirection() is unaffected — targetFragment defaults to "", and getRedirectFragment() returns "" for every redirect written before this feature existed.

Worth a maintainer's eyes on

Storing the fragment as a shared_ptr<const string> on writer::Dirent (not an inline string, not unique_ptr — Dirent is copy-constructed into DirentPool's storage, which rules out move-only types) still grows Dirent by one pointer's worth of bytes — 29 → 45 on 64-bit here — for every dirent, not just redirects with fragments. DirentTest.size exists specifically because this matters at the scale of a large ZIM's entry count, so flagging this plainly rather than glossing over it.

Verification

• Full test suite: 31/31 passing.
• Coverage: confirmed via gcovr (llvm-cov gcov backend) that every line this diff touches is exercised — 100% on src/writer/_dirent.h; on the other touched files, the only uncovered lines reported are pre-existing code outside this diff (checked by line number against the actual patch, not just the file-level percentage).
• New tests: codec round-trip/edge-cases (test/tooltesting.cpp), writer/reader dirent round-trip with and without a fragment (test/dirent.cpp), and an end-to-end Creator → Archive → Entry test (test/archive.cpp).

Not attempted

Anything depending on inspecting item content or interpreting #/? as meaningful path characters — both are exactly what's ruled out above, so nothing from this PR's UrlUtils/mini-HTML-parsing approach carries over. The mini-HTML workaround remains the only option for readers that don't understand this new fragment field yet, matching @kelson42's stated interim plan on #1001.

Related: #1001, #317 (future dirent-parameter extension mentioned there).

[kelson42]

@soloturn Can we have a PR which does only things related to the issue and nothing else please?

[soloturn]

@soloturn Can we have a PR which does only things related to the issue and nothing else please?

done.