Uso de claves y referencias de clave
Arbortext Editor proporciona soporte completo para referencias basadas en claves definidas en la sección Key based (indirect) addressing de DITA Architectural Specification de OASIS. La interfaz de usuario de Arbortext Editor proporciona varias funciones que ayudan tanto en la definición de definiciones de clave en los mapas DITA como en la inserción de referencias de claves en los mapas y temas. Además, Arbortext Editor proporciona un mapa DITA especializado destinado a contener simplemente definiciones de clave, denominado el mapa de definiciones de clave DITA. Este mapa permite proporcionar información adicional para las definiciones de clave.
Para almacenar las definiciones de claves, se recomienda tener un mapa DITA dedicado exclusivamente a contener definiciones de clave. A continuación, se puede usar un elemento mapref para incluir el mapa que contiene las definiciones de clave en cualquier otro mapa DITA, según sea necesario. Se sugiere el uso del mapa de definiciones de clave DITA para almacenar las definiciones de claves.
Interfaz de usuario de referencias de claves
Las siguientes partes de la interfaz de usuario de Arbortext Editor soportan referencias de claves:
• En el menú Insertar se incluyen las opciones siguientes:
◦ Definición de clave: permite abrir el Administrador de recursos con la ficha Definición de clave activa.
◦ Referencia de clave: permite abrir el cuadro de diálogo Insertar referencia de clave.
• En el menú Herramientas se incluyen las opciones siguientes:
◦ Claves y referencias de clave: permite abrir el cuadro de diálogo Claves y referencias de clave.
◦ Buscar referencias de clave: permite abrir el cuadro de diálogo Claves y referencias de clave en el que se muestran solo las claves incluidas en la etiqueta que contiene el cursor.
Esta opción también está disponible en el menú de accesos directos de Arbortext Editor.
◦ Información de referencia de clave: permite abrir el cuadro de diálogo Información de referencia de clave.
Esta opción también está disponible en el menú de accesos directos de Arbortext Editor.
• La barra de herramientas Marcador tiene un botón Insertar referencia de clave 
que permite abrir el cuadro de diálogo Insertar referencia de clave.
que permite abrir el cuadro de diálogo Insertar referencia de clave.• Las siguientes características del Administrador de recursos soportan referencias de claves:
◦ La ficha Definición de clave se encuentra disponible en los mapas DITA para ayudar a definir definiciones de clave.
Hay una versión de esta ficha para modificar las definiciones clave disponibles en el cuadro de diálogo Modificar atributos, el mapa del documento y la vista en columnas.
◦ La opción Referencia de clave se encuentra disponible en todas las fichas y los cuadros de diálogo del Administrador de recursos, excepto los de referencias de contenido, que permite introducir un nombre de clave para insertar en el atributo keyref de la referencia que se está creando o modificando.
◦ La opción Conkeyref se encuentra disponible en la ficha y el cuadro de diálogo del Administrador de recursos para las referencias de contenido que permite introducir un nombre de clave para insertar en el atributo conkeyref para la referencia que se esté creando o modificando.
◦ Las fichas y los cuadros de diálogo Vínculo/Referencia cruzada, Referencia de contenido y Tema permiten inspeccionar los mapas DITA que contienen definiciones de clave y usar una definición de clave seleccionada para la referencia insertada o modificada.
• Los siguientes cuadros de diálogo soportan las referencias de claves:
◦ Insertar referencia de clave: permite insertar referencias de claves en un documento.
◦ Añadir/Quitar mapa: permite añadir o quitar mapas de la lista de mapas que proporcionan definiciones de clave para el cuadro de diálogo Insertar referencia de clave.
◦ Seleccionar referencia: permite seleccionar el documento que se debe abrir cuando un elemento de referencia tiene más de un destino de referencia definido.
◦ Información de referencia de clave: permite mostrar la información acerca de la definición de clave asociada con una referencia de clave.
◦ Claves y referencias de clave: permite mostrar las definiciones de clave y las referencias de claves incluidas en el documento actual y en cualquiera de los documentos a los que se hace referencia desde el documento actual.
Ocultar la interfaz de usuario de referencia de clave
Por defecto, la interfaz de usuario de referencia de clave está disponible en Arbortext Editor. Si no se usan referencias de clave en la documentación de DITA, se pueden quitar las funciones de referencia de clave de la interfaz de usuario.
La preferencia avanzada ditakeyrefui permite controlar si la interfaz de usuario de referencia de clave está disponible o no. Defina el valor de esta preferencia en off para quitar la interfaz de usuario de referencia de clave.
Establecimiento del contexto de clave
Para que Arbortext Editor encuentre las definiciones de clave asociadas a las referencias de clave, debe conocer el contexto de clave del documento actual. El contexto de clave es un mapa DITA que contiene las definiciones de clave relevantes. Si el mapa que contiene las definiciones es un mapa de definiciones de clave DITA, se puede añadir información adicional a las definiciones de clave que aparecen en la interfaz de usuario de referencia de clave. El contexto de clave para un documento se determina mediante la configuración de la opción definida ditakeycontext.
La opción ditakeycontext se configura en un mapa sencillo y permite definir el contexto de clave principal para el documento actual durante la sesión actual. Cuando un documento tiene establecido un contexto de clave, esto afecta a cómo Arbortext Editor gestiona las referencias. Por ejemplo, si una etiqueta de imagen tiene definidos tanto un atributo href como un atributo keyref, Arbortext Editor muestra la imagen desde la definición de clave del atributo keyref. Arbortext Editor proporciona una referencia de clave o prioridad de referencia de clave de contenido cuando hay un contexto de clave establecido que contiene una definición de clave coincidente.
ditakeycontext se puede definir explícitamente, aunque Arbortext Editor lo define automáticamente en ciertos casos. Por ejemplo, si se abre un documento al pulsar dos veces en una referencia cruzada, referencia de tema, etc., el contexto de clave para el documento original se aplica al documento recién abierto. De manera similar, cuando se abre un documento desde un cuadro de diálogo de Arbortext Editor relacionado con DITA, se aplica el contexto de clave del documento actual al documento abierto. Si el documento original es un mapa DITA que no tiene un contexto de clave, dicho mapa se convierte en el contexto de clave para el documento abierto.
Otra opción que permite determinar las definiciones de clave disponibles para su inserción en un documento es la opción definida ditakeybaselist. La opción ditakeybaselist se usa principalmente para establecer la lista de mapas usados para las definiciones de clave mostradas en el cuadro de diálogo Insertar referencia de clave y en la opción Referencia de clave del Administrador de recursos. A diferencia de ditakeycontext, ditakeybaselist es una preferencia avanzada, puede contener varios mapas y persiste a través de las sesiones de Arbortext Editor. Si se ha asignado un valor a ditakeybaselist y el mapa que es el ditakeycontext actual no se encuentra en dicha lista, el mapa de contexto de clave se añade al principio de la lista de mapas ditakeybaselist para la sesión actual.
Uso del mapa de definiciones de clave DITA
Arbortext Editor proporciona un mapa DITA especializado denominado el mapa de definiciones de clave DITA. Este mapa contiene elementos adicionales que permiten proporcionar más información en las definiciones de claves y está destinado a su uso exclusivo para almacenar definiciones de clave. La información de definición de clave adicional se muestra en la interfaz de usuario de referencia de clave en diverso lugares. El mapa de definiciones de clave DITA se encuentra en las categorías DITA Technical Content del cuadro de diálogo Nuevo.
El mapa de definiciones de clave permite añadir elementos adicionales al elemento topicmeta que proporciona más información acerca de las definiciones de clave. Para usar estos elementos, es necesario insertar un elemento keydef en el mapa, un elemento topicmeta en el elemento keydef y un elemento keyinfo en topicmeta. A continuación, se puede insertar cualquiera de los nuevos elementos de metadatos que se deban usar dentro de keyinfo. También se puede usar la ficha Definición de clave del Administrador de recursos en un mapa de definiciones de clave para añadir esta información adicional a las definiciones de clave.
En topicmeta están disponibles los siguientes elementos adicionales para referencias de claves normales:
• keyinfo: permite encerrar los demás elementos, excepto el elemento keytext.
• keydescription: permite incluir una descripción de texto de la clave.
• keysubelementid: permite especificar (en el atributo value) un ID de elemento específica a la que debe aplicarse esta clave.
• keyreftags: permite incluir (en el atributo value) una lista de uno o varios nombres de elementos que deben usarse para hacer referencia a esta clave.
• keytext: permite especificar el texto variable o de vínculo; también especifica texto alternativo para las imágenes a las que hacen referencia las claves. Este elemento solo está disponible para los documentos DITA 2.0.
Uso de referencias de clave de contenido
Para reemplazar el contenido a través de una referencia de clave en Arbortext Editor, se puede usar el atributo conkeyref en un elemento para configurar una referencia de clave de contenido. Al igual que sucede con las referencias de claves normales, cuando una referencia de clave de contenido tiene una definición asociada en el contexto de clave para un documento y un elemento tiene definido tanto el atributo conref como el atributo conkeyref, Arbortext Editor muestra el contenido asociado con conkeyref y proporciona generalmente la prioridad de referencia de contenido de clave.
Se puede usar una definición de clave normal para configurar las claves para referencias de claves de contenido. No obstante, en el mapa de definiciones de clave DITA se proporcionan algunos elementos adicionales para ayudar en las definiciones de clave para referencias de contenido. Además, para incluir referencias de clave de contenido en el cuadro de diálogo Insertar referencia de clave, es necesario definir las definiciones de clave asociadas en un mapa de definiciones de clave DITA. Están disponibles los siguientes elementos adicionales para referencias de claves de contenido:
• keyconrefs: permite definir definiciones de clave específicamente para referencias de clave de contenido.
El elemento es una especialización del elemento keydef. Los elementos con ID dentro de temas o mapas que hacen referencia a un nombre de clave definido con keyconrefs se muestran como destinos para una referencia conkeyref en el cuadro de diálogo Insertar referencia de clave. El atributo scope de este elemento está definido en local. El atributo format está definido en dita (el valor por defecto) o bien en ditamap.
En el elemento también se incluyen el nuevo elemento keyinfo y todos sus subelementos. Si se asigna un valor al elemento keysubelementid en una definición keyconrefs, solo estarán disponibles los elementos con ID específicas para una referencia de clave de contenido que use dicha definición. En caso contrario, estarán disponibles todos los elementos con ID
• keyforconrefs: permite indicar que una definición de clave es para una referencia de clave de contenido.
Este elemento se incluye en el elemento keyinfo. Cuando el atributo value del elemento keyforconrefs se define en true (el valor por defecto), indica que esta definición de clave es para una referencia de clave de contenido y se tratará como tal en el cuadro de diálogo Insertar referencia de clave. Esto permitirá usar keydef y otros elementos en el mapa para definir definiciones de clave para referencias de clave de contenido.
Mediante un mapa de definiciones de clave DITA, se pueden configurar las definiciones de clave de contenido de modo que solo esté disponible un único elemento para una referencia de clave de contenido o bien estén disponibles todos los elementos con ID Para que un único elemento esté disponible para una referencia conkeyref en el cuadro de diálogo Insertar referencia de clave, es necesario definirlo en el mapa de definiciones de clave DITA mediante el siguiente marcador:
• El atributo href de la definición de clave debe señalar el tema o mapa que contiene el elemento.
El ID del elemento no debe estar incluida en href.
• El atributo value del elemento keysubelementid debe especificar el ID del elemento.
• El atributo value del elemento keyreftags debe contener el nombre del elemento que tiene el ID especificada, con el prefijo de la cadena conkeyref:.
Por ejemplo, la siguiente definición de clave añade el elemento ph con el ID custom en el tema strings.dita al cuadro de diálogo Insertar referencia de clave como destino de 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>
<topicmeta>
<keyinfo>
<keydescription>Description of the “custom” element</keydescription>
<keysubelementid value=”custom”/>
<keyreftags value=”conkeyref:ph”/>
</keyinfo>
</topicmeta>
</keydef>
Para que todos los elementos con ID estén disponibles en un mapa o tema para una referencia conkeyref en el cuadro de diálogo Insertar referencia de clave, es necesario definirlo en un mapa de definiciones de clave DITA. Este marcador puede definirse de una de las maneras siguientes:
• Usar el elemento keyconrefs para crear la definición de clave.
Por ejemplo:
<keyconrefs href=”strings.dita” keys=”strings”/>
• Usar cualquier elemento válido para definir una definición de clave con un elemento keyforconrefs dentro del elemento keyinfo en el elemento topicmeta.
Por ejemplo:
<keydef href=”strings.dita” keys=”strings”>
<topicmeta>
<keyinfo>
<keyforconrefs/>
</keyinfo>
</topicmeta>
</keydef>
<topicmeta>
<keyinfo>
<keyforconrefs/>
</keyinfo>
</topicmeta>
</keydef>
Inserción de texto con referencias de clave
También se pueden utilizar referencias de clave normales para insertar texto en los documentos. Muchos elementos DITA presentan el atributo keyref. Es posible incluir texto en las definiciones de clave para insertar en estos elementos, si el elemento está vacío y tiene un conjunto de referencias de clave. El elemento debe estar vacío para que se pueda usar para insertar texto. Por ejemplo, el documento podría contener el siguiente elemento:
<ph keyref="product-name"></ph>
La clave hace referencia a la siguiente definición de clave:
Para DITA 1.3 | Para DITA 2.0 |
|---|---|
<keydef keys="product-name"> <topicmeta> <keywords> <keyword>Acme Product</keyword> </keywords> </topicmeta> </keydef> | <keydef keys="product-name"> <topicmeta> <keytext>Acme Product</keytext> </topicmeta> </keydef> |
Al publicar el documento, se inserta el texto siguiente en el elemento ph:
<ph>Acme Product</ph>
También se puede incluir un marcador con el texto que se desea insertar. Por ejemplo, cuando la clave hace referencia a la definición de clave siguiente:
<keydef keys="product-name">
<topicmeta>
<keywords>
<keyword><i>Acme Product</i></keyword>
</keywords>
</topicmeta>
</keydef>
<topicmeta>
<keywords>
<keyword><i>Acme Product</i></keyword>
</keywords>
</topicmeta>
</keydef>
El texto siguiente se inserta en el documento:
<ph><i>Acme Product</i></ph>
Además de insertar texto, se pueden convertir los elementos sin vínculos en elementos con vínculos y viceversa, para lo cual se debe incluir el atributo href en la definición de clave. Por ejemplo, considere las siguientes definiciones de clave:
<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>
<topicmeta>
<keywords>
<keyword>Acme Product</keyword>
</keywords>
</topicmeta>
</keydef>
<keydef keys="product-name-no-link">
<topicmeta>
<keywords>
<keyword>Acme Product</keyword>
</keywords>
</topicmeta>
</keydef>
Los siguientes elementos del documento hacen referencia a estas definiciones de clave:
<ph keyref="product-name"></ph>
<xref keyref="product-name"></xref>
<ph keyref="product-name-no-link"></ph>
<xref keyref="product-name-no-link"></xref>
<xref keyref="product-name"></xref>
<ph keyref="product-name-no-link"></ph>
<xref keyref="product-name-no-link"></xref>
Cuando se publica el documento, se le inserta el texto siguiente:
<ph>
<xref href="acme.dita">Acme Product</xref>
</ph>
<xref href="acme.dita">Acme Product</xref>
<ph>Acme Product</ph>
<xref>Acme Product</xref>
<xref href="acme.dita">Acme Product</xref>
</ph>
<xref href="acme.dita">Acme Product</xref>
<ph>Acme Product</ph>
<xref>Acme Product</xref>
Tenga en cuenta que si la definición de clave tiene un atributo href asignado, el elemento en el que se ha insertado el texto se convierte en un elemento con vínculos. Si no tiene el atributo href asignado, no contendrá vínculos aunque se trate de un elemento con vínculos, como xref. Este comportamiento de definición de vínculos se aplica aunque el elemento que hace referencia a la definición de clave presente contenido y no se pueda utilizar para la inserción de texto. Por ejemplo, considere los casos en que el siguiente elemento hace referencia a la definición de clave anterior:
<ph keyref="product-name">New Acme Product</ph>
En este caso, la referencia de clave convierte el elemento en un elemento con vínculos y no inserta el texto en la definición de clave al publicar el documento:
<ph>
<xref href="acme.dita">New Acme Product</xref>
</ph>
<xref href="acme.dita">New Acme Product</xref>
</ph>
El texto que se debe insertar de una definición de clave está determinado por el siguiente orden de prioridad en caso de documentos DITA 1.3:
1. El contenido del primer elemento keyword del elemento keywords del elemento topicmeta de la definición de clave
2. El contenido del primer elemento term del elemento keywords del elemento topicmeta de la definición de clave
3. El contenido del elemento linktext del elemento topicmeta de la definición de clave
4. El contenido del elemento navtitle del elemento topicmeta de la definición de clave
5. El contenido del atributo navtitle de la definición de clave
Por ejemplo, la definición de clave siguiente contiene texto en más de una de las posibles áreas de inserción de texto:
<keydef keys="product-name" navtitle="New Acme Product">
<topicmeta>
<keywords>
<keyword>Acme Product</keyword>
</keywords>
</topicmeta>
</keydef>
<topicmeta>
<keywords>
<keyword>Acme Product</keyword>
</keywords>
</topicmeta>
</keydef>
El texto que se debe insertar de una definición de clave está determinado por el siguiente orden de prioridad en caso de documentos DITA 2.0:
1. El contenido del primer elemento keytext del elemento topicmeta de la definición de clave
2. El contenido del primer elemento titlealt con el valor de atributo título-rol definido como 'linking' o el primer elemento linktext del elemento topicmeta de la definición de clave
3. El contenido del primer elemento titlealt con el valor de atributo título-rol definido como 'navigation' o el primer elemento navtitle del elemento topicmeta de la definición de clave
Por ejemplo, la definición de clave siguiente contiene texto en más de una de las posibles áreas de inserción de texto:
<keydef keys="product-name">
<topicmeta>
<keytext>Acme Product</keytext>
<navtitle>New Acme Product</navtitle>
</topicmeta>
</keydef>
<topicmeta>
<keytext>Acme Product</keytext>
<navtitle>New Acme Product</navtitle>
</topicmeta>
</keydef>
En este caso, el texto insertado para una referencia de clave es el contenido del elemento keytext, dado que tiene mayor prioridad que el contenido del elemento navtitle.
Los siguientes elementos son casos especiales para la inserción de texto:
• link
El elemento link no contiene texto directamente. Incluye los elementos opcionales linktext y desc que pueden contener texto. En este caso, si se tienen los elementos linktext y desc en el elemento topicmeta de la definición de clave, dichos elementos se insertarán en el elemento link cuando se publique el documento.
• image
El elemento image contiene un elemento alt que proporciona una descripción textual de la imagen. Si un elemento image vacío presenta una referencia de clave a una definición de clave que contiene texto para insertar, el texto se insertará en la image como un elemento alt durante la publicación.
• Elementos que no permiten contenido de texto
Algunos elementos DITA, como longdescref, contienen el atributo keyref pero no admiten contenido de texto. Estos elementos no se pueden utilizar para la inserción de texto a través de referencias de clave.
La interfaz de usuario de Arbortext Editor proporciona las siguientes funciones para admitir la inserción de texto con referencias de clave:
• El cuadro de diálogo Información de referencia de clave presenta la opción Texto, que permite visualizar el contenido del texto, incluidos los marcadores, de la definición de clave.
• El cuadro de diálogo Insertar referencia de clave muestra el contenido del texto de una definición de clave, incluidos los marcadores, en la columna Recurso.
Asimismo, si la preferencia avanzada ditatextkeyrefs está definida en on, los elementos sin vínculos que permitan una referencia de clave se mostrarán en la lista desplegable Insertar.
• Los elementos vacíos con una referencia de clave asignada muestran el nombre de la referencia de clave entre paréntesis cuando se edita un documento DITA:
Tenga en cuenta que solo se soporta para elementos sin vínculos en las hojas de estilo por defecto de los documentos DITA. El nombre de la referencia de clave solo aparece cuando se editan documentos en Arbortext Editor. No aparece cuando se publica el documento.