path: root/tde-i18n-es/docs/quanta/quanta/extending-quanta.docbook

<chapter id="extending-quanta">
<title
>Extendiendo &quanta;</title>
<para
>Este capítulo describe cómo personalizar &quanta; para sus necesidades particulares y cómo puede ayudar a que &quanta; sea mejor.</para>

<sect1 id="creating-quanta-docs">
<sect1info>
<author
> <firstname
></firstname
> <surname
></surname
> </author>
</sect1info>
<title
>Creando sus propios documentos en &quanta;</title>
<para
>Probablemente, los añadidos más notables en &quanta; para el usuario general son la adición de documentación para sus lenguajes de marcado o de script favoritos. Por ello, este capítulo le explicaré cómo creé el árbol de documentación php para mi uso personal.</para>
<para
>Antes de empezar a crear su propia documentación, puede querer comprobar el <ulink url="http://quanta.sourceforge.net/main1.php?contfile=resource"
>depósito de &quanta;</ulink
> para ver si alguien más ha hecho ya esto.</para>
<para
>Hay dos partes en este proceso. Primero, debe obtener la documentación existente para el lenguaje de marcado/script/etc que quiera. Segundo, tiene que crear el archivo docrc. Lo primero cosa suya, lo segundo es lo que trataremos aquí.</para>

<para
>El formato general del archivo docrc es como el siguiente: <informalexample
> <literallayout>
#KDE Config File
[Tree]
Doc dir=&lt;ruta, relativa a este archivo, de los archivos de documentación html&gt; por ejemplo php42/
#elementos del nivel superior
Top Element=&lt;Su descripción para estos documentos
> por ejemplo, Documentación de PHP 4.2

Section 1=Section1.html
Section 2=#Sec2.1,#Sec2.2,#Sec2.3
Sec2.1=Sec2.1.html
Sec2.2=Sec2.2.html
Sec2.3=Sec2.3.html
...

[Context]
ContextList=func1,func2,tag1,tag2,tag3
func1=func1.html
func2=func2.html
tag1=tag1.html
tag2=tag2.html
tag3=tag3.html
</literallayout
> </informalexample
> El docrc está dividido en dos secciones: Tree (árbol) y Context (contexto). </para>
<para
>La sección Tree (árbol) define el aspecto de la presentación de la documentación en la pestaña de documentación. Por ejemplo, verá que en los documentos php tiene algo parecido a esto:</para>
<para
><inlinemediaobject>
<imageobject>
<imagedata fileref="doc-view1.png" format="PNG" />
</imageobject>
</inlinemediaobject>
</para
><para
>Según lo de arriba mi docrc de php se parece a lo siguiente: <informalexample
> <literallayout>
#Archivo de configuración de KDE

[Tree]

Doc dir=php42/

#elementos de nivel superior
Top Element=Documentación de PHP 4.2

Documentación de PHP 4.2=Tabla de contenidos,#Empezando,#Referencia del lenguaje

Tabla de contenidos=index.html

Empezando=Introducción, ...
Introducción=introduction.html
...

Referencia del lenguaje=Sintaxis básica, ...
Sintaxis básica=language.basic-syntax.html
...

</literallayout
> </informalexample
> Tenga en cuenta que la # delante de <quote
>Empezando</quote
> y <quote
>Referencia del lenguaje</quote
>. Esto indica que estos son subcontenedores en el árbol y tienen contenidos por sí mismos. No creo que haya un límite de profundidad aquí (más allá de los que imponga su salud mental) - use su buen juicio. </para>
<para
>Para la Tabla de contenidos, tendrá en cuenta que se hace referencia directamente a un archivo (y consecuente se muestra al final del árbol de vista - los directorios primero).</para>
<important
> <para
>Los espacios no afectan negativamente a nada, pero tenga cuidado con los caracteres &amp; y &lt;. Los debe reemplazar con &amp;amp; y &amp;lt; respectivamente en todos los archivos de recursos de &quanta; basado en xml.</para
> </important>
<para
>La sección Context (contexto) es la sección del archivo docrc que se usa para facilitar la ayuda sensible al contexto. Por ejemplo, está escribiendo un script de PHP y le gustaría ver la documentación para la función mysql_fetch_array. Simplemente debe resaltar la función y luego pulsar <menuchoice
> <shortcut
> <keycombo action="simul"
>&Ctrl;<keycap
>H</keycap
> </keycombo
> </shortcut
> <guimenu
></guimenu
> </menuchoice
> para la ayuda contextual. ¡Vaya! Está viendo la documentación de mysql_fetch_array. Sólo hay dos tipos de entradas aquí: ContextList y las líneas de asociación de archivos. <variablelist
> <varlistentry
> <term
>ContextList</term
> <listitem
> <para
>Realmente sencilla, sólo es una lista separada por comas de los elementos de contexto que desee tener disponibles (para PHP, son las funciones de PHP). </para
></listitem
> </varlistentry
> <varlistentry
> <term
>Líneas de asociación de archivos</term
> <listitem
><para
> Éstas son de la forma elemento de econtexto=página de documentación de html. Por ejemplo, acos=function.acos.html</para
></listitem
> </varlistentry
> </variablelist
> Una versión acotada de la sección Context de mi docrc es la siguiente: <informalexample
> <literallayout>
#Claves para la ayuda contextual
[Context]
ContextList=abs,acos,acosh,addcslashes,addslashes,...

abs=function.abs.html
acos=function.acos.html
acosh=function.acosh.html
addcslashes=function.addcslashes.html
addslashes=function.addslashes.html
...
</literallayout
> </informalexample
> </para>
<para
>Ahora puede guardar su archivo docrc, guárdelo en <filename class="directory"
> $<envar
>HOME</envar
>/.kde/share/apps/quanta/doc</filename
> o <filename class="directory"
> $<envar
>TDEDIR</envar
>/share/apps/quanta/doc</filename
> para usarlo local o globalmente respectivamente. Luego, cree un directorio (el especificado en su archivo docrc) en el mismo directorio que su archivo docrc y copie sus páginas de documentación en html allí.</para>
<para
>Tendrá que reiniciar &quanta; y luego verá allí sus documentos.</para>
<para
>Una vez que esté seguro de que es lo suficientemente bueno par ser compartido, envíe el archivo docrc junto con una descripción de cualquier información pertinente sobre qué documentos usó al <ulink url="http://quanta.sourceforge.net/main1.php?contfile=resource"
>depósito de &quanta;</ulink
> para que lo pueda usar la comunidad de &quanta;. No se hará rico, pero se sentirá genial al saber que ha contribuído al desarrollo de la mejor plataforma de desarrollo web.</para>

</sect1>

<sect1 id="creating-actions">
<sect1info>
<author
> <firstname
>Robert</firstname
> <surname
>Nickel</surname
> </author>
</sect1info>
<title
>Creando acciones en &quanta;</title>
<para
>Las acciones en &quanta; son las bases para casi todas las extensiones actuales de &quanta; y las que tenga en el futuro. Es el mismo mecanismo que define una acción en &quanta; que activa la terminación automática y los diálogos de las etiquetas. Con las acciones, el límite de lo que puede hacer es virtualmente ilimitado. Para verlo con un ejemplo, usaremos <ulink url="http://www.w3c.org/People/Raggett/tidy/"
>html tidy</ulink
> en nuestras páginas web.</para>

<para
>Comencemos: <menuchoice
><guimenu
>Preferencias</guimenu
><guimenuitem
>Configurar acciones</guimenuitem
></menuchoice
> </para>
<para
> Una vez que se inicie el cuadro de diálogo de accioens verá esta ventana. A la izquierda está la lista de las acciones conocidas actualmente. Puede seleccionar una de esas para realizar las mismas acciones para una acción existente que nuestra acción de html tidy. </para>
<para
><inlinemediaobject>
<imageobject>
<imagedata fileref="conf-action.png" format="PNG" />
</imageobject>
</inlinemediaobject>
</para>
<para
>Vamos a hacer una acción nueva, por tanto hacemos clic sobre el botón nuevo (abajo a la izquierda) y comenzar.</para>

<para
>Ahora se le muestra un conjunto de opciones vacías para que las rellene: <variablelist
> <varlistentry
> <term
>Texto</term
> <listitem
><para
>Este es el nombre de la acción</para
></listitem
> </varlistentry
> <varlistentry
> <term
>Consejo</term
> <listitem
><para
>No estoy seguro de dónde se muestra. Es opcional.</para
></listitem
> </varlistentry
> <varlistentry
> <term
>Texto de estado</term
> <listitem
><para
>No sé para qué es esto ni donde se usa. Es opcional.</para
></listitem
> </varlistentry
> <varlistentry
> <term
>Poner esta acción en (marca de verificación)</term
> <listitem
><para
>Esto activa la lista desplegable para que elija una barra de herramientas en la que poner esta acción. Si no lo selecciona ahora, siempre puede añadirlo más tarde desde<menuchoice
><guimenu
>Preferencias</guimenu
><guimenuitem
>Configurar barras de herramientas</guimenuitem
></menuchoice
>.</para
></listitem
> </varlistentry
> </variablelist
> Tras rellenar esta información básica, puede seleccionar un icono para la acción haciendo clic sobre el botón del icono a la izquierda del cuadro de texto «Texto». </para>

<para
>Ahora viene lo imporante. La definición de la acción.</para>
<para
><inlinemediaobject>
<imageobject>
<imagedata fileref="conf-action1.png" format="PNG" />
</imageobject>
</inlinemediaobject>
</para>
<para
>Si estuviéramos definiendo una etiqueta de marcado, podríamos usar la pestaña etiqueta aquí para introducir los parámetros de la etiqueta.</para>
<para
> Para qué: <variablelist
> <varlistentry
> <term
>&lt;tag
></term
> <listitem
><para
>Aquí es donde introduce el nombre de la etiqueta tal y como aparecerá en su documento. Por ejemplo, &lt;div align=center&gt;</para
></listitem
> </varlistentry
> <varlistentry
> <term
>&lt;/tag
></term
> <listitem
><para
>Aquí es donde introduce la etiqueta de cierre, si la hay, o desmarque el cuadro si no hay ninguna. Por ejemplo, &lt;/div&gt;</para
></listitem
> </varlistentry
> <varlistentry
> <term
>Lance el cuadro de diálog <quote
>Editar etiqueta</quote
> si está disponible</term
> <listitem
><para
>Esto lanza el cuadro de diálogo del editor si hay un archivo de etiquetas definido para este elemento. Vea la sección <link linkend="tag-files"
>archivos de etiquetas</link
> para más información sobre los archivos de etiqueta.</para
></listitem
> </varlistentry
> </variablelist
> </para>
<para
>Y ahora... de vuelta al programa planificado regularmente. Seguimos con la creación de la acción de html tidy.</para>
<para
>Clic sobre la pestaña Script para mostrar lo siguiente:</para>
<para
><inlinemediaobject>
<imageobject>
<imagedata fileref="conf-action2.png" format="PNG" />
</imageobject>
</inlinemediaobject
></para>
<para
> <variablelist
> <varlistentry
> <term
>Texto de entrada arriba</term
> <listitem
><para
>Aquí es donde pone los ejecutables en cuestión. En nuestro caso, debería ser /usr/local/bin/tidy porque es donde guardé tidy.</para
></listitem
> </varlistentry
> </variablelist
> </para>
<para
>Ahora vamos con las pestañas Entrada/Salida/Error.</para>
<para
><emphasis
>Pestaña Entrada</emphasis
> <variablelist
> <varlistentry
> <term
>Ninguno (botón de radio)</term
> <listitem
><para
>No toma ninguna entrada para este script. Esto debería ser útil si estuviera llamando a un script Tcl/Tk que mostrara una ventana para hacer la interacción con el usuario y luego devolviera sus resultados. Seleccionaremos algún otro para tidy.</para
></listitem
> </varlistentry
> <varlistentry
> <term
>Texto seleccionado (botón de radio)</term
> <listitem
><para
>Lo que dice. Pone una copia del texto seleccionado actualmente en la entrada estándar del script en el cuadro de texto de arriba. Podríamos usar esto para tidy, pero no es divertido seleccionarlo todo en un documento grande.</para
></listitem
> </varlistentry
> <varlistentry
> <term
>Documento actual (botón de radio)</term
> <listitem
><para
>Manda los contenidos de la versión del editor del archivo a través de la entrada estándar del script al cuadro de texto superior. Esto es lo que usaremos para tidy.</para
></listitem
> </varlistentry
> </variablelist
> </para>
<para
>Ahora haga clic sobre la pestaña <emphasis
>Salida</emphasis
>. Aquí es donde decidiremos nuestra redirección para la salida de sus scripts. <variablelist
> <varlistentry
> <term
>Ninguna</term
> <listitem
><para
>Vaya. Esto estaría bien si estuviera lanzando una aplicación externa que sólo tomara la entrada y no tuviera salida alguna. Esto no el útil con tidy.</para
></listitem
> </varlistentry
> <varlistentry
> <term
>Insertar en la posición del cursor</term
> <listitem
><para
>Lo que dice. Tenga claro dónde quiere que se inserte el texto. No es bueno para tidy.</para
></listitem
> </varlistentry
> <varlistentry
> <term
>Reemplazar el documento actual</term
> <listitem
><para
>Aquí está el reemplazo total del archivo. No sobreescribirá el archivo en disco, pero arrollará su sesión de edición actual. Usar con precaución. No usaremos esto para tidy.</para
></listitem
> </varlistentry
> <varlistentry
> <term
>Crear un documento nuevo</term
> <listitem
><para
>La salida va a un documento nuevo en la ventana de edición. Esta es la mejor opción para tidy.</para
></listitem
> </varlistentry
> <varlistentry
> <term
>Ventana de mensajes</term
> <listitem
><para
>La salida va a la ventana de mensajes <menuchoice
><shortcut
><keycombo action="simul"
>&Ctrl;<keycap
>M</keycap
> </keycombo
></shortcut
><guimenu
></guimenu
></menuchoice
>. Esto es útil para depuración y la pestaña de error, pero no mucho más para la salida. No es bueno para tidy.</para
></listitem
> </varlistentry
> </variablelist
> </para>
<para
> Para la pestaña Edición, las opciones son las mismas que para la pestaña Salida. Normalmente, usará la ventana de mensajes para ayudarle en la depuración, o la opción ninguna.</para>
</sect1>
</chapter>