내맘대로의 EPUB 제작 가이드

CSS documents must be encoded in UTF-8, detected %1$s;

이 오류는 CSS 파일이 EPUB 표준에서 요구하는 UTF-8 방식이 아닌, 다른 방식(%1$s)으로 저장되었음을 의미합니다.

이는 이전의 'UTF-16 인코딩' 오류와 거의 동일하며, %1$s 부분에는 실제로 감지된 인코딩 방식의 이름(예: ANSI, ISO-8859-1 등)이 표시됩니다.

## 왜 UTF-8 인코딩이 중요한가요?

모든 전자책 기기와 소프트웨어에서 글자나 기호가 깨지는 일 없이 스타일시트가 항상 올바르게 적용되도록 하기 위한 글로벌 표준 약속입니다. 🌐 %1$s에 표시된 인코딩 방식은 일부 시스템에서 호환성 문제를 일으켜 스타일이 적용되지 않을 수 있습니다.

## 해결 방법: 파일을 UTF-8로 다시 저장하기

해결 방법은 간단합니다. 텍스트 편집기를 사용하여 파일의 인코딩을 UTF-8로 변경하면 됩니다.

### 전문 텍스트 편집기 (Visual Studio Code, Notepad++ 등)

1. 문제가 된 CSS 파일을 편집기에서 엽니다.
2. 창의 오른쪽 하단 상태 표시줄에서 현재 인코딩(%1$s) 이름을 클릭합니다.
3. 나타나는 메뉴에서 '인코딩하여 저장(Save with Encoding)' 옵션을 선택합니다.
4. 목록에서 **'UTF-8'**을 선택하고 파일을 저장합니다.

### 윈도우 메모장

1. CSS 파일을 메모장으로 엽니다.
2. 상단 메뉴에서 **'파일 > 다른 이름으로 저장'**을 선택합니다.
3. 저장 창 하단의 '인코딩' 드롭다운 목록에서 **'UTF-8'**을 선택하고 저장하여 기존 파일을 덮어씁니다.

CSS document is encoded in UTF-16. It should be encoded in UTF-8 instead.

이 오류는 CSS 파일이 컴퓨터가 이해하는 '언어(인코딩)' 중 잘못된 방식으로 저장되었다는 의미입니다. EPUB은 전 세계 모든 기기에서 글자가 깨지지 않도록, 모든 텍스트 기반 파일(HTML, CSS 등)을 UTF-8이라는 통일된 방식으로 저장하도록 약속했습니다. 🌐

## 왜 UTF-8을 사용해야 하나요?

UTF-8은 거의 모든 국가의 언어를 표현할 수 있는 국제 표준 인코딩 방식입니다. EPUB이 이 방식을 표준으로 채택한 이유는, 어떤 국가의 어떤 전자책 뷰어에서 열더라도 스타일 정보나 특수 문자가 깨지는 현상을 막고 완벽한 호환성을 보장하기 위해서입니다.

이 규칙을 지키지 않은 UTF-16 인코딩 파일을 사용하면, 일부 기기에서는 CSS 스타일이 전혀 적용되지 않아 디자인이 없는 평범한 텍스트로만 보일 수 있습니다.

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

이 문제는 사용하고 있는 텍스트 편집기 프로그램을 사용하여 파일의 인코딩 방식을 변경하고 다시 저장하면 간단히 해결할 수 있습니다.

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

1. 해당 CSS 파일을 편집기에서 엽니다.
2. 편집기 창의 오른쪽 아래에 있는 상태 표시줄을 보면 현재 인코딩(예: 'UTF-16 LE' 또는 'UTF-16 BE')이 표시됩니다.
3. 표시된 인코딩 이름을 클릭하면 메뉴가 나타납니다.
4. 메뉴에서 '인코딩하여 저장(Save with Encoding)' 또는 유사한 옵션을 선택합니다.
5. 나타나는 목록에서 **'UTF-8'**을 선택하고 파일을 저장합니다.

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

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

