번역서 정보 | 번역서 질문&의견 | 번역 이야기 | 문서 창고 | 방명록

근황 - 2014-03-27

류광, 2014/03/31 00:06
번역서 소식, 닥북 - epub 변환 도구.

작년 말과 올해 초에 걸쳐서 The Performance of Open Source Applications라는 작지만 묵직한 책을 번역했고, 저번 주에 2차 교정을 마쳤습니다. 번역서는 4월 중에 나올 것 같습니다.

지금은 The Browser Hacker's Handbook이라는 흥미진진한 책을 번역하고 있습니다. 컴퓨터로 할 수 있는 거의 모든 일을 웹 브라우저에서 할 수 있는 시절인만큼 브라우저에 대한/를 이용한 해킹[1]은 사용자에게나 개발자에게나 상당히 중요한 분야일 것입니다.

APUE3rd는 안타깝게도 출판사의 조판 편집 작업 일정이 아직 잡히지 않은 상태입니다. 따라서 번역서가 언제 나올 지는 알 수 없습니다....

저번 에서 설명한 "닥북으로 epub 만들기" 관련 도구를 닥북 한국 홈페이지에 올렸습니다. 링크: 닥북 - epub 변환 도구


[1]아직 책을 다 보지는 못했지만, 이 책에서 말하는 해킹의 크래킹에 해당하는 것 같습니다.

top
트랙백 0 : 의견 # + 0

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

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

