PostgreSQL 9.3.5 문서
이전위로부록 J. 문서 작업다음

J.3. 문서 만들기

모든 사전 작업이 끝났다면, doc/src/sgml 디렉토리로 이동해서, 아래에서 설명하고 있는 명령 가운데 원하는 작업을 할 명령을 실행한다. (make는 GNU make를 사용해야한다.)

참고: 이 한국어 문서가 utf-8 인코딩으로 되어 있어 다음과 같은 오류가 발생할 것이다. 

openjade:postgres.sgml:15:33:E: non SGML character number 132
openjade:postgres.sgml:15:34:E: non SGML character number 156

이 문제를 해결하려면, SP_ENCODING 쉘 환경 변수값으로 "UTF-8" 로 지정해야한다. 

$ export SP_ENCODING=UTF-8

몇 리눅스 배포판에서는 dockbook dtd가 4.2버전 외의 여러 버전이 함께 설치되어 openjade 명령이 정상적으로 실행되지 않는다. CentOS 경우라면, openjade 명령은 /etc/sgml/catalog 파일을 카탈로그 파일로 사용해야하며, 그 파일에는 다음과 같이 4.2 버전의 dtd 내용만 있어야 정상적으로 html 문서를 만들 수 있다. 

$ cat /etc/sgml/catalog
CATALOG "/etc/sgml/sgml-docbook-4.2-1.0-30.1.cat"
CATALOG "/etc/sgml/xml-docbook-4.2-1.0-30.1.cat"
CATALOG "/etc/sgml/openjade-1.3.2-27.soc"

J.3.1. HTML

HTML 양식의 문서를 만드려면 다음과 같이 한다: 

doc/src/sgml$ gmake html

이것이 make 작업의 기본이다. 최종 결과물은 html 하위 디렉토리안에 만들어진다.

이 기본 작업에는 문서 색인을 처리하기 위해, 여러 작업을 거친다. 이 색인 작업을 무시하려면, draft 옵션을 사용한다: 

doc/src/sgml$ gmake draft

하나의 HTML 페이지를 만드려면: 

doc/src/sgml$ gmake postgres.html

J.3.2. 맨페이지

맨페이지는 DocBook XSL 스타일시트를 이용해서, DocBook refentry 페이지로 변환해서 만든다. 이 페이지는 맨페이지와 호환 된다. 맨페이지도 HTML 버전과 비슷하게, tar 묶음 파일로 배포된다. 직접 맨페이지를 만드려면 다음 명령을 실행한다: 

cd doc/src/sgml
gmake man

J.3.3. JadeTeX 패키지를 이용한 출판물 만들기

참고: 이 UTF-8 인코딩 한국어 문서 소스를 가지고 JadeTeX 패키지를 이용해서 .ps 파일이나, .pdf 파일을 만들 수 없었다. 현재까지는 인쇄용 출력물을 만드는 방법으로는 먼저 .rtf 파일로 만들고, 그것을 이용해서, .pdf 파일을 만들어보았다.

JadeTex 패키지를 이용하면, 문서 소스로부터 인쇄가 가능한 출판물을 만들 수 있다. 작업 방식은 다음과 같다:

JadeTeX 패키지를 이용할 때, 다음과 같이 TeX 내부 환경 설정값들의 조정이 필요할 수도 있다. 이 설정은 texmf.cnf 파일에서 지정한다. 

hash_extra.jadetex  = 200000
hash_extra.pdfjadetex  = 200000
pool_size.jadetex = 2000000
pool_size.pdfjadetex = 2000000
string_vacancies.jadetex = 150000
string_vacancies.pdfjadetex = 150000
max_strings.jadetex = 300000
max_strings.pdfjadetex = 300000
save_size.jadetex = 15000
save_size.pdfjadetex = 15000

J.3.4. 페이지 넘침 현상

가끔 문서가 자동 줄바꿈 기능이 없는 내용이거나, 출력용 크기보다 큰 도표를 사용한 경우에 여백이 없어 출력될 수 없는 경우가 생긴다. 이때는 TeX 로그 출력 파일(postgres-US.log 또는 postgres-A4.log)에 "Overfull hbox" 메시지가 기록되는데, 이것을 보고 적당한 조정이 필요하다. (다음 영문 문서의 내용을 그대로 둔다.)