Empty or NULL reference found.

이 오류는 CSS 파일에서 다른 파일(예: 이미지, 폰트, 다른 CSS 파일)을 불러오려고 시도했지만, 정작 불러올 파일의 경로가 비어있다는 의미입니다.

목적지가 적히지 않은 텅 빈 이정표가 있는 것과 같습니다. 🗺️ 방향은 가리키지만 어디로 가야 할지 알려주지 않는 상황입니다.

## 주로 확인해야 할 부분

CSS 파일에서 url() 함수가 사용된 곳을 찾아보세요. 특히 다음과 같은 속성들을 중점적으로 확인해야 합니다.

• background-image: url(); (배경 이미지를 지정했지만 이미지 파일 경로가 없는 경우)
• @font-face 규칙 안의 src: url(); (폰트를 불러오려 했지만 폰트 파일 경로가 없는 경우)
• @import url(); (다른 CSS 파일을 가져오려 했지만 파일 경로가 없는 경우)
• list-style-image: url(); (목록의 글머리기호를 이미지로 지정했지만 파일 경로가 없는 경우)

## 해결 방법

두 가지 방법으로 간단히 해결할 수 있습니다.

1. 올바른 경로 입력하기 만약 파일이 실제로 필요한 것이라면, 비어있는 url() 괄호 안에 정확한 파일 경로를 입력합니다.

• 수정 전:
• CSS

   

  div { background-image: url(); }
  

• 수정 후: ✅
• CSS

   

  div { background-image: url('../images/background.png'); }
  

2. 불필요한 코드 삭제하기 만약 해당 스타일이 더 이상 필요하지 않다면, 코드 줄 전체를 삭제하는 것이 가장 좋습니다.

• 수정 전:
• CSS

   

  li { 
    color: black;
    list-style-image: url(); /* 더 이상 사용하지 않는 스타일 */
  }
  

• 수정 후: ✅
• CSS

   

  li { 
    color: black;
  }

The "%1$s" property must not be included in an EPUB Style Sheet.

이 오류는 전자책의 CSS 파일에 EPUB 표준에서 금지된 스타일 속성(%1$s)이 포함되어 있다는 의미입니다.

## 일부 속성이 금지되는 이유

EPUB은 독자가 글자 크기, 여백, 화면 방향을 자유롭게 바꿔도 내용이 그에 맞춰 부드럽게 재배열('리플로우')되어야 합니다. 📖 하지만 금지된 속성 중 일부는 레이아웃을 특정 위치에 고정시키거나 크기를 강제하여, 독자가 설정을 변경했을 때 글자가 화면 밖으로 벗어나거나 다른 내용과 겹치는 등 심각한 문제를 일으킬 수 있습니다.

독자의 편안한 읽기 환경을 보장하기 위해 이러한 속성들의 사용이 제한됩니다.

## 자주 발견되는 금지 속성 예시

• position: fixed; 또는 position: absolute;
  • 문제점: 요소를 화면의 특정 좌표에 고정시켜, 독자가 글자 크기를 키우면 본문과 겹쳐 보일 수 있습니다.
• -webkit-text-fill-color: 등 특정 뷰어 전용 속성
  • 문제점: 모든 전자책 뷰어에서 동일하게 보이지 않아 기기마다 디자인이 다르게 표현될 수 있습니다.

## 해결 방법

1. 오류 메시지에서 금지된 속성의 정확한 이름(%1$s)을 확인합니다.
2. EPUB에 포함된 모든 CSS 파일을 열어 해당 속성을 검색하여 찾습니다.
3. 찾아낸 코드 줄 전체(예: position: fixed;)를 삭제합니다.
4. 만약 해당 스타일이 꼭 필요하다면, margin, padding, float 등 EPUB에서 허용되는 다른 속성을 사용하여 비슷한 효과를 내도록 코드를 수정해야 합니다.

Error encountered while processing an item "%1$s"; skip other checks for the item.

