Nota: El sistema de ayuda se halla todavía en proceso de desarrollo y es previsible que se efectúen cambios hasta que se consiga la plena estabilidad. Se ha puesto a disposición en esta etapa para solicitar la opinión de los primeros en utilizarlo, bien entendido que los detalles de los mecanismos de contribución podrían cambiar de forma sustancial. |
Descripción: Registro de una contribución de ayuda en línea para un plug-in individual.
Todo plug-in que contribuya archivos de ayuda debería por lo general efectuar lo siguiente:
<!ELEMENT topics EMPTY>
<!ATTLIST topics name CDATA #REQUIRED>
<!ELEMENT topics (topic)* ) >
<!ATTLIST topics id ID #REQUIRED >
<!ELEMENT topic (topic)* >
<!ATTLIST topic id ID #IMPLIED >
<!ATTLIST topic label CDATA #REQUIRED >
<!ATTLIST topic href CDATA #IMPLIED
>
Señalamiento de configuración para Infosets(es lo que contiene el archivo manifiesto delinfoset):
<!ELEMENT infoset (infoview)* >
<!ATTLIST infoset id ID
#REQUIRED >
<!ATTLIST infoset etiqueta CDATA
#REQUIRED >
<!ATTLIST infoset href CDATA
#IMPLIED >
<!ATTLIST infoset standalone
(false|true) false #IMPLIED >
<!ELEMENT infoview EMPTY>
<!ATTLIST infoview id ID #REQUIRED >
<!ATTLIST infoview label CDATA #IMPLIED >
Señalamiento de configuración para Insertar acciones(es lo que contiene el archivo manifiesto de acciones):
<!ELEMENT actions (insert)* >
<!ATTLIST actions infoview CDATA #REQUIRED
>
<!ATTLIST actions standalone (true | false)
false #IMPLIED >
<!ELEMENT insert (insert) >
<!ATTLIST insert from CDATA #REQUIRED >
<!ATTLIST insert to CDATA #REQUIRED >
<!ATTLIST insert as (child
| first-child | last-child | prev-sib | next-sib) "child" >
<!ATTLIST insert label CDATA #IMPLIED >
Por lo general, un plug-in que requiera proporcionar ayuda en línea, definirá sus propios manifiestos de temas y los manifiestos de acciones necesarios para guiar los temas al lugar correcto. Al fin, el sistema de ayuda está configurado para iniciarse tras determinadas acciones, y el identificador del conjunto de información puede utilizarse para hacerlo.
Un plug-in puede utilizar cuatro tipos de elementos XML: el tema, el infoset, las acciones y los elementos insertados.
El elemento tema
Con respecto a los elementos tema, todos los temas son contribuidos como parte del elemento contenedor de temas. Pueden presentar una estructura jerárquica, o bien listarse como una lista plana. Un manifiesto de temas es visto como una fuente de datos para promover el intercalado y la organización de los temas en una web integrada, con perspectivas distintas. Además, puede accederse a los temas especificando sus identificadores, aunque uno también puede actuar sobre un grupo de temas especificando el identificador de los temas contenidos o del elemento tema Más tarde, al conectar los temas con las vistas o con otros temas, se mantendrá la estructura definida en el manifiesto de temas (sujeto a alteraciones que efectúen las acciones que se inserten).
El elemento tema es el caballo de batalla de la estructura de navegación. El elemento tema es usado típicamente de tres maneras:
1. Para proporcionar un enlace a un archivo de documentación - por lo general un archivo HTML.
2. Para actuar como contenedor de otros temas, tanto del mismo manifiesto como de cualquier otro.
3. Para proporcionar un punto de inserción para otros temas, tanto del mismo manifiesto como de otro.
1. Temas como enlaces
La forma más sencilla de utilizar un tema es como enlace a un archivo de documentación.
<etiqueta de tema="Archivo de algún concepto" href="conceptos/some_file.html" />
El atributo href es relativo al plug-in al que pertenece el archivo. Si necesita acceder a un archivo de otro plug-in, puede utilizar la sintaxis
<etiqueta de tema="tema en otro plug-in" href="/other.plugin.id/concepts/some_other_file.html" />
2. Temas como contenedores
El otro uso más común de un tema es como contenedor de otros temas. El tema contenedor en sí mismo siempre puede referirse también a un archivo en particular.
<etiqueta de tema="Entorno de desarrollo integrado" href="concepts/ciover.htm"
>
<etiqueta de tema="Iniciar IDE" href="concepts/blah.htm"
/>
...
</topic>
3. Temas como puntos de inserción
Los temas pueden utilizarse como puntos de inserción. Proporcionan un sitio lógico para otros temas
posibles y su fusión. Para actuar como punto de inserción, el tema deberá tener un atributo de identificación.
Elemento infoset
Un conjunto de información es un punto de entrada de una web de documentación. Puede ser mediante una colección de vistas.
Las vistas proporcionan agrupaciones semánticas de alto nivel dentro de una web de documentación. Se definen utilizando el elemento infoview definido en un infoset. Un equipo de documentación podría utilizar una vista para producir secciones de iniciación, tareas y referencias (u otras vistas definidas por el equipo del producto). La plataforma no especifica las secciones existentes, únicamente el mecanismo para definirlas.
Por ejemplo, puede darse una "vista de tareas" definida que sea una fusión de todos los temas en base a la perspectiva "cómo hacer algo". También puede definirse otra vista, la "vista de componentes", la cual es un árbol de temas que muestra todos los componentes y su documentación.
El elemento infoview representa un contenedor para temas que pueden ser "compartidos" mediante plug-ins. Es una perspectiva de la documentación al completo. Algunas veces puede darse que varios plug-ins distintos contribuyan al mismo componente de documentación lógica. Este elemento garantiza que durante una "vista de componentes", éstos estén fusionados de forma correcta en una vista coherente.
Elemento acciones
El manifiesto de acciones contiene acciones de escritura a efectuar en temas y vistas. Actualmente sólo existe un tipo de acción, la acción de insertar, utilizada para grabar juntos temas y vistas en una web de información integrada, con múltiples vistas.
Al tratarse de acciones estructurales (insertar), se aplican a una infoview en particular. Así, la totalidad de acciones de inserción en un manifiesto construyen la jerarquía de temas en una infoview.
Elemento insertar
Una de las partes más complicadas de una navegación componentizada es cómo crear una estructura integrada con un flujo continuo de navegación. Para ello, necesitaremos un mecanismo para publicar puntos de inserción, elegir qué punto de inserción queramos utilizar, e indicar dónde queremos insertar temas (padre, hijo, antes, después).
Los puntos de inserción pueden ser temas o vistas. Un tema indica su disposición a ser un punto de inserción al proporcionar un identificador. Las vistas necesitan tener identificadores. Únicamente los identificadores totalmente calificados se utilizan como referencias. Por ejemplo, el identificador totalmente calificado del tema <identificador del tema="conceptos" etiqueta="conceptos"> del plug-in org.eclipse.help.examples.ex1 es org.eclipse.help.examples.ex1.concepts.
Como los puntos de inserción acostumbran a estar localizados en otros plug-ins, y puede que éstos no estén instalados, puede especificarse un punto de inserción alternativo. Por omisión, si ninguno da resultado, el tema permanece bajo su jerarquía de componentes. El atributo "a" especifica el punto de inserción de destino. El tema especificado por el atributo "from" es el tema a insertar. Las siguientes son algunas de las maneras posibles de insertar un tema, y están especificadas utilizando el atributo "as":
Se proporcionan opciones alternativas de inserción, que se ejecutarán cuando las previas no puedan ejecutarse. Estas alternativas son proporcionadas por los subelementos de inserción anidados del elemento de inserción. Es como un mecanismo al que recurrir cuando falla una acción de inserción, pues ejecutará la acción de inserción anidada. Si la primera opción de punto de inserción resulta satisfactoria, los otros puntos de inserción alternativos son ignorados.
Ejemplos:
A continuación podemos observar un ejemplo de utilización del punto de extensión contribuciones. Asumiendo que se trata de un plug-in con el identificador denominado "org.eclipse.help.examples.ex1". (El ejemplo intenta ser una muestra general, y debe constatarse que la misma jerarquía de documentación resultante de todos los archivos contribuidos, también puede crearse con varias combinaciones de temas y archivos de acciones).
(in file plugin.xml)
<!-- Utilice el punto de extensión de contribución del sistema de ayuda para definir Infosets, temas, -->
<!-- y archivos de contribución de acciones. Para mayor claridad, el punto de extensión se utiliza -->
<!-- dos veces, una para definir el Infoset y su vista, y otra para definir los -->
<!-- temas y sus acciones asociadas.
-->
<extension point="org.eclipse.help.contributions">
<infoset name="infoset.xml"/>
</extension>
<extension point="org.eclipse.help.contributions">
<topics name="infosetTopics.xml"/>
<actions name="infosetActions.xml"/>
</extension>
<!-- Configure la contribución de ayuda para este conector
-->
<!-- Esta parte debería estar en un plugin de documentación
-->
<extension point="org.eclipse.help.contributions">
<topics name="topics.xml"/>
<actions name="topicsActions.xml"
/>
</extension>
(en el archivo infoset.xml)
<!-- Defina el Infoset, y cualquier vista que tenga.-->
<infoset id="ex1InfosetId" etiqueta="%ejemplo_del_sistema_de_ayuda">
<infoview id="topicsView" label="%topics"/>
</infoset>
(en el archivo infosetTopics.xml)
<!-- Ahora defina un tema "contenedor" que contenga sus temas generales. Ello facilita -->
<!-- una rápida inserción de todos esos temas generales en la vista del -->
<!-- Infoset. -->
<topics id="topLevelTopics">
<topic id="concepts" label="%concepts"/>
<topic id="tasks" label="%tasks"/>
<topic id="references" label="%references"/>
<topic id="samples" label="%samples"/>
</topics>
Define los temas contenidos en los temas generales anteriormente citados:
(in file topics.xml)
<topics id="temas">
<topic id="aConceptId" label="%introducción" href="conceptos/concept.html"/>
<topic id="aTaskId" label="%crear_un_proyecto" href="tasks/task1.html">
<topic id="aSubTaskId1" label="%crear_un_proyecto_web" href="tasks/task2.html"/>
<topic id="aSubTaskId2" label="%crear_un_proyecto_java" href="tasks/task3.html"/>
</topic>
<topic id="aReferenceId" label="%interfaces" href="ref/ref1.html"/>
<topic id="aSampleId" label="%ejemplo_de_ayuda_del_sistema" href="MissingFile.html"/>
</topics>
Ahora defina las acciones de inserción necesarias para crear la jerarquía de documentación:
(in file infosetActions.xml)
<actions infoview="org.eclipse.help.examples.ex1.topicsView">(en el archivo topicsActions.xml)
<insert from="org.eclipse.help.examples.ex1.topLevelTopics"
to="org.eclipse.help.examples.ex1.topicsView" as="child"/>
</actions>
<actions infoview="org.eclipse.help.examples.ex1.topicsView">Aquí tenemos la jerarquía de documentación resultante en el entorno de trabajo Eclipse
<insert from="org.eclipse.help.examples.ex1.aConceptId"
to="org.eclipse.help.examples.ex1.concepts" as="child"/><insert from="org.eclipse.help.examples.ex1.aTaskId"
to="org.eclipse.help.examples.ex1.tasks" as="child"/><insert from="org.eclipse.help.examples.ex1.aReferenceId"
to="org.eclipse.help.examples.ex1.references" as="child"/><insert from="org.eclipse.help.examples.ex1.aSampleId"
to="org.eclipse.help.examples.ex1.samples" as="child"/>
</actions>
Información del API: No es necesario ningún código para utilizar este punto de extensión. Todo lo que se necesita es suministrar los archivos de manifiesto apropiados, mencionados en el archivo plugin.xml.
Implementación suministrada: La implementación opcional por defecto del UI del sistema de ayuda proporcionado con la plataforma Eclipse da soporte completo al punto de extensión contribuciones.