내맘대로의 EPUB 제작 가이드

The property "region-based" is only allowed on nav elements in Data Navigation Documents.

이 오류는 만화책, 복잡한 다이어그램 등 한 페이지 내의 특정 **'영역(region)'**을 순서대로 보여주는 특수한 내비게이션 기능과 관련된 고급 문제입니다.

epub:type="region-based" 속성은 바로 이 '영역 기반 내비게이션'을 정의할 때 사용하며, EPUB 표준은 이 속성을 두 가지 조건 하에서만 사용하도록 엄격히 제한합니다.

1. 반드시 <nav> 요소 안에서만 사용해야 합니다.
2. 반드시 **'데이터 내비게이션 문서'**라는 특별한 종류의 파일 안에서만 사용해야 합니다.

이 오류는 위 두 가지 규칙 중 하나 또는 둘 다를 어겼을 때 발생합니다.

## 해결 방법

이 문제를 해결하는 방법은 이 기능을 의도적으로 사용했는지 여부에 따라 달라집니다.

### 경우 1: 만화책과 같은 특수 내비게이션을 만들지 않는 경우 (대부분 여기에 해당)

일반적인 소설이나 에세이 등 텍스트 위주의 책을 만들고 있다면, 이 속성은 필요 없습니다. 아마도 템플릿이나 예제 코드를 복사하는 과정에서 실수로 포함되었을 가능성이 높습니다.

• 해결책: HTML/XHTML 파일을 열어 epub:type="region-based" 속성을 찾아서 그 속성 자체를 완전히 삭제하세요.
• 수정 예시:▼
• HTML

   

  <ol>
    ...
  </ol>
  

• HTML

   

  <ol epub:type="region-based">
    ...
  </ol>
  

### 경우 2: 의도적으로 영역 기반 내비게이션을 만드는 경우 (고급)

만화책의 컷(panel)을 순서대로 보여주는 등의 기능을 구현하려는 의도가 있었다면, epub:type="region-based" 속성이 <nav> 요소에 올바르게 적용되었는지, 그리고 해당 코드가 일반 본문 파일이 아닌 별도의 '데이터 내비게이션 문서'에 작성되었는지 확인해야 합니다. 이는 EPUB의 고급 제작 기술에 해당합니다.

Found Microdata semantic enrichments but no RDFa. EDUPUB recommends using RDFa Lite.

이 메시지는 수정이 필요한 오류가 아니라, EDUPUB이라는 교육용 전자책 표준에 특화된 고급 권장 사항입니다.

쉽게 말해, 문서의 의미를 기계가 더 잘 이해하도록 돕는 '시맨틱 강화' 주석을 추가했는데, EDUPUB 표준이 권장하는 RDFa Lite 방식이 아닌 Microdata 방식을 사용했다는 뜻입니다.

특정 학술지에 논문을 제출하는데, 그 학술지(EDUPUB)는 논문 인용 방식을 'APA 스타일(RDFa Lite)'로 통일하기로 약속했습니다. 📝 이 메시지는 편집자가 "당신은 'MLA 스타일(Microdata)'로 인용했는데, 우리 학술지는 'APA 스타일'을 권장합니다"라고 알려주는 것과 같습니다. MLA 스타일 자체는 유효하지만, 해당 학술지의 규칙과는 다른 것입니다.

## 어떻게 해야 하나요?

이 메시지에 대한 조치는 만들고 있는 책의 목적에 따라 달라집니다.

### 경우 1: 일반적인 전자책(소설, 에세이 등)을 만드는 경우

이 메시지를 안전하게 무시하셔도 됩니다.

Microdata는 웹에서 널리 사용되는 유효한 시맨틱 마크업 방식입니다. 만들고 있는 책이 EDUPUB 표준을 반드시 따라야 하는 교육용 교재가 아니라면, 이 권장 사항을 따를 필요가 없습니다.

### 경우 2: EDUPUB 표준의 교육용 교재를 만드는 경우

권장 사항에 따라 Microdata를 RDFa Lite로 수정해야 합니다.

EDUPUB 표준을 완벽하게 준수해야 한다면, Microdata 구문을 RDFa Lite 구문으로 변경해야 합니다. 두 방식은 사용하는 속성의 이름이 조금 다릅니다.

## Microdata와 RDFa Lite 구문 비교 예시

• Microdata 사용 예시:
• HTML

   

  <div itemscope itemtype="http://schema.org/Book">
    <span itemprop="name">EPUB 3 Best Practices</span>
    by <span itemprop="author">Matt Garrish</span>.
  </div>
  

