File di sommario (toc)

Ora che si dispone dei file di contenuto di esempio, è possibile creare un file di sommario (toc). Un file toc definisce i punti di immissione chiave nei file di contenuto HTML associando un'etichetta di argomento a un riferimento in uno dei file HTML. 

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

Un plugin può avere uno o più file toc. La documentazione di esempio è organizzata in tre categorie principali: concetti, attività e riferimento. Come si creano file toc che rappresentano questa struttura?

È possibile creare un file toc complessivo, oppure creare un file toc 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 toc separati in categorie.  Questa impostazione non è dettata dall'architettura della piattaforma.

In questo esempio, verrà creato un file toc per ogni categoria di contenuto principale. Per un numero ridotto di file non sarebbe necessario separare i file toc 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:

toc_Concepts.xml

   <toc label="Concepts">
      <topic label="Concept1" href="html/concepts/concept1.html">
         <topic label="Concept1_1" href="html/concepts/concept1_1.html"/>
         <topic label="Concept1_2" href="html/concepts/concept1_2.html"/>
      </topic> 
   </toc>

toc_Tasks.xml

   <toc label="Tasks">
      <topic id="plainTasks" label="Plain Stuff">
         <topic label="Task1" href="html/tasks/task1.html"/>
         <topic label="Task2" href="html/tasks/task2.html"/>
      </topic>
      <topic id="funTasks" label="Fun Stuff" >
         <topic label="Task3_1" href="html/tasks/task3_1.html"/>
         <topic label="Task3_2" href="html/tasks/task3_2.html"/>
      </topic>
   </toc>

toc_Ref.xml

   <toc label="Reference">
      <topic label="Ref1" href="html/ref/ref1.html"/>
      <topic label="Ref2" href="html/ref/ref2.html"/>
   </toc>

Un argomento può essere un semplice collegamento al contenuto.  Ad esempio, "Task1" fornisce un collegamento mediante label e href al contenuto.  Un argomento può essere anche un raggruppamento gerarchico di argomenti secondari privo di contenuto proprio.  Ad esempio, "Fun Stuff" presenta solo un label e argomenti secondari, senza href .  Gli argomenti possono comportarsi anche in entrambi i modi.  "Concept1" presenta un href e argomenti secondari.