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>
Códigos XML de configuración para el archivo toc:
<!ELEMENT toc (topic | anchor | link)* >
<!ATTLIST toc link_to CDATA #IMPLIED >
<!ATTLIST toc label CDATA #REQUIRED >
<!ATTLIST toc topic CDATA #IMPLIED >
<!ELEMENT topic (topic | anchor | link )*
>
<!ATTLIST topic label CDATA #REQUIRED >
<!ATTLIST topic href CDATA #IMPLIED >
<!ELEMENT anchor EMPTY >
<!ATTLIST anchor id ID #REQUIRED >
<!ELEMENT link EMPTY >
<!ATTLIST link toc CDATA #REQUIRED >
Por lo general, un conector que tenga que proporcionar ayuda en línea definirá sus propios archivos TOC. Al final, el sistema de ayuda está configurado para que su lanzamiento se produzca cuando puedan usarse para ello algunas acciones y la vía de acceso del archivo TOC.
El elemento topic
Todos los elementos topic de ayuda se proporcionan como parte del elemento contenedor toc. Pueden presentar una estructura jerárquica o bien figurar en una lista plana.
El elemento topic es el caballo de tiro de la estructura de la tabla de contenido. El elemento topic se suele usar de dos maneras:
1. Para proporcionar un enlace de acceso a un archivo de documentación, que
habitualmente es un archivo HTML.
2. Para actuar como contenedor de otros elementos toc, ya estén en el
mismo manifiesto o en otro.
1. Temas como enlaces
La forma más sencilla de utilizar un tema es como enlace de acceso a un
archivo de la documentación.
<topic label="Archivo de algún concepto" href="concepts/some_file.html" />
El atributo href es relativo al conector al que pertenece el archivo de manifiesto. Si necesita acceder a un archivo situado en otro conector, puede utilizar la sintaxis:
<topic label="tema situado en otro conector" href="../other.plugin.id/concepts/some_other_file.html" />
2. Temas como contenedores
El siguiente uso más común de un elemento topic es en forma de contenedor
de otro elemento toc. Asimismo, el propio tema contenedor siempre puede hacer
referencia a un archivo concreto.
<topic label="Entorno de desarrollo integrado" href="concepts/ciover.htm"
>
<topic label="Iniciar el IDE" href="concepts/blah.htm"
/>
...
</topic>
El elemento link
El elemento link permite enlazar una tabla de contenido (TOC) definida en otro archivo toc. Todos los temas del archivo toc especificado en el atributo toc aparecerán en la tabla de contenido como si se hubieran definido directamente en el lugar del elemento link. Para incluir un atributo toc del archivo api.xml, se podría escribir:
<topic label="Referencias" >
...
<link toc="api.xml" />
...
</topic>
El elemento anchor
El elemento anchor (ancla) define un punto que permitirá enlazar otros archivos toc con esta navegación y ampliarla sin utilizar el elemento link ni hacer referencia a otros archivos toc desde este punto. Para permitir la inserción de una tabla de contenido con más temas después del documento "ZZZ", se definiría un ancla de la siguiente manera:
...
<topic label="zzz" href="zzz.html" />
<anchor id="moreapi" />
...
El elemento toc
El elemento toc es una tabla de contenido que agrupa temas y otros elementos definidos en este archivo. La etiqueta identifica la tabla de contenido de cara al usuario, cuando éste la visualiza. El atributo topic opcional es la vía de acceso a un archivo de temas que describe la TOC. El atributo opcional link_to permite enlazar la toc de este archivo con otro archivo toc situado en un nivel más alto de la jerarquía de navegación. El valor del atributo link_to debe especificar un ancla en otro archivo toc.Para que el elemento toc del archivo myapi.xml quede enlazado con un archivo api.xml especificado en otro conector, se emplearía la sintaxis:
<toc link_to="../anotherPlugin/api.xml#moreapi" label="Mi API de herramientas"/>
...
<toc />
donde el carácter # separa el nombre del archivo toc del identificador del ancla.
<!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.
index/
, nl/ja/JP/index/
,
nl/en/US/index/
, etc.).(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).
Copyright (c) 2000, 2005 IBM Corporation y otros.
Reservados todos los derechos. Este programa y sus materiales adjuntos están
disponibles bajo los términos de la licencia pública común (Eclipse Public
License) v1.0 que acompaña a esta distribución, y está disponible en
http://www.eclipse.org/legal/epl-v10.html