Menu

문서정보

목차

소개

http://www.docbook.org/graphics/button.jpg

Joinc위키 운영초기 (대략 2002년정도?)에 Docbook를 컨텐츠 저작 형식으로 사용한 적이 있었다. Docbook를 사용한 가장 큰 이유는 문서의 외형에 신경쓸 필요 없이 구조에만 신경쓰고 문서를 만들 수 있다는 것과 만들어진 문서를 자유스럽게 HTML(:12), PDF(:12) 등의 형식으로 변환할 수 있다는 것 때문이었다. 출력물의 품질도 꽤나 맘에 들었다.

그전에 Latex(:12)와 같은 조판도구를 사용하기도 했는데, Latex는 사용하기가 지나치게 번거로워서 사용을 꺼리게 됐다.

그러다가 wiki(:12)로 넘어갔다. Docbook으로 문서 작성하는 것도 너무 번거롭다는 생각이 들어서였기 때문이다. Docbook으로 문서를 작성하고 나면 변환 과정을 거치면서 문법 오류를 수정하고 - SGML 이였기 때문에 문법오류 등에 민감했다. - 그걸 다시 wiki에 옮겨야 했다. kldp와 같이 docbook 문서를 직접 HTML로 변환해주는 wiki 시스템을 내장하는 방법도 생각해 봤지만 귀찮았다.

다시 관심을 가지게 된 계기

2010년경 성우 연기를 배우게 된다. 재미있었다. 발성연습과 시사 상식을 늘리기 위해서 신문을 이용한 리딩연습을 많이 하게 되는데, 전자책을 사용하기로 마음 먹었다. 그전에는 스케치북에 스크랩을 했는데, 괜찮은 방법이긴 하지만 스크랩하는게 귀찮고 많은 무엇 보다 이동성이 떨어지는게 문제였다.

게다가 리딩할때는 단어의 장단음과 뜻에도 신경을 써야 하는데, 마침 전자책이 장단음을 포함한 단어사전을 내장하고 있어서 구입했다.

그렇게 구입해서 ebook(:12)을 사용하다 보니, 자연스럽게 이북 컨텐츠 제작에 관심을 가지게 되었다. 그때 고민한게 어떡하면 간편한 ebook 저작환경을 만들 수 있을까 였는데, 찾아보니 결국 docbook(:12)가 그 해답이더라는.. 그래서 다시 docbook을 시작하게 됐다.

예전에 docbook 레퍼런스 문서를 만든적이 있었는데, 워낙 오래전 문서인데다가 SGML를 기준으로 하고 있어서 docbook xml 기준으로 다시 배워야할 처지. 뭐 SGML이나 XML이나 그게 그거라서 큰 문제가 되지는 않지만.

Docbook XML

DocBook는 기술 문서를 작성하기 위한 마크업 언어로 XML로 구현했다. XML로 구현된 많은 개발 도구들이 그렇듯이, Docbook도 문서의 구조와 문서의 재현을 분리할 수 있다. Docbook을 이용할 경우 문서 작성자는 잡다한 것에 신경쓰지 않고, 문서 자체에만 신경쓸 수 있다.

DocBook가 기술문서를 작성하기 위해서 사용되는 이유다. 이런 류의 문서 작성도구는 문서의 아름다움을 필요로 하는 영역에는 적당하지 않다. 썰렁하게 보이기 때문이다. Docbook처럼 정보를 저장하기 좋은 도구도 없는데 말이다.

Docbook 문서 타입

레포트와 논문과 책등 문서의 출판형식에 따라서 구성에도 차이가 있을 수 밖에 없다. Docbook 는 다음과 같은 문서 형태를 지원한다.
  • set : 이것은 문서 형식이 아니다. 하나 이상의 책의 모음이다.
  • book : 여러개의 장 (chapter), article 로 이루어진 문서형태로 glossaries(용어집) 와 appendics(부록)등을 포함하기도 한다.
  • article : 하나의 제목을 가지는 논문형식의 짧은 문서
  • chapter : 주로 book의 구성요소로 사용한다.
  • appendix : 본문끝에 덧붙이는 참고용 문서

문서 예제

다음은 docbook의 일반적인 문서 형태다.
<article xmlns="http://docbook.org/ns/docbook" version="5.0" encoding="UTF-8" lang="ko">
<info>
    <title>헤드라인</title>
</info>

<section xml:lang="ko">
<info>
    <title>초고속 인터페이서 '썬더볼트'에 대한 궁금증</title>
    <author>
        <surname>인터넷 한겨례</surname>
    </author>
    <pubdate>2011/2/28</pubdate>
