Qt Help 프로젝트

Qt 도움말 프로젝트는 압축된 도움말 파일을 생성하는 데 필요한 모든 데이터를 수집합니다. 목차, 색인 키워드 및 도움말 문서와 같은 실제 도움말 데이터와 함께 도움말 파일을 식별하는 네임스페이스와 같은 몇 가지 추가 정보가 포함되어 있습니다. 하나의 도움말 프로젝트는 하나의 문서 세트(예: qmake 매뉴얼)를 나타냅니다.

Qt Help 프로젝트 파일 형식

파일 형식은 XML 기반입니다. 형식에 대한 이해를 돕기 위해 다음 예제를 살펴보겠습니다:

<?xml version="1.0" encoding="UTF-8"?>
<QtHelpProject version="1.0">
    <namespace>mycompany.com.myapplication.1.0</namespace>
    <virtualFolder>doc</virtualFolder>
    <customFilter name="My Application 1.0">
        <filterAttribute>myapp</filterAttribute>
        <filterAttribute>1.0</filterAttribute>
    </customFilter>
    <filterSection>
        <filterAttribute>myapp</filterAttribute>
        <filterAttribute>1.0</filterAttribute>
        <toc>
            <section title="My Application Manual" ref="index.html">
                <section title="Chapter 1" ref="doc.html#chapter1"/>
                <section title="Chapter 2" ref="doc.html#chapter2"/>
                <section title="Chapter 3" ref="doc.html#chapter3"/>
            </section>
        </toc>
        <keywords>
            <keyword name="foo" id="MyApplication::foo" ref="doc.html#foo"/>
            <keyword name="bar" ref="doc.html#bar"/>
            <keyword id="MyApplication::foobar" ref="doc.html#foobar"/>
        </keywords>
        <files>
            <file>classic.css</file>
            <file>*.html</file>
        </files>
    </filterSection>
</QtHelpProject>

네임스페이스

QHelpEngine 에서 지정된 링크에 대한 적절한 문서를 검색할 수 있도록 하려면 모든 문서 집합에 고유 식별자가 있어야 합니다. 또한 고유 식별자는 도움말 컬렉션이 파일 이름에 의존하지 않고도 문서 세트를 추적할 수 있게 해줍니다. Qt 도움말 시스템은 필수 네임스페이스 태그에 의해 정의되는 네임스페이스를 식별자로 사용합니다. 위의 예에서 네임스페이스는 "mycompany.com.myapplication.1.0"입니다.

가상 폴더

모든 문서 집합에 네임스페이스가 있다는 것은 당연히 문서 집합이 상당히 분리되어 있다는 것을 의미합니다. 헬프 엔진의 관점에서는 이 점이 유용합니다. 하지만 작성자의 입장에서는 절대 링크를 지정하지 않고도 한 매뉴얼에서 다른 매뉴얼로 특정 주제를 상호 참조하는 것이 바람직한 경우가 많습니다. 이 문제를 해결하기 위해 도움말 시스템에 가상 폴더라는 개념을 도입했습니다.

가상 폴더는 압축된 도움말 파일에서 참조되는 모든 파일의 루트 디렉터리가 됩니다. 두 문서 세트가 동일한 가상 폴더를 공유하는 경우 서로를 가리키는 하이퍼링크를 정의할 때 상대 경로를 사용할 수 있습니다. 파일이 두 문서 세트에 모두 포함되어 있으면 현재 문서 세트의 파일이 다른 문서 세트보다 우선합니다.

...
<virtualFolder>doc</virtualFolder>
...

위의 예에서는 doc를 가상 폴더로 지정합니다. 다른 설명서에서 동일한 폴더를 지정하는 경우(예: 작은 헬퍼 도구인 내 애플리케이션)에는 doc.html#section1을 작성하여 내 애플리케이션 설명서의 첫 번째 섹션을 참조하면 충분합니다.

가상 폴더 태그는 필수이며 폴더 이름에 슬래시(/)가 포함되어서는 안 됩니다.

필터 섹션

필터 섹션에는 실제 문서가 포함됩니다. Qt 도움말 프로젝트 파일에는 필터 섹션이 두 개 이상 포함될 수 있습니다. 모든 필터 섹션은 목차, 키워드 및 파일 목록으로 구성됩니다. 이론상 모든 부분은 선택 사항이지만 아무것도 지정하지 않으면 문서 세트가 비어 있습니다.

목차

...
<toc>
    <section title="My Application Manual" ref="index.html">
        <section title="Chapter 1" ref="doc.html#chapter1"/>
        <section title="Chapter 2" ref="doc.html#chapter2"/>
        <section title="Chapter 3" ref="doc.html#chapter3"/>
    </section>
</toc>
...

하나의 섹션 태그는 목차에서 하나의 항목을 나타냅니다. 섹션은 어느 정도까지 중첩할 수 있지만 사용자 관점에서 볼 때 4~5단계를 넘지 않아야 합니다. 섹션은 제목과 참조로 정의됩니다. 참조는 Qt 도움말 프로젝트의 모든 파일 참조와 마찬가지로 도움말 프로젝트 파일 자체에 상대적입니다.

키워드

...
<keywords>
   <keyword name="foo" id="MyApplication::foo" ref="doc.html#foo"/>
   <keyword name="bar" ref="doc.html#bar"/>
   <keyword id="MyApplication::foobar" ref="doc.html#foobar"/>
</keywords>
...

키워드 섹션에는 이 필터 섹션의 모든 키워드가 나열됩니다. 키워드는 기본적으로 이름과 파일 참조로 구성됩니다. 속성 이름을 사용하면 여기에 지정된 키워드가 표시되는 색인에 나타납니다. 즉, QHelpIndexModel 클래스를 통해 액세스할 수 있습니다. id를 사용하는 경우 키워드는 색인에 나타나지 않으며 QHelpEngineCore::documentsForIdentifier()를 통해서만 액세스할 수 있습니다. 이름과 id를 동시에 지정할 수 있습니다.

파일

...
<files>
    <file>classic.css</file>
    <file>*.html</file>
</files>
...

마지막으로 실제 문서 파일을 나열해야 합니다. 도움말을 표시하는 데 필요한 모든 파일이 언급되어 있는지 확인하세요. 즉, 스타일시트나 이와 유사한 파일도 나열해야 합니다. 이 파일들은 Qt 도움말 프로젝트의 모든 파일 참조와 마찬가지로 도움말 프로젝트 파일 자체에 상대적입니다. 예제에서 볼 수 있듯이 와일드카드를 사용하여 파일(디렉터리는 제외)을 패턴으로 지정할 수도 있습니다. 나열된 모든 파일은 압축되어 Qt 압축 도움말 파일에 기록됩니다. 따라서 결국 하나의 Qt 도움말 파일에는 모든 문서 파일과 내용 및 인덱스가 포함됩니다.