아래 도구들은 문서 작업에 필요하다. 몇몇은 선택적으로 필요하기도 하다.
DocBook 문서 형식 정의 파일이다. PostgreSQL 문서는 4.2 버전을 사용하다. 다른 버전을 사용할 수 없다. 그외, DocBook DTD를 사용하기 위해서, 기타 여러 SGML DTD와 XML DTD가 필요하다. 이들은 대부분 배포판에서 분리되어 배포하고 있다.
DocBook SGML에서 사용되지만, ISO에서 관리하기 때문에, 이 파일들은 분리되어 있다.
DocBook 소스를 HTML과 같은 다른 문서 형태로 변환 할 때 필요하다.
1.77.0 버전 이상을 필요로 하나, 보다 나은 환경은 사용 가능한 최신 버전을 사용한다.
이것은 SGML 처리에 가장 좋은 도구다. 여기서는 더이상 OpenJade를 사용하지 않고, DSSSL을 이용해 SGML 문서를 XML 문서로 변화는 작업만 사용한다.
xmllint This library and the xmllint tool it contains are
used for processing XML. Many developers will already
have Libxml2 installed, because it is also
used when building the PostgreSQL code. Note, however,
that xmllint might need to be installed from a
separate subpackage.
xsltproc 사용하기 위한 LibxsltXSLT 스타일시트를 이용한 처리 도구다. 이 프로그램은 XSLT 스타일시트를 이용해 XML 문서를 여러 다른 양식으로 변환하는데 사용한다.
XML 문서를 PDF 문서로 변환하는데 사용한다.
아래 내용은 문서 작업을 하면서 겪은 여러 경험들을 소개한 것이다. 여기에는 여러 패키지들을 설치할 때의 문제와 사용할 때의 문제를 설명하고 있다. 이곳에 없는 여러 문제점들이 발견되면, 문서 메일링 리스트를 통해 알려주면, 이 문서에 계속 추가할 것이다.
DocBook XML, DocBook XSLT 스타일시트를 굳이 설치할 필요는 없다. 이들은
작업 중에 온라인으로 다운로드 받고, 캐시로 보관해서 사용하기 때문이다. 이
방법은 사용 환경이 옛 버전만 이용할 수 있는 환경에서 좋은 해결책이다. 이와
달리 배포판에서 제공하는 패키지를 이용하고자 한다면,
xmllint, xsltproc 명령의
--nonet 옵션에 대해서 살펴보면 된다.
관련 패키지를 설치하기 위해서는 다음 명령을 실행한다:
yum install docbook-dtds docbook-style-xsl fop libxslt opensp
설치할 RPM 패키지 이름은 각 리눅스 배포판 마다 약간씩 차이가 있다. 참고로, RedHat 계열(Enterprise Linux, CentOS)은 openjade, opensp, docbook-dtds, docbook-utils, docbook-style-dsssl, sgml-common 패키지들이 필요하다.
The FreeBSD Documentation Project is itself a heavy user of DocBook, so it comes as no surprise that there is a full set of “ports” of the documentation tools available on FreeBSD. The following ports need to be installed to build the documentation on FreeBSD.
textproc/docbook-sgml
textproc/openjade-xml
textproc/docbook-xsl
textproc/dsssl-docbook-modular
textproc/libxslt
textproc/fop
textproc/opensp
To install the required packages with pkg, use:
pkg install docbook-sgml docbook-xml docbook-xsl fop libxslt opensp
When building the documentation from the doc
directory you'll need to use gmake, because the
makefile provided is not suitable for FreeBSD's make.
More information about the FreeBSD documentation tools can be found in the FreeBSD Documentation Project's instructions.
Debian GNU/Linux에서는 다음 패키지들을 설치하면 된다. 간단하게:
apt-get install docbook docbook-xml docbook-xsl fop libxml2-utils opensp xsltproc
MacPort를 사용한다면, 다음 명령을 실행한다:
sudo port install docbook-sgml-4.2 docbook-xml-4.2 docbook-xsl fop libxslt opensp
The manual installation process of the DocBook tools is somewhat complex, so if you have pre-built packages available, use them. We describe here only a standard setup, with reasonably standard installation paths, and no “fancy” features. For details, you should study the documentation of the respective package, and read SGML introductory material.
The installation of OpenSP offers a GNU-style
./configure; make; make install build process.
Details can be found in the OpenSP source distribution. In a nutshell:
./configure --enable-default-catalog=/usr/local/etc/sgml/catalog make make install
Be sure to remember where you put the “default catalog”; you
will need it below. You can also leave it off, but then you will have to
set the environment variable SGML_CATALOG_FILES to point
to the file whenever you use any programs from OpenSP later on. (This
method is also an option if OpenSP is already installed and you want to
install the rest of the toolchain locally.)
Obtain the DocBook V4.2 distribution.
Create the directory
/usr/local/share/sgml/docbook-4.2 and change
to it. (The exact location is irrelevant, but this one is
reasonable within the layout we are following here.)
$mkdir /usr/local/share/sgml/docbook-4.2$cd /usr/local/share/sgml/docbook-4.2
Unpack the archive:
$unzip -a ...../docbook-4.2.zip
(The archive will unpack its files into the current directory.)
Edit the file
/usr/local/share/sgml/catalog (or whatever
you told jade during installation) and put a line like this
into it:
CATALOG "docbook-4.2/docbook.cat"
Download the ISO 8879 character entities archive, unpack it, and put the files in the same directory you put the DocBook files in:
$cd /usr/local/share/sgml/docbook-4.2$unzip ...../ISOEnts.zip
Run the following command in the directory with the DocBook and ISO files:
perl -pi -e 's/iso-(.*).gml/ISO\1/g' docbook.cat
(This fixes a mixup between the names used in the DocBook catalog file and the actual names of the ISO character entity files.)
configure 명령으로 확인 문서 파일을 만들기 전에 필요한 패키지들이 모두 있는지
확인 하는 방법은 PostgreSQL
소스 디렉터리에서 configure 명령을
실행해 보면 된다. 이 명령을 실행하면, 다음과
비슷한 내용이 출력된다. 이를 확인 해 보고, 적당한 작업(
해당 프로그램이 없다고 나온다면, 그 프로그램이 있는
경로를 지정한다든가, 적당한 패키지를 설치한다든가)을
한다:
checking for onsgmls... onsgmls
checking for DocBook V4.2... yes
checking for dbtoepub... dbtoepub
checking for xmllint... xmllint
checking for xsltproc... xsltproc
checking for osx... osx
checking for fop... fop
onsgmls 이나 nsgmls
프로그램 모두 찾지 못했다면, 나머지 문서 작업 관련 모든 검사는
생략된다. nsgmls 프로그램은 OpenSP 패키지
안에 있다. 자동으로 이것을 못 찾는다면,
NSGMLS 쉘 환경 변수를 지정해서 사용할 수도 있다. 또한
“DocBook V4.2” 관련 파일을 못 찾는다면,
OpenSP 안에 있는 DocBook DTD 키트를 설치하지 않았거나,
catalog 파일 설정을 하지 않는 경우이다. 이 때는
이 문서 앞 부분을 다시 차근히 읽어 보길 바란다.