내맘대로의 EPUB 제작 가이드

SVG hyperlink has no accessible name

이 오류는 SVG(이미지의 한 종류) 안에 클릭 가능한 링크가 있지만, 그 링크가 무엇에 대한 것인지 알려주는 텍스트 설명이 없다는 의미입니다. 

이는 접근성에 있어 중요한 문제입니다. 시각적으로는 링크가 걸린 도형이나 아이콘을 보고 클릭할 수 있지만, 시각 장애가 있는 사용자가 이용하는 화면 낭독기(Screen Reader)는 이 링크를 발견해도 무엇이라고 읽어줘야 할지 알 수 없습니다. '라벨 없는 버튼'과 같은 상황입니다.

## 해결 방법: <title> 요소 추가하기

이 문제를 해결하는 가장 간단한 방법은 링크를 만드는 <a> 태그 안에 <title> 요소를 추가하여 링크에 대한 설명을 제공하는 것입니다.

예시

아래는 파란색 원 전체에 링크를 건 SVG 코드입니다.

• 오류 예시 (수정 전):이 코드에서 화면 낭독기는 클릭 가능한 영역이 있다는 것은 알지만, 그 목적지는 알려줄 수 없습니다.
• XML

   

  <svg width="100" height="100" viewBox="0 0 100 100">
    <a href="https://example.com">
      <circle cx="50" cy="50" r="40" stroke="black" stroke-width="3" fill="blue" />
    </a>
  </svg>
  

• 수정 예시 (수정 후): ✅이제 <a> 태그 안에 <title> 요소가 추가되었습니다. 화면 낭독기는 이 링크를 만나면 **"Example.com 홈페이지로 이동"**이라고 명확하게 읽어주어 사용자가 링크의 목적을 정확히 알 수 있게 됩니다.
• XML

   

  <svg width="100" height="100" viewBox="0 0 100 100">
    <a href="https://example.com">
      <title>Example.com 홈페이지로 이동</title>
      <circle cx="50" cy="50" r="40" stroke="black" stroke-width="3" fill="blue" />
    </a>
  </svg>
  

MathML should either have an "alttext" attribute or "annotation-xml" child element.

이 오류는 책에 포함된 수학 수식(MathML)에 대한 설명이 빠져있다는 의미입니다. ♿

수식은 시각적으로는 보이지만, 화면 낭독기(Screen Reader)와 같은 보조 기술은 수식을 이미지처럼 인식하여 내용을 읽어줄 수 없습니다. 따라서 시각 장애가 있는 독자를 위해 수식이 무엇을 의미하는지 알려주는 대체 텍스트를 반드시 제공해야 합니다.

해결 방법은 오류 메시지에 나온 대로 두 가지가 있습니다.

## 해결 방법 1: alttext 속성 사용 (쉬운 방법)

가장 간단하고 일반적인 해결책은 <math> 태그에 직접 alttext 속성을 추가하여 수식에 대한 간단한 설명을 제공하는 것입니다.

• 오류 예시 (수정 전):
• XML

   

  <math>
    <mrow>
      <mi>a</mi>
      <msup>
        <mi>x</mi>
        <mn>2</mn>
      </msup>
      <mo>+</mo>
      <mi>b</mi>
      <mi>x</mi>
      <mo>+</mo>
      <mi>c</mi>
    </mrow>
  </math>
  

• 수정 예시 (수정 후): ✅
• XML

   

  <math alttext="ax 제곱 더하기 bx 더하기 c">
    <mrow>
      <mi>a</mi>
      <msup>
        <mi>x</mi>
        <mn>2</mn>
      </msup>
      <mo>+</mo>
      <mi>b</mi>
      <mi>x</mi>
      <mo>+</mo>
      <mi>c</mi>
    </mrow>
  </math>
  

## 해결 방법 2: annotation-xml 요소 사용 (고급 방법)

더 자세하거나 구조적인 설명이 필요할 때 사용하는 방법입니다. 기존의 <math> 태그를 <semantics> 태그로 감싸고, 그 안에 <annotation-xml> 요소를 추가하여 설명을 넣습니다.

• 수정 예시: ✅
• XML

   

  <math>
    <semantics>
      <mrow>
        <mi>E</mi>
        <mo>=</mo>
        <mi>m</mi>
        <msup>
          <mi>c</mi>
          <mn>2</mn>
        </msup>
      </mrow>
      <annotation-xml encoding="application/mathml-alternative">
        <mrow>
          <mtext>에너지(E)는 질량(m) 곱하기 빛의 속도(c)의 제곱과 같다.</mtext>
        </mrow>
      </annotation-xml>
    </semantics>
  </math>
  

⭐ 추천: 대부분의 경우, alttext 속성을 사용하는 첫 번째 방법으로 충분히 문제를 해결할 수 있고 훨씬 간편합니다.

Rule %1$s is under review and its severity may change in a future release. See the discussion at %2$s

오류 의미

이 메시지는 사용자의 전자책 파일에 오류가 있다는 뜻이 아닙니다.

이것은 EPUBCheck라는 검사 프로그램 개발자들이 사용자에게 보내는 **'정보성 안내 메시지'**입니다.

쉽게 말해, "당신의 파일에서 발견된 특정 규칙(%1$s 부분)은 저희 개발자들이 현재 재검토하고 있습니다. 그래서 다음 버전의 EPUBCheck 프로그램에서는 이 규칙의 심각도(단순 경고인지, 심각한 오류인지)가 변경될 수 있습니다. 더 자세한 논의 내용이 궁금하시면 여기 주소(%2$s 부분)를 방문해주세요." 라는 의미입니다.

