내맘대로의 EPUB 제작 가이드

이 오류는 사용자가 지정한 '사용자 정의 메시지 파일'(%2$s)을 성공적으로 열었지만, 그 파일의 내용에 문제가 있음을 의미합니다.

구체적으로, EPUBCheck의 기본 메시지를 변경하기 위해 파일에 적어둔 메시지 ID(%1$s)가 존재하지 않는, 잘못된 ID라는 뜻입니다.

## 원인: 잘못된 메시지 ID

EPUBCheck의 모든 오류나 경고 메시지에는 고유한 ID(예: ACC_004, RSC_001)가 있습니다. 이 ID는 각 메시지의 '식별 번호'와 같습니다.

사용자 정의 파일에서 특정 메시지를 바꾸려면 이 '식별 번호'를 정확하게 사용해야 하는데, 파일에 적힌 ID(%1$s)에 오타가 있거나 존재하지 않는 ID를 사용하여 프로그램이 어떤 메시지를 바꿔야 할지 인식하지 못하는 상황입니다.

## 해결 방법

1. 오류 메시지에 언급된 사용자 정의 메시지 파일(%2$s)을 텍스트 편집기에서 엽니다.
2. 파일 안에서 잘못된 메시지 ID(%1$s)를 찾습니다.
3. ID에 오타가 있는지 확인하고, 올바른 ID로 수정합니다. (예: 하이픈 - 과 밑줄 _ 을 혼동하는 경우가 많습니다.)

### 올바른 메시지 ID 목록 확인하기

EPUBCheck에서 사용 가능한 모든 공식 메시지 ID 목록은 터미널이나 명령 프롬프트에서 다음 명령어를 실행하여 확인할 수 있습니다. 이 목록을 참고하여 ID를 정확하게 수정하세요.

epubcheck --listChecks

또는 단축 명령어로,

epubcheck -l

The custom message overrides file was not found.

이 오류는 EPUBCheck의 고급 기능과 관련된 메시지입니다.

간단히 말해, EPUBCheck의 기본 오류 메시지나 심각도(경고, 오류 등)를 사용자가 직접 변경할 수 있는 **'사용자 정의 설정 파일'**을 사용하도록 명령했지만, 프로그램이 그 파일을 지정된 위치에서 찾지 못했다는 의미입니다. ⚙️

## 오류가 발생하는 이유

이 오류는 주로 두 가지 상황 중 하나일 때 발생합니다.

1. 의도적으로 사용했지만 파일 경로가 틀린 경우: 고급 사용자가 --customMessages (또는 단축 명령어 -c) 옵션을 사용하여 직접 만든 메시지 설정 파일을 적용하려고 했으나, 파일 이름에 오타가 있거나 파일 경로를 잘못 지정한 경우입니다.
2. 의도치 않게 명령어를 잘못 입력한 경우 (가장 흔한 원인): EPUBCheck를 실행하는 명령어를 입력하다가 실수로 -c 같은 옵션을 포함시킨 경우입니다. 프로그램은 이를 '사용자 정의 메시지 파일을 사용하라'는 명령으로 오해하고 파일을 찾으려 하지만, 실제 파일이 없으므로 오류가 발생합니다. 대부분의 사용자는 이 경우에 해당합니다.

## 해결 방법

• 만약 이 기능을 사용할 의도가 없었다면, EPUBCheck를 실행한 명령어를 다시 확인해 보세요. 명령어에 불필요한 -c 또는 --customMessages 옵션이 포함되어 있다면, 그 부분을 삭제하고 다시 실행하면 됩니다.
  • 잘못된 명령어 예시: epubcheck mybook.epub -c somefile.txt
  • 올바른 명령어 예시: ✅ epubcheck mybook.epub
• 만약 사용자 정의 메시지 파일을 의도적으로 사용했다면, 지정한 파일의 이름과 경로가 정확한지 다시 한번 꼼꼼히 확인해 주십시오.

요약: 이 기능은 특정 목적을 위해 EPUBCheck의 동작을 미세하게 조정하는 고급 기능입니다. 대부분의 경우, 실행 명령어에 포함된 오타가 원인이므로 명령어를 수정하는 것만으로 간단히 해결할 수 있습니다.

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