키 및 키 참조 사용
Arbortext Editor는 OASIS
DITA Architectural Specification의
Key based (indirect) addressing 섹션에 정의된 대로 키 기반 참조를 지원합니다.
Arbortext Editor 사용자 인터페이스에는 DITA 맵에서 키 정의를 정의하고 맵과 주제에 키 참조를 삽입하는 작업을 도와주는 다양한 기능이 제공됩니다. 또한
Arbortext Editor에는 키 정의만 모아 둔
DITA 키 정의 맵이라고 하는 특수 DITA 맵이 있습니다. 이 맵을 사용하여 키 정의에 대한 추가 정보를 제공할 수 있습니다.
키 정의를 보관하는 가장 좋은 방법은 키 정의만 모아 두는 전용 DITA 맵을 사용하는 것입니다. 이렇게 하면 필요할 경우 mapref 요소를 사용하여 키 정의를 포함하는 맵을 다른 DITA 맵에 포함시킬 수 있습니다. DITA 키 정의 맵을 사용하여 키 정의를 보관하는 것이 좋습니다.
키 참조 사용자 인터페이스
다음은 Arbortext Editor 사용자 인터페이스에서 키 참조를 지원하는 부분입니다.
• 삽입 메뉴에는 다음과 같은 옵션이 있습니다.
◦ 키 정의 - 키 정의 탭이 활성화된 리소스 매니저를 엽니다.
◦ 키 참조 - 키 참조 삽입 대화 상자를 엽니다.
• 도구 메뉴에는 다음과 같은 옵션이 있습니다.
◦ 키 및 키 참조 - 키 및 키 참조 대화 상자를 엽니다.
◦ 키 참조 찾기 - 커서가 있는 태그에 포함된 키만 표시하는 키 및 키 참조 대화 상자를 엽니다.
이 옵션은 Arbortext Editor 바로 가기 메뉴에서도 사용할 수 있습니다.
◦ 키 참조 정보 - 키 참조 정보 대화 상자를 엽니다.
이 옵션은 Arbortext Editor 바로 가기 메뉴에서도 사용할 수 있습니다.
• 마크업 도구 모음에는
키 참조 삽입
버튼이 있으며, 이 버튼을 클릭하면
키 참조 삽입 대화 상자가 열립니다.
• 다음은 리소스 매니저에서 키 참조를 지원하는 기능입니다.
◦ DITA 맵에서
키 정의 탭을 사용하여 키 정의를 정의할 수 있습니다.
키 정의를 수정하기 위한 이 탭 버전은 속성 수정 대화 상자, 문서 맵 및 열 보기에서 사용할 수 있습니다.
◦ 콘텐츠 참조를 제외한 모든 리소스 매니저 탭과 대화 상자에서 Keyref 옵션을 사용할 수 있으며, 이를 통해 참조를 만들거나 수정할 때 keyref 속성에 삽입할 키 이름을 입력하거나 선택할 수 있습니다.
◦ 콘텐츠 참조를 위한 리소스 매니저 탭과 대화 상자에서 Conkeyref 옵션을 사용할 수 있으며, 이를 통해 참조를 만들거나 수정할 때 conkeyref 속성에 삽입할 키 이름을 입력할 수 있습니다.
◦ 링크/Xref, 콘텐츠 참조 및 주제 탭과 대화 상자를 사용하여 키 정의가 들어 있는 DITA 맵을 찾아볼 수 있으며, 삽입하거나 수정한 참조에 선택한 키 정의를 사용할 수 있습니다.
• 다음은 키 참조를 지원하는 대화 상자입니다.
◦ 맵 추가/제거 -
키 참조 삽입 대화 상자에 키 정의를 제공하는 맵 목록에서 맵을 추가하거나 제거할 수 있습니다.
◦ 참조 선택 - 참조 요소에 정의된 참조 대상이 두 개 이상일 경우 어느 문서를 열 것인지 선택할 수 있습니다.
◦ 키 참조 정보 - 키 참조와 연관된 키 정의에 대한 정보를 표시합니다.
◦ 키 및 키 참조 - 현재 문서 및 현재 문서에서 참조하는 문서에 포함된 키 정의와 키 참조를 표시합니다.
키 참조 사용자 인터페이스 숨기기
Arbortext Editor에서는 기본적으로 키 참조 사용자 인터페이스를 사용할 수 있습니다. DITA 문서에서 키 참조를 사용하지 않을 경우 사용자 인터페이스에서 키 참조 기능을 제거할 수 있습니다.
키 참조 사용자 인터페이스를 사용할지 여부는 ditakeyrefui 고급 기본 설정으로 제어합니다. 키 참조 사용자 인터페이스를 제거하려면 이 기본 설정의 값을 off로 설정합니다.
키 컨텍스트 설정
Arbortext Editor에서 키 참조와 연관된 키 정의를 찾으려면 현재 문서의 키 컨텍스트를 알아야 합니다. 키 컨텍스트는 관련된 키 정의가 들어 있는 DITA 맵입니다. 정의가 들어 있는 맵이 DITA 키 정의 맵일 경우 키 참조 사용자 인터페이스에 표시할 추가 정보를 키 정의에 추가할 수 있습니다. 문서의 키 컨텍스트는 ditakeycontext set 옵션의 설정에 따라 결정됩니다.
ditakeycontext 옵션은 단일 맵으로 설정되고 현재 세션 동안 현재 문서의 기본 키 컨텍스트를 정의합니다. 문서에 키 컨텍스트가 설정되어 있을 경우 Arbortext Editor에서 참조를 처리하는 방식에 영향을 줍니다. 예를 들어, 이미지 태그에 href 및 keyref 속성이 모두 정의될 경우 Arbortext Editor는 keyref 속성의 키 정의의 이미지를 표시합니다. Arbortext Editor는 일치하는 키 정의를 포함하는 키 컨텍스트가 설정되어 있을 경우 키 참조 또는 콘텐츠 키 참조 우선 순위를 부여합니다.
ditakeycontext는 사용자가 명시적으로 설정하거나 경우에 따라 Arbortext Editor에서 자동으로 설정합니다. 예를 들어 상호 참조 및 주제 참조 등을 두 번 클릭하여 문서를 열 경우 원본 문서의 키 컨텍스트가 새로 연 문서에 적용됩니다. 마찬가지로 Arbortext Editor DITA 관련 대화 상자에서 문서를 열 경우 현재 문서의 키 컨텍스트가 연 문서에 적용됩니다. 원본 문서가 키 컨텍스트를 포함하지 않는 DITA 맵일 경우 이 맵이 연 문서의 키 컨텍스트가 됩니다.
문서에 삽입하기 위해 키 정의를 정의하는 또 다른 옵션은 ditakeybaselist set 옵션입니다. 키 참조 삽입 대화 상자와 리소스 매니저의 Keyref 옵션에 표시될 키 정의에 사용되는 맵 목록을 설정하려면 기본적으로 ditakeybaselist 옵션을 사용합니다. ditakeycontext와 달리 ditakeybaselist는 고급 기본 설정으로서 여러 맵을 포함할 수 있으며 Arbortext Editor 세션 간에 유지됩니다. ditakeybaselist에 값을 지정했으며 현재 ditakeycontext인 맵이 이 목록에 없을 경우 현재 세션에 대한 ditakeybaselist 맵 목록의 앞에 키 컨텍스트 맵이 추가됩니다.
DITA 키 정의 맵 사용
Arbortext Editor는 DITA 키 정의 맵이라고 하는 특별한 DITA 맵을 제공합니다. 이 맵에는 키 정의에 정보를 추가로 제공할 수 있는 추가 요소가 들어 있으며, 이 맵은 키 정의를 보관하기 위한 전용 맵입니다. 추가 키 정의 정보는 키 참조 사용자 인터페이스의 다양한 위치에 표시됩니다. DITA 키 정의 맵은 새로 만들기 대화 상자의 DITA Technical Content 카테고리에 있습니다.
키 정의 맵은 topicmeta 요소에 요소를 추가하여 키 정의에 대한 자세한 정보를 제공합니다. 이러한 요소를 사용하려면 keydef 요소를 맵에 삽입하고, topicmeta 요소를 keydef 요소에 삽입하며 keyinfo 요소를 topicmeta에 삽입합니다. 그런 다음 keyinfo 내에 사용하려는 새 메타데이터 요소를 삽입할 수 있습니다. 또한 키 정의 맵에서 리소스 매니저의 키 정의 탭을 사용하여 키 정의에 이러한 정보를 추가할 수도 있습니다.
다음은 topicmeta에서 일반 키 참조에 사용할 수 있는 추가 요소입니다.
• keyinfo - 다른 요소를 포함합니다.
• keydescription - 키의 텍스트 설명을 포함합니다.
• keysubelementid - 이 키를 적용할 특정 요소 ID를 지정합니다(value 속성 사용).
• keyreftags - 이 키를 참조하는 데 사용할 하나 이상의 요소 이름 목록을 포함합니다(value 속성 사용).
콘텐츠 키 참조 사용
Arbortext Editor에서 키 참조를 통해 콘텐츠를 바꾸려면 요소에서 conkeyref 속성을 사용하여 콘텐츠 키 참조를 설정하면 됩니다. 일반 키 참조와 마찬가지로, 콘텐츠 키 참조의 키 컨텍스트에 문서에 대한 관련 정의가 있고 요소에 conref 속성과 conkeyref 속성이 모두 정의되어 있을 경우 Arbortext Editor는 conkeyref와 연관된 콘텐츠를 표시하고 일반적으로 키 콘텐츠 참조 우선 순위를 부여합니다.
일반 키 정의를 사용하여 콘텐츠 키 참조에 대한 키를 설정할 수 있습니다. 하지만 DITA 키 정의 맵은 콘텐츠 참조를 위한 키를 정의할 수 있도록 몇 가지 추가 요소를 제공합니다. 또한 키 참조 삽입 대화 상자에 콘텐츠 키 참조를 포함시키려면 DITA 키 정의 맵에 연관된 키 정의를 정의해야 합니다. 다음은 콘텐츠 키 참조에 사용할 수 있는 추가 요소입니다.
• keyconrefs - 콘텐츠 키 참조 전용의 키 정의를 정의할 수 있습니다.
이 요소는 keydef 요소의 특수화 요소입니다. keyconrefs로 정의된 키 이름을 참조하는 주제나 맵 내에 ID를 포함하는 요소는 키 참조 삽입 대화 상자에서 conkeyref 참조의 대상으로 표시됩니다. 이 요소의 scope 속성은 local로 설정됩니다. format 속성은 dita(기본값) 또는 ditamap으로 설정됩니다.
또한 이 요소에는 새 keyinfo 요소와 그 하위 요소가 모두 포함됩니다. keyconrefs 정의의 keysubelementid 요소에 값을 지정하면 해당 ID를 가진 요소만 해당 정의를 사용하는 콘텐츠 키 참조에 사용할 수 있게 됩니다. 값을 지정하지 않으면 ID를 가진 모든 요소를 사용할 수 있습니다.
• keyforconrefs - 키 정의가 콘텐츠 키 참조용임을 나타냅니다.
이 요소는 keyinfo 요소에 포함됩니다. keyforconrefs 요소의 value 속성을 true(기본값)로 설정할 경우 이 요소는 이 키 정의가 콘텐츠 키 참조용임을 나타내며 해당 키 정의는 키 참조 삽입 대화 상자에서와 같이 처리됩니다. 따라서 keydef 및 맵의 다른 요소를 사용하여 콘텐츠 키 참조에 대한 키 정의를 정의할 수 있습니다.
DITA 키 정의 맵을 사용하면 콘텐츠 키 참조에 단일 요소를 사용하거나 ID를 포함하는 모든 요소를 사용하도록 콘텐츠 키 정의를 설정할 수 있습니다. 키 참조 삽입 대화 상자에서 conkeyref 참조에 대해 단일 요소를 사용하도록 하려면 다음 마크업을 사용하여 DITA 키 정의 맵에 이를 정의해야 합니다.
• 키 정의의 href 속성은 해당 요소를 포함하는 주제나 맵을 가리켜야 합니다.
요소의 ID는 href에 포함시키지 않습니다.
• keysubelementid 요소의 value 속성은 해당 요소의 ID를 지정해야 합니다.
• keyreftags 요소의 value 속성은 지정된 ID를 갖는 요소의 이름을 포함해야 하며 요소 이름 앞에 conkeyref: 문자열이 와야 합니다.
예를 들어 다음 키 정의는 strings.dita 주제에 custom이라는 ID를 갖는 ph 요소를 키 참조 삽입 대화 상자에 conkeyref 대상으로 추가합니다.
<keydef keys=”strings” href=”strings.dita”>
<topicmeta>
<keyinfo>
<keydescription>Description of the “custom” element</keydescription>
<keysubelementid value=”custom”/>
<keyreftags value=”conkeyref:ph”/>
</keyinfo>
</topicmeta>
</keydef>
키 참조 삽입 대화 상자의 conkeyref 참조에 대해 ID를 갖는 모든 요소를 맵이나 주제에서 사용할 수 있도록 하려면 역시 DITA 키 정의 맵에 이를 정의해야 합니다. 이 마크업은 다음 방법 중 하나를 사용하여 정의할 수 있습니다.
• keyconrefs 요소를 사용하여 키 정의를 만듭니다.
예를 들면 다음과 같습니다.
<keyconrefs href=”strings.dita” keys=”strings”/>
• topicmeta 요소의 keyinfo 요소 내에 keyforconrefs 요소를 사용하여 키 정의를 정의하는 데 사용할 수 있는 요소를 사용합니다.
예를 들면 다음과 같습니다.
<keydef href=”strings.dita” keys=”strings”>
<topicmeta>
<keyinfo>
<keyforconrefs/>
</keyinfo>
</topicmeta>
</keydef>
키 참조를 포함하여 텍스트 삽입
일반 키 참조를 사용하여 문서에 텍스트를 삽입할 수도 있습니다. 여러 DITA 요소에는 Keyref 속성이 있습니다. 요소가 비어 있고 키 참조 세트가 있는 경우 키 정의에 텍스트를 포함하여 이러한 요소를 삽입할 수 있습니다. 텍스트 삽입에 사용하려면 요소가 비어 있어야 합니다. 예를 들어 문서에 다음 요소가 있을 수 있습니다.
<ph keyref="product-name"></ph>
키는 다음 키 정의를 참조합니다.
<keydef keys="product-name">
<topicmeta>
<keywords>
<keyword>Acme Product</keyword>
</keywords>
</topicmeta>
</keydef>
문서를 게시할 때 ph 요소에 다음 텍스트가 삽입됩니다.
<ph>Acme Product</ph>
삽입할 텍스트와 함께 마크업을 포함할 수도 있습니다. 예를 들어, 키가 다음 키 정의를 참조하는 경우
<keydef keys="product-name">
<topicmeta>
<keywords>
<keyword><i>Acme Product</i></keyword>
</keywords>
</topicmeta>
</keydef>
다음 텍스트가 문서에 삽입됩니다.
<ph><i>Acme Product</i></ph>
텍스트 삽입 외에도 키 정의에 href 속성을 포함하여 비연결 요소를 연결 요소로 바꾸거나, 반대로 연결 요소를 비연결 요소로 바꿀 수도 있습니다. 예를 들어, 다음 키 정의를 생각해 보십시오.
<keydef keys="product-name" href="acme.dita">
<topicmeta>
<keywords>
<keyword>Acme Product</keyword>
</keywords>
</topicmeta>
</keydef>
<keydef keys="product-name-no-link">
<topicmeta>
<keywords>
<keyword>Acme Product</keyword>
</keywords>
</topicmeta>
</keydef>
이러한 키 정의는 문서의 다음 요소에서 참조됩니다.
문서가 게시되면 문서에 다음 텍스트가 삽입됩니다.
키 정의에 href가 지정된 경우 이러한 텍스트가 삽입된 요소가 연결 요소가 됩니다. href가 지정되지 않은 경우에는 xref와 같은 연결 요소도 링크를 포함하지 않습니다. 이 연결 동작은 키 정의를 참조하는 요소에 콘텐츠가 포함된 경우에도 적용되며 텍스트 삽입에는 사용할 수 없습니다. 예를 들어, 다음 요소가 위의 키 정의를 참조하는 경우를 생각해 보십시오.
<ph keyref="product-name">New Acme Product</ph>
이때, 키 참조는 문서를 게시할 때 요소를 연결 요소로 만들기만 할 뿐, 키 정의에 텍스트를 삽입하지 않습니다.
<ph>
<xref href="acme.dita">New Acme Product</xref>
</ph>
키 정의에서 삽입할 텍스트는 다음 우선 순위 순서에 따라 결정됩니다.
1. 키 정의의 topicmeta 요소에 있는 keywords 요소의 첫 번째 keyword 요소의 콘텐츠
2. 키 정의의 topicmeta 요소에 있는 keywords 요소의 첫 번째 term 요소의 콘텐츠
3. 키 정의의 topicmeta 요소에 있는 linktext 요소의 콘텐츠
4. 키 정의의 topicmeta 요소에 있는 navtitle 요소의 콘텐츠
5. 키 정의의 navtitle 속성의 콘텐츠
예를 들어, 다음 키 정의의 영역 둘 이상에 텍스트가 포함된 경우(가능한 경우)
<keydef keys="product-name" navtitle="New Acme Product">
<topicmeta>
<keywords>
<keyword>Acme Product</keyword>
</keywords>
</topicmeta>
</keydef>
이때, 키 참조용으로 삽입되는 텍스트는 keyword 요소의 콘텐츠입니다. 이 요소는 navtitle 속성의 콘텐츠보다 우선 순위가 높기 때문입니다.
다음 요소는 특수한 텍스트 삽입 케이스입니다.
• link
link 요소는 텍스트를 직접 포함하지 않고, 텍스트를 포함할 수 있는 linktext 및 desc 요소(선택사항)를 포함합니다. 이때, 키 정의의 topicmeta 요소에 linktext 및 desc 요소가 포함되어 있으면 문서를 게시할 때 해당 요소가 link 요소에 삽입됩니다.
• image
image 요소에 이미지의 텍스트 설명을 제공하는 alt 요소가 포함되어 있습니다. 빈 image 요소에 키 정의(텍스트 삽입에 사용할 텍스트를 포함하고 있음)에 대한 키 참조가 있으면 문서 게시 중에 해당 텍스트가 image에 alt 요소로 삽입됩니다.
• 텍스트 내용을 허용하지 않는 요소
longdescref와 같은 일부 DITA 요소에는 keyref 속성이 포함되지만 텍스트 내용은 허용되지 않습니다. 이러한 요소는 키 참조를 통한 텍스트 삽입에 사용할 수 없습니다.
Arbortext Editor 사용자 인터페이스(UI)에서는 키 참조를 통한 텍스트 삽입을 지원하기 위해 다음 기능을 제공합니다.
• 키 참조 정보 대화 상자에서는 키 정의에 제공된 텍스트 내용(마크업 포함)을 표시하는
텍스트 옵션을 제공합니다.
• 키 참조 삽입 대화 상자의
리소스 열에는 키 정의용 텍스트 내용(마크업 포함)이 표시됩니다.
또한 ditatextkeyrefs 고급 기본 설정을 on으로 설정하면 키 참조를 허용하는 비연결 요소가 삽입 드롭다운 목록에 표시됩니다.
• DITA 문서 편집 시, 키 참조가 지정된 빈 요소는 괄호 안에 키 참조 이름을 표시합니다.
이것은 DITA 문서의 기본 스타일시트에 있는 비연결 요소에 대해서만 지원됩니다. 키 참조 이름은 Arbortext Editor에서 문서를 편집할 때만 나타납니다. 문서를 게시할 때는 나타나지 않습니다.
키 참조와 주제 참조 함께 사용
주제 참조에 키 참조가 포함된 경우 topicmeta 요소의 일부 정보가 키 정의에 있는 유사 정보와 충돌할 수 있습니다. 키 정의와 마찬가지로 topicref 요소에 topicmeta 요소가 포함됩니다. 키 참조가 있는 topicref의 topicmeta 콘텐츠를 참조된 키 정의와 병합할 때 다음 규칙을 따릅니다.
• topicref 요소의 locktitle 속성은 키 정의의 locktitle 속성보다 우선 적용됩니다.
• 키 정의의 다른 메타데이터는 topicref 요소의 동일한 메타데이터를 무시합니다.
• 키 정의의 메타데이터와 일치하지 않는 topicref 요소의 메타데이터는 그대로 유지됩니다.