• RDFa Lite 사용 예시: ✅
• HTML

   

  <div vocab="http://schema.org/" typeof="Book">
    <span property="name">EPUB 3 Best Practices</span>
    by <span property="author">Matt Garrish</span>.
  </div>

SVG Fixed-Layout Documents must have a "viewBox" attribute (on the outermost "svg" element).

이 오류는 SVG 파일을 사용하여 고정 레이아웃 페이지를 만들 때 발생하는 문제입니다.

오류의 의미는, SVG 파일의 가장 바깥쪽 <svg> 태그에 해당 SVG 이미지의 크기와 좌표계를 정의하는 필수 속성인 viewBox가 빠졌다는 것입니다.

## viewBox 속성이란?

viewBox는 SVG 이미지의 '캔버스' 크기를 정의하는 가장 중요한 속성입니다. XHTML 기반의 고정 레이아웃 페이지에서는 <meta name="viewport"> 태그가 페이지의 크기를 알려주는 역할을 했다면, SVG 기반 페이지에서는 바로 이 viewBox 속성이 그 역할을 합니다.

이 속성이 없으면 전자책 뷰어는 SVG 페이지의 의도된 크기를 알 수 없어 페이지를 올바르게 표시할 수 없습니다. 🖼️

## 해결 방법

해결책은 간단합니다. SVG 파일의 최상단 <svg> 태그에 viewBox 속성을 추가하면 됩니다.

1. 먼저, SVG 페이지의 정확한 가로(width)와 세로(height) 크기를 확인합니다. (예: 1024 x 768)
2. SVG 파일을 텍스트 편집기에서 엽니다.
3. 가장 처음에 나오는 <svg> 태그를 찾습니다.
4. viewBox="0 0 [가로크기] [세로크기]" 형식에 맞게 속성을 추가합니다. 앞의 0 0은 일반적으로 고정된 값입니다.

### 수정 예시

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

   

  <svg version="1.1" xmlns="http://www.w3.org/2000/svg">
    </svg>
  

• 수정 후 (올바른 코드): ✅
• XML

   

  <svg version="1.1" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1024 768">
    </svg>
  

중요: 위 예시의 1024 768 부분은 반드시 자신의 SVG 페이지 실제 크기에 맞게 수정해야 합니다.

Viewport metadata "%1$s" has a syntax error

이 오류는 고정 레이아웃 EPUB에 필수적인 <meta name="viewport"> 태그를 추가했지만, 그 내용(content)의 작성 형식, 즉 구문(syntax)이 잘못되었다는 의미입니다.

주소를 적을 때 '도로명 주소, 도시' 형식으로 적기로 약속했다고 상상해보세요. 📬 이 오류는 '도로명 주소: 도시' 처럼 콜론을 쓰거나, '도로명 주소; 도시' 처럼 세미콜론을 쓰는 등 약속된 형식을 따르지 않았다는 뜻입니다. 정보는 있지만 형식이 잘못되어 우체부(전자책 뷰어)가 주소를 제대로 인식할 수 없는 상황입니다.

## Viewport의 올바른 구문

content 속성 안의 내용은 반드시 다음 규칙을 따라야 합니다.

• width와 height 값은 **쉼표(,)**로 구분합니다.
• 각 값은 이름=숫자 형식이어야 합니다 (예: width=1024).
• 숫자 뒤에 px와 같은 단위를 붙이지 않습니다.
• 쉼표(,)와 등호(=) 외에 다른 기호(예: :, ;)를 사용하지 않습니다.

## 해결 방법

meta 태그의 content 속성 값을 올바른 구문에 맞게 수정하면 됩니다.

### 잘못된 구문 예시 (오류 발생)

<meta name="viewport" content="width: 1024, height: 768" />

<meta name="viewport" content="width=1024; height=768" />

<meta name="viewport" content="width=1024px, height=768px" />

### 올바른 구문 예시 (수정 후) ✅

<meta name="viewport" content="width=1024, height=768" />

Fixed layout document has no "viewport" meta element.

이 오류는 잡지나 그림책과 같은 고정 레이아웃(Fixed Layout) EPUB에서 발생하는 중대한 문제입니다.

오류의 의미는, 각 페이지의 정확한 크기(가로, 세로 픽셀)가 얼마인지 전자책 뷰어에게 알려주는 필수 정보인 <meta name="viewport"> 태그가 누락되었다는 뜻입니다.

