내맘대로의 EPUB 제작 가이드

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. 파일 권한 및 위치 확인: 파일의 속성을 확인하여 '읽기 전용'이 아닌지 보고, 접근이 쉬운 폴더(예: 바탕화면)로 파일을 옮겨서 다시 시도해 보세요.

Unable to parse the custom format parameter in message overrides file "%1$s".

이 오류는 사용자 정의 메시지 파일(%1$s)에 포함된 매개변수(parameter) 자체의 형식에 오타나 문법 오류가 있을 때 발생합니다.

쉽게 말해, '빈칸 채우기'를 위한 %1$s와 같은 특별한 코드를 작성했는데, 그 코드의 형식이 잘못되어 컴퓨터가 이해하지 못하는 상황입니다. 💻

## '파싱(Parsing) 오류'란?

'파싱할 수 없다'는 것은 컴퓨터가 코드의 구조를 문법에 따라 분석하고 이해할 수 없다는 뜻입니다. 매개변수는 %, 숫자, $, s 등이 정해진 규칙에 따라 조합되어야 하는데, 이 규칙이 깨져 잘못된 명령으로 인식된 것입니다.

가장 흔한 원인은 매개변수를 입력할 때 발생한 단순 오타입니다.

## 해결 방법

1. 오류가 발생한 사용자 정의 메시지 파일(%1$s)을 엽니다.
2. 파일 안에 사용된 모든 매개변수(%... 형태의 코드)를 주의 깊게 살펴봅니다.
3. 아래의 올바른 형식과 비교하여 잘못된 부분을 수정합니다.

### 매개변수의 올바른 형식과 흔한 실수

• 올바른 형식: % 기호로 시작하고, 이어서 숫자, $ 기호, 그리고 마지막으로 s가 순서대로 와야 합니다.
  • 예시: %1$s, %2$s
• 흔한 실수:
  • % 1$s (중간에 공백이 들어간 경우)
  • %1s ($ 기호가 빠진 경우)
  • %$s (숫자가 빠진 경우)
  • %s1$ (순서가 잘못된 경우)

## 수정 예시

• 오류가 발생하는 사용자 정의 메시지:➡️ 매개변수에서 $ 기호가 빠졌기 때문에 '파싱 오류'가 발생합니다.

• RSC_001 = "%1s" 파일이 누락되었습니다.
  

• 올바르게 수정한 사용자 정의 메시지: ✅➡️ 올바른 형식인 %1$s로 수정하면 문제가 해결됩니다.

• RSC_001 = "%1$s" 파일이 누락되었습니다.
  

The custom suggestion contains too many parameters in message overrides file "%1$s".

이 오류는 바로 이전 오류(CHK_004)와 거의 동일하지만, 이번에는 '오류 메시지' 본문이 아닌 '수정 제안(suggestion)' 부분의 매개변수(parameter)가 잘못되었다는 점이 다릅니다.

## '메시지'와 '제안'의 차이

EPUBCheck의 일부 경고나 오류는 두 부분으로 구성됩니다.

• 메시지: 문제가 무엇인지 알려줍니다. (예: "잘못된 미디어 타입을 사용했습니다.")
• 제안: 그 문제를 어떻게 해결할 수 있는지 힌트를 줍니다. (예: "대신 'application/xhtml+xml'을 사용하세요.")

이 오류는 사용자가 직접 만든 '제안' 문장에 포함된 매개변수(%1$s, %2$s 등)의 개수가, EPUBCheck가 제공하는 원본 '제안'의 매개변수 개수보다 많을 때 발생합니다.

## 해결 방법

해결 방법은 이전과 동일합니다. 사용자 정의 파일(%1$s)을 열고 문제가 되는 **제안(suggestion)**을 찾으세요. 그 다음, 제안에 포함된 매개변수의 개수를 원본 제안의 개수와 같거나 적도록 수정하면 됩니다.

## 수정 예시

• 오류 ID: OPF_035
• 원본 메시지: XHTML/OPS 문서에는 "text/html" 미디어 타입을 사용할 수 없습니다. (매개변수 0개)
• 원본 제안 (OPF_035_SUG): "application/xhtml+xml"을 사용하세요. (매개변수 0개)
• 오류가 발생하는 사용자 정의 제안:➡️ 이 제안은 원본 제안에는 없는 매개변수 %1$s를 새로 추가했기 때문에 오류가 발생합니다. EPUBCheck는 이 빈칸에 무엇을 넣어야 할지 모릅니다.

• OPF_035_SUG = "%1$s" 대신 "application/xhtml+xml"을 사용하세요.
  

• 올바르게 수정한 사용자 정의 제안: ✅➡️ 이 제안은 원본과 마찬가지로 매개변수를 사용하지 않으므로 정상적으로 처리됩니다.

• OPF_035_SUG = 대신 권장 미디어 타입인 "application/xhtml+xml"을 사용해야 합니다.
  

The custom message contains too many parameters in message overrides file "%1$s".

이 오류는 사용자가 직접 만든 '사용자 정의 오류 메시지'의 내용에 문제가 있다는 뜻입니다. 구체적으로는, 메시지에 사용된 '매개변수(parameter)'의 개수가 원본 메시지보다 많다는 의미입니다.

## 매개변수(Parameter)란?

매개변수는 %1$s, %2$s 와 같이 표시되며, EPUBCheck가 오류를 보고할 때 그 자리에 구체적인 정보(예: 파일명, 잘못된 속성 값)를 채워 넣는 **'빈칸'**과 같습니다. 📝

예를 들어, 원본 오류 메시지가 "%1$s" 파일을 찾을 수 없습니다. 라면, EPUBCheck는 %1$s라는 빈칸에 실제 파일명(images/cover.jpg)을 채워 넣어 최종 메시지를 보여줍니다.

이 오류는 원본 메시지가 제공하는 '빈칸'은 하나인데, 사용자가 만든 새로운 메시지에는 '빈칸'을 두 개 이상 만들어 달라고 요청한 상황입니다. EPUBCheck는 추가된 빈칸에 무엇을 채워 넣어야 할지 모르기 때문에 오류를 보고합니다.

## 해결 방법

1. 오류가 발생한 사용자 정의 메시지 파일(%1$s)을 엽니다.
2. 문제가 되는 메시지를 찾습니다.
3. 사용자가 만든 메시지에 포함된 매개변수( %1$s, %2$s 등)의 개수가 원본 오류 메시지가 사용하는 매개변수의 개수와 같거나 적도록 수정해야 합니다.

Tip: 특정 오류 ID의 원본 메시지에 매개변수가 몇 개 있는지 확인하는 가장 좋은 방법은, 해당 오류가 발생하는 샘플 EPUB을 EPUBCheck로 검사하여 기본적으로 출력되는 메시지를 직접 확인하는 것입니다.

## 수정 예시

• 오류 ID: RSC_001
• 원본 메시지: "%1$s" 파일을 찾을 수 없습니다. (매개변수 1개: 파일명)
• 오류가 발생하는 사용자 정의 메시지:➡️ 이 메시지는 원본에 없는 두 번째 매개변수 %2$s를 사용하려고 하므로 오류가 발생합니다.

• RSC_001 = "%1$s" 파일을 "%2$s" 위치에서 찾지 못했습니다.
  

• 올바르게 수정한 사용자 정의 메시지: ✅➡️ 이 메시지는 원본과 동일하게 매개변수를 하나만 사용하므로 정상적으로 처리됩니다.

• RSC_001 = 중요: EPUB 패키지 안에 "%1$s" 파일이 누락되었습니다.