이 메시지는 EPUBCheck가 특정 파일(%1$s)을 검사하던 중, 매우 심각하거나 기본적인 오류를 발견했음을 알리는 일종의 '작업 중단' 알림입니다.

자동차 정비를 생각해보면 쉽습니다. 🚗 정비사가 시동을 걸었는데 엔진이 완전히 고장나 켜지지 않는다면, 그 차의 와이퍼나 타이어 공기압을 점검하는 것은 의미가 없습니다.

이 메시지는 바로 그런 상황과 같습니다. 파일의 구조가 깨지는 등 첫 번째로 발견된 오류가 너무 심각해서, 그 파일에 대한 나머지 세부 검사(예: 링크 확인, 스타일 검사 등)를 진행하는 것이 무의미하다고 판단하여 모두 '중단'한 것입니다.

## 해결 방법

이 메시지 자체는 직접 수정할 대상이 아닙니다. 문제 해결의 핵심은 이 메시지 바로 전에 보고된 오류에 있습니다.

1. 가장 먼저 보고된 오류에 집중하세요. EPUBCheck 오류 목록에서, 이 '검사 중단' 메시지가 나오기 직전에 %1$s 파일에 대해 보고된 첫 번째 오류를 찾으세요. 그 오류가 모든 문제의 근본 원인입니다.
2. 첫 번째 오류를 해결하세요. 예를 들어, "XML 파싱 오류"와 같은 메시지가 먼저 나왔다면, 해당 파일의 태그가 깨졌거나 문법이 틀린 부분을 수정해야 합니다.
3. 다시 검사하세요. 원인이 된 첫 번째 오류를 수정한 후 EPUBCheck를 다시 실행하면, 이 '검사 중단' 메시지는 자연히 사라지고 해당 파일에 대한 모든 세부 검사가 정상적으로 진행될 것입니다.

Error encountered while processing custom message file "%1$s": "%2$s".

이 오류는 EPUBCheck가 사용자 정의 메시지 파일(%1$s)을 읽는 도중에 예상치 못한 문제가 발생했을 때 나타나는 포괄적인 메시지입니다. ⚙️

오류의 정확한 원인은 메시지의 두 번째 부분(%2$s)에 자세히 설명되어 있습니다. 이 부분을 확인하는 것이 문제 해결의 가장 중요한 첫걸음입니다.

## 발생할 수 있는 일반적인 원인

%2$s에 표시될 수 있는 구체적인 원인은 다양하지만, 주로 다음과 같은 문제들로 인해 발생합니다.

• 파일 인코딩 문제 📄: 사용자 정의 파일이 UTF-8 형식이 아닌 다른 방식(예: ANSI)으로 저장된 경우, 프로그램이 파일을 제대로 읽지 못할 수 있습니다.
• 파일 접근 권한 문제 🚫: EPUBCheck 프로그램이 해당 파일을 읽을 수 있는 운영체제 권한이 없습니다. 파일이 '읽기 전용'으로 설정되어 있거나 보호된 폴더에 있을 수 있습니다.
• 파일 손상 또는 잠금 🔒: 파일 자체가 손상되었거나, 다른 프로그램이 파일을 사용하고 있어 접근할 수 없는 경우입니다.

## 해결 방법

1. 오류 메시지(%2$s) 확인: 가장 먼저, %2$s에 표시된 구체적인 오류 내용을 읽고 원인을 파악합니다.
2. 인코딩 확인 및 변환: 파일을 텍스트 편집기(예: Notepad++, Visual Studio Code)에서 열어 'UTF-8' 형식으로 다시 저장해 보세요. 많은 경우 이 방법으로 문제가 해결됩니다.
3. 파일 권한 및 위치 확인: 파일의 속성을 확인하여 '읽기 전용'이 아닌지 보고, 접근이 쉬운 폴더(예: 바탕화면)로 파일을 옮겨서 다시 시도해 보세요.