군더더기 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 파일의 전체적인 구성 정보를 담은 OEBPScontent.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 파일을 변경한다면 <head> 요소 안의 <link rel="stylesheet" type="text/css" href="***.css"/>의 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에 <item id="..." href="..." media-type="image/png"/> 형태의 항목들을 추가해 주고, 해당 이미지 파일들(기본적으로는 닥북 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 특성이 적절히 삽입되므로 둘을 구분할 수 있습니다.

top
트랙백 0 : 의견 # + 0

닥북(DocBook)으로 epub 파일(전자책 표준 형식) 만들기

류광, 2014/02/11 00:15
닥북으로 epub 파일을 만들기 -- 개방 표준 형식의 파일들과 오픈소스 소프트웨어만으로 전자책을 만들어 봅시다.

이 글에서는 소프트웨어 문서화 분야에서 널리 쓰이고 있는 닥북 형식의 문서를 전자책의 사실상 표준인 EPUB 파일로 변환하는 방법을 설명합니다. epub 파일을 만들어 주는 도구는 많이 있지만, 이 글에서 말하는 방법은 다음 두 가지 면에서 의미가 있습니다.

  1. 표준 DocBook 형식을 따르는 문서를 원본으로 사용하기 때문에 저작, 변환, 검색, 추출 등에서 자동화 여지가 아주 큽니다. 예를 들어 프로그램 소스 코드의 주석이나 데이터베이스로부터 자동으로 닥북 문서를 만들어내고 그것을 다시 자동으로 전자책으로 변환해서 소스코드 문서화나 보고서를 생성하는 것은 현업에 바로 적용할 수 있는 수준으로 가능하고, 이론적으로 닥북으로 변환할 수 있는 것이면 무엇이든 epub로도 변환할 수 있습니다. 예를 들어 오픈오피스나 MS 워드, 아래아한글(HWP) 파일을 자동으로 epub 파일로 변환하는 것도 가능합니다.
  2. 변환 과정에 쓰이는 도구들이 모두 오픈소스입니다. '공짜'라는 점도 중요하겠지만, 필요하다면 자신의 요구에 맞게 수정해서 사용할 수 있다는 점이 더욱 중요합니다.

위키 백과 EPUB에서 보듯이, epub 파일은 기본적으로 HTML 파일들과 관련 정보 파일을 zip 형식으로 압축한 것입니다. 따라서 닥북 문서를 epub 파일로 만드는 기본적인 절차는 다음과 같습니다.

  1. 닥북 문서를 적절한 HTML 파일들과 관련 정보 파일로 변환한다.
  2. 그 파일들을 몇 가지 규칙에 따라 하나의 zip 파일로 압축한다.

1번 과정을 위해서는 xsltproc 같은 XSLT 프로세서와 epub 파일을 위해 마련된 XSLT 스타일시트들이 필요합니다. Windows 사용자라면 그냥 닥북 한국의 Windows용 닥북 모음집(이하 간단히 닥북 모음집) 하나로 해결이 됩니다. 다른 주요 OS들에도 닥북 변환을 위한 패키지가 마련되어 있을 것입니다. 이 글에서는 닥북 모음집을 기준으로 합니다.

2번 과정을 위해서는 zip을 지원하는 압축 프로그램이 필요합니다. 잠시 후 설명할 "몇 가지 규칙"을 만족하는 문제나 이 방법의 중요한 장점인 '자동화'를 위해서는 일반적인 GUI 압축 프로그램보다는 명령줄 기반 압축 프로그램이 유리한데요. 이 글에서는 Info-ZIP의 명령줄 유틸리티 zip.exe를 사용합니다. "zip.exe"으로 웹을 검색해 보면 미리 빌드된 실행 파일을 구할 수 있을 것입니다.

좀 더 구체적인 과정으로 들어가서, 닥북 문서를 epub를 위한 파일들로 변환하는 가장 간단한 방법은 DocBook XSL 스타일시트의 epub/docbook.xsl을 적용하는 것입니다. xsltproc을 사용한다고 하면, 명령줄(cmd.exe)에서 다음을 실행하면 됩니다.

> xsltproc 닥북_XSL_스타일시트/epub/docbook.xsl 닥북문서.xml

닥북 모음집에서는 다음과 같이 하면 됩니다. 기본적으로 위의 방법과 같은 결과를 내지만, 타이핑이 적고 저자 이름이 이름 성 순서가 아니라 성 이름 순서로 표시되는 등의 추가적인 장점이 생깁니다.

> docbookto html {dbk-epub.xsl} 닥북문서.xml

변환이 성공적이면 현재 디렉터리에 OEBPS라는 디렉터리와 META-INF라는 디렉터리가 생깁니다. OEBPS 디렉터리에는 전자책의 내용을 구성하는 HTML 파일들이, META-INF에는 전자책의 전체적인 구성에 대한 정보를 담은 파일이 들어 있습니다. 여기까지가 1번 과정입니다.

이제 2번 과정으로 넘어가서, 내용 파일들을 zip으로 압축하기 전에 추가적인 파일 하나가 더 필요합니다. 바로 mimetype이라는 파일인데요. 이 파일은 application/epub+zip 라는 문자열을 담은 텍스트 파일입니다. 이 파일은 한 번만 만들어 두고 새 epub를 만들 때마다 재활용하면 됩니다. 텍스트 편집기를 이용해서 만들어도 되고, 명령줄에서 바로 만들 수도 있습니다:

> copy CON mimetype
application/epub+zip^Z

마지막의 ^Z는 Ctrl+Z입니다.

이제 필요한 파일들이 모두 만들어졌습니다. 그런데 이 파일들을 무작정 zip으로 압축하면 안 됩니다. 앞에서 잠깐 언급한 "몇 가지 규칙"을 지켜야 하는데, 다음과 같습니다.

  1. 압축 파일의 첫 파일은 반드시 mimetype 파일이어야 한다.
  2. 그 mimetype 파일은 압축률이 0%이고(즉, 압축하지 않고 그대로 포함) 추가적인 헤더가 없어야 한다.

개인적인 경험으로, GUI 압축 프로그램으로는 이 두가지를 제대로 만족하기가 어려웠습니다. 심지어 7zip의 명령줄 버전 7za.exe로도 잘 안 되고, 앞에서 언급한 zip.exe로 하는 게 제일 확실하더군요. 만들고자 하는 epub 파일 이름이 test.epub라고 할 때, 다음과 같이 하면 됩니다.

> del test.epub
> zip -0 -X test.epub mimetype
> zip -r test.epub OEBPS META-INF

설명하자면, 우선 같은 이름의 epub 파일이 있을 수도 있으므로 먼저 삭제해 줍니다. 그런 다음 mimetype 파일 하나만으로 test.epub 압축 파일을 만듭니다(zip 파일을 먼저 만든 후 확장자를 바꿀 필요 없이 처음부터 확장자를 .epub로 하면 됩니다). -0이라는 옵션은 압축을 하지 말라는 뜻이고 -X는 추가적인 헤더를 포함시키지 말라는 뜻입니다. 이 두 옵션이 앞에서 말한 두 가지 규칙을 지키는 데 핵심입니다. 마지막으로 OEBPSMETA-INF를 test.epub에 추가합니다.

이렇게 해서 하나의 epub 파일이 완성되었습니다. 완성된 epub 파일이 표준을 제대로 따르는지를 EPUB Validator에서 검사해 볼 수 있으니 활용하시고요.

이상은 가장 기본적인 과정이고, 이미지 파일을 참조하는 등의 좀 더 복잡한 형태의 닥북 문서를 변환할 때에는 1번과 2번 사이에서 추가적인(그러나 자동화가 가능한) 처리가 필요합니다. 이에 대해서는 다음에 좀 더 이야기해 보겠습니다.

top
트랙백 0 : 의견 # + 0

GEG 2 번역서 출간 소식 + 독자 증정 이벤트

류광, 2014/01/21 18:49
GEG2 번역서 나왔습니다. 독자 증정 이벤트도 있습니다.

본문 열기

top
TAG 번역서
트랙백 0 : 의견 # + 0

2014년 새해 복 많이 받으세요!

류광, 2014/01/06 01:05

작년 한 해 제 번역서와 블로그에 관심 가져주셔서 고맙습니다. 모두들 새해 복 많이 받으세요!

올해 초에는 Game Engine Gems 2 번역서가 나올 예정이고 Advanced Programming in UNIX Evironment 3rd의 번역서도 아마 여름이 되기 전에 나올 것입니다. 그 외에도 오픈소스 관련 책과 Unity 관련 책 등 다양한 책들을 준비하고 있습니다.

올해에는 근황 글이나 번역서 소개 글 외의 글도 많이(적어도 예년보다는) 올릴 계획입니다. 좀더 구체적으로, 루아, 닥북과 epub, C++, 번역어, 프로그래밍 등에 대해 분야별로 적어도 글 두어 개 정도는 쓰려고 합니다. 사실 매년 새해 인사 글을 쓸 때마다 "올해에는 블로그에 글을 더 많이 써야지" 하는 생각을 하는데, 헛된 약속이 될까봐 그냥 생각만 하고 글로 쓰지는 않았던 적이 많았습니다. 올해부터는 좀 달라지겠습니다.

다시 한 번, 모두 새해 복 많이 받으시고 건강하세요!

top
트랙백 0 : 의견 # + 0

◀ PREV : [1] : [2] : [3] : [4] : [5] : ... [51] : NEXT ▶