Qt Help 프로젝트

Qt Help 도움말 프로젝트는 압축된 도움말 파일을 생성하는 데 필요한 모든 데이터를 수집합니다. 목차, 색인 키워드, 도움말 문서와 같은 실제 도움말 데이터 외에도, 도움말 파일을 식별하기 위한 네임스페이스와 같은 추가 정보도 포함됩니다. 하나의 도움말 프로젝트는 하나의 문서 세트를 나타내며, 예를 들어 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 Help 시스템은 필수 네임스페이스 태그로 정의된 네임스페이스를 식별자로 사용합니다. 위 예시에서 네임스페이스는 "mycompany.com.myapplication.1.0"입니다.

가상 폴더

모든 문서 세트에 네임스페이스가 있다는 것은 당연히 문서 세트들이 상당히 분리되어 있음을 의미합니다. 도움말 엔진의 관점에서 보면 이는 유익합니다. 그러나 작성자의 관점에서 볼 때, 절대 경로를 명시하지 않고도 한 매뉴얼의 특정 주제를 다른 매뉴얼에서 상호 참조할 수 있기를 바라는 경우가 종종 있습니다. 이 문제를 해결하기 위해 도움말 시스템은 가상 폴더라는 개념을 도입했습니다.

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

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

위의 예제에서는 doc를 가상 폴더로 지정하고 있습니다. 다른 설명서(예: 작은 보조 도구인 ‘My Application’의 설명서)에서도 동일한 폴더를 지정하는 경우, ‘doc.html#section1’을 작성하기만 하면 ‘My Application’ 설명서의 첫 번째 섹션을 참조할 수 있습니다.

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

필터 섹션

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

목차

...
<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 Help 프로젝트 내의 모든 파일 참조와 마찬가지로, Help 프로젝트 파일 자체를 기준으로 상대 경로입니다.

키워드

...
<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>
...

키워드 섹션에는 이 필터 섹션의 모든 키워드가 나열됩니다. 키워드는 기본적으로 이름과 파일 참조로 구성됩니다. 속성 이름 (attribute name )이 사용된 경우, 해당 위치에 지정된 키워드는 가시적인 인덱스에 표시됩니다. 즉, ` QHelpIndexModel ` 클래스를 통해 접근할 수 있습니다. id가 사용된 경우, 해당 키워드는 인덱스에 표시되지 않으며 ` QHelpEngineCore::documentsForIdentifier()`를 통해서만 접근할 수 있습니다. 이름(name) 과 id는 동시에 지정할 수 있습니다.

파일

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

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