보통 이 메시지는 실제 오류나 경고 메시지 바로 아래에 함께 표시됩니다.

핵심 요약:

• 이 줄 자체는 오류가 아닙니다.
• 함께 표시된 다른 오류/경고 규칙이 현재 개발자들 사이에서 논의 중이라는 것을 알려주는 공지사항입니다.

해결 방법

이 메시지에 대해서는 아무것도 수정할 필요가 없습니다.

이 메시지는 무시하시고, 이 메시지와 함께 나온 실제 오류 또는 경고 메시지에 집중하여 그 문제를 해결해야 합니다.

예시:

만약 EPUBCheck 검사 결과가 아래와 같이 나왔다고 가정해 보겠습니다.

1. 경고(CSS-008): style.css 파일에서 접두사가 없는 CSS 속성을 사용해야 합니다.
2. 정보(INFO_001): 'CSS-008' 규칙은 현재 검토 중이며...

이 경우, 우리가 신경 써야 할 것은 2번 정보 메시지가 아니라 1번 경고 메시지입니다. style.css 파일의 문제를 해결하면, 1번 경고 메시지가 사라지면서 2번 정보 메시지도 자연스럽게 함께 사라지게 됩니다.

따라서 이 메시지가 보이면, '아, 내가 해결해야 할 저 오류가 나중에 기준이 바뀔 수도 있구나' 정도로만 이해하고, 함께 나온 실제 오류를 해결하는 데에만 집중하시면 됩니다.

Content Documents do not use "epub:type" attributes for semantic inflection.

오류 의미

이 메시지는 전자책의 HTML 문서 본문에 epub:type이라는 속성이 사용되지 않았다는 뜻입니다.

쉽게 비유하자면, 책의 내용은 잘 들어가 있지만, 어떤 부분이 **'표지'**인지, 어떤 부분이 **'목차'**인지, 그리고 어디서부터가 진짜 **'본문'**의 시작인지 컴퓨터(전자책 리더기, 스크린 리더 등)에게 정확히 알려주는 **'꼬리표'**가 붙어있지 않다는 의미입니다.

epub:type은 바로 이 '꼬리표' 역할을 하는 속성입니다. 이 꼬리표를 붙여주면 전자책을 읽어주는 프로그램이 책의 구조를 더 잘 이해하게 되어, 시각장애인을 위한 스크린 리더 기능이 향상되고 검색 기능이 정확해지는 등 전자책의 접근성과 기능성이 전반적으로 좋아집니다.

해결 방법

책의 각 구성 요소에 맞는 epub:type 꼬리표(속성)를 해당 HTML 태그에 추가해주면 됩니다. HTML을 전혀 모르시더라도, 전자책 편집 프로그램(예: Sigil)의 코드 보기 기능을 이용해 간단히 수정할 수 있습니다.

1. 책의 주요 구성 요소 파악하기

먼저 내 책이 어떤 부분들로 이루어져 있는지 파악합니다. (예: 표지, 제목 페이지, 목차, 서문, 본문 챕터들, 참고 문헌 등)

2. 올바른 epub:type 꼬리표 찾기

각 구성 요소에 맞는 표준 epub:type 꼬리표(값)들이 정해져 있습니다. 자주 사용하는 것들은 다음과 같습니다.

• cover: 표지 이미지
• titlepage: 제목, 저자, 출판사 정보가 담긴 페이지
• toc: 목차
• preface: 서문, 머리말
• bodymatter: 본문 전체를 감싸는 영역
•  
• chapter: 각 장 (챕터)
• acknowledgments: 감사의 말
• bibliography: 참고 문헌
• footnote: 각주 내용
• page-list: 종이책 페이지 번호 목록

3. HTML 코드에 epub:type 속성 추가하기

각 구성 요소를 감싸고 있는 HTML 태그(주로 <section>이나 <div> 태그)에 epub:type 속성을 추가합니다.

수정 예시 1: 챕터(Chapter) 표시하기

챕터 하나를 감싸고 있는 <section> 태그를 찾아서 다음과 같이 수정합니다.

• 수정 전:
• HTML

  <section>
    <h2>제1장 새로운 시작</h2>
    <p>이야기는 이렇게 시작됩니다...</p>
  </section>
  

• 수정 후:
• HTML

  <section epub:type="chapter">
    <h2>제1장 새로운 시작</h2>
    <p>이야기는 이렇게 시작됩니다...</p>
  </section>
  

수정 예시 2: 목차(Table of Contents) 표시하기

목차를 감싸고 있는 <nav> 태그에 다음과 같이 epub:type 속성을 추가합니다.

• 수정 전:
• HTML

  <nav>
    <h1>목차</h1>
    <ol>
      <li><a href="chapter1.xhtml">제1장</a></li>
      <li><a href="chapter2.xhtml">제2장</a></li>
    </ol>
  </nav>
  

• 수정 후:
• HTML

  <nav epub:type="toc">
    <h1>목차</h1>
    <ol>
      <li><a href="chapter1.xhtml">제1장</a></li>
      <li><a href="chapter2.xhtml">제2장</a></li>
    </ol>
  </nav>
  

이처럼 책의 모든 구조적 요소(서문, 각 챕터, 감사의 말 등)에 해당하는 태그를 찾아 알맞은 epub:type 꼬리표를 붙여주면 오류 메시지가 사라지고, 훨씬 더 품질 좋은 전자책이 됩니다.