800x600 픽셀 크기의 그림을 벽에 걸어야 하는 상황을 생각해보세요. 🖼️ viewport 메타 태그는 그림 뒷면에 "이 그림의 너비는 800, 높이는 600입니다"라고 붙여두는 라벨과 같습니다. 이 라벨이 없으면, 전시 담당자(전자책 뷰어)는 그림을 얼마나 크게 표시해야 할지 알 수 없어 너무 작게 보여주거나 그림의 일부를 잘라버리는 등 엉뚱하게 표시할 수 있습니다.

## 해결 방법

해결책은 고정 레이아웃 EPUB에 포함된 모든 HTML/XHTML 파일의 <head> 섹션 안에 viewport 메타 태그를 추가하는 것입니다.

1. 페이지 크기 확인: 먼저, 제작하려는 고정 레이아웃 페이지의 정확한 가로(width)와 세로(height) 크기를 픽셀 단위로 확인해야 합니다. (예: 1024 x 768)
2. 메타 태그 추가: 아래 형식에 맞게 width와 height 값을 자신의 프로젝트에 맞게 수정한 뒤, 모든 HTML 파일의 <head> ... </head> 안쪽에 추가합니다.

### 수정 예시

• 수정 전 (오류가 발생하는 <head>):
• HTML

   

  <head>
    <meta charset="UTF-8" />
    <title>1 페이지</title>
    <link rel="stylesheet" href="../css/style.css" />
  </head>
  

• 수정 후 (올바른 코드): ✅
• HTML

   

  <head>
    <meta charset="UTF-8" />
    <title>1 페이지</title>
    <link rel="stylesheet" href="../css/style.css" />
  
    <meta name="viewport" content="width=1024, height=768" />
  </head>
  

중요: 위 예시의 width=1024, height=768 부분은 반드시 자신의 고정 레이아웃 페이지 실제 크기에 맞게 수정해야 합니다.

Empty hrefs are valid self-references. These should be validated to ensure that this is the desired intent.

네, 맞습니다. 이 메시지는 EPUBCheck가 코드에서 href="" 와 같이 비어있는 링크를 발견했을 때 보여주는 경고입니다.

오류가 아니라고 하는 이유는, href=""가 문법적으로는 '현재 페이지를 다시 불러오는' 유효한 링크이기 때문입니다. 하지만 EPUBCheck는 "문법적으로는 맞지만, 사용자를 혼란스럽게 할 수 있는 의심스러운 코드이니 정말 의도한 것이 맞는지 확인해보세요"라고 알려주는 것입니다.

복도에 있는 문을 열었더니 바로 그 복도로 다시 나오는 것과 같습니다. 🚪 문 자체는 멀쩡하지만(유효함), 그 기능은 대부분의 경우 쓸모없고 혼란스럽습니다.

## 확인이 필요한 이유

비어있는 링크는 보통 다음과 같은 경우에 발생하며, 사용자 경험에 좋지 않은 영향을 줍니다.

• 실수 또는 누락: 링크 주소를 나중에 넣으려고 비워뒀다가 잊어버린 경우.
• 혼란스러운 동작: 독자가 링크를 클릭했는데 아무 데로도 이동하지 않고 페이지가 새로고침되면, 링크가 고장났다고 생각하게 됩니다.
• 접근성 문제: 화면 낭독기 사용자는 '링크'라고 안내를 받지만, 링크를 실행해도 아무런 변화가 없어 혼란을 겪을 수 있습니다.

## 해결 방법

코드에서 href=""를 찾은 뒤, 원래 의도가 무엇이었는지에 따라 아래와 같이 수정합니다.

### 경우 1: 실제 링크 주소를 넣으려다 빠뜨린 경우

가장 흔한 경우입니다. 비어있는 href 속성 안에 정확한 목적지 주소(다른 파일 경로, 웹사이트 주소 등)를 입력합니다.

• 수정 전:
• HTML

   

  <p>자세한 내용은 <a href="">부록</a>을 참고하세요.</p>
  

• 수정 후: ✅
• HTML

   

  <p>자세한 내용은 <a href="appendix.xhtml">부록</a>을 참고하세요.</p>
  

### 경우 2: 링크 기능이 필요 없는 경우

링크처럼 보이게 스타일만 주려 했거나, 스크립트 등을 위해 임시로 사용한 경우입니다. 이럴 때는 링크 태그인 <a>를 사용하는 것 자체가 잘못된 것이므로, <a> 태그를 아예 삭제하는 것이 가장 좋습니다.

• 수정 전:
• HTML

   

  <p>중요한 단어: <a href="">강조</a></p>
  

• 수정 후: ✅(그 후 CSS에서 .emphasis 클래스에 원하는 스타일을 적용합니다.)
• HTML

   

  <p>중요한 단어: <span class="emphasis">강조</span></p>