Tabla de contenido (TOC)

org.eclipse.help.toc

Permite registrar una contribución de ayuda en línea para un conector individual.

Todo conector que contribuya con archivos de ayuda debe, por lo general, efectuar lo siguiente:

Opcionalmente, puede preconstruirse y registrarse un índice de búsqueda utilizando un elemento index respecto al rendimiento del primer intento de búsqueda. Sólo puede registrarse un índice por conector: varios elementos index darán como resultado un comportamiento indefinido.

<!ELEMENT extension (toc* , index?)>

<!ATTLIST extension

point CDATA #REQUIRED

id    CDATA #IMPLIED

name  CDATA #IMPLIED>


<!ELEMENT toc EMPTY>

<!ATTLIST toc

file     CDATA #REQUIRED

primary  (true | false) "false"

extradir CDATA #IMPLIED>


<!ELEMENT index EMPTY>

<!ATTLIST index

path CDATA #REQUIRED>

(desde la versión 3.1) elemento opcional que permite la declaración de un índice de búsqueda preconstruido creado a partir de documentos contribuidos por este conector.



A continuación figura un ejemplo de utilización del punto de extensión toc

(en el archivo plugin.xml)

 

<extension point=

"org.eclipse.help.toc"

>

<toc file=

"maindocs.html"

primary=

"true"

/>

<toc file=

"task.xml"

/>

<toc file=

"sample.xml"

extradir=

"samples"

/>

<index path=

"index/"

/>

</extension>

(en el archivo maindocs.xml)

<toc label="Ejemplo del sistema de ayuda">
 <topic label="Introducción" href="intro.html"/>
 <topic label="Tareas">
  <topic label="Crear un proyecto" href="tasks/task1.html">
   <topic label="Crear un proyecto Web" href="tasks/task11.html"/>
   <topic label="Crear un proyecto Java" href="tasks/task12.html"/>
  </topic>
  <link toc="task.xml" />
  <topic label="Probar un proyecto" href="tasks/taskn.html"/>
 </topic>
 <topic label="Ejemplos">
  <topic label="Crear un proyecto Java" href="samples/sample1.html">
   <topic label="Lanzar un asistente" href="samples/sample11.html"/>
   <topic label="Establecer opciones" href="samples/sample12.html"/>
   <topic label="Finalizar la creación de un proyecto" href="samples/sample13.html"/>
  </topic>
  <anchor id="samples" />
 </topic>
</toc>


(en el archivo tasks.xml)

<toc label="Construir un proyecto">
 <topic label="Construir un proyecto" href="build/building.html">
  <topic label="Construir un proyecto Web" href="build/web.html"/>
  <topic label="Construir un proyecto Java" href="build/java.html"/>
 </topic>
</toc>


(en el archivo samples.xml)

<toc link_to="maindocs.xml#samples" label="Utilizar la herramienta de compilación">
 <topic label="Ejemplo de la herramienta de compilación" href="compilesample/example.html">
  <topic label="Paso 1" href="compilesample/step1.html"/>
  <topic label="Paso 2" href="compilesample/step2.html"/>
  <topic label="Paso 3" href="compilesample/step3.html"/>
  <topic label="Paso 4" href="compilesample/step4.html"/>
 </topic>
</toc>

Suponiendo que haya más documentos cuya vía de acceso empieza por "samples", ninguno de ellos se visualizará en el árbol de navegación, pero se podrá acceder a ellos mediante la búsqueda.  Ello se debe a la presencia del atributo "extradir" en el elemento <toc file="sample.xml" extradir="samples" />, dentro del archivo plugin.xml.Por ejemplo, la búsqueda de la serie "Crear proyecto Java" podría devolver un documento titulado "Otras formas de crear proyecto Java", cuya vía de acceso es samples/sample2.html.

Internacionalización Los archivos XML TOC pueden traducirse y la copia resultante (con las etiquetas traducidas) debe colocarse en el directorio nl/<idioma>/<país> o nl/<idioma>.  <idioma> y <país> corresponden a códigos de idioma y país de dos letras utilizados en los códigos de entorno local.  Por ejemplo, las traducciones al Chino tradicional deben colocarse en el directorio nl/zh/TW.   El directorio nl/<idioma>/<país> tiene una prioridad más alta que el directorio nl/<idioma>.  Sólo se utilizará el archivo que resida en el directorio nl/<idioma> si no se encuentra ningún archivo en el directorio nl/<idioma>/<país>.  En último lugar, se buscará en el directorio raíz de un conector.

La documentación que hay en un archivo doc.zip se puede adaptar al entorno local creando un archivo doc.zip que tenga la versión traducida de los documentos y colocando el archivo doc.zip en
el directorio nl/<idioma>/<país> o nl/<idioma>. El sistema de ayuda buscará los archivos en estos directorios antes de tomar por omisión el directorio plugin (de conectores).
 

No se necesita código adicional para utilizar este punto de extensión. Tan solo hay que suministrar los archivos de manifiesto apropiados que se mencionan en el archivo plugin.xml.

El punto de extensión toc está totalmente soportado por la implementación por omisión de la UI del sistema de ayuda que se proporciona con la plataforma Eclipse.