Patroon voor voetnootverwijzing en voetnoottekst via Connect

Patroon voor voetnootverwijzing en -tekst via Connect

In een oogopslag

Geef voetnootverwijzingen en voetnootteksten weer via Connect, zodat de structuurboom de PDF 2.0-voetnootrollen bevat. De inline-markering wordt omgezet naar een footnote/endnote-verwijzing en de voetnoottekst naar een notetekst, met een wederzijdse terugverwijzing tussen beide. Drie HTML-vormen leveren dezelfde uitvoer op: een koppeling binnen een superscript, een expliciete Accessible Rich Internet Applications (ARIA) role="doc-noteref", en een <aside class="footnote">-tekstcontainer. De verificatie gebruikt het toegankelijkheidshulpmiddel op Pro-niveau. NextPDF detecteert dit met class_exists() en registreert het alleen wanneer nextpdf/premium naast de server is geïnstalleerd.

Een geslaagd resultaat van het toegankelijkheidshulpmiddel betekent dat de toegankelijkheidscontrole is geslaagd; het is geen onafhankelijke conformiteitscertificering.

Installeren

composer require nextpdf/server

Controleer met een tools/list-aanroep of het Pro-toegankelijkheidshulpmiddel beschikbaar is; zie /connect/tool-catalog/.

Conceptueel overzicht

PDF 2.0 definieert specifieke footnote/endnote-structuurtypen en de relatie tussen een verwijzing en de bijbehorende tekst (PDF/UA-2 §8.2.5). Een voetnootverwijzing moet aan de bijbehorende tekst zijn gekoppeld (PDF/UA-2 §8.2.5), zodat een schermlezer de verwijzing kan aankondigen en de koppeling kan volgen om de noot te lezen. Zowel de verwijzing als de tekst moeten bereikbaar zijn via de structuurboom (PDF/UA-2 §8.2.4).

De pijplijn herkent drie verwijzingsvormen:

<sup><a href="#fn-N">N</a></sup> — verkorte notatie voor een koppeling in superscript.
<sup role="doc-noteref" aria-describedby="fn-N">N</sup> — expliciete Digital Publishing Accessible Rich Internet Applications (DPUB-ARIA)-rol; aria-describedby wordt doorgegeven als doel van de terugverwijzing.
<aside class="footnote" id="fn-N">…</aside> (of role="doc-footnote") — de tekstcontainer, weergegeven als notetekst met een interne verwijzing terug naar de bijbehorende verwijzing.

API-oppervlak

Controleer hulpmiddelnamen aan de hand van het actieve register met tools/list. De gezaghebbende catalogus is /connect/tool-catalog/. Dit recipe gebruikt de basishulpmiddelen voor documenten en HTML plus de Pro-toegankelijkheidscontrole, en noemt het aantal hulpmiddelen niet opnieuw.

Codevoorbeeld — Snelstart

Maak een getagd document met een ingestelde taal en voeg daarna de verwijzing toe met de verkorte koppelingsnotatie:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "create_pdf",
    "arguments": { "page_size": "A4", "title": "Footnote Patterns", "language": "en" }
  }
}

Codevoorbeeld — Productie

Voeg beide verwijzingen en beide teksten toe via één HTML-toevoeging en voer daarna de controle uit:

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "add_html",
    "arguments": {
      "document_id": "<id from create_pdf>",
      "html": "<p>Revenue grew 24%<sup><a href=\"#fn-1\">1</a></sup>.</p><p>Margin 33%<sup role=\"doc-noteref\" aria-describedby=\"fn-2\">2</sup>.</p><aside class=\"footnote\" id=\"fn-1\"><p>YoY vs prior year.</p></aside><aside class=\"footnote\" id=\"fn-2\" role=\"doc-footnote\"><p>(Revenue − OpEx) / Revenue.</p></aside>"
    }
  }
}

De toegankelijkheidscontrole rapporteert de gekoppelde reference/body-rollen en de wederzijdse terugverwijzingen.

Randgevallen en valkuilen

Verwijzing maar geen tekst (of tekst maar geen verwijzing) wordt door de controle gerapporteerd; elke verwijzing heeft een bijbehorende tekst nodig en omgekeerd.
id-discrepantie tussen aria-describedby en de id van de tekst laat het paar onopgelost (hoofdlettergevoelig).
Een superscript-anker naar een externe URL levert een gewone koppeling op, geen voetnootverwijzing; gebruik de expliciete rol voor een extern doel.
Een kale <aside> zonder class/role wordt behandeld als een oriëntatiepunt, niet als een notetekst. Voeg class="footnote" of role="doc-footnote" toe.
Hulpmiddel afwezig. Zonder nextpdf/premium wordt het Pro-toegankelijkheidshulpmiddel niet geregistreerd, waardoor de verificatie mislukt met een fout voor een onbekend hulpmiddel.

Prestaties

Het budget in de frontmatter is een documentatielimiet; de koppeling van voetnoten maakt deel uit van de normale structuurfase.

Beveiligingsopmerkingen

Niet van toepassing buiten de algemene richtlijnen voor Connect-transport.

Conformiteit

PDF/UA-2-toewijzing

Bewering	Clausule	reference_id
Footnote/endnote-structuurtypen en reference/body-relatie	PDF/UA-2 §8.2.5
Een voetnootverwijzing is gekoppeld aan de bijbehorende tekst	PDF/UA-2 §8.2.5
Verwijzing en tekst bereikbaar via de structuurboom	PDF/UA-2 §8.2.4

Tag → ISO 32000-2 §14.9-kruisverwijzing

De verwijzing en de tekst gebruiken de PDF 2.0-standaardstructuurtypen footnote/endnote. De wederzijdse terugverwijzing vormt het contract voor een toegankelijke voetnoot.

WCAG 2.2-toewijzing

Een gekoppelde voetnootverwijzing en -tekst ondersteunen Web Content Accessibility Guidelines (WCAG) 2.2 SC 1.3.1 (Info and Relationships) en SC 2.4.1 (Bypass Blocks) op contentniveau.

Een geslaagd resultaat van het toegankelijkheidshulpmiddel betekent dat de toegankelijkheidscontrole is geslaagd, geen conformiteitscertificering; die vaststelling gebeurt via een onafhankelijke controle.

Commerciële context

Het hulpmiddel voor de toegankelijkheidscontrole valt onder het Pro-niveau en registreert zich alleen wanneer nextpdf/premium naast de server is geïnstalleerd.

Connect-bijzonderheden

Transportbeschikbaarheid (MCP / REST / gRPC)

create_pdf, add_html en de toegankelijkheidscontrole worden via Model Context Protocol (MCP), REST en gRPC op identieke wijze aangeroepen door de gedeelde hulpmiddeluitvoerder.

HITL-risiconiveau

Documentcreatie en HTML-invoer vallen onder het voorzichtigheidsniveau; de toegankelijkheidscontrole is alleen-lezen. Geen van deze hulpmiddelen is standaard approval_required. Zie /connect/hitl-risk-niveaus/.

JSON-envelop van de bevestigingspoort

Deze hulpmiddelen activeren de poort niet, tenzij een operator-override er een van verhoogt naar approval_required. Het contract voor de envelop en het eenmalige token staat beschreven in /connect/hitl-risk-niveaus/.

Zie ook

/cookbook/connect/aria-tagged-pdf/ — toewijzing van oriëntatiepuntrollen.
/cookbook/connect/figure-caption/ — geneste Figure-/Caption-structuur.
/connect/tool-catalog/ — berekening van de hulpmiddelset per niveau.
/connect/hitl-risk-niveaus/ — het risicomodel en de poort.