닥북으로 epub 만들기 - 추가 작업과 함정들

Twitter icon류광, 2014-02-21 19:02
DocBook XSL의 epub 변환용 스타일시트가 자동으로 처리해주지 않은 작업과 기타 주의사항.

군더더기 index.html 파일에 관련된 항목을 추가했습니다 -- 2014-02-21 23:37

이전 글에서 닥북(DocBook) 문서를 EPUB 파일로 변환하는 기본적인 방법을 설명했습니다. 이번 글에서는 구성이 좀 더 복잡한 EPUB 파일을 만들 때 필요한 추가적인 과정을 설명하고, 현재의 DocBook XSL 스타일시트와 XSLT 도구들의 버그 또는 한계 때문에 생기는 함정과 해결책도 소개합니다.

이전 글의 방법은 텍스트로만 구성된 전자책을 만드는 경우에는 이전 글의 방법으로 충분합니다. 그러나 이미지나 CSS 스타일시트, 커스텀 글꼴을 포함하는 좀 더 복잡한 형태의 EPUB 파일을 만들기 위해서는 관련 파일들을 적절한 장소로 복사하고 필요하다면 전자책 구성 정보를 담은 XML 파일을 수정하는 과정이 필요합니다.

아래 내용을 읽다 보면 아마 "이런 걸 일일이 처리하려면 상당히 지겹겠다"라는 생각이 들 텐데요. 그래서 이를 자동화해주는 Lua 스크립트를 틈틈히 만들고 있습니다. 조만간 닥북 모음집의 기존 docbookto 명령을 갱신하는 형태로 공개하겠습니다.

이 글과 이전 글에서 말하는 EPUB는 EPUB 버전 2에 해당합니다. 좀 더 최근의 EPUB 3은 나중에 기회가 되면 다루어 보겠습니다.

추가 파일 처리

EPUB 파일은 완결적이어야 합니다. 무슨 말이냐 하면, 전자책에 필요한 모든 파일이 epub 파일에 포함되어 있어야 한다는 점입니다. 그리고 mimetype과 META-INF/container.xml, 그리고 content.opf 파일 자신을 제외한 모든 파일이 content.opf 파일에 언급되어 있어야 합니다. 이번 절의 내용은 결국 이 규칙을 만족하는 방법을 장황하게 쓴 것일 뿐입니다.

이미지 파일 처리

변환하려는 닥북 문서가 C:\docbook\work\project02 디렉터리에 있고, 닥북 문서의 imagedata 요소에서 filehref="fig_1-02.png"로 C:\docbook\work\project02\fig_1-02.png를 참조한다고 합시다. EPUB 변환용 닥북 XSL 스타일시트를 이용해서 닥북 문서를 변환하고 나면 OEBPS 디렉터리에 <img src="fig_1-02.png" />가 포함된 HTML 파일이 만들어 집니다. 그리고 EPUB 파일의 전체적인 구성 정보를 담은 OEBPS\content.opf 파일에는 <item id="id582243" media-type="image/png" href="fig_1-02.png"/> 같은 항목이 있습니다. 문제는, 변환 과정에서 fig_1-02.png 파일이 OEBPS에 복사되지는 않는다는 것입니다. 그래서 생성된 epub 파일을 열어 보면 이미지가 나타나지 않으며, 유효성 검사를 실행해 보면 content.opf에 언급된 파일이 빠져 있다는 오류를 보게 됩니다. 짐작했겠지만 해결책은 zip으로 epub 파일을 만들기 전에 fig_1-02.png 파일을 OEBPS 디렉터리에 복사하는 것입니다.

그런데 이런 간단한 방법으로는 해결되지 않는 경우가 있습니다. 이번에는 닥북 문서의 imagedata에서 filehref="../../common/images/note.png"로 C:\docbook\common\images\note.png라는 파일을 참조한다고 합시다. 앞에서 말한 간단한 방법을 적용한다면 note.png 파일을 압축할 OEBPS 디렉터리보다 두 수준 위의 디렉터리에 복사해야 하는데, 그러면 최종 epub 파일에는 note.png 파일이 포함되지 않습니다. 이런 경우에는 이미지 파일이 닥북 문서의 지역 디렉터리로 옮기고 해당 imagedate 요소의 fileref 특성 자체를 변경해 주어야 합니다. content.opf 파일 역시 그에 맞게 갱신하고요.

마찬가지로, 지역 파일이 아닌 웹의 이미지 파일을 참조하는 경우에는 해당 파일을 내려 받아서 OEBPS 디렉터리에 복사한 후 관련 속성들을 적절히 일치시켜야 합니다. 전용 전자책 단말기들 중에는 웹 접속 기능이 없는 것들이 아직 많이 남아 있고, 웹에 접속할 수 있다고 해도 배터리나 데이터 요금 절약 차원에서 이런 처리가 필요합니다.

어떤 경우이든, 원본 문서를 건드리지 않고 싶다면 변환된 HTML 파일의 img 요소 src 특성을 변경하면 됩니다.

css 파일 처리

커스텀 CSS를 적용하는 경우 CSS 파일도 마찬가지 방식으로 OEBPS 디렉터리에 옮겨야 합니다. 지역 디렉터리 관련해서 닥분 문서 대신 HTML 파일을 변경한다면 요소 안의 의 href 특성을 변경하면 됩니다.

참고로, CSS 스타일시트 적용을 위한 닥북 XSL 매개변수는 html.stylesheet입니다. 닥북 모음집의 경우에는 docbookto 명령에 -p html.stylesheet <CSS 파일 경로>를 추가하면 됩니다.

