Pattern per riferimento e corpo della nota a piè di pagina tramite Connect

In sintesi

Eseguire il rendering dei riferimenti e dei corpi delle note a piè di pagina tramite i trasporti Connect, in modo che l’albero della struttura esponga i ruoli PDF 2.0 delle note a piè di pagina. Il marcatore inline diventa un riferimento footnote/endnote e il testo della nota a piè di pagina diventa il corpo della nota, con un riferimento di ritorno reciproco tra i due. Tre forme HTML producono lo stesso output: un link all’interno di un apice, un attributo ARIA role="doc-noteref" esplicito e un contenitore del corpo <aside class="footnote">. La verifica usa lo strumento di accessibilità di livello Pro. NextPDF lo rileva tramite class_exists() e lo registra solo quando nextpdf/premium è installato insieme al server.

Un esito positivo dello strumento di accessibilità è una verifica di accessibilità, non una certificazione di conformità indipendente.

Installazione

composer require nextpdf/server

Verificare la presenza dello strumento di accessibilità Pro tramite una chiamata tools/list; vedere /connect/tool-catalog/.

Panoramica concettuale

PDF 2.0 definisce tipi di struttura footnote/endnote dedicati e la relazione tra un riferimento e il relativo corpo (PDF/UA-2 §8.2.5). Un riferimento alla nota a piè di pagina deve essere associato al suo corpo (PDF/UA-2 §8.2.5) affinché un lettore di schermo possa annunciare il riferimento e seguire il link per leggere la nota. Sia il riferimento sia il corpo devono essere raggiungibili tramite l’albero della struttura (PDF/UA-2 §8.2.4).

La pipeline riconosce tre forme di riferimento:

<sup><a href="#fn-N">N</a></sup> — forma abbreviata con link in apice.
<sup role="doc-noteref" aria-describedby="fn-N">N</sup> — ruolo DPUB-ARIA esplicito; aria-describedby viene inoltrato come destinazione del riferimento di ritorno.
<aside class="footnote" id="fn-N">…</aside> (oppure role="doc-footnote") — il contenitore del corpo, emesso come corpo della nota con un riferimento interno alla voce di riferimento corrispondente.

Superficie API

Controllare i nomi degli strumenti nel registry in esecuzione tramite tools/list. Il catalogo di riferimento è /connect/tool-catalog/. Questa ricetta usa gli strumenti per documenti e HTML del core più la verifica di accessibilità Pro, senza ripetere il conteggio degli strumenti.

Esempio di codice — Avvio rapido

Creare un documento taggato con una lingua impostata, quindi aggiungere il riferimento in forma abbreviata con link:

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

Esempio di codice — Produzione

Generare entrambi i riferimenti ed entrambi i corpi in un’unica aggiunta di HTML, quindi verificare:

{
  "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>"
    }
  }
}

La verifica di accessibilità riporta i ruoli reference/body abbinati e i riferimenti di ritorno reciproci.

Casi limite e insidie

Riferimento ma nessun corpo (o corpo ma nessun riferimento) viene segnalato dalla verifica; ogni riferimento richiede un corpo corrispondente e viceversa.
Discordanza di id tra aria-describedby e l’id del corpo lascia la coppia irrisolta (sensibile a maiuscole/minuscole).
Un’ancora in apice verso un URL esterno genera un link semplice, non un riferimento alla nota a piè di pagina; usare il ruolo esplicito per una destinazione esterna.
Un <aside> semplice senza class/role viene trattato come un landmark, non come un corpo della nota. Aggiungere class="footnote" oppure role="doc-footnote".
Strumento assente. Senza nextpdf/premium lo strumento di accessibilità Pro non viene registrato, quindi la verifica fallisce con un errore di strumento sconosciuto.

Prestazioni

Il budget nel front matter è un limite documentale; l’abbinamento delle note a piè di pagina fa parte del normale passaggio di strutturazione.

Note di sicurezza

Nulla di specifico oltre alle indicazioni generali sul trasporto Connect.

Conformità

Mappatura PDF/UA-2

Asserzione	Clausola	reference_id
Tipi di struttura footnote/endnote e relazione reference/body	PDF/UA-2 §8.2.5
Un riferimento alla nota a piè di pagina è associato al suo corpo	PDF/UA-2 §8.2.5
Riferimento e corpo raggiungibili tramite l’albero della struttura	PDF/UA-2 §8.2.4

Riferimento incrociato tag → ISO 32000-2 §14.9

Il riferimento e il corpo usano i tipi di struttura standard footnote/endnote di PDF 2.0. Il riferimento di ritorno reciproco costituisce il contratto della nota a piè di pagina accessibile.

Mappatura WCAG 2.2

Un riferimento e un corpo di nota a piè di pagina associati supportano i WCAG 2.2 SC 1.3.1 (Info and Relationships) e SC 2.4.1 (Bypass Blocks) a livello di contenuto.

Un esito positivo dello strumento di accessibilità è una verifica di accessibilità, non una certificazione di conformità; tale determinazione spetta a un checker indipendente.

Contesto commerciale

Lo strumento di verifica dell’accessibilità è di livello Pro e si registra solo quando nextpdf/premium è installato insieme al server.

Specifiche di Connect

Disponibilità dei trasporti (MCP / REST / gRPC)

create_pdf, add_html e la verifica di accessibilità vengono invocati allo stesso modo tramite MCP, REST e gRPC attraverso l’esecutore di strumenti condiviso.

Livello di rischio HITL

La creazione di documenti e l’acquisizione di HTML sono di livello cautela; la verifica di accessibilità è di sola lettura. Nessuno è approval_required per impostazione predefinita. Vedere /connect/hitl-risk-tiers/.

Envelope JSON del gate di conferma

Questi strumenti non attivano il gate a meno che un override dell’operatore non imposti uno di essi su approval_required. L’envelope e il contratto del token monouso si trovano in /connect/hitl-risk-tiers/.

Vedere anche

/cookbook/connect/aria-tagged-pdf/ — mappatura dei ruoli landmark.
/cookbook/connect/figure-caption/ — struttura Figure / Caption annidata.
/connect/tool-catalog/ — calcolo dell’insieme di strumenti per livello.
/connect/hitl-risk-tiers/ — il modello di rischio e il gate.