</info>
<para>
며칠 전 애플은 초고속 인터페이스 ‘썬더볼트’를 채택한 새로운 노트북 '맥북 프로' 시리즈를 발표했다. 
PC업계는 썬더볼드의 기술과 배경에 많은 관심을 나타내고 있다. 썬더볼트는 
파이어와이어와 USB 3.0을 대체할 수 있는 고성능 인터페이스 기술이기 때문이다.
</para>

<para>
그래서인지 썬더볼트에 대한 의문점도 그만큼 많다. 인텔 발표를 기준으로 썬더볼트에 관한 궁금증을 
문답 형식으로 정리했다.
</para>

<para>
1. 세부사양이 공개되는 시기는?
</para>
이 문서는 article형태의 문서로 title과 section 그리고 부제목과 저자, 작성일 등의 정보를 가지고 있다. encoding는 UTF-8이며 한글로된 문서라는 정보를 가지고 있다.

또 다른 문서의 형태인 Book의 예다.
<book xml:id="simple_book" xmlns="http://docbook.org/ns/docbook" version="5.0">
  <title>Very simple book</title>
  <chapter xml:id="chapter_1">
    <title>Chapter 1</title>
    <para>Hello world!</para>
    <para>I hope that your day is proceeding <emphasis>splendidly</emphasis>!</para>
  </chapter>
  <chapter xml:id="chapter_2">
    <title>Chapter 2</title>
    <para>Hello again, world!</para>
  </chapter>
</book>

문서의 구조

다양한 문서의 종류가 있긴 하지만, 문서의 구성을 이해하고 있다면 문서의 종류와 상관없이 간단하게 원하는 형식의 문서를 작성할 수 있다.

문서의 구성요소는 여기에서 크게 벗어나지 않는다.
  1. 제목과 메타 정보들 : 문서가 어떤 정보를 포함하고 있는 지를 알려주는 제목과 문서의 저자 작성일등등의 부가 정보
  2. 문단 :
글의 최소 단위는 문장이다. 하지만 문장과 문장을 개별적으로 관리하면 가독성이 떨어지기 때문에 비슷한 맥락을 따라는 몇개의 무장을 엮어서 문단을 구성한다. 글의 가독성은 문단의 구성이 절반을 차지한다고 볼 수 있다. 너무 적은 수의 문장으로 문단을 구성하면, 맥락이 뚝뚝 끊기는 느낌을 갖는다. 반면 너무 많은 문장으로 문단이 구성되면, 복잡도가 높아져서 (정보가 많아져서) 독자는 맥락의 이해에 어려움을 느낀다. 보통은 이 글은 읽기에 지루해라는 느낌을 가진다. 가독성이 그리 좋지 않은 LCD에서 수십줄의 문장으로 구성된 문단은 독자를 질리게 만든다.

제목과 문단만 가지고도 문서를 만들 수 있다. 예컨데 Article 같은 비교적 짧은 문서같은 경우에는 몇 개의 문단만으로도 문서를 완성할 수 있을 것이다. 하지만 Book 같은 경우에는 문단만으로 문서를 구성하면 내용을 효과적으로 전달하기가 힘들어진다. 정보의 양이 많아지면 사람은 혼란을 느낀다. 정보의 양을 줄이는 가장 좋은 방법은 다시 몇 단계로 구조화 하는 것이다.

문서들은 대게의 겨우 chapter와 section으로 문서의 내용을 논리적으로 재 구성한다. chapter는 이고 section은 로 보면 된다. 절은 두 단계 이상의 깊이를 가질 수 있다. 이제 chapter과 section으로 문서를 구조화 해보자.

장과 절로 이루어진 Book 형식 문서의 전형적인 구조를 볼 수 있다.

이 문서의 구조만 알고 있다면, 간단하게 Docbook 문서를 만들 수 있다. 문단과 제목, 섹션, 챕터에 대한 태그만 알면 된다.

Docbook 문서 작성

여기에서는 기본적인 문서 작성 형태만 살펴볼 것이다. 고급 응용은 레퍼런스 문서를 참고하기 바란다. 문서의 각 타입별로 작성 방법을 알아볼 것이다.

article

논문같이 10장 이내로 이루어지는 단순한 형태의 문서로 다음과 같은 구조를 가진다.
<!DOCTYPE article>
<article xmlns="http://docbook.org/ns/docbook" version="5.0" encoding="UTF-8" lang="ko">
<info>
    <title>헤드라인</title>