내장 글꼴

전자책 단말기나 앱이 기본으로 제공하는 글꼴 이외의 글꼴을 사용하려면 원하는 글꼴 파일을 epub 파일 안에 포함시키고 CSS 파일의 @font-face 구문을 통해서 그 파일을 참조해야 하는데요. 앞의 경우들과 마찬가지로, EPUB 변환 XSL 스타일시트가 글꼴 파일을 자동으로 복사해주지는 않습니다. 해당 글꼴 파일을 OEBPS 파일에 복사하고, content.opf 파일의 해당 item 항목과 CSS 파일의 @font-face의 src 속성을 설정해 주면 해결이 됩니다.

참고로, 글꼴 내장을 위한 닥북 XSL 매개변수는 epub.embedded.fonts입니다. 닥북 모음집의 경우에는 docbookto 명령에 -p epub.embedded.fonts <글꼴 파일 경로>를 추가하면 됩니다.

OpenType 글꼴(확장자 oft)이 아닌 TrueType 글꼴(확장자 ttf)을 지정하면 content.opf 파일의 해당 item 요소의 media-type 특성이 설정되지 않습니다. 이는 TTF 파일에 MIME 형식 이름이 아직 배정되지 않았기 때문인데요. EPUB Validator의 유효성 검사를 통과하려면 media-type 특성이 반드시 존재해야 하므로 아무 값으로라도 해당 항목에 media-type 특성을 추가해야 합니다. OTF의 font/opentype을 본따서 font/truetype 정도로 하면 되겠습니다.

기타 처리 사항

다음은 주로 관련 도구나 XSL 스타일시트의 버그 또는 한계에서 비롯되는 문제점들입니다.

자동으로 추가되는 알림 아이콘

닥북 문서에 note나 caution, important 같은 요소가 존재하고 닥북 변환 시 닥북 XSL admon.graphics 매개변수를 1로 지정했다면 해당 요소에 손가락이나 느낌표 같은 아이콘이 추가됩니다. 그런데 현재 버전의 EPUB 변환용 닥북 XSL 스타일시트는 이를 인식하지 못해서 해당 아이콘 파일을 content.opf에 포함시키지 않습니다. 앞의 '이미지 파일 처리' 절에서 말한 문제와는 좀 다릅니다. 앞에서는 content.opf에는 있지만 OEBPS에는 없는 것이 문제였고, 이번에는 아예 content.opf에 빠져 있다는 것이 문제입니다. 따라서 content.opf에 형태의 항목들을 추가해 주고, 해당 이미지 파일들(기본적으로는 닥북 XSL 스타일시트의 images 디렉터리에 있습니다)을 OEBPS 디렉터리에 옮기고, 필요하다면 HTML 파일들의 해당 img 요소의 src도 적절히 조정해 주어야 합니다.

Xalan과 Saxon 관련 문제

닥북 문서를 현재 버전의 Xalan이나 Saxon으로 변환하면 toc.ncx 파일(차례 정보를 담은 XML 파일)과 content.opf 파일에 엉뚱한 DTD 선언문이 포함됩니다. xsltproc에서는 이런 문제가 없습니다.

두 파일에서 <?xml ...?> 다음의 <!DOCTYPE ... > 부분을 삭제해 주면 해결이 됩니다.

index.html 제거

닥북 문서의 최상위 요소나 변환 관련 설정에 따라서는 content.opf 파일에 참조되지 않는, 그리고 전자책의 실질적인 내용에 포함되지 않는 index.html이 생성되기도 합니다. 예를 들어 book이 최상위 요소인 닥북 문서를 변환했을 때 실질적인 목차 페이지는 bk01-toc.html 파일이며, 함께 생성되는 index.html은 군더더기일 뿐입니다. 이 index.html 파일은 아마도 EPUB 변환용 XSL 스타일시트가 내부적으로 사용하는 XHTML 변환용 XSL 스타일시트의 잔재로 보입니다.

content.opf 파일에는 전자책을 구성하는 모든 내용 파일에 대한 item 항목이 존재해야 하며, 반대로 content.opf 파일에 없는 파일은 전자책 epub 파일에 포함되지 말아야 합니다. 따라서 OEBPS 디렉터리의 파일들을 zip으로 압축할 때 이 index.html 파일은 제외해야 유효한 epub 파일이 만들어집니다. 먼저 index.html 파일을 삭제한 후 압축하면 해결이 됩니다.

XInclude 관련 팁

XInclude를 이용해서 다른 닥북 XML 문서를 현재 닥북 XML 문서에 포함시키는 경우, 변환 시 keep.relative.image.uris 매개변수를 0으로 설정하는 것이 파일 경로 관련 혼동을 피하는 데 도움이 됩니다.

예를 들어 Prj1 디렉터리에 있는 문서 A의 imagedata 요소가 Prj1 디렉터리의 fig1.png라는 이미지 파일을 참조하고 Prj2 디렉터리에 있는 문서 B의 imagedata 요소가 Prj2 디렉터리의 fig1.png를 참조하고, 문서 A가 XInclude를 이용해서 문서 B를 포함시킨다고 합시다. keep.relative.image.uris가 1(기본 값)인 상태에서 문서 A를 변환하면 두 요소가 위치가 다른 두 fig1.png를 동일한 이름으로 참조하게 되므로 HTML 파일들에서 둘을 구분할 수 없습니다. keep.relative.image.uris를 0으로 하면 상대적인 위치 차이에 대한 정보를 담은 xml:base 특성이 적절히 삽입되므로 둘을 구분할 수 있습니다.

태그: DocBook 닥북

comments powered by Disqus