La plataforma utiliza un servidor de documentación propio para proporcionar las páginas Web reales de la documentación del plug-in. Un servidor personalizado permite a la plataforma manejar el contenido HTML de manera independiente del navegador y proporcionar soporte de detección de plug-ins. La diferencia principal que ello supone para el usuario, en calidad de desarrollador de plug-ins, es que dispone de algo más de flexibilidad a la hora de estructurar los archivos y especificar los enlaces.
Un plug-in de documentación puede ejecutarse desde un archivo jar o
desempaquetarse en el directorio de plug-in durante la instalación. Un jar de archivado de plug-in no se expande en un directorio de plug-in si
el valor del atributo unpack
del elemento plugin
se
especifica como true en el
manifiesto de
características. En un plug-in de este tipo, la documentación se comprime en el jar del plug-in junto con otros archivos del plug-in.
En los plug-ins 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 plug-in. En nuestro plug-in 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 plug-ins. En el caso que nos ocupa, debe contener el subdirectorio html y todo el contenido incluido bajo html.
Observe que, para los plug-ins 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 plug-in sin explotar no está soportada por el sistema de ayuda
Al resolver los nombres de los archivos en un plug-in 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 plug-ins. Cuando se emplea como enlace, el argumento de un atributo href se toma como relativo al plug-in actual. Supongamos el siguiente enlace:
<topic label="Ref1" href="html/ref/ref1.html"/>
El plug-in 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 plug-in, 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 plug-in. Para ello se utiliza una notación especial de referencias cruzadas de plug-ins cuya resolución realiza el servidor de la ayuda:
<topic label="Ref1" href="PLUGINS_ROOT/id_de_otro_plug-in/ref/ref1.html"/>
Aquí PLUGINS_ROOT
se resolverá en tiempo de ejecución y se sustituirá por el directorio raíz de los
plug-ins. Puede especificar su propio id de plug-in para id_de_otro_plug-in
. 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="PLUGINS_ROOT/org.eclipse.platform.doc.isv/guide/help.html"/>
Antes de 3.2, las referencias a los documentos de otros plug-ins se realizaban utilizando
'..' para subir al nivel de plug-in y haciendo referencia después al id de plug-in
seguido del HREF al tema de dentro del plug-in. La forma
recomendada de hacer esto ahora consiste en utilizar PLUGINS_ROOT
en lugar de '..'. La utilización de esta
variable evita estos viajes arriba y abajo en las referencias y puede utilizarse para todos los URL de recurso de los
documentos de ayuda (imágenes, enlaces, archivos CSS, archivos javascript, etc.)
Nota: cuando se hace referencia al contenido de otro plug-in, hay que asegurarse de utilizar el id del plug-in, 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 plug-in 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 plug-in de producto desde la tabla de contenido
o temas que utilicen el identificador especial PRODUCT_PLUGIN
para el ID de plug-in. Por ejemplo:
href="PLUGINS_ROOT/PRODUCT_PLUGIN/book.css"
hace referencia a una hoja de estilo que reside en el plug-in para el producto que se ejecuta actualmente.