Arbortext Editor fornisce il supporto per i riferimenti basati su chiave definiti nella sezione Key based (indirect) addressing della specifica DITA Architectural Specification di OASIS. L'interfaccia utente di Arbortext Editor fornisce numerose funzionalità che consentono di semplificare la definizione delle definizioni chiave nelle mappe DITA e l'inserimento dei riferimenti chiave nelle mappe e negli argomenti. Inoltre, Arbortext Editor fornisce una mappa DITA specializzata progettata per contenere solo le definizioni chiave, denominata Mappa di definizioni chiave DITA. Questa mappa consente di fornire informazioni aggiuntive per le definizioni chiave.

Il metodo migliore per archiviare le definizioni chiave consiste nel configurare una mappa DITA da utilizzare esclusivamente per la memorizzazione delle definizioni chiave. È possibile quindi utilizzare un elemento mapref per includere la mappa contenente le definizioni chiave in qualsiasi altra mappa DITA, in base alle esigenze. È consigliabile utilizzare la mappa di definizioni chiave DITA per archiviare le definizioni chiave.

I riferimenti chiave sono supportati dalle sezioni dell'interfaccia utente di Arbortext Editor descritte di seguito.

Per default, l'interfaccia utente per i riferimenti chiave è disponibile in Arbortext Editor. Se non si utilizzano i riferimenti chiave presenti nella documentazione DITA, è possibile rimuovere le funzioni dei riferimenti chiave dall'interfaccia utente.

La disponibilità dell'interfaccia utente per i riferimenti chiave è determinata dalla preferenza avanzata ditakeyrefui. Per rimuovere l'interfaccia utente per i riferimenti chiave, impostare il valore di questa preferenza su off.

Per configurare Arbortext Editor per la ricerca delle definizioni chiave associate ai riferimenti chiave, è necessario che l'applicazione sia in grado di riconoscere il contesto chiave per il documento corrente. Il contesto chiave è una mappa DITA che contiene le definizioni chiave rilevanti. Se la mappa contenente le definizioni è una mappa di definizioni chiave DITA, è possibile aggiungere ulteriori informazioni alle definizioni chiave visualizzate nell'interfaccia utente per i riferimenti chiave. Il contesto chiave per un documento è determinato dalle impostazioni dell'opzione ditakeycontext.

L'opzione ditakeycontext è impostata su una singola mappa e definisce il contesto chiave principale per il documento corrente durante la sessione corrente. Quando per un documento viene stabilito un contesto chiave, quest'ultimo influenza la modalità di gestione dei riferimenti in Arbortext Editor. Se, ad esempio, per un tag immagine è definito sia un attributo href che un attributo keyref, in Arbortext Editor viene visualizzata l'immagine della definizione chiave dell'attributo keyref. Quando viene stabilito un contesto chiave che contiene una definizione chiave corrispondente, in Arbortext Editor viene data la precedenza a un riferimento chiave o a un riferimento chiave a contenuto.

È possibile impostare ditakeycontext in modo esplicito o, in alcuni casi, questo comando viene impostato automaticamente da Arbortext Editor. Se, ad esempio, si apre un documento facendo doppio clic su un riferimento incrociato, un riferimento ad argomento e così via, il contesto chiave per il documento originale viene applicato al documento appena aperto. Analogamente, se si apre un documento da una finestra di dialogo relativa a DITA di Arbortext Editor, il contesto chiave per il documento corrente viene applicato al documento aperto. Se il documento originale è una mappa DITA a cui non è associato alcun contesto chiave, la mappa diventa il contesto chiave per il documento aperto.

Un'altra opzione che determina le definizioni chiave disponibili per l'inserimento in un documento è rappresentata dall'opzione ditakeybaselist. L'opzione ditakeybaselist viene utilizzata principalmente per stabilire l'elenco delle mappe utilizzate per le definizioni chiave visualizzate nella finestra di dialogo Inserisci riferimento chiave e nell'opzione Riferimento chiave di Gestione risorse DITA. A differenza di ditakeycontext, il comando ditakeybaselist è una preferenza avanzata, può contenere più mappe ed è persistente nelle sessioni di Arbortext Editor. Se si è assegnato un valore a ditakeybaselist e la mappa impostata come ditakeycontext corrente non si trova nell'elenco, la mappa contesto chiave vene aggiunta all'inizio dell'elenco delle mappe ditakeybaselist per la sessione corrente.

Arbortext Editor fornisce una mappa DITA specializzata denominata mappa di definizioni chiave DITA. Questa mappa contiene elementi aggiuntivi che consentono di fornire ulteriori informazioni nelle definizioni chiave ed è progettata per essere utilizzata esclusivamente per l'archiviazione delle definizioni chiave. Le informazioni sulle definizioni chiave aggiuntive vengono visualizzate nell'interfaccia utente per i riferimenti chiave in diverse posizioni. La mappa di definizioni chiave DITA si trova nella categoria DITA Technical Content della finestra di dialogo Nuovo.

La mappa di definizioni chiave aggiunge ulteriori elementi all'elemento topicmeta che forniscono informazioni aggiuntive sulle definizioni chiave. Per utilizzare questi elementi, inserire un elemento keydef nella mappa, un elemento topicmeta nell'elemento keydef e un elemento keyinfo in topicmeta. È possibile quindi inserire uno dei nuovi elementi metadati che si desidera utilizzare all'interno di keyinfo. È inoltre possibile utilizzare la scheda Definizione chiave di Gestione risorse DITA in una mappa di definizioni chiave per aggiungere ulteriori informazioni alle definizioni chiave.

