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.

Contribuciones

Identificador: org.eclipse.help.contributions

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:

Señalamiento de configuración para el punto de extensión contribuciones:

    <!ELEMENT topics EMPTY>
    <!ATTLIST topics name CDATA #REQUIRED>

    <!ELEMENT actions EMPTY>
    <!ATTLIST actions name CDATA #REQUIRED>     <!ELEMENT infoset EMPTY>
    <!ATTLIST infoset name CDATA #REQUIRED> Señalamiento de configuración para Temas(es lo que contiene el archivo manifestar temas):

    <!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":

Actualmente, un tema sólo puede insertarse una vez en una infoview; puede, no obstante, insertarse en múltiples infoviews. Ello significa que si un tema padre, y por tanto, su subárbol, se inserta en un infoset, ninguno de sus hijos puede reinsertarse en la misma infoview. Básicamente, la inserción crea particiones indivisibles para una infoview específica.

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">
 <insert from="org.eclipse.help.examples.ex1.topLevelTopics"
   to="org.eclipse.help.examples.ex1.topicsView" as="child"/>
</actions>
(en el archivo topicsActions.xml)
<actions infoview="org.eclipse.help.examples.ex1.topicsView">
 <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>
 
 

Aquí tenemos la jerarquía de documentación resultante en el entorno de trabajo Eclipse


 

Componentes no integrados

A veces uno puede esperar que un plug-in se instale por sí mismo, y en otros casos será instalado como parte de un componente o producto más extenso. Si se trata de un plug-in de libre flotación deberá asegurarse de que esté visible el infoset. Cuando los temas estén integrados en una web más grande no tendrá sentido seguir mostrando un libro autónomo. Para dar soporte a esta documentación no integrada o integrada libremente, un plug-in puede definir un infoset y acciones asociadas y establecer su atributo autónomo como true. Ello produce el efecto de ejecutar las acciones de inserción únicamente cuando aquellos temas nunca hayan sido contribuidos en ninguna parte menos aquí, y solamente visualizan el infoset si no está vacío.  Es útil establecer atributos autónomos en las acciones e infosets cuando se proporciona un escenario que "lo coge todo", cuando la documentación no puede ser contribuída a un infoset conocido pero la documentación del plug-in deba aparecer aún en alguna parte.

Externalizar series

Los archivos Plugin.xml externalizan sus series al sustituir la cadena de caracteres por una clave (p.ej. %NombredelPlugin) y creando una entrada en el archivo plugin.properties del formulario:
    pluginName = "Plugin de ejemplo de ayuda en línea"
Los archivos XML de contribución se externalizan de un modo similar. Para externalizar un <identificador de tema="plainTasks" de etiqueta="Plain Stuff">, sustituya su etiqueta por una clave %plainStuff . El tema se verá así:
    <topic id="plainTasks" label="%plainStuff">
Cree una entrada en el archivo doc.properties que contenga la entrada:
    plainStuff = Plain Stuff
El sistema de ayuda utilizará doc.properties al buscar series externalizadas por nuestras contribuciones de ayuda en línea.
 

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.

Copyright IBM Corp. 2000, 2001.  Reservados todos los derechos.