내맘대로의 EPUB 제작 가이드

HTML documents must be encoded in UTF-8, but UTF-16 was detected.

이 오류는 이전에 다루었던 CSS 인코딩 문제와 동일하며, 이번에는 EPUB의 **본문 파일(HTML/XHTML)**이 잘못된 '언어(인코딩)' 방식으로 저장되었다는 의미입니다.

EPUB 표준은 전 세계 모든 기기에서 글자나 특수 기호가 깨지는 현상 없이 완벽하게 호환되도록, 모든 텍스트 기반 파일을 UTF-8이라는 단일 방식으로 저장하도록 엄격하게 요구합니다. 🌏

UTF-16으로 저장된 HTML 파일은 일부 전자책 뷰어에서 내용을 전혀 표시하지 못하거나 글자가 깨져 보일 수 있습니다.

## 해결 방법: 인코딩을 UTF-8로 변경하기

해결 방법은 간단합니다. 문제가 된 HTML 파일을 텍스트 편집기에서 열어 인코딩 방식을 UTF-8로 변경한 후 다시 저장하면 됩니다.

### Visual Studio Code, Notepad++ 등 전문 편집기 사용 시

1. 오류가 발생한 HTML 파일을 편집기에서 엽니다.
2. 편집기 창의 오른쪽 아래에 있는 상태 표시줄에서 현재 인코딩(예: UTF-16 LE)이 표시된 부분을 클릭합니다.
3. 나타나는 메뉴에서 '인코딩하여 저장(Save with Encoding)' 또는 유사한 옵션을 선택합니다.
4. 목록에서 **'UTF-8'**을 선택하고 파일을 덮어써 저장합니다.

### 윈도우 메모장 사용 시

1. HTML 파일을 메모장으로 엽니다.
2. 상단 메뉴에서 **'파일 > 다른 이름으로 저장'**을 클릭합니다.
3. 저장 대화상자 하단에 있는 '인코딩' 드롭다운 메뉴에서 **'UTF-8'**을 선택합니다.
4. '저장' 버튼을 눌러 기존 파일을 덮어씁니다.

Viewport "" value must be a positive number or the keyword "device-"

이 오류는 고정 레이아웃 EPUB의 <meta name="viewport"> 태그에 있는 width(너비) 또는 height(높이) 속성의 값이 잘못되었음을 의미합니다.

페이지의 너비나 높이 값은 반드시 0보다 큰 양수이거나, 특수한 경우에만 사용되는 특정 키워드여야 한다는 규칙이 있습니다.

## 값에 대한 규칙

width와 height 속성에 사용할 수 있는 값은 두 종류입니다.

1. 양수 (Positive Number) 가장 일반적인 방법으로, 1024나 768처럼 0보다 큰 정수를 사용해야 합니다. 페이지의 크기가 0이거나 음수일 수는 없으므로, width=0이나 height=-100과 같은 값은 오류를 발생시킵니다.
2. 특수 키워드 (Special Keywords) device-width와 device-height라는 키워드를 사용할 수 있습니다. 이는 뷰포트의 크기를 기기의 화면 크기에 맞추라는 의미이지만, 이 방식은 주로 화면 크기에 따라 내용이 변하는 반응형 웹사이트에서 사용됩니다. 모든 페이지의 크기가 동일해야 하는 고정 레이아웃 EPUB에서는 일반적으로 사용하지 않습니다.

따라서, 고정 레이아웃 EPUB을 제작할 때는 항상 양수 값을 사용하는 것이 올바른 방법입니다.

## 해결 방법

viewport 메타 태그의 width와 height 값을 페이지 크기에 맞는 양수로 수정하면 됩니다.

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

   

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

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

   

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

중요: 너비와 높이 값은 반드시 자신의 고정 레이아웃 페이지 실제 크기에 맞는 양수로 지정해야 합니다.

Viewport metadata has no "%1$s" dimension (both "width" and "height" properties are required)

이 오류는 고정 레이-아웃 EPUB의 <meta name="viewport"> 태그에 너비(width)와 높이(height) 중 하나가 빠져있다는 의미입니다.

고정 레이-아웃 페이지의 정확한 크기를 정의하려면, 가로와 세로 크기 정보가 모두 반드시 필요합니다.

액자 프레임을 주문하는데, "가로 10인치짜리 프레임을 만들어주세요" 라고만 하고 세로 길이를 알려주지 않는 것과 같습니다. 🖼️ 정보가 절반만 있어서는 정확한 크기의 프레임(전자책 페이지)을 만들 수 없습니다.

## 해결 방법

해결책은 간단합니다. viewport 메타 태그의 content 속성 안에 빠져있는 속성(width 또는 height)을 추가하여 두 가지 정보를 모두 제공하면 됩니다.

• 규칙: content 속성에는 width=[숫자]와 height=[숫자]가 **쉼표(,)**로 구분되어 모두 포함되어야 합니다.

## 수정 예시

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

   

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

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

   

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

중요: 위 예시의 1024와 768 값은 반드시 자신의 고정 레이-아웃 페이지 실제 크기에 맞는 숫자로 수정해야 합니다.

