| PostgreSQL 9.6.2 문서 | |||
|---|---|---|---|
| 이전 | 위로 | 부록 J. 문서 작업 | 다음 |
아래 도구들은 문서 작업에 필요하다. 몇몇은 선택적으로 필요하기도 하다.
DocBook 문서 형식 정의 파일이다. PostgreSQL 문서는 4.2 버전을 사용하다. 다른 버전을 사용할 수 없다. 그외, DocBook DTD를 사용하기 위해서, 기타 여러 SGML DTD가 필요하다. 또한 맨 페이지를 만들위 해서는 같은 버전의 XML DTD도 필요하다.
DocBook에서 사용되지만, ISO에서 관리하기 때문에, 이 파일들은 분리되어 있다.
DocBook 소스를 HTML과 같은 다른 문서 형태로 변환 할 때 필요하다.
맨 페이지를 만들거나, HTMLHelp 파일을 만들 때 이것을 이용한다. 이 스타일로 HTML이나, PDF 문서를 만들 수 있지만, 현재, 공식 PostgreSQL 문서는 DSSSL 스타일시트를 사용하고 있다.
현재 최소 1.74.0 이상 버전이 필요하다.
SGML 파일을 처리하는 기본 패키지다. 이 패키지에는 SGML 파서와 DSSSL 처리기(SGML 파일과, DSSSL 스타일시트 파일을 가지고, 다른 문서 형태로 만드는 도구)가 포함 되어 있다. 또한 기타 여러 관련 도구들이 포함되어 있다. Jade 패키지는 더이상 James Clark에 의해 관리되지 않고, OpenJade 그룹에서 관리되고 있다.
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.
XSLT 스타일시트를 이용한 처리 도구다. (DSSSL 스타일시트 파일을 이용하기 위한 jade와 같다.)
TeX 형태로 파일을 만드려면, JadeTeX 패키지를 이용할 수 있다. JadeTeX 패키지는 PostScript 또는 PDF (책갈피를 포함한) 파일을 만드는데 사용될 수 있다.
하지만, JadeTeX 결과물은 RTF 형태로 만든 것 보다 품질이 떨어진다. 표 모양과 문서 상하좌우 여백 처리에 문제가 좀 있다. 또한 그 결과물을 다시 편집할 수도 없다.
아래 내용은 문서 작업을 하면서 겪은 여러 경험들을 소개한 것이다. 여기에는 여러 패키지들을 설치할 때의 문제와 사용할 때의 문제를 설명하고 있다. 이곳에 없는 여러 문제점들이 발견되면, 문서 메일링 리스트를 통해 알려주면, 이 문서에 계속 추가할 것이다.
관련 패키지를 설치하기 위해서는 다음 명령을 실행한다:
yum install docbook-dtds docbook-style-dsssl docbook-style-xsl libxslt openjade
참고: 설치할 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/openjade
A number of things from /usr/ports/print (tex, jadetex) might also be of interest.
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-dsssl docbook-xsl libxml2-utils openjade1.3 opensp xsltproc
MacPort를 사용한다면, 다음 명령을 실행한다:
sudo port install docbook-dsssl docbook-sgml-4.2 docbook-xml-4.2 docbook-xsl libxslt openjade 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 OpenJade offers a GNU-style ./configure; make; make install build process. Details can be found in the OpenJade source distribution. In a nutshell:
./configure --enable-default-catalog=/usr/local/share/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 jade later on. (This method is also an option if OpenJade is already installed and you want to install the rest of the toolchain locally.)
참고: Some users have reported encountering a segmentation fault using OpenJade 1.4devel to build the PDFs, with a message like:
openjade:./stylesheet.dsl:664:2:E: flow object not accepted by port; only display flow objects accepted make: *** [postgres-A4.tex-pdf] Segmentation faultDowngrading to OpenJade 1.3 should get rid of this error.
Additionally, you should install the files dsssl.dtd, fot.dtd, style-sheet.dtd, and catalog from the dsssl directory somewhere, perhaps into /usr/local/share/sgml/dsssl. It's probably easiest to copy the entire directory:
cp -R dsssl /usr/local/share/sgml
Finally, create the file /usr/local/share/sgml/catalog and add this line to it:
CATALOG "dsssl/catalog"
(This is a relative path reference to the file installed in 단계 2. Be sure to adjust it if you chose your installation layout differently.)
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.)
To install the style sheets, unzip and untar the distribution and move it to a suitable place, for example /usr/local/share/sgml. (The archive will automatically create a subdirectory.)
$ gunzip docbook-dsssl-1.xx.tar.gz $ tar -C /usr/local/share/sgml -xf docbook-dsssl-1.xx.tar
The usual catalog entry in /usr/local/share/sgml/catalog can also be made:
CATALOG "docbook-dsssl-1.xx/catalog"
Because stylesheets change rather often, and it's sometimes beneficial to try out alternative versions, PostgreSQL doesn't use this catalog entry. See J.2.6절 for information about how to select the stylesheets instead.
To install and use JadeTeX, you will need a working installation of TeX and LaTeX2e, including the supported tools and graphics packages, Babel, AMS fonts and AMS-LaTeX, the PSNFSS extension and companion kit of "the 35 fonts", the dvips program for generating PostScript, the macro packages fancyhdr, hyperref, minitoc, url and ot2enc. All of these can be found on your friendly neighborhood CTAN site. The installation of the TeX base system is far beyond the scope of this introduction. Binary packages should be available for any system that can run TeX.
Before you can use JadeTeX with the PostgreSQL documentation sources, you will need to increase the size of TeX's internal data structures. Details on this can be found in the JadeTeX installation instructions.
Once that is finished you can install JadeTeX:
$ gunzip jadetex-xxx.tar.gz $ tar xf jadetex-xxx.tar $ cd jadetex $ make install $ mktexlsr
The last two need to be done as root.
문서 파일을 만들기 전에 필요한 패키지들이 모두 있는지 확인 하는 방법은 PostgreSQL 소스 디렉토리에서 configure 명령을 실행해 보면 된다. 이 명령을 실행하면, 다음과 비슷한 내용이 출력된다. 이를 확인 해 보고, 적당한 작업( 해당 프로그램이 없다고 나온다면, 그 프로그램이 있는 경로를 지정한다든가, 적당한 패키지를 설치한다든가)을 한다:
checking for onsgmls... onsgmls checking for openjade... openjade checking for DocBook V4.2... yes checking for DocBook stylesheets... /usr/share/sgml/docbook/stylesheet/dsssl/modular checking for collateindex.pl... /usr/bin/collateindex.pl checking for xsltproc... xsltproc checking for osx... osx
onsgmls 이나 nsgmls 프로그램 모두 찾지 못했다면, 나머지 문서 작업 관련 모든 검사는 생략된다. nsgmls 프로그램은 Jade 패키지 안에 있다. 자동으로 이것을 못 찾는다면, JADE와 NSGMLS 쉘 환경 변수를 지정해서 사용할 수도 있다. 또한 "DocBook V4.2" 관련 파일을 못 찾는다면, 그것을 설치하지 않았거나, catalog 파일 설정을 하지 않는 경우이다. 이 때는 이 문서 앞 부분을 다시 차근히 읽어 보길 바란다. DocBook stylesheet 관련 파일을 못찾는다면, DOCBOOKSTYLE 환경 변수를 지정해서 찾는 디렉토리의 위치를 알려 줄 수도 있다. 이렇게 필요한 패키지를 설치하거나 환경 설정을 다시 했다면, 다시 configure 명령을 실행해서 문서 작업 관련 설정을 다시 확인해 본다.