링크 만들기

이 명령어들은 클래스, 함수, 예제 및 기타 대상에 대한 하이퍼링크를 생성하는 데 사용됩니다.

\l (링크)

\l 링크 명령어는 다양한 종류의 대상에 대한 하이퍼링크를 생성하는 데 사용됩니다. 이 명령어의 일반적인 구문은 다음과 같습니다:

\l [ link criteria ] { link target } { link text }

...여기서 괄호 안에 있는 ` link criteria `는 선택 사항이지만, ` link target `가 모호한 경우에는 필수일 수 있습니다. 아래의 ‘모호한 링크 수정’을 참조하십시오.

\l 명령어를 사용하여 다음 대상에 링크를 설정할 수 있습니다:

• 외부 페이지:

  An URL with a custom link text:
  \l {https://doc.qt.io/qt-6/} {Qt 6 Documentation}.
  
  An URL without a custom link text: \l {https://doc.qt.io/qt-6/}.

  다음과 같이 표시됩니다:

  사용자 정의 링크 텍스트가 포함된 URL: Qt 6 문서.

  사용자 지정 링크 텍스트가 없는 URL: https://doc.qt.io/qt-6/.

  참조 \externalpage.

• 문서 페이지. 링크 대상은 다음과 같을 수 있습니다:
  • 다음과 같이 지정된 페이지 제목 \title 명령어로 지정된 페이지 제목:

    Here is a link with a custom link text:
    \l {Getting Started with QDoc}{QDoc - Getting Started}.
    
    Here is a link with a link text that is the same as the link
    target: \l {Getting Started with QDoc}.

    다음과 같이 표시됩니다:

    다음은 사용자 정의 링크 텍스트가 포함된 링크입니다: QDoc - 시작하기.

    다음은 링크 텍스트가 링크 대상과 동일한 링크입니다: QDoc 시작하기.

  • 다음 \page 다음과 같이 지정된 페이지 파일 이름은:

    \page 08-qdoc-commands-creatinglinks.html
    \title Creating Links
    
    These commands are for creating hyperlinks to classes, functions,
    examples, and other targets.
    
    ...
    
    The \l {08-qdoc-commands-creatinglinks.html} {Creating Links page}
    explains how to create links with QDoc.

    다음과 같이 표시됩니다:

    '링크 만들기' 페이지 문서에서는 QDoc을 사용하여 링크를 만드는 방법을 설명합니다.

  • 다음 명령어를 사용하여 \keyword 명령어가 포함된 페이지.
• 문서 내의 특정 앵커 섹션입니다. 링크 대상은 다음과 같을 수 있습니다:
  • 다음 Section 명령어 중 하나로 지정된 섹션 제목:

    Here is a link to a QDoc Commands section of the Writing
    Documentation topic:
    \l {Writing Documentation#QDoc Commands}{QDoc Commands}.
    
    If you have unique section titles across your documentation
    project, you can use the section title as a target without
    the need to add the topic title:
    \l {QDoc Commands}.

    다음과 같이 표시됩니다:

    다음은 ‘문서 작성’ 주제 내의 ‘QDoc 명령어’ 섹션으로 연결되는 링크입니다: QDoc 명령어.

    문서 프로젝트 전체에 걸쳐 고유한 섹션 제목이 있는 경우, 주제 제목( QDoc 명령어)을 추가할 필요 없이 섹션 제목을 대상으로 사용할 수 있습니다.

    # 문자는 문서 내 링크를 생성하는 데 사용되므로, 해당 문자가 포함된 제목으로 링크할 때는 그대로 사용할 수 없습니다. 대신 백슬래시를 사용하여 이스케이프 처리해야 합니다:

    \l {Using Qt with C\\#}

    QDoc이 링크 명령에 텍스트를 전달하기 전에 해당 텍스트를 처리하기 때문에 백슬래시를 두 개 사용합니다.

  • 다음 명령어로 정의된 앵커: \target 명령어로 정의된 앵커:

    \target assertions
    
    Assertions make some statement about the text at the
    point where they occur in the regexp, but they do not
    match any characters.
    
    ...
    
    Regexps are built up from expressions, quantifiers, and
    \l {assertions} {assertions}.

• API 항목. 대상 링크는 다음과 같을 수 있습니다:
  • \l QWidget - \class 또는 \qmltype 명령어로 문서화된 클래스 이름.
  • \l QWidget::sizeHint() - 매개변수가 없는 함수의 시그니처. 매개변수가 없는 일치하는 함수를 찾을 수 없는 경우, 가장 먼저 발견된 일치하는 함수로 링크가 설정됩니다.
  • \l QWidget::removeAction(QAction* action) - 매개변수가 있는 함수의 시그니처. 정확히 일치하는 항목이 발견되지 않으면 링크가 성립되지 않으며, QDoc은 “Can't link to...” 오류를 보고합니다.
  • \l <QtGlobal> - \headerfile 명령의 대상.

  링크에 함수 이름만 표시되도록 하려면 다음 구문을 사용할 수 있습니다: \l{QWidget::}{sizeHint()}.

• 예시입니다. 대상 링크는 예시 제목이거나 \example 명령어에서 사용된 상대 경로입니다:

  /*!
      \example widgets/imageviewer
      \title ImageViewer Example
      \brief Shows how to combine QLabel and QScrollArea
      to display an image.
  
      ...
  */
  
  ...
  
  See the example: \l widgets/imageviewer

링크 대상이 링크 텍스트와 동일하다면, 두 번째 인수를 생략할 수 있습니다.

예를 들어, 다음과 같은 문서가 있다면:

/*!
    \target assertions

    Assertions make some statement about the text at the
    point where they occur in the regexp, but they do not
    match any characters.

    ...

    Regexps are built up from expressions, quantifiers, and
    \l {assertions} {assertions}.
*/

이를 다음과 같이 간소화할 수 있습니다:

/*!
    \target assertions

    Assertions make some statement about the text at the
    point where they occur in the regexp, but they do not
    match any characters.

    ...

    Regexps are built up from expressions, quantifiers, and
    \l assertions.
*/

단일 매개변수 버전의 경우, 중괄호를 생략할 수 있는 경우가 많습니다.

자동 연결

QDoc은 또한 일반적인 영어 단어와 닮지 않은 단어, 예를 들어 Qt 클래스 이름이나 함수( QWidget 이나 QWidget::sizeHint() 등)에 대해서도 링크를 생성하려고 시도합니다. 이러한 경우 \l 명령을 실제로 생략할 수 있지만, 이 명령을 사용하면 QDoc이 링크 대상을 찾을 수 없을 때 경고 메시지를 출력하도록 보장할 수 있습니다.

자동 링크 기능으로 인해 우연히 링크 대상과 일치하는 단어에 대해 원치 않는 링크가 생성되는 경우, ignorewords 구성 변수를 사용하여 이를 억제할 수 있습니다.

모호한 링크 수정하기

모호한 링크란 하나 이상의 Qt 모듈이나 문서 세트에 일치하는 대상이 있는 링크를 말합니다. 예를 들어, 동일한 섹션 제목이 두 개 이상의 Qt 모듈에 나타날 수 있거나, 한 모듈의 C++ 클래스 이름이 다른 모듈의 QML 유형 이름과 동일할 수 있습니다. Qt에서 실제 예로 Qt라는 이름 자체가 있습니다. 이 이름은 QtCore 의 C++ 네임스페이스 이름이자 QtQml 의 QML 유형 이름이기도 합니다.

Qt C++ namespace 에 링크를 걸고자 한다고 가정해 봅시다. QDoc이 이 HTML 페이지를 생성했을 당시에는 해당 링크가 정확했습니다. 지금도 여전히 C++ 네임스페이스로 연결될까요? QDoc은 다음 링크 명령을 사용하여 해당 링크를 생성했습니다:

• \l {Qt} {Qt C++ namespace}

이제 Qt QML type 로 링크를 연결하고 싶다고 가정해 봅시다. QDoc이 이 HTML 페이지를 생성했을 당시에는 그 링크도 정확했지만, 다음 링크 명령을 사용해야 했습니다:

• \l [QML] {Qt} {Qt QML type}

대괄호 안에 있는 QML은 대상이 QML 페이지에 있을 때만 일치하는 대상을 허용하도록 QDoc에 지시합니다. QDoc은 실제로 C++ 네임스페이스 대상을 먼저 찾지만, 해당 대상이 C++ 페이지에 있기 때문에 QDoc은 이를 무시하고 QML 페이지에서 동일한 대상을 찾을 때까지 계속 검색합니다.

선택 사항인 대괄호 내의 ` \l ` 명령어 지정이 없다면, QDoc은 처음 발견한 일치하는 대상에 링크를 생성합니다. QDoc은 다른 일치하는 대상이 존재한다는 사실을 알지 못하기 때문에, 이러한 경우 링크가 모호하다는 경고를 표시할 수 없습니다.

대괄호 안에 어떤 인수를 지정할 수 있나요?

대괄호 인자를 갖는 링크 명령어의 구문은 다음과 같습니다:

\l [QML|CPP|DOC|attached|QtModuleName] {link target} {link text}

대괄호 인수는 ` \l (link) ` 명령어에서만 허용됩니다. 위의 예제는 ` QML `를 대괄호 인수로 사용하여 QDoc이 QML 대상을 매칭하도록 강제하는 방법을 보여줍니다. 대부분의 경우 이는 QML 타입이 되겠지만, QML 멤버 함수나 속성일 수도 있습니다. 또한, 일부 QML 타입에는 동일한 이름을 가진 속성과 부착 속성이 포함되어 있습니다. 부착 속성은 ` attached ` 인수를 사용하여 선택할 수 있습니다. ` attached `를 생략하면, 이름이 중복된 부착 속성보다 일반 속성이 우선적으로 링크됩니다.

이 예제에서 QDoc은 Qt C++ 네임스페이스 페이지를 찾기 위해 대괄호 인수를 사용할 필요가 없었습니다. 어차피 QDoc이 찾은 첫 번째 일치 대상이었기 때문입니다. 하지만 일치하는 QML 대상이 방해가 될 때 QDoc이 C++ 대상을 찾도록 강제하려면, 대괄호 인수로 ` CPP `를 사용할 수 있습니다. 예를 들어, 다음 링크는 QDoc이 Qt Qml 타입을 무시하고 Qt C++ 네임스페이스와 일치할 때까지 검색을 계속하도록 강제합니다.

• \l [CPP] {Qt} {Qt C++ namespace}

링크 대상이 C++이나 QML 엔티티가 아닌 경우, DOC 을 대괄호 인자로 사용하여 QDoc이 이들 중 어느 쪽과도 일치하지 않도록 할 수 있습니다. 이 글을 작성하는 시점에서는 DOC 을 사용해야 하는 모호한 링크 사례는 없었습니다.

대개 문서 작성자는 링크 대상이 어느 Qt 모듈에 속하는지 알고 있습니다. 모듈 이름을 알고 있다면, 그 모듈 이름을 대괄호 인자로 사용하십시오. 위 예시에서, Qt라는 이름의 Qml 유형이 QtQml 모듈에 있다는 것을 알고 있다면, 링크 명령을 다음과 같이 작성할 수 있습니다:

• \l [QtQml] {Qt} {Qt QML type}

모듈 이름을 대괄호 인자로 사용할 경우, QDoc은 해당 모듈 내에서만 링크 대상을 검색합니다. 이를 통해 링크 대상 검색이 더욱 효율적으로 이루어집니다.

마지막으로, 모듈 이름과 엔티티 유형 인수는 공백으로 구분하여 결합할 수 있으므로 다음과 같은 형식도 허용됩니다:

• \l [CPP QtQml] {Window} {C++ class Window}

이 글을 작성하는 시점에서는 이 두 가지를 결합해야 하는 사례는 없었습니다.

참조 \sa, \target, 그리고 \keyword.

\sa (참조)

\sa 명령어는 문서 단위 하단에 별도의 “참조 항목” 섹션으로 표시될 링크 목록을 정의합니다.

이 명령어는 쉼표로 구분된 링크 목록을 인수로 받습니다. 줄 끝이 쉼표로 끝나면 다음 줄에서 목록을 이어갈 수 있습니다. 일반적인 구문은 다음과 같습니다:

\sa {the first link}, {the second link},
    {the third link}, ...

QDoc은 속성의 다양한 함수들을 서로 연결하는 “참조” 링크를 자동으로 생성하려고 시도합니다. 예를 들어, setVisible() 함수에는 visible()로 연결되는 링크가 자동으로 생성되며, 그 반대의 경우도 마찬가지입니다.

일반적으로 QDoc은 동일한 속성에 접근하는 함수들을 서로 연결하는 “참조” 링크를 생성합니다. QDoc은 네 가지 다른 구문 형식을 인식합니다:

• property()
• setProperty()
• isProperty()
• hasProperty()

\sa 명령어는 \l 명령과 동일한 종류의 링크를 지원합니다.

/*!
    Appends the actions \a actions to this widget's
    list of actions.

    \sa removeAction(), QMenu, addAction()
*/
void QWidget::addActions(QList<QAction *> actions)
{
    ...
}

참조: \l, \target 그리고 \keyword.

\target

\target 명령어는 \l (link) 및 \sa (see also) 명령어를 사용하여 링크할 수 있는 문서 내의 위치를 지정합니다.

줄 바꿈까지의 텍스트가 대상 이름이 됩니다. 대상 이름 뒤에는 반드시 줄 바꿈을 넣어야 합니다. 대상 이름을 중괄호로 묶을 필요는 없지만, 링크 명령어에서 대상 이름을 사용할 때는 중괄호가 필요할 수 있습니다. 아래를 참조하십시오.

/*!
    \target capturing parentheses
    \section1 Capturing Text

    Parentheses allow us to group elements together so that
    we can quantify and capture them.

    ...
*/

대상 이름을 묶는 괄호 안의 내용은 다음과 같은 방식으로 링크할 수 있습니다:

• \l {capturing parentheses}

위 예시에서 대상 이름은 공백이 포함되어 있으므로 대괄호로 묶여 있습니다.

\target 에서 \table

표 내에서 ` \target ` 명령어를 사용할 때는, ` \target ` 명령어가 \li-명령(테이블 셀) 뒤에 위치하도록 해야 합니다. 일부 생성기는 전체 행이 아닌 개별 셀을 대상으로만 지원하기 때문입니다. 또한, 해당 명령이 별도의 줄에 있거나, 포함된 줄에서 마지막 내용으로 위치해야 합니다. 이는 ` \target ` 명령어의 작동 방식 때문입니다. 이 명령어는 다음 줄 바꿈까지의 모든 내용을 매개변수로 처리합니다. 즉, 테이블 내에 ` \target ` 명령어가 필요한 경우, 반드시 다음 구조를 따르도록 해야 합니다:

\table
    \row
        \li \target my-target
        My text goes here.
        \li This is my next table cell.
\endtable

참조 \l, \sa 그리고 \keyword.

\keyword

\keyword 명령어는 \l (링크) 및 \sa (참조) 명령어를 사용하여 연결할 수 있는 문서 내의 위치를 지정합니다. 또한 생성된 색인에 해당 키워드와 위치를 추가합니다.

\keyword 명령어는 \target 명령과 유사하지만, 키워드에 링크를 설정할 때 기본적으로 링크가 \keyword 가 포함된 QDoc 주석(주제)의 맨 위로 연결된다는 점이 다릅니다.

주제 내에서 section 유닛에 대한 키워드를 생성하려면, 섹션 제목 바로 위에 \keyword 를 추가하십시오:

\keyword debug
\section1 Debug command line option (--debug)
...

\target 와 달리, 키워드는 생성된 오프라인 문서 파일(.qch)의 색인에 등록됩니다. 이를 통해 사용자는 예를 들어 Qt Assistant 의 색인 검색에서 키워드로 위치를 조회할 수 있으며, Qt Creator 의 컨텍스트 도움말에서도 해당 키워드를 이용할 수 있습니다.

키워드는 QDoc 실행 중에 처리되는 모든 문서에서 고유해야 합니다. 이 명령어는 줄의 나머지 부분을 인수로 사용합니다. 키워드 뒤에는 반드시 줄바꿈을 넣어 주십시오.

/*!
    \class QRegularExpression
    \reentrant
    \brief The QRegularExpression class provides pattern
           matching using regular expressions.
    \ingroup tools
    \ingroup misc
    \ingroup shared

    \keyword regular expression

    Regular expressions, or "regexps", provide a way to
    find patterns within text.

    ...
*/

키워드로 표시된 위치에는 다음을 사용하여 링크를 연결할 수 있습니다:

/*!
    When a string is surrounded by slashes, it is
    interpreted as a \l {regular expression}.
*/

키워드 텍스트에 공백이 포함된 경우, 괄호를 반드시 사용해야 합니다.

\l (링크), \sa (참조) 및 \target.