The "" element should not be used (discouraged construct)

이 메시지는 HTML 코드에 현재는 사용이 권장되지 않는 **'구식(deprecated)' HTML 태그(%1$s)**가 포함되어 있다는 경고입니다.

오래된 스마트폰 모델을 생각하면 쉽습니다. 📱 제조사에서 더 좋은 성능의 새 모델을 출시하면서 이전 모델을 단종시키고 더 이상 지원하지 않기로 하는 것과 같습니다. 이전 모델이 당장 작동은 하지만, 앞으로 호환성이나 기능 면에서 문제가 생길 수 있으므로 새 모델을 사용하는 것이 권장됩니다.

HTML 태그도 마찬가지입니다. 웹 표준이 발전하면서 일부 오래된 태그들은 더 좋고 효율적인 CSS 스타일링 방식으로 대체되었습니다.

## 왜 일부 태그의 사용이 권장되지 않나요?

현대적인 웹 표준의 핵심 원칙은 **'구조와 표현의 분리'**입니다.

• HTML: 문서의 구조를 나타냅니다. (예: 이것은 '제목'이다 <h1>, 이것은 '문단'이다 <p>)
• CSS: 문서의 표현을 담당합니다. (예: 글자는 '빨간색'이고 '가운데 정렬'이다)

사용이 권장되지 않는 태그들(예: <center>, <font>)은 이러한 원칙을 어기고, 구조를 나타내는 HTML 코드 안에서 직접적으로 표현(디자인)을 제어하기 때문에 더 이상 사용하지 않는 것이 좋습니다.

## 해결 방법: CSS로 대체하기

해결책은 구식 태그를 제거하고, 그 기능을 CSS 클래스로 대체하는 것입니다.

1. 경고 메시지에 나온 구식 태그(%1$s)를 HTML 문서에서 찾습니다.
2. 해당 태그를 제거하고, 대신 일반적인 태그(예: <p>, <div>)에 식별 가능한 class 이름을 붙여줍니다.
3. CSS 파일에서 해당 class에 원하는 스타일을 지정합니다.

### 수정 예시 (<center> 태그)

• 수정 전 (경고 발생 예시):
• HTML

   

  <center>이 텍스트를 가운데로 정렬합니다.</center>
  

• 수정 후 (올바른 코드): ✅
  1. HTML 파일 수정:
  2. HTML

      

     <p class="center-align">이 텍스트를 가운데로 정렬합니다.</p>
     

  3. CSS 파일에 스타일 추가:
  4. CSS

      

     .center-align {
       text-align: center;
     }
     

### 자주 사용되는 구식 태그와 CSS 대체 속성

Custom attribute namespace ("%1$s") must not include the string "%2$s" in its domain.

이 오류는 EPUB에서 사용자 정의 속성을 만들기 위해 선언한 네임스페이스(namespace) URI에 문제가 있음을 의미하는 고급 오류입니다.

쉽게 말해, 자신만의 특별한 속성을 만들기 위해 '신분증'과 같은 고유 주소(네임스페이스 URI)를 만들었는데, 그 주소의 도메인 이름에 EPUB이나 웹 표준을 관장하는 공식 기관의 이름(예: idpf.org, w3.org)을 무단으로 사용했다는 뜻입니다.

자신만의 회사를 설립하면서 '삼성전자 공식 파트너'나 '구글 버거 가게'처럼 다른 공식 기관의 이름을 회사 이름에 넣어 사람들을 혼란스럽게 해서는 안 되는 것과 같은 이치입니다. 🏢

## 규칙

사용자가 직접 만드는 네임스페이스 URI의 도메인 이름에는 EPUB이나 관련 표준 기관의 소유로 오해받을 수 있는 다음과 같은 예약된 문자열을 포함할 수 없습니다.

• idpf.org
• w3.org
• daisy.org
• 등 기타 공식 기관의 도메인

## 해결 방법

해결책은 자신이 만든 네임스페이스 URI를 공식 기관의 이름이 포함되지 않은, 자신이 제어할 수 있는 고유한 주소로 변경하는 것입니다.

1. 오류가 발생한 XHTML 파일을 엽니다.
2. 파일 상단의 <html> 태그에서 사용자가 직접 추가한 네임스페이스 선언(예: xmlns:myprefix="...")을 찾습니다.
3. 따옴표 안의 잘못된 URI 주소(%1$s)를 자신이 소유한 도메인 주소나, 오해의 소지가 없는 다른 고유한 주소로 변경합니다. (주소가 실제로 인터넷에 존재할 필요는 없으며, 고유 식별자로만 사용됩니다.)

### 수정 예시

• 수정 전 (오류 예시 - idpf라는 예약어를 사용):
• XML

   

  <html xmlns="http://www.w3.org/1999/xhtml"
        xmlns:mycorp="http://www.my-idpf-vocab.com/terms/">
  

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

   

  <html xmlns="http://www.w3.org/1999/xhtml"
        xmlns:mycorp="http://www.my-ebook-corp.com/terms/">

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의 고급 제작 기술에 해당합니다.