Definizione degli argomenti della guida

Ora che si dispone dei file di contenuto di esempio, è possibile creare un file di argomenti. Un file di argomenti definisce i punti di immissione chiave nei file di contenuto HTML associando un id e un'etichetta di argomento a un riferimento in uno dei file HTML. Un file di argomenti agisce come una tabella di contenuti per un insieme di contenuto HTML.

Le applicazioni che vengono trasferite alla piattaforma possono riutilizzare la documentazione esistente utilizzando il file di argomenti per definire i punti di immissione all'interno di tale documentazione.

Un plug-in può avere uno o più file di argomenti. I file di argomenti vengono spesso definiti file di esplorazione, poiché descrivono le modalità di esplorazione del contenuto html. La documentazione di esempio è organizzata in tre categorie principali: concetti, attività e riferimento. Come si creano file di argomenti che rappresentano questa struttura?

È possibile creare un file di argomenti complessivo, oppure creare un file di argomenti separato per ciascuna categoria di contenuto principale. Questa decisione deve essere presa in base ai criteri adottati dai team della documentazione. Se ogni categoria viene controllata da un diverso autore, può essere preferibile mantenere i file di argomenti separati in categorie.  Questa impostazione non è dettata dall'architettura della piattaforma.

In questo esempio, verrà creato un file di argomenti per ogni categoria di contenuto principale. Per un numero ridotto di file non sarebbe necessario separare i file di argomenti per ciascuna categoria.  Nell'esempio ci si comporterà come se si disponesse di un numero maggiore di file e di autori separati che controllano ciascuna categoria di contenuto.

I file dovrebbero apparire nella forma seguente:

topics_Concepts.xml

<topics id="conceptsAll">

 <topic label="Concept1" href="doc/concepts/concept1.html">

     <topic label="Concept1_1" href="doc/concepts/concept1_1.html"/>

     <topic label="Concept1_2" href="doc/concepts/concept1_2.html"/>

 </topic> 
</topics>

topics_Tasks.xml

<topics id="tasksAll">

 <topic id="plainTasks" label="Plain Stuff">

 <topic label="Task1" href="doc/tasks/task1.html"/>

 <topic label="Task2" href="doc/tasks/task2.html"/>

 </topic> <topic id="funTasks" label="Fun Stuff" >

     <topic label="Task3_1" href="doc/tasks/task3_1.html"/>

     <topic label="Task3_2" href="doc/tasks/task3_2.html"/>

 </topic>

</topics>

topics_Ref.xml

<topics id="refAll">

 <topic label="Ref1" href="doc/ref/ref1.html"/>

 <topic label="Ref2" href="doc/ref/ref2.html"/>

</topics>

Gli argomenti vengono forniti come parte dell'elemento contenitore degli argomenti. Un argomento può essere un semplice collegamento al contenuto.  Ad esempio, "Task1" fornisce un collegamento mediante label e href al contenuto.  Un argomento può anche essere un raggruppamento gerarchico di sottoargomenti senza alcun contenuto proprio.  Ad esempio, "Fun Stuff" presenta solo un label e dei sottoargomenti, ma nessun href.  Gli argomenti possono anche comportarsi in entrambi i modi.  "Concept1" presenta un href e sottoargomenti.

Quando è utilizzato come un collegamento, l'argomento in un href viene interpretato come relativo al plug-in corrente. 

Quando si inizia a collegare questi argomenti nel web della documentazione generale, si farà riferimento ad essi attraverso i rispettivi id. Solo gli argomenti che dispongono di un id possono essere gestiti. Per collegare tutti i sottoargomenti di un particolare argomento, è possibile effettuare il collegamento dell'argomento principale.  Ad esempio, il collegamento di "Concept1" determinerà anche il collegamento di "Concept1_1" e "Concept1_2."   

Successivamente, plugin.xml verrà modificato per aggiungere gli effettivi contributi che puntano a questi file.