링크 만들기

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

\l (링크)

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

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

...여기서 대괄호 안의 link criteria 은 선택 사항이지만 link target 이 모호한 경우 필수일 수 있습니다. 아래의 모호한 링크 수정하기를 참조하세요.

l 명령을 사용하여 링크할 수 있습니다:

• 외부 페이지로 연결할 수 있습니다:

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

  다른 이름으로 렌더링합니다:

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

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

  외부 페이지도 참조하세요.

• 문서 페이지. 링크 대상은 다음과 같습니다:
  • 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 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으로 링크를 만드는 방법에 대해 설명합니다.

  • 키워드 명령으로 페이지를 렌더링하는 방법을 설명합니다.
• 문서 내의 특정 앵커 섹션으로 연결할 수 있습니다. 링크 대상은 다음과 같습니다:
  • 섹션 명령 중 하나로 지정된 섹션 제목:

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

  • 대상 명령으로 정의된 앵커:

    \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에서 연결할 수 없음... 오류를 보고합니다.
  • \l <QtGlobal> - headerfile 명령의 제목입니다.
• 예제입니다. 대상 링크는 예제 제목 또는 \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은 QWidget 또는 QWidget::sizeHint()과 같이 일반적인 영어 단어와 유사하지 않은 단어(예: Qt 클래스 이름이나 함수)로 링크를 만들려고 시도합니다. 이러한 경우 \l 명령은 실제로 생략할 수 있지만 이 명령을 사용하면 링크 대상을 찾을 수 없는 경우 QDoc이 경고를 표시하도록 할 수 있습니다. 또한 링크에 함수 이름만 표시하려면 다음 구문을 사용할 수 있습니다:

• \l {QWidget::} {sizeHint()}

모호한 링크 수정하기

Qt 5.0부터 시작된 Qt의 모듈화로 인해 QDoc이 모호한 링크를 처리해야 할 가능성이 높아졌습니다. 모호한 링크는 둘 이상의 Qt 모듈에 일치하는 대상이 있는 링크입니다. 예를 들어, 동일한 섹션 제목이 둘 이상의 Qt 모듈에 나타날 수 있거나 한 모듈의 C++ 클래스 이름이 다른 모듈의 QML 유형 이름일 수 있습니다. Qt5의 실제 예는 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++ 페이지에 있기 때문에 이를 무시하고 QML 페이지에서 동일한 대상을 찾을 때까지 계속 찾습니다.

선택적 대괄호 인수에 \l 명령의 안내가 없으면 QDoc은 가장 먼저 찾은 일치하는 대상에 연결합니다. 이러한 경우 다른 일치하는 대상이 존재한다는 것을 알지 못하기 때문에 QDoc은 링크가 모호하다는 경고를 표시하지 않습니다.

대괄호 안에 어떤 인수가 표시될 수 있나요?

대괄호 인수가 있는 링크 명령의 구문은 다음과 같습니다:

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

대괄호 인수는 \l (link) 명령에서만 허용됩니다. 위의 예는 QML 을 대괄호 인수로 사용하여 QDoc이 QML 대상과 일치하도록 하는 방법을 보여줍니다. 대부분의 경우 이 인수는 QML 유형이지만 속성의 QML 멤버 함수일 수도 있습니다.

이 예제에서는 QDoc이 Qt C++ 네임스페이스 페이지를 찾는 데 대괄호 인수가 필요하지 않았는데, 그 이유는 이 페이지가 QDoc이 가장 먼저 찾은 일치하는 대상이었기 때문입니다. 그러나 일치하는 QML 타겟이 방해가 될 때 QDoc이 C++ 타겟을 찾도록 하려면 CPP 을 대괄호 인수로 사용할 수 있습니다. 예를 들어

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

...는 QDoc이 Qt QML 유형을 무시하고 Qt C++ 네임스페이스와 일치할 때까지 검색을 계속하도록 합니다.

링크 대상이 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은 동일한 프로퍼티에 액세스하는 함수를 상호 연결하는 "참조" 링크를 생성합니다. 네 가지 구문 버전을 인식합니다:

• 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(링크) 및 \sa(참조) 명령을 사용하여 링크할 수 있는 위치의 이름을 지정합니다.

줄 바꿈까지의 텍스트가 대상 이름이 됩니다. 대상 이름 뒤에는 반드시 줄 바꿈이 와야 합니다. 대상 이름 주변에는 중괄호가 필요하지 않지만 링크 명령에 대상 이름을 사용할 때는 중괄호가 필요할 수 있습니다. 아래를 참조하세요.

/*!
    \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

표에서 \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도 참조하세요.

\키워드

키워드 명령은 문서에서 \l(링크) 및 \sa(참조) 명령을 사용하여 링크할 수 있는 위치의 이름을 지정합니다. 또한 생성된 인덱스에 키워드와 위치를 추가합니다.

키워드에 링크할 때 기본적으로 링크가 해당 키워드가 나타나는 QDoc 댓글(주제)의 맨 위로 이동한다는 점을 제외하면 \keyword 명령은 \target 명령과 비슷합니다.

토픽 내에서 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도 참조하세요.