내맘대로의 EPUB 제작 가이드

Table elements should include a caption element.

이 규칙은 표(table)에 대한 접근성과 가독성을 높이는 데 매우 중요합니다.

<caption> 요소는 표의 '공식적인 제목' 역할을 합니다. 📚

## 중요한 이유

화면 낭독기(Screen Reader)와 같은 보조 기술은 표를 인식했을 때 이 <caption>에 있는 내용을 가장 먼저 읽어줍니다. 이 제목을 통해 사용자는 표의 전체 내용을 살펴보기 전에 무엇에 대한 정보인지 미리 파악할 수 있습니다.

## 해결 방법

해결 방법은 간단합니다. <table> 태그 바로 아래, 첫 번째 <tr> 태그 위에 <caption> 요소를 추가하고 그 안에 표의 제목을 적으면 됩니다.

올바른 구조:

<table>
  <caption>월별 판매 보고서</caption>
  <tr>
    <th>월</th>
    <th>수량</th>
  </tr>
  <tr>
    <td>1월</td>
    <td>150</td>
  </tr>
</table>

이렇게 하면 모든 사용자가 표의 목적을 더 명확하게 이해할 수 있습니다.

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 속성을 사용하는 첫 번째 방법으로 충분히 문제를 해결할 수 있고 훨씬 간편합니다.

Html "a" element must have text.

HTML "a" 요소에는 텍스트가 있어야 합니다.

오류 해결 방법 : 이 오류는 웹페이지에서 다른 페이지로 연결되는 링크를 만드는 <a> 태그 안에 클릭할 수 있는 글자(텍스트)가 없다는 의미입니다.

<a> 태그는 사용자가 클릭해서 다른 곳으로 이동할 수 있는 하이퍼링크를 만듭니다. 하지만 <a> 태그와 </a> 태그 사이에 아무 내용이 없으면, 화면에 링크가 보이지 않아 사용자가 클릭할 수 없습니다.

잘못된 코드 예시

<a href="page2.xhtml"></a>

위와 같이 코드가 작성되면 <a> 태그는 아무런 텍스트를 가지고 있지 않기 때문에 화면에 보이지 않고, 따라서 사용자가 링크를 클릭하여 page2.xhtml 파일로 이동할 수 없습니다.

올바른 코드 예시

문제를 해결하려면 <a> 태그와 </a> 태그 사이에 사용자가 보고 클릭할 수 있는 설명 텍스트를 넣어주어야 합니다.

<a href="page2.xhtml">다음 페이지로 이동하기</a>

이렇게 수정하면, 화면에 '다음 페이지로 이동하기'라는 글자가 나타나고 사용자는 이 글자를 클릭해서 링크로 이동할 수 있습니다.

이미지를 링크로 사용하는 경우

만약 텍스트 대신 이미지를 클릭해서 링크를 이동하게 만들고 싶다면, <a> 태그 안에 <img> 태그를 넣고, <img> 태그에 alt 속성을 사용해 이미지에 대한 설명을 반드시 추가해야 합니다. 이 alt 속성의 설명이 링크의 텍스트 역할을 대신하게 됩니다.

<a href="cart.xhtml">
  <img src="images/cart_icon.png" alt="장바구니로 이동">
</a>

위 코드에서는 alt 속성의 '장바구니로 이동'이라는 텍스트가 링크의 목적을 설명해 주는 역할을 합니다.

이 오류는 EPUB에서 사용할 수 없는 HTML 태그를 사용했을 때 표시됩니다.

Col: 10: ERROR(RSC-005): "ruby" 요소는 어디에도 사용할 수 없습니다.; end-tag 요소, text 또는 "a", "abbr", "acronym", "applet", "b", "bdo", "big", "br", "cite", "code", "del", "dfn", "em", "i", "iframe", "img", "ins", "kbd", "map", "noscript", "ns:svg", "object", "q", "samp", "script", "small", "span", "strong", "sub", "sup", "tt" 또는 "var" (with xmlns:ns="http://www.w3.org/2000/svg") 요소이(가) 예상됨 파일을 분석하는 동안 "오류"가 발견되었습니다.

ruby, aside, mark, header, footer, section 같은 태그를 EPUB2.0 버전에서 사용했을 때 이런 오류가 표시됩니다.

HTML5.0 이후 버전에서 추가된 태그를 EPUB2에서 사용할 때 이런 오류가 표시될 가능성이 높습니다.