Per i normali riferimenti chiave, in topicmeta sono disponibili gli elementi aggiuntivi decritti di seguito.

Per sostituire il contenuto tramite un riferimento chiave in Arbortext Editor, è possibile utilizzare l'attributo conkeyref in un elemento per impostare un riferimento chiave a contenuto. Analogamente ai normali riferimenti chiave, quando a un riferimento chiave a contenuto è associata una definizione nel contesto chiave per un documento e per un elemento sono definiti sia l'attributo conref che l'attributo conkeyref, in Arbortext Editor viene visualizzato il contenuto associato a conkeyref e in genere viene data la precedenza al riferimento a contenuto chiave.

Per impostare le chiavi per i riferimenti chiave a contenuto, è possibile utilizzare una normale definizione chiave. Tuttavia, la mappa di definizioni chiave DITA fornisce alcuni elementi aggiuntivi che consentono di semplificare la definizione delle definizioni chiave per i riferimenti a contenuto. Inoltre, per includere i riferimenti chiave a contenuto nella finestra di dialogo Inserisci riferimento chiave, è necessario definire le definizioni chiave associate in una mappa di definizioni chiave DITA. Per i riferimenti chiave a contenuto, sono disponibili gli elementi aggiuntivi descritti di seguito.

Utilizzando una mappa di definizioni chiave DITA, è possibile impostare le definizioni chiave del contenuto in modo che sia disponibile un singolo elemento per un riferimento chiave a contenuto o siano disponibili tutti gli elementi con ID. Per rendere disponibile un singolo elemento per un riferimento conkeyref nella finestra di dialogo Inserisci riferimento chiave, è necessario definirlo in una mappa di definizioni chiave DITA utilizzando il markup descritto di seguito.

Ad esempio, la definizione chiave riportata di seguito aggiunge l'elemento ph con l'ID custom nell'argomento strings.dita alla finestra di dialogo Inserisci riferimento chiave come destinazione conkeyref.

Per rendere disponibili tutti gli elementi con ID in una mappa o un argomento per un riferimento conkeyref nella finestra di dialogo Inserisci riferimento chiave, è necessario definire tale impostazione anche in una mappa di definizioni chiave DITA. È possibile definire tale markup in uno dei modi descritti di seguito.

È possibile anche utilizzare normali riferimenti chiave per inserire il testo nei documenti. Molti elementi DITA presentano l'attributo keyref. È possibile includere il testo nelle definizioni chiave da inserire in questi elementi se l'elemento è vuoto e presenta un insieme di riferimenti chiave. Affinché possa essere utilizzato per l'inserimento del testo, l'elemento deve essere vuoto. Ad esempio, è possibile che il documento contenga il seguente elemento:

La chiave fa riferimento alla seguente definizione chiave:

Durante la pubblicazione del documento, il seguente testo viene inserito nell'elemento ph:

È possibile inoltre includere markup con il testo da inserire. Ad esempio, quando la chiave fa riferimento alla seguente definizione chiave:

Il seguente testo viene inserito nel documento:

In aggiunta all'inserimento del testo, è possibile anche trasformare elementi non di collegamento in elementi di collegamento e viceversa includendo un attributo href nella definizione chiave. Ad esempio, si considerino le seguenti definizioni chiave:

A queste definizioni chiave fanno riferimento i seguenti elementi presenti nel documento:

Durante la pubblicazione del documento, il seguente testo viene inserito nel documento:

Quando alla definizione chiave è stato assegnato un attributo href, l'elemento nel quale viene inserito il testo diventa un elemento di collegamento. Quando non gli è stato assegnato un attributo href, anche un elemento di collegamento come xref non contiene un link. Questo comportamento di creazione di link si applica anche se l'elemento che fa riferimento alla definizione chiave presenta del contenuto e non può essere utilizzato per l'inserimento del testo. Ad esempio, si consideri l'ipotesi in cui il seguente elemento fa riferimento alla definizione chiave precedente:

In questo caso, il riferimento chiave rende semplicemente l'elemento un elemento di collegamento e non inserisce il testo nella definizione chiave quando il documento viene pubblicato:

Il testo da inserire da una definizione chiave è determinato nel seguente ordine di priorità:

Ad esempio, la seguente definizione chiave contiene del testo in più di una delle possibili aree per l'inserimento del testo:

In questo caso, il testo inserito per un riferimento chiave è il contenuto dell'elemento keyword dal momento che ha una priorità più alta rispetto al contenuto dell'attributo navtitle.

I seguenti elementi sono casi particolari per l'inserimento del testo:

L'interfaccia utente dell'Arbortext Editor fornisce le funzionalità descritte di seguito per supportare l'inserimento del testo con riferimenti chiave.

Quando un riferimento ad argomento contiene un riferimento chiave, alcune informazioni nell'elemento topicmeta possono essere in conflitto con informazioni simili nella definizione chiave. L'elemento topicref contiene un elemento topicmeta analogamente a quanto avviene per una definizione chiave. Di seguito vengono riportate le regole che devono essere rispettate durante l'unione del contenuto topicmeta di un topicref con un riferimento chiave e la definizione chiave a cui si fa riferimento.