La plataforma utiliza un servidor de documentación propio para proporcionar las páginas Web reales de la documentación del conector. Un servidor personalizado permite a la plataforma manejar el contenido HTML de manera independiente del navegador y proporcionar soporte de detección de conectores. La diferencia principal que ello supone para el usuario, en calidad de desarrollador de conectores, es que dispone de algo más de flexibilidad a la hora de estructurar los archivos y especificar los enlaces.
Un conector de documentación puede ejecutarse desde un archivo jar o
desempaquetarse en el directorio de conector durante la instalación.
Un jar de archivado de conector no se expande en un directorio de conector si
el valor del atributo unpack
del elemento plugin
se
especifica como true en el
manifiesto de
características. En un conector de este tipo, la documentación se comprime en el jar del conector junto con otros archivos del conector.
En los conectores que se ejecutan desempaquetados, la documentación puede entregarse en un archivo zip, para evitar los problemas que pueden producirse si hay una gran cantidad de archivos en un directorio de conector. En nuestro conector de ejemplo, hemos creado un subdirectorio llamado html. Otra posibilidad sería la de haber colocado los archivos html en un archivo zip llamado doc.zip. Este archivo zip debe imitar la estructura de archivos del directorio de conectores. En el caso que nos ocupa, debe contener el subdirectorio html y todo el contenido incluido bajo html.
Observe que, para los conectores que se conectan desde un archivo jar, no es necesario que se contenga la documentación de manera adicional en doc.zip y una configuración así de doc.zip en un jar de conector sin explotar no está soportada por el sistema de ayuda
Al resolver los nombres de los archivos en un conector que se ejecuta desempaquetado, el servidor de la ayuda busca los documentos en el archivo doc.zip antes de buscarlos en el propio directorio de los conectores. Cuando se emplea como enlace, el argumento de un atributo href se toma como relativo al conector actual. Supongamos el siguiente enlace:
<topic label="Ref1" href="html/ref/ref1.html"/>
El conector de la ayuda buscará este archivo de la manera siguiente:
Se puede usar un enlace totalmente calificado para hacer referencia a cualquier contenido de la Web.
<topic label="Ref1" href="http://www.example.com/myReference.html"/>
El sistema de ayuda de la plataforma emplea el mismo esquema de búsqueda de directorio de idioma nacional que el que se emplea en el resto de la plataforma para localizar los archivos traducidos. (En Archivos específicos del entorno local hallará una descripción de esta estructura de directorios). Si está utilizando un archivo doc.zip, deberá producir un archivo doc.zip para cada entorno local y colocarlo dentro del directorio del entorno local correcto. (No hay que replicar la estructura del directorio de entorno local nl dentro del archivo doc.zip).
Además de los directorios específicos del entorno local, el sistema de ayuda comprueba los directorios del sistema de ventanas y del sistema operativo cuando localiza recursos de ayuda. La búsqueda se realiza en el orden siguiente: subdirectorios ws, os y nl, y luego el raíz del conector, hasta que se localice el recurso. Los documentos y otros recursos, como las imágenes, que difieren entre sistemas, deben colocarse bajo los directorios ws u os para la plataforma específica.
El argumento href también puede hacer referencia al contenido de otro conector. Para ello se utiliza una notación especial de referencias cruzadas de conectores cuya resolución realiza el servidor de la ayuda:
<topic label="Ref1" href="../"id_de_otro_conector"/ref/ref1.html"/>
Por ejemplo, para enlazarse con el presente capítulo del manual del programador, se utilizaría el siguiente elemento topic:
<topic label="Capítulo de Ayuda de Doc de Plataforma" href="../org.eclipse.platform.doc.isv/guide/help.html"/>
Nota: cuando se hace referencia al contenido de otro conector, hay que asegurarse de utilizar el id del conector, tal como está declarado en el correspondiente archivo plugin.xml, no el nombre del directorio. Si bien en la práctica suelen coincidir, es importante que compruebe que está utilizando el id, no el nombre del directorio.
La información de marcas suele colocarse en un conector que define un producto tal como se explica en el tema Definición de un producto. Se puede hacer referencia a los recursos de ayuda del conector de producto desde la tabla de contenido o temas que utilicen el identificador especial "PRODUCT_PLUGIN" para el ID de conector. Por ejemplo:
href="../PRODUCT_PLUGIN/book.css"
hace referencia a una hoja de estilo que reside en el conector para el producto que se ejecuta actualmente.