u 태그는 구 버전에서 밑줄(underline)을 표시하기 위해 사용하였으나 HTML5.0 이후 버전에서 비텍스트 주석(non-textual annotation) 처리를 위한 태그로 변경되었고, 더 이상 밑줄을 긋기 위한 태그로 사용하지 않습니다. 그래서 EPUB2에서는 u 태그를 사용하면 이 오류가 표시됩니다.

이 오류를 해결하려면 EPUB에서 사용할 수 없는 html 태그를 파악하고 사용을 피해야합니다.

EPUB2에서 이런 오류가 자주 발생을 하기 때문에 아래와 같은 태그는 EPUB2 편집을 할 때 사용을 하지 않아야 합니다.

● ruby: 루비 문자를 표현하는 데 사용됩니다. (예: 한자 위에 발음을 표기)
● mark: 텍스트의 특정 부분을 강조하는 데 사용됩니다.
● section, footer, header: 문서의 구조를 나타내는 데 사용됩니다.
● aside: 본문 내용과 관련된 추가 정보를 제공하는 데 사용됩니다.
● figure: 이미지, 다이어그램 등을 포함하는 데 사용됩니다.

EPUBCheck는 오류 내용에 이 태그 대산 사용할 수 있는 태그 목록을 보여줍니다.

"a", "abbr", "acronym", "applet", "b", "bdo", "big", "br", "cite", "code", "del", "dfn", "em", "i", "iframe", "img", "ins", "kbd", "map", "noscript", "ns:svg", "object", "q", "samp", "script", "small", "span", "strong", "sub", "sup", "tt" 또는 "var"

이 태그는 모두 EPUB3에서 사용 할 수 있습니다.

따라서 이 태그를 반드시 사용해야 한다면 EPUB3로 제작을 해야합니다.

이 중 몇몇 태그는 국내 주요 유통사(교보문고, 예스24, 알라딘, 리디북스)에서 EPUB2에 사용할 수 있도록 하고 있습니다.

EPUBCheck에서 오류가 나면 유통사에 등록을 할 수 없으나 ruby, aside 등 일부 태그에 한해서 등록을 허용합니다.

유통사 별로 이용 가능한 태그 목록은 유통사 담당자에게 확인하시기 바랍니다.

이 오류는 링크 또는 링크 기능을 이용한 주석/팝업 주석을 편집할 때 종종 볼 수 있습니다.

이 오류가 생기는 이유는 ID와 관련되어 있습니다.

ID 오류와 함께 생기는 경우가 많으니 이 글도 참고하세요.

https://www.epubguide.net/574

이 오류를 제대로 해결하려면 프래그먼트 식별자가 무엇인지 알아야합니다.

EPUB에서 말하는 프래그먼트 식별자는 웹주소 또는 링크에서 사용하는 식별자를 의미합니다.

웹 주소(URL)에서 # 기호 뒤에 오는 부분을 프래그먼트 식별자라고 합니다. 마치 책의 목차에서 특정 페이지를 가리키는 쪽번호처럼, 웹 페이지 내의 특정 위치를 가리키는 역할을 합니다.

https://example.com/page#FragmentID

EPUB에서 주석 링크를 연결하거나 특정 페이지를 참조하도록 링크를 연결할 때 Fragment 식별자를 이용하지요.

오류 메시지를 잘 읽어보면 왜 오류가 생겼는지 알 수 있습니다.

Col: 26: ERROR(RSC-012): Fragment 식별자가 정의되지 않았습니다.

식별자가 정의되지 않았다는 것은, 식별자에 사용한 ID를 찾을 수 없다는 의미입니다. 식별자는 사용했는데 ID가 없으니 정의되지 않았다고 오류메시지를 표시하는것이지요.

Fragment 식별자를 사용하려면 본문의 특정 위치를 가리키는 ID가 있어야합니다. 본문 내 주석 번호라면 이 번호가 가리키는 주석 설명에 ID가 반드시 있어야합니다. 그래야 링크를 클릭할 때 그 위치로 넘어가겠지요?

ID가 없으면 EPUBCheck는 Fragment 식별자가 정의되지 않았다는 오류메시지를 표시합니다.

오류가 생겼다면 ID가 없거나, ID 이름에 오타가 있거나 둘 중 하나입니다.

ID도 대소문자를 구분하기 때문에 footnoteID01과 footnoteid01은 서로 다른 식별자입니다.

<p>...<a href="#footnoteid01">1)</a>...</p>

...

<p class="footnoteID01">...</p>

이렇게 대소문자를 틀리게 입력해도 EPUBCheck는 식별자가 정의됮 않았다고 메시지를 보냅니다.

링크 파일 경로를 잘못 지정해도 이런 오류가 생길 수 있으니 파일 경로, ID 이름이 정확한지 확인해 보시기 바랍니다.