June 6, 2001
이 글은 스크롤키퍼의 기능적인 면과 이를 명령행에서 직접 사용하는 방법에 대해 기본적 내용을 다룹니다. 실제 구현에 대한 더 자세한 내용은 소스를 읽어보거나 메일링리스트에 질문하세요. 스크롤키퍼를 어떻게 사용하는가에 대한 더 자세한 정보는 scrollkeeper-exampe1란 이름의 예제와 함께 포함된 문서를 보세요.
[참고]스크롤키퍼의 몇 부분들은 RPM과 같은 패키징 시스템의 필요에 맞게 디자인되었습니다 이 글에서 RPM은 패키징 시스템의 한 예로서 다루어집니다. 스크롤키퍼는 Unix-like한 다양한 운영체제들의 패키징 시스템과 잘 맞도록 되어 있습니다.
Contents List - 이것은 시스템에 있는 문서들의 리스트로서(일반적으로는 로컬 머신에 깔려있지 않은 문서들까지 포함합니다) 트리 구조로 정렬되어 있습니다. 이 트리 구조는 흔히 제목에 따라 정렬되는데 이것은 제목의 controlled list를 사용해 이루어집니다.
TOC (Table of Contents) - 이것은 문서의 섹션과 서브섹션을 보여주는 트리구조입니다. TOC는 SGML/XML 문서로부터 추출할 수 있습니다.
확장된(Extended) Contents List - 이것은 각 문서들의 TOC까지 보여주는 리스트입니다. 이렇게 하면 단지 시스템에 있는 문서 제목 뿐 아니라 그 안의 섹션들까지 모두 트리구조로 볼 수 있습니다.
보통, help browser는 위에 나열된 모든 정보를 보여주려고 합니다. Contents List는 OMF 메타데이터로부터 결정되는데, 이것은 OMF 파일로부터 직접 얻을 수도 있고 (미래에는) 메타데이터 정보를 지닌 DocBook 문서로부터 자동으로 얻을 수도 있습니다. TOC는 DocBook 문서로부터 자동적으로 생성됩니다. 이 모든 메타데이터들은 자주 억세스되어야 하기 때문에, 퍼포먼스 문제를 피하기 위해 메타데이터는 인스톨될 때와 언인스톨될 때만 처리하게 되어 있습니다. 쉬운 억세스를 위해, XML 파일에 저장된 데이타는 help browser가 읽게 되지만 필요하다면 스크롤키퍼가 읽을 수도 있습니다.
ScrollKeeper 0.2의 경우OMF 문서는 어플리케이션 빌드 프로세스 과정을 통해 가공됩니다. 이것은 흔히 'make all'의 한부분입니다. 이렇게 하는 목적은 문서에 URL을 지정해 문서가 실제로 어디에 설치되어 있는지 알 수 있게 하기 위해서 입니다. 문서의 설치 위치는 빌드를 거쳐야 비로소 알 수 있는 경우가 많기 때문에 이렇게 합니다.
이 과정은 'scrollkeeper-preinstall' 명령으로 이루어집니다. 이 명령은 세가지 파라미터를 알아내는데, 설치된 문서의 URL, XML 파일 안에 있는 오리지날 OMF 메타데이타, 그리고 생성할 OMF 파일의 이름입니다. 예를 들어 봅시다.
scrollkeeper-preinstall
file:$(docdir)/foo-manual.sgml
foo-manual-fr.omf
$(omf-dir)/foo-manual-fr.omf
[참고] 스크롤키퍼가 패키징하는 사람의 시스템에 설치되어 있어야 합니다.
또한 $(docdir)은 RPM 빌드 과정에서 'make install' 과정 중의 $RPMBUILDROOT에 설정되어 있는 $(prefix) 값을 기반으로 하는 경우가 많습니다. 그래서 'scrollkeeper-preinstall' 과정이 'make install' 단계가 아니라 'make' 단계에서 딱 한번 실행되었다는 사실을 보증하기 위해 꼭 타임스탬프를 사용해야 합니다. 이렇게 하지 않으면 URL은 틀리게 될 것입니다.
OMF 파일에 적힌 경로가 존재하지 않는다면, 생성하게 됩니다. 이 예제에서, OMF 파일 $(omf-dir)/foo-manual-fr.omf 은 OMF 파일 foo-manual-fr.omf을 복사함으로써 생성됩니다. 이에 맞게 $(docdir)/foo-manual.sgml의 IDENTIFIER도 변경됩니다.$(omf-dir)에 해당하는 경로가 없다면, 이것도 새로 만들어집니다.
OMF 파일은 다른 패키지에 속한 파일과 충돌이 나는 것을 막기 위해 <document_title>-<locale>.omf 이런 식으로 이름이 붙여진다는 점을 알아두세요.
설치는 문서와 OMF 파일을 시스템에 복사하고 스크롤키퍼의 데이터베이스를 업데이트하는 과정입니다. 이는 'scrollkeeper-update' 명령으로 이루어집니다.
install:
install foo-manual.sgml $(docdir)
install $(omf-dir)/foo-manual-fr.omf $(pkgomfdir)
-scrollkeeper-update -p $(SCROLLKEEPER_DB_DIR)
SCROLLKEEPER_DB_DIR은 스크롤키퍼 데이타베이스가 사용하는 디렉토리입니다. 이것은 $localstatedir를 기반으로 하며, 인스톨되는 실제 시스템의 데이터베이스를 가리키고, RPM을 빌드할때 RPMBUILDROOT 를 가리킵니다. 예를 들어, 어떤 어플리케이션이 --localstatedir=/var/lib 옵션과 함께 configure 되었다면 SCROLLKEEPER_DB_DIR은 $(localstatedir)/scrollkeeper이 되어야 합니다.
-p 옵션은 빌드나 테스트를 하기 위해 중요하며, 패키징 어플리케이션에서는 언제나 사용되어야 합니다. 예를 들어 RPM를 빌드할 때, 이것은 빌드하는 사람의 컴터 머신에 있는 데이터베이스를 실제로 수정하고 있음을 보증해 주며, RPMBUILDROOT 아래에 새로운 데이터베이스를 생성하고 수정합니다. 이 방식은 테스트 목적으로도 확실히 유용한 점이 있습니다.
scrollkeeper-update는 $(omf-dir)에 있는 OMF 파일들이 새로 생기거나 수정이 되었는지 알아냅니다. 그리고 새로운 메타데이터를 등록합니다.
언인스톨도 'scrollkeeper-update'로 하게 됩니다.
uninstall:
rm $(docdir)/foo-manual.sgml
rm $(pkgomfdir)/foo-manual-fr.omf
scrollkeeper-update -p $(SCROLLKEEPER_DB_DIR)
scrollkeeper-update는 OMFDIR에 있는 OMF 파일이 삭제되었는지 살펴보고 옛 메타데이터를 등록 해제합니다.
scrollkeeper-update는 또한 -v (vorbose) 옵션이 있습니다. 모든 경고와 에러는 기본적으로 로그 파일에 기록되지만(/var/log/scrollkeeper.log) 이 옵션을 주면 표준 출력으로도 보여줍니다.
위에 설명한 명령들(scrollkeeper-preinstall, scrollkeeper-update)에 추가해서 스크롤키퍼는 다음의 추가 유틸리티를 제공합니다.
이것은 스크롤키퍼 데이터베이스를 OMFDIR에 있는 원본 OMF 파일만으로 완전히 새로 만들기 위한 것입니다. -p 옵션을 주면 새로 생성될 데이터베이스가 출력될 디렉토리를 지정할 수 있습니다. -v (verbose) 옵션을 주면 에러가 경고들을 표준출력에서 볼 수 있습니다. 또한 모든 에러와 경고들은 로그 파일로도 저장됩니다(/var/log/scrollkeeper.log)
이것은 스크롤키퍼에게 다양한 설정을 하기 위해 사용됩니다.
--help scrollkeeper-config 사용법을 보여줍니다.
--version Scrollkeeper 버전을 보여줍니다.
--prefix Scrollkeeper configure prefix. (eg. /usr)
--localstatedir Scrollkeeper configure localstatedir. (eg. /var)
--pkglocalstatedir Scrollkeeper data directory.
(eg. /var/lib/scrollkeeper)
--pkgdatadir Scrollkeeper home directory.
(eg. /usr/share/scrollkeeper)
--omfdir ScrollKeeper가 OMF 파일을 찾을 디렉토리
(eg. /usr/share`/omf)
여기서는 스크롤키퍼의 기능에 대해 좀더 자세히 살펴봅니다.
$SCROLLKEEPER_DB_DIR 은 스크롤키퍼가 데이터 파일들을 보관하기 위한 디렉토리입니다(대개 /var/lib/scrollkeeper).
$SCROLLKEEPER_DIR은 스크롤키퍼가 인스톨되고 static data 파일들과 문서들이 저장되는 디렉토리입니다(대개 /usr/share/scrollkeeper). 모든 로케일을 위한 content list template 파일들이 이곳에 저장됩니다.
$SCROLLKEEPER_DOC_DIR은 스크롤키퍼의 개발과 관련된 정보를 담은 파일들이 저장됩니다. README, 라이센스 등이 해당됩니다(대개 /usr/share/doc/scrollkeeper-$version).
$OMFDIR은 각 패키지들이 해당 OMF 파일들을 저장하는 곳입니다. 스크롤키퍼는 이곳에서 OMF 파일들을 찾습니다(대개 /usr/share/omf.)
scrollkeeper-update [-v] [-p <SCROLLKEEPER_DB_DIR>] [-o <OMF_DIR>]
OMF_DIR과 OMF_DIR의 서브디렉토리에서 추가되거나,삭제되거나,업데이트된 파일을 찾습니다. 때에 따라서 필요하면 scrollkeeper-install이나 scrollkeeper-uninstall을 부릅니다.
-v - 많은 수의 flag,메세지가 stderr로 프린트됩니다. /var/log/scrollkeeper.log와는 별개입니다.
-p - Scrollkeeper 데이터베이스 디렉토리를 지정합니다.(scrollkeeper-config --pkglocalstatedir과 같습니다)
-o - OMF디렉토리를 지정합니다(scrollkeeper-config --omfdir과 같습니다)
OMF_DIR환경변수를 세팅하여서 다수의 OMF디렉토리를 지정할수 있습니다.
scrollkeeper-install ?-v ?-p <scrollkeeper_db_dir> <omfname> (만약 -v flag가 쓰이면, 다양한 에러가 다음 과정을 거쳐 STDERR로 보내집니다.)
1) $scrollkeeper_db_dir에 Path를 지정합니다.
만약 -p옵션이나 `scrollkeeper-config --pkglocalstatedir`가 사용되었으면 <scrollkeeper-db_dir>가 됩니다.
2) content list 템플릿 파일이 데이터베이스 디렉토리에 모두 복사되어 있지 못했으면
(처음실행때나)복사를 하고 확장된 content list파일을 만듭니다.(당장은 단순한 content list파일과 같습니다)
3) <omfname>의 각 엔트리는 다음을 따릅니다:
A) 존재하는 OMF 엔트리에서 URL을 확인합니다 (예>it points to on the drive
actually exists.) 만약 이것이 실패하면 이 OMF entry에서의 작업은 종료합니다.
B) $scrollkeeper_db_dir/scrollkeeper-docs에 엔트리를 추가합니다.
(위파일이 존재하지 않으면 새로 생성됩니다)(V. for format을 보십쇼)
C) Contents List업데이트:
a) Contents List에서 각각TITLE,LANGUAGE,SUBJECT.category를 이용하여 제목,언어,위치를 판단합니다.
b) Verify that the SUBJECT.category lies within the controlled list
of categories for the locale specified by LANGUAGE
c) 이 문서를 적절한 언어 디렉토리에 있는 Content List파일에 추가합니다.
$scrollkeeper_db_dir/<LANGUAGE>/scrollkeeper_cl.xml
(V. for format을 보십쇼) (분리시키는데 쓰일 문서의 ID를 기억하십쇼.)
D) (DocBook에서만 쓰임) 문서에서 TOC를 표출하여 파일에 넣습니다:
<scrollkeeper_db_dir>/TOC/<IDNUMBER>
(이 파일이 없다면 새로 생성됩니다. 존재한다면 덮어씁니다.)
E) (SGML,XML문서에서만 쓰임) TOC를 확장된 contents list에 삽입합니다.
확장된 contents list는 각 문서에 sub-tree형태로 된 TOC가 있는 Contents List입니다.
전과 같이, 문서의 ID는 분리시키는데 사용됩니다. 이 파일은 여기에 있습니다:
$scrollkeeper_db_dir/<LANGUAGE>/scrollkeeper_extended_cl.xml
scrollkeeper-uninstall ?-v ?-p <scrollkeeper_db_dir> <omfname>
(Flags는 scrollkeeper-install의 그것과 같습니다)
1) $scrollkeeper_db_dir에 Path를 지정합니다.
만약 -p옵션이나 `scrollkeeper-config --pkglocalstatedir`가 사용되었으면 <scrollkeeper-db_dir>가 됩니다.
2) $scrollkeeper-db-dir/scrollkeeper_docs에 있는 문서의 ID를 식별합니다
3) $scrollkeeper-db-dir/scrollkeeper_docs과 $scrollkeeper-db-dir/<LANGUAGE>에 있는 문서를 삭제합니다(둘다 contents list파일입니다)
4) 문서에 쓰이는 TOC파일을 삭제합니다. 위치는: $scrollkeeper-db-dir/TOC/<docid>
scrollkeeper-rebuilddb ?-v ?-p <scrollkeeper_db_dir>:
(Flags는 scrollkeeper-install의 그것과 같습니다)
1) $scrollkeeper_db_dir에 Path를 지정합니다.
만약 -p옵션이나 `scrollkeeper-config --pkglocalstatedir`가 사용되었으면 <scrollkeeper-db_dir>가 됩니다.
2) 오래된 데이터베이스를 지웁니다('rm -rf $scrollkeeper_db_dir/*')
3) 'scrollkeeper-update -p $scrollkeeper_db_dir'을 실행합니다.
이것은 $scrollkeeper_db_dir에 새로운 데이터베이스를 생성하고 여기에 OMF파일을 등록합니다.
(잘못되거나 구식인 데이터베이스에서도 언제든지 사용될수 있습니다.
또한 새버젼이 깔렸을 때 ScrollKeeper가 강제로 데이터베이스를 업데이트 하도록 하는 데 쓰일수 있습니다. 이것은 ScrollKeeper의 각 버전과의 호환성을 없앨수도 있습니다.)
-- For use by help browsers -- scrollkeeper-get-contents-list <language>:
1) Returns the path:
${pkglocalstatedir}/<language>/scrollkeeper_cl.xml if it
exists
scrollkeeper-get-extended-contents-list <language>:
1) Returns the path:
${pkglocalstatedir}/<language>/scrollkeeper_extended_cl.xml
if it exists
scrollkeeper-get-toc-from-docpath <docpath>:
1) Looks in ${pkglocalstatedir}/scrollkeeper-docs to find doc id
for <docpath>
2) Returns the path:
${pkglocalstatedir}/TOC/<docid>
-- i18n 지원 --
0.3버젼에 추가한 중요한 특징중 하나는 문서마다 대체(fallback)가 가능하다는것입니다. 즉, 요청한 로케일의 문서가 설치되어 있지 않으면, Scrollkeeper는 다른 로케일로 된 문서가 있으면 그것을 내보냅니다(fallback). 대체(fallback)에 쓰이는 언어 list는 LANGUAGE환경변수에 저장되어 있습니다. 브라우저가 content list를 요청하면 가능한 언어list의 모든 언어로 각각의 트리를 만드는걸로 고려합니다. 대체(fallback)는 문서와 그 문서의 번역본에 유일하게 할당된 독립된 ID가 있을때만 사용가능합니다.
The ID is generated by:
scrollkeeper-gen-seriesid
이것은 반드시 매개변수 없이 돌아가야 하고 그러면 스크린에 독립된 ID를 프린트 합니다. 스크립트가 어디에서 돌아가더라도,같은 ID를 만들어 내는 일은 거의 없습니다.
생성된 ID는 다음과 같이 문서의 모든 번역본의 OMF파일에 추가되어야 합니다.
<relation seriesid="seriesid"/>
아래 예제를 보시기 바랍니다.
작업후에 대체(fallback)가 제대로 지원됩니다.
scrollkeeper-docs: 이것은 OMF metadata의 위치목록을 저장하는 문서가 어떤것인지 흔적을 남기는데 사용됩니다.그리고 코드에 의해 구별된 분리가 간단하고 다른 task에서도 쓰일수 있는 문서를 식별합니다. 또한 scrollkeeper-update가 OMF파일이 언제 update되었는지 확인하기 위해서 OMF파일이 마지막으로 기록한 시간이 저장 되어있습니다. 마지막으로 설치된 문서의 한부분이 유지되어 있습니다.
/usr/doc/omf/foo-manual-fr.omf
000001
/usr/doc/foo/foo-manual.sgml
Sun Oct 29 13:48:50
C
/usr/doc/omf/bar-manual-en_US.omf
000002
/usr/doc/bar/bar-manual.sgml
Tue Oct 24 02:47:28
en_US
/usr/doc/omf/foob-manual-da.omf
000003
/usr/doc/foob/foob-manual.sgml
Tue Oct 24 02:47:28
da
scrollkeeper_cl.xml:
다음은 Contents List가 뭔지 OMF파일과 문서가 어디있는지 보여주는 간단한 xml파일입니다.
이것은 "확장된 Contents List"를 표시하는 help browser에 의해 사용되었습니다.
[간단한 DTD작업이 필요합니다]
<sect>
<title>응용프로그램</title>
<sect>
<title>게임</title>
<doc docid="000050">
<doctitle>프리셀</doctitle>
<docomf>/usr/local/games/freecell/freecell-omf.xml</docomf>
<docsource>/usr/local/games/freecell/freecell.sgml</docsource>
<docformat>SGML</docformat>
</doc>
</sect>
</sect>
TOC/<IDNUMBER>: 문서의 layout을 구문화 시키는 것에 대한 설명을 포함합니다. 또한 각 section마다 URI를 포함 시키는데 URI가 포함되어 있지 않으면 연결할수 없기 때문입니다.
scrollkeeper_extended_cl.xml: TOC정보가 들어가있는것을 제외하곤 scrollkeeper-contents-list.xml과 비슷합니다. 이것은 "확장된 Contents List"를 표시하는 help browser에 의해 사용되었습니다.
<sect>
<title>응용프로그램</title>
<sect>
<title>게임</title>
<doc docid="000050">
<doctitle>프리셀</doctitle>
<docomf>/usr/local/games/freecell/freecell-omf.xml</docomf>
<docsource>/usr/local/games/freecell/freecell.sgml</docsource>
<docformat>SGML</docformat>
<toc>
<tocsect1 linkid="introduction">프리셀 소개</tocsect1>
<tocsect1 linkid="playing">프리셀 진행중!
<tocsect2 linkid="winning">프리셀 이겼다!</tocsect2>
</tocsect1>
</toc>
</doc>
</sect>
</sect>
foo-manual.omf:
다음은 문서의 metadata입니다. 대체로 다음과 같습니다:
<omf>
<resource>
<title>
ScrollKeeper Manual
</title>
<creator>
<person>
<firstName>길동</firstName>
<lastName>고</lastName>
<email>길동@둘리.외계</email>
</person>
</creator>
<subject>
<category>시스템|기타</category>
</subject>
<description>
이 문서는 ScrollKeeper가 뭔지, 어떻게 동작하는지,ScrollKeeper를 유지,보수를 위한
기본시스템이 무엇인지,ScrollKeeper로 등록된 문서를 어떻게 패키지로 만드는지,
help browser로 어찌 내보내는지에 대해서 설명합니다.
</description>
<type>
manual
</type>
<format mime="text/sgml"/>
<relation seriesid="0bb19496-4b87-11d5-8e3d-f0dc97dbfcaa"/>
<identifier url="/usr/share/scrollkeeper/doc/scrollkeeper_manual/C/scrollkeeper_manual.sgml"/>
<language code="C"/>
</resource>
</omf>
OMF중 메타데이터에 대한 설명을 기초로 하였습니다. http://www.ibiblio.org/osrt/omf/