</info>

<section xml:lang="ko">
<info>
    <title>초고속 인터페이서 '썬더볼트'에 대한 궁금증</title>
    <author>
        <surname>인터넷 한겨례</surname>
    </author>
    <pubdate>2011/2/28</pubdate>
</info>
<para>
며칠 전 애플은 초고속 인터페이스 ‘썬더볼트’를 채택한 새로운 노트북 '맥북 프로' 시리즈를 발표했다. 
PC업계는 썬더볼드의 기술과 배경에 많은 관심을 나타내고 있다. 썬더볼트는 파이어와이어와 USB 3.0을 
대체할 수 있는 고성능 인터페이스 기술이기 때문이다.
</para>
    <section>
    <info>
        <title>썬더볼트의 구매시기</title>
    </info>
    <para>
        그렇다면 선더볼트의 구매시기는 언제 쯤으로 하는게 ..
    </para>
    </section>
</section>
</article>
구성 요소를 살펴보자.
  1. 제목과 같은 문서의 메타 정보. <info>
  2. 문서의 구조를 만들기 위한 장. <section>
장>절 과 같이 여러 깊이의 문서 구조를 만들 수 있다.
  1. 문단을 위한 <para>
간단하다.

<section>을 중첩해서 사용하는 걸로 간단하게 장>절로 이어지는 구조를 만들 수 있지만, <section>을 여러개 중첩해서 사용하면 가독성이 떨어질 수 있다. 이럴 때는 <sect1> <sect2> 등을 사용하는게 낫다.
<sect1>
<sect2>
<sect/2>
</sect1>

book

여러 개의 chapter로 구성된 많은 분량의 문서에 적합한 형식이다. 일반적인 형식은 다음과 같다.
<book version="5.0" encoding="UTF-8" xml:lang="ko">
<title>큰 곰 가죽구두 요정의 모험</title>
<titleabbrev>못난이 요정의 모험</titleabbrev>
<bookinfo>
  <legalnotice><para>기억에서 잊혀진 모든 요정에게 바침</para></legalnotice>
  <author><firstname>윤</firstname><surname>상배</surname></author>
</bookinfo>
<dedication>
<para>
연습용 책입니다.
</para>
</dedication>
<preface><title>서론</title>
<para>
한때 요정과 사람이 같이 살던 때가 있었습니다. 지금은 기억에서 잊혀진..
</para>
</preface>
<chapter><title>모험의 준비</title>
<para>
아주 오랜 옛날, 사람들이 요정을 기억하고 있을 적의 일입니다. 
지금은 우리의 기억에서 잊혀진 큰 바다에 둘러싸인 어느 마을에 가죽구두요정이 살고 있었습니다. 
이 가죽구두요정의 이름은 큰곰가죽구두요정 입니다. 하지만 "큰곰가죽구두요정아 구두만드는데 
너의 날개 가루가 필요해"."큰곰가죽구두요정아 이틀동안 집을 비울거다. 
이름없는 고양이 좀 보살펴달라". 큰곰가죽구두요정아... ... 이렇게 이름을 매번 부르는 것은 번거로운 
일이였기 때문에 그냥 줄여서 "큰곰요정"이라고 부르곤 했습니다.
</para>
<sect1><title>무료한 999번의 생일</title>
<para>
가죽구두요정은 인간보다 훨씬 오래 삽니다. 확실히 999년은 살거라고 알려져 있습니다. 
하지만 누구도 이 요정이 몇살까지 사는지는 알지 못했습니다. 왜냐하면 어떤 이유로 
999번째의 생일을 맞이하면 모험을 떠나고, 그 후로는 영영 집으로 돌아오질 않았기 때문입니다...
</para>
</sect1>
</chapter>
<appendix><title>부록</title>
<para>
소설에서 하지 못한 짤막한 이야기를 담았습니다.
</para>
</appendix>
</book>
책이기 때문에 이런 저런 구성요소가 꽤 많음을 알 수 있다. 여기에서는 책 제목과 서론, 저자 정도만 기록하고 있는데, 번역자, 출판일, 문서 버전등 다양한 요소를 첨가할 수 있다. 그리고 책 마지막에는 부록과 (기술문서일 경우)용어 해석을 위한 glossary 참고문헌을 위한 epigraph, 부록문서등을 포함할 수 있다.

<chapter>를 둬서 문서를 한 단계 더 구조화 한다는 것을 제외하고는 article와 동일함을 알 수 있다.

문서 분할 관리

프로그래밍 언어들이 소스코드를 관리하기 위해서 파일을 분할하는 것처럼 Docbook 문서도 분할해서 관리할 수 있다. book 처럼 여러개 챕터로 이루어지는 문서의 경우 챕터별로 파일로 나누어서 관리하면, 문서 작성이 훨씬 수월해 진다.

다음은 챕터별로 문서를 관리하는 예제 문서다.
<?xml version="1.0"?>
<!DOCTYPE book [
<!ENTITY introduction SYSTEM "chap1.xml">
<!ENTITY background SYSTEM "chap2.xml">
<!ENTITY features SYSTEM "chap3.xml">
<!ENTITY input SYSTEM "chap4.xml">
<!ENTITY buffer-overflow SYSTEM "chap5.xml">
<!ENTITY internals SYSTEM "chap6.xml">
<!ENTITY call-out SYSTEM "chap7.xml">
<!ENTITY output SYSTEM "chap8.xml">
<!ENTITY language-specific SYSTEM "chap9.xml">
<!ENTITY special SYSTEM "chap10.xml">
<!ENTITY conclusion SYSTEM "chap11.xml">
<!ENTITY bibliography SYSTEM "chap12.xml">
]>

<!-- 문서의 메타 정보들 -->
<book version="5.0" encoding="UTF-8" xml:lang="ko">
<bookinfo xml:lang="ko">
<title>Secure Programming for Linux and Unix HOWTO</title>
<author>
<firstname>David</firstname>
<othername role="mi">A.</othername>
<surname>Wheeler</surname>
</author>
<affiliation><address><email>dwheeler@dwheeler.com</email></address></affiliation>
<pubdate>v2.92, 8 January 2002</pubdate>
<edition>v2.92</edition>
<!-- FYI: The LDP claims they don't use the "edition" tag.  -->
<copyright>
 <year>1999</year>
 <year>2000</year>
 <year>2001</year>
 <year>2002</year>
 <holder>David A. Wheeler</holder>
</copyright>

</bookinfo>
&introduction;
&background;
&features;
&input;
&buffer-overflow;
&internals;
&call-out;
&output;
&special;
&conclusion;
&bibliography;
</book>
이제 나머지 장별 문서 (chap1.xml chap2.xml)를 작성하면 된다. 다음은 chap1.xml의 내용
<chapter xml:id="introduction" xml:lang="ko"> <!-- xml:id가 키다
<title>소개</title>
<epigraph>
<attribution>Proverbs 21:22 (NIV)</attribution>
<para>
A wise man attacks the city of the mighty and pulls down the stronghold in which they trust.
</para>
</epigraph>

<para>
이 책은 리눅스와 유닉스 시스템에서 보안적인 프로그램을 작성하기 위한 일련의 설계 및 구현 지침들을 기술한다. 
이 책의 목적을 위해 보안적인 (secure) 프로그램을 보안 경계에 존재하여 프로그램과 동일한 권한을 갖지 않는 
출처로부터 입력을 받아들이는 프로
그램으로 정의할 수 있는데 이들로는 원격 뷰어로 사용되는 애플리케이션 프로그램, CGI 스크립트를 포함한 웹 애플리케이션, 
네트>워크 서버와 setuid/setgid 프로그램들이 있다. 이 책에서 논의되는 원리들중 다수가 
적용됨에도 불구하고 운영 체제의 커널 자체를 수정하는 것을 다루지는 않는다. 
이 지침들은 저자가 추가한 의견과 함께 보안적인 프로그램들을 만드는 방법에 대한 다양한 출처들로부터 배운 교훈들을 
조사함으로써 개발되었으며 일련의 더욱 커다란 원리들로 재구성되었다. 이 책은 C, C++, 자바, 펄, PHP, 
파이썬, TCL 과 Ada95 를 포함한 많은 언어들에 대한 구체적인 안내를 포함한다.
</para>
파일 이름과 xml:id만 잘 맞춰주면 된다.

기타 문서 요소

문서는 text뿐만 아니라 표, 그림, 각주등 다양한 요소를 가질 수 있다. 이들 요소를 적절히 사용하면 문서의 내용을 더 풍부하게 할 수 있다.

그림

<mediaobject>
    <imageobject role="html">
        <imagedata fileref="imgs/AbstractViewofaProgram.png" format="PNG" scale="90"/>
    </imageobject>
    <caption>
abstract view of a program
    </caption>
</mediaobject>

<para>
그 뒤 1년이 흐른 지금, 우리는 얼마나 자성하고 분발했는지 따져봐야 한다. 
소프트파워 중심으로 재편되는 모바일 시장은 아직 초>창기다. 그만큼 기회도 많다. 
이젠 모바일 HW 강국에서 모바일 SW 강국으로 대변신을 모색할 때가 됐다.
<table>
    <title>세계 IT 시장 현황 (단위 : 달러)</title>
    <tgroup cols='2'>
    <tbody>
        <row>
            <entry>정보 통신 서비스</entry>
            <entry>1조 5700억</entry>
        </row>
        <row>
            <entry>소프트웨어</entry>
            <entry>1조 300억</entry>
        </row>
        <row>
            <entry>하드웨어</entry>
            <entry>7700억</entry>
        </row>
    </tbody>
    </tgroup>
</table>

<table>
    <title>모바일 앱 다운로드 건수(단위:백만건) /자료 퓨처소스 컨설팅</title>
    <tgroup cols='3'>
    <tbody>
        <row>
            <entry>2008</entry>
            <entry>530</entry>
        </row>
        <row>
            <entry>2009</entry>
            <entry>3059</entry>
        </row>
        <row>
            <entry>2010</entry>
            <entry>6610</entry>
        </row>
        <row>
            <entry>2011</entry>
            <entry>9880</entry>
        </row>
        <row>
            <entry>2012</entry>
            <entry>13250</entry>
        </row>
        <row>
            <entry>2013</entry>
            <entry>16210</entry>
        </row>
    </tbody>
    </tgroup>
</table>
</para>

링크

외부 URL 링크
NSA 의 <ulink url="http://www.radium.ncsc.mil/tpep/library/fers/index.html">Final
Evaluation Reports (FERs)</ulink> 에서 얻을 수 있다.

문서 내에서 다른 문서를 참고
더욱 자세한 정보는 <xref linkend="avoid-vfork" />을 참조해라.
이렇게 하면 id가 avoid-vfork인 문서영역으로 내부링크가 걸린다.
<sect1 id="avoid-vfork">
<title>vfork(2) 사용을 피해라 </title>

<para>
유닉스 계열 시스템에서 새로운 프로세스를 생성하는 이식성 있는 방법은
fork(2) 호출을 사용하는 것이다. BSD 는 최적화 기법으로 vfork(2) 라는
...
</para>

리스트

<itemizedlist>
<listitem>
<para>
서로 다른 표기법으로 작성된 구성요소들은 필연적으로 결합도(coupling)가 낮아진다. (깔끔한 인터페이스는 없겠지만)
</para>
</listitem>
<listitem>
<para>
각 요소들을 개별적으로 재작성함으로써 새로운 언어/플랫폼으로 발전시키기 쉽다.
</para>
</listitem>
<listitem>
<para>
실제로는 어떤 모듈들이 최신의 것으로 갱신되었기 때문일 수도 있다.
</para>
</listitem>
</itemizedlist>

문서변환

xsltproc라는 툴을 이요하면 docbook문서를 다양한 형식의 문서로 변환할 수 있다.

Docbook에서 HTML로 변환

# xsltproc /usr/share/xml/docbook/stylesheet/docbook-xsl/html/docbook.xsl article.xml > article.html

Docbook에서 epub로 변환

xsltproc로도 변환할 수 있지만 그 보다는 dbtoepub를 사용하는 걸 권장한다. epub(:12)는 전자책을 위한 표준 포맷이다.
# dbtoepub mybook.xml
성공적으로 실행되면, 확장자가 .epub인 파일이 만들어진다.

독북 활용

객체지향 프로그래밍 언어를 사용하면, 자연 스럽게 객체지향적 사고 방식을 가지게 된다고 했다. 독북을 이용해서 문서를 작성하다보면 자연 스럽게 구조적인 문서를 쓸 수 있다. 글쓰기 연습이 된다고나 할까 ?

역시 문제는 웹과 함께 사용하기에는 그닥 좋은 시스템이 아니라는 점이다. (Docbook으로 변환해주는 wiki가 있긴 하지만) 그리고 프리젠테이션용 문서 시스템도 아니다. 메뉴얼과 레퍼런스 문서의 작성에 특화됐다. 하긴 docbook사이트도 docbook이 기술문서 개발을 위한 언어라고 소개하고 있으니...

공개 소프트웨어 진영의 경우 오래전부터 많은 문서가 docbook 으로 저작되는데, Linux Document Project의 문서들이 대표적이다. 이런 영향 때문인지, 심심 찮게 docbook로 작성되고 변환된 문서들을 볼 수 있다.

문서 예제