<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">

<article lang="ko">

<articleinfo>
<authorgroup>
	<author>
	<surname>류</surname><firstname>광</firstname>
	</author>

</authorgroup>

</articleinfo>
<title>닥북 모음집용 docbookto 명령에 대해</title>
  <para>docbookto 명령은 DocBook XML 파일을 다른 형식의 파일로 변환하는 명령입니다.
<ulink url="http://docbook.or.kr/">닥북 한국</ulink>의 <ulink url="http://docbook.or.kr/phpBB2/profile.php?mode=viewprofile&amp;u=4">류광</ulink>이 작성했으며 <ulink url="http://www.lua.org/license.html#5">Lua 5.0+ 라이선스</ulink>를 따릅니다.
소스 코드는 %DOCBOOK_HOME%\software\luascript\docbookto\ 디렉터리에 있습니다.
</para>

<section><title>사용법:</title>


	<section><title>명령 구문</title>

	<programlisting> docbookto html [옵션] &lt;입력파일.xml&gt;
</programlisting>
	<para>여러 개의 HTML 파일들을 생성합니다.
	</para>
	<programlisting> docbookto onehtml [옵션] &lt;입력파일.xml&gt; [출력파일.html]
</programlisting>
	<para>하나의 HTML 파일을 출력합니다. [출력파일]에 출력 HTML 파일 이름을
	지정하면 그 파일에 저장됩니다. 지정하지 않으면 표준 출력(콘솔)으로
	출력됩니다.
	</para>
	<programlisting> docbookto pdf [옵션] &lt;입력파일.xml 또는 입력파일.fo&gt; [출력파일.pdf]
</programlisting>
	<para>PDF 파일을 생성합니다. [출력파일.pdf]을 생략하며 &lt;입력파일.pdf&gt;가
	쓰입니다.
	</para>
	<programlisting> docbookto fo [옵션] &lt;입력파일.xml&gt; [출력파일.fo]
</programlisting>
	<para>XSL-FO 파일을 생성합니다. [출력파일.fo]로 출력 FO 파일 이름을
	지정하면 그 파일에 저장됩니다. 지정하지 않으면 표준 출력(콘솔)으로
	출력됩니다.
	</para>

	</section>

	<section><title>옵션</title>

	<programlisting> -c &lt;설정 파일&gt;
</programlisting>
	<para>지정된 파일에 담긴 XSLT 매개변수 설정들이 XSLT 처리기에 적용됩니다. 설정 파일의 구조에 대해서는 다음 절에서 좀 더 설명합니다.
	</para>
	<programlisting> -p &lt;XSLT 매개변수&gt; &lt;값&gt;
</programlisting>
	<para>추가적인 XSLT 매개변수와 값을 지정하는 옵션으로, 설정 파일을 수정하지 않고도 매개변수들을 시험해 보고자 할 때 유용합니다. -c 옵션으로 지정한 설정 파일에 같은 이름의 매개변수가 있는 경우 설정 파일의 것이 무시됩니다. 여러 개의 매개변수들을 지정하는 경우 매번 -p를 지정해야 합니다.
	</para>
	<programlisting> -s &lt;XSL 스타일시트 파일&gt;
</programlisting>
	<para>기본 XSL 스타일시트 파일 대신 지정된 파일을 사용합니다. {XSL파일.xsl}
	형태로 지정하면 %DOCBOO_HOME%\stylesheet\XSL파일.xsl 로 간주됩니다.
	</para>
	<programlisting> --xalan
</programlisting>
	<para>XSLT 처리기로 기본 xsltproc 대신 Xalan을 사용합니다.
	</para>
	<programlisting> --saxon
</programlisting>
	<para>XSLT 처리기로 기본 xsltproc 대신 Saxon을 사용합니다.
	</para>
	<programlisting> --debug
</programlisting>
	<para>변환 명령을 실제로 실행하지는 않고 명령문만 출력합니다.
	</para>

	</section>

</section>

<section><title>설정 파일에 대해</title>

<para>-c 옵션으로 지정하는 설정 파일은
</para>
<programlisting> 매개변수이름 = 값
</programlisting>
<para>형태의 항목들이 한 줄에 하나씩 존재하는 파일이어야 합니다. 각 매개변수는 유효한 닥북 XSL
매개변수이어야 합니다.<footnote>
<para>
닥북 변환의 여러 특성들을 제어하는 XSL 매개변수들에 대해서는 DocBook XSL: The Complete Guide의 <ulink url="http://www.sagehill.net/docbookxsl/OptionsPart.html">Part II. Stylesheet options</ulink> 또는 <ulink url="http://docbook.sourceforge.net/release/xsl/current/doc/reference.html">DocBook XSL Stylesheets Reference Documentation</ulink>을 참고하세요.
</para>
</footnote>

</para>

<para>다음은 설정 파일의 예입니다.
</para>
<programlisting># 목차 관련
generate.toc=book toc,title article toc,title
toc.section.depth=2

# 이미지 관련
admon.graphics = 1
admon.graphics.path = {DBK_BASE_URL}/stylesheet/docbook-xsl/images/
callout.graphics.path = {DBK_BASE_URL}/stylesheet/docbook-xsl/images/callouts/

# callout (xalan)
use.extensions=1
callouts.extension=1
textinsert.extension=1
</programlisting>
<para>설정 파일에서 #로 시작하는 줄은 주석입니다. 그리고 값 부분의 {DBK_BASE_URL}은
docbookto 명령 실행 시 환경 변수 DBK_BASE_URL의 값(dbkshell.bat에 정의된)로 치환됩니다.
</para>
<para>docbookto가 인식하는 설정 파일은 runlua xslt 명령에도 사용할 수 있습니다.
</para>
<para>-c 옵션으로 지정된 파일은 절대 경로일 수도 있고 상대 경로일 수도 있습니다.
상대 경로인 경우 현재 docbookto를 실행한 디렉터리를 기준으로 합니다.
또한 {설정 파일} 형태로 지정하면 %DOCBOOK_HOME%\conf에서 해당 파일을 찾습니다.
예를 들어 닥북 모음집을 e:\docbook에 설치했다고 할 때,
</para>
<programlisting> &gt; docbookto html -c {custom-html.conf} test.xml
</programlisting>
<para>은 e:\docbook\conf\custom-html.conf 를 사용합니다.
</para>
<para>-c 옵션을 지정하지 않은 경우 다음과 같은 기본 설정 파일들이 쓰입니다.
</para>
<itemizedlist>
<listitem><para>docbookto pdf나 docbookto fo: %DOCBOOK_HOME%\conf\dbk-pdf.conf</para>
</listitem>
<listitem><para>docbookto html : %DOCBOOK_HOME%\conf\dbk-html.conf</para>
</listitem>
<listitem><para>docbookto onehtml : %DOCBOOK_HOME%\conf\dbk-onehtml.conf</para>
</listitem>
</itemizedlist>

</section>

<section><title>Xalan 관련</title>

<para>닥북 모음집 1.0(dbkpack-1.0)에는 Xalan 2.7.1이 포함되어 있습니다. docbookto 실행 시 --xalan 옵션을 지정하면 xsltproc 대신 Xalan이 XSL 변환을 수행합니다.
</para>
<para>Xalan은 xsltproc보다 느리지만 (현재의)xsltproc으로는 처리할 수 없는 기능 몇 가지를 제공합니다. 대표적인 것이 callout 입니다. <ulink url="http://docbook.or.kr/phpBB2/viewtopic.php?t=471">http://docbook.or.kr/phpBB2/viewtopic.php?t=471</ulink> 를 참고하세요.
</para>
<programlisting> &gt; docbookto pdf programlisting.xml
</programlisting>
<para>로 생성한 PDF와
</para>
<programlisting> &gt; docbookto pdf --xalan programlisting.xml
</programlisting>
<para>로 생성한 PDF를 비교해 보시면 차이를 알 수 있을 것입니다.
</para>

</section>

<section><title>Saxon 관련</title>

<para>닥북 모음집 1.0(dbkpack-1.0)에는 Saxon 6.5.5가 포함되어 있습니다. docbookto 실행 시 --saxon 옵션을 지정하면 xsltproc 대신 Saxon이 XSL 변환을 수행합니다.
</para>
<para>Saxon은 xsltproc보다 느리지만 (현재의)xsltproc으로는 처리할 수 없는 기능 몇 가지를 제공합니다. 대표적인 것이 한글 색인입니다. 이에 대해서는 <ulink url="http://docbook.or.kr/phpBB2/viewtopic.php?topic=733">http://docbook.or.kr/phpBB2/viewtopic.php?topic=733</ulink>을 참고하세요.
</para>
<para>&lt;index /&gt;와 &lt;indexterm&gt;들이 적절히 존재하는 XML 파일로부터 가, 나, 다 순의 한글 색인이 포함된 PDF를 생성하는 방법은 다음과 같습니다.
</para>
<programlisting> &gt; docbook pdf --saxon -s {dbk-fo-autoidx.xsl} test.xml
</programlisting>
<para>또한 Saxon은 앞 절에서 말한 callout 기능도 제공합니다.
</para>
<!-- hr -->

</section>

</article>
