Connect를 통한 각주 참조 및 본문 패턴

한눈에 보기

Connect 전송 계층으로 각주 참조와 각주 본문을 렌더링해 구조 트리에 PDF 2.0 각주 역할이 포함되도록 합니다. 인라인 마커는 footnote/endnote 참조가 되고 각주 텍스트는 노트 본문이 되며, 둘 사이에는 상호 역참조가 생깁니다. 세 가지 HTML 형태는 동일한 출력을 만듭니다: 위 첨자 안의 링크, 명시적 ARIA role="doc-noteref", 그리고 <aside class="footnote"> 본문 컨테이너입니다. 검증에는 Pro 등급 접근성 도구를 사용합니다. NextPDF는 class_exists()를 통해 이 도구를 발견하며, nextpdf/premium이 서버와 함께 설치된 경우에만 등록합니다.

접근성 도구 통과 결과는 접근성 점검 결과이며, 독립적인 적합성 인증이 아닙니다.

설치

composer require nextpdf/server

tools/list를 호출해 Pro 접근성 도구가 존재하는지 확인합니다. /connect/tool-catalog/.를 참조하십시오.

개념 개요

PDF 2.0은 전용 footnote/endnote 구조 유형과 참조 및 해당 본문 사이의 관계를 정의합니다(PDF/UA-2 §8.2.5). 각주 참조는 해당 본문과 연관되어야 하며(PDF/UA-2 §8.2.5), 그래야 스크린 리더가 참조를 안내하고 링크를 따라 노트를 읽을 수 있습니다. 참조와 본문은 모두 구조 트리를 통해 접근 가능해야 합니다(PDF/UA-2 §8.2.4).

파이프라인은 세 가지 참조 형태를 인식합니다:

<sup><a href="#fn-N">N</a></sup> — 위 첨자 안의 링크 약식 표기.
<sup role="doc-noteref" aria-describedby="fn-N">N</sup> — 명시적 DPUB-ARIA 역할로, aria-describedby가 역참조 대상으로 전달됩니다.
<aside class="footnote" id="fn-N">…</aside> (또는 role="doc-footnote") — 본문 컨테이너로, 일치하는 참조로 돌아가는 내부 참조와 함께 노트 본문으로 출력됩니다.

API 표면

tools/list로 실행 중인 레지스트리와 대조해 도구 이름을 검증합니다. 기준 카탈로그는 /connect/tool-catalog/.입니다. 이 레시피는 코어 문서 및 HTML 도구와 Pro 접근성 점검을 사용하며, 도구 개수는 다시 명시하지 않습니다.

코드 샘플 — 빠른 시작

언어가 설정된 태그 문서를 생성한 다음 링크 약식 표기 참조를 추가합니다:

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

코드 샘플 — 프로덕션

HTML을 한 번 추가해 두 참조와 두 본문을 모두 출력한 다음 점검합니다:

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

접근성 점검은 쌍으로 연결된 reference/body 역할과 상호 역참조를 보고합니다.

예외 사례 및 유의 사항

참조는 있지만 본문이 없는 경우(또는 본문은 있지만 참조가 없는 경우)는 점검에서 보고됩니다. 모든 참조에는 일치하는 본문이 필요하며, 반대의 경우도 마찬가지입니다.
aria-describedby와 본문 id 사이의 id 불일치는 쌍이 해소되지 않은 상태로 남습니다(대소문자 구분).
외부 URL을 가리키는 위 첨자 앵커는 각주 참조가 아니라 일반 링크를 출력합니다. 외부 대상에는 명시적 역할을 사용하십시오.
class/role이 없는 **단독 <aside>**는 노트 본문이 아니라 랜드마크로 처리됩니다. class="footnote" 또는 role="doc-footnote"을 추가하십시오.
도구가 없는 경우. nextpdf/premium이 없으면 Pro 접근성 도구가 등록되지 않으므로, 검증은 알 수 없는 도구 오류로 실패합니다.

성능

프런트매터 예산은 문서상의 상한이며, 각주 페어링은 일반 구조 패스에 포함됩니다.

보안 참고 사항

일반 Connect 전송 지침 외에 별도로 해당되는 사항은 없습니다.

적합성

PDF/UA-2 매핑

주장	조항	reference_id
Footnote/endnote 구조 유형 및 reference/body 관계	PDF/UA-2 §8.2.5
각주 참조가 해당 본문과 연관됨	PDF/UA-2 §8.2.5
참조와 본문이 구조 트리를 통해 접근 가능함	PDF/UA-2 §8.2.4

태그 → ISO 32000-2 §14.9 상호 참조

참조와 본문은 PDF 2.0 footnote/endnote 표준 구조 유형을 사용합니다. 상호 역참조는 접근 가능한 각주 계약을 구성합니다.

WCAG 2.2 매핑

서로 연관된 각주 참조와 본문은 콘텐츠 수준에서 WCAG 2.2 SC 1.3.1(정보 및 관계)과 SC 2.4.1(블록 건너뛰기)을 지원합니다.

접근성 도구 통과 결과는 접근성 점검 결과이며 적합성 인증이 아닙니다. 해당 판정은 독립적인 검사기가 내립니다.

상용 맥락

접근성 점검 도구는 Pro 등급이며, nextpdf/premium이 서버와 함께 설치된 경우에만 등록됩니다.

Connect 세부 사항

전송 가용성 (MCP / REST / gRPC)

create_pdf, add_html, 그리고 접근성 점검은 공유 도구 실행기를 통해 MCP, REST, gRPC에서 동일하게 호출됩니다.

HITL 위험 등급

문서 생성과 HTML 수집은 주의 등급이며, 접근성 점검은 읽기 전용입니다. 기본적으로 어떤 작업도 approval_required가 아닙니다. /connect/hitl-risk-tiers/.를 참조하십시오.

확인 게이트 JSON 봉투

이 도구들은 운영자 재정의로 어느 하나가 approval_required로 상향되지 않는 한 게이트를 트리거하지 않습니다. 봉투 및 일회용 토큰 계약은 /connect/hitl-risk-tiers/.에 있습니다.

참고 자료

/cookbook/connect/aria-tagged-pdf/ — 랜드마크 역할 매핑.
/cookbook/connect/figure-caption/ — 중첩된 Figure / Caption 구조.
/connect/tool-catalog/ — 등급별 도구 집합 계산.
/connect/hitl-risk-tiers/ — 위험 모델과 게이트.