There are 72 points in an inch so anything reported as over 72 points too wide will probably not fit on the printed page (assuming one inch margins). To find the SGML text causing the overflow, find the first page number mentioned above the overflow message, e.g. [50 ###] (page 50), and look at the page after that (e.g. page 51) in the PDF file to see the overflow text and adjust the SGML accordingly.

J.3.5. RTF 출력물 만들기

참고: 이 부분의 내용도 국내에서는 잘 쓰지 않는 Applixware 소프트웨어를 이용한 것에 대한 장황한 설명인데, 변역하지 않았다. 차라리, postgres.rtf 파일을 만들고, OpenOffice 소프트웨어를 이용한 목차 만들기, 페이지 정리, 최종 출력물 만들기 문서가 필요할 듯하다.

You can also create a printable version of the PostgreSQL documentation by converting it to RTF and applying minor formatting corrections using an office suite. Depending on the capabilities of the particular office suite, you can then convert the documentation to PostScript of PDF. The procedure below illustrates this process using Applixware.

참고: It appears that current versions of the PostgreSQL documentation trigger some bug in or exceed the size limit of OpenJade. If the build process of the RTF version hangs for a long time and the output file still has size 0, then you might have hit that problem. (But keep in mind that a normal build takes 5 to 10 minutes, so don't abort too soon.)

Applixware RTF Cleanup

OpenJade omits specifying a default style for body text. In the past, this undiagnosed problem led to a long process of table of contents generation. However, with great help from the Applixware folks the symptom was diagnosed and a workaround is available.

  1. Generate the RTF version by typing: 

    doc/src/sgml$ gmake postgres.rtf

  2. Repair the RTF file to correctly specify all styles, in particular the default style. If the document contains refentry sections, one must also replace formatting hints which tie a preceding paragraph to the current paragraph, and instead tie the current paragraph to the following one. A utility, fixrtf, is available in doc/src/sgml to accomplish these repairs: 

    doc/src/sgml$ ./fixrtf --refentry postgres.rtf

    The script adds {\s0 Normal;} as the zeroth style in the document. According to Applixware, the RTF standard would prohibit adding an implicit zeroth style, though Microsoft Word happens to handle this case. For repairing refentry sections, the script replaces \keepn tags with \keep.

  3. Open a new document in Applixware Words and then import the RTF file.

  4. Generate a new table of contents (ToC) using Applixware.

    1. Select the existing ToC lines, from the beginning of the first character on the first line to the last character of the last line.

    2. Build a new ToC using Tools->Book Building->Create Table of Contents. Select the first three levels of headers for inclusion in the ToC. This will replace the existing lines imported in the RTF with a native Applixware ToC.

    3. Adjust the ToC formatting by using Format->Style, selecting each of the three ToC styles, and adjusting the indents for First and Left. Use the following values:

      StyleFirst Indent (inches)Left Indent (inches)
      TOC-Heading 10.40.4
      TOC-Heading 20.80.8
      TOC-Heading 31.21.2

  5. Work through the document to:

    • Adjust page breaks.

    • Adjust table column widths.

  6. Replace the right-justified page numbers in the Examples and Figures portions of the ToC with correct values. This only takes a few minutes.

  7. Delete the index section from the document if it is empty.

  8. Regenerate and adjust the table of contents.

    1. Select the ToC field.

    2. Select Tools->Book Building->Create Table of Contents.

    3. Unbind the ToC by selecting Tools->Field Editing->Unprotect.

    4. Delete the first line in the ToC, which is an entry for the ToC itself.

  9. Save the document as native Applixware Words format to allow easier last minute editing later.

  10. "Print" the document to a file in PostScript format.

J.3.6. 일반 텍스트 파일 만들기

The installation instructions are also distributed as plain text, in case they are needed in a situation where better reading tools are not available. The INSTALL file corresponds to 15장, with some minor changes to account for the different context. To recreate the file, change to the directory doc/src/sgml and enter gmake INSTALL.

예전에는 릴리즈 노트와 단위 테스트 방법에 대한 문서들도 일반 텍스트 파일로 제공했으나, 이제부터는 더 이상 이들 문서들에 대해서는 일반 텍스트 파일로 제공하지 않는다.

J.3.7. 문법 검사

원하는 최종 결과물을 만드는데, 꽤 긴 시간이 걸린다. 작업한 파일의 문법이 틀려서 작업 도중 오류를 내면 다시 작업해야하기에 문서 생성 전에 먼저 작업한 파일의 문법이 맞는지 검사를 해 보는 것이 작업 시간을 최소화 할 수 있다. 문법 검사 방법은 다음과 같다: 

doc/src/sgml$ gmake check

이전처음으로다음
작업 도구들위로문서 작성 방법