# Extendiendo &quanta;

Este capítulo describe cómo personalizar &quanta; para sus necesidades particulares y cómo puede ayudar a que &quanta; sea mejor.

## Creando sus propios documentos en &quanta;

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.

Antes de empezar a crear su propia documentación, puede querer comprobar el depósito de &quanta; para ver si alguien más ha hecho ya esto.

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í.

El formato general del archivo docrc es como el siguiente:

    #KDE Config File
    [Tree]
    Doc dir=<ruta, relativa a este archivo, de los archivos de documentación html> por ejemplo php42/
    #elementos del nivel superior
    Top Element=<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

El docrc está dividido en dos secciones: Tree (árbol) y Context (contexto).

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:

Según lo de arriba mi docrc de php se parece a lo siguiente:

    #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
    ...

Tenga en cuenta que la # delante de Empezando y Referencia del lenguaje. 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 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).

Los espacios no afectan negativamente a nada, pero tenga cuidado con los caracteres & y <. Los debe reemplazar con &amp; y &lt; respectivamente en todos los archivos de recursos de &quanta; basado en xml.

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 &Ctrl;H 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.

ContextList

  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).

Líneas de asociación de archivos

  Éstas son de la forma elemento de econtexto=página de documentación de html. Por ejemplo, acos=function.acos.html

Una versión acotada de la sección Context de mi docrc es la siguiente:

    #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
    ...

Ahora puede guardar su archivo docrc, guárdelo en `$`HOME`/.kde/share/apps/quanta/doc` o `$`KDEDIR`/share/apps/quanta/doc` 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í.

Tendrá que reiniciar &quanta; y luego verá allí sus documentos.

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 depósito de &quanta; 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.

Robert
Nickel

## Creando acciones en &quanta;

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 html tidy en nuestras páginas web.

Comencemos: Preferencias Configurar acciones

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.

Vamos a hacer una acción nueva, por tanto hacemos clic sobre el botón nuevo (abajo a la izquierda) y comenzar.

Ahora se le muestra un conjunto de opciones vacías para que las rellene:

Texto

  Este es el nombre de la acción

Consejo

  No estoy seguro de dónde se muestra. Es opcional.

Texto de estado

  No sé para qué es esto ni donde se usa. Es opcional.

Poner esta acción en (marca de verificación)

  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 desdePreferencias Configurar barras de herramientas.

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».

Ahora viene lo imporante. La definición de la acción.

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 qué:

<tag >

  Aquí es donde introduce el nombre de la etiqueta tal y como aparecerá en su documento. Por ejemplo, <div align=center>

</tag >

  Aquí es donde introduce la etiqueta de cierre, si la hay, o desmarque el cuadro si no hay ninguna. Por ejemplo, </div>

Lance el cuadro de diálog Editar etiqueta si está disponible

  Esto lanza el cuadro de diálogo del editor si hay un archivo de etiquetas definido para este elemento. Vea la sección archivos de etiquetas para más información sobre los archivos de etiqueta.

Y ahora... de vuelta al programa planificado regularmente. Seguimos con la creación de la acción de html tidy.

Clic sobre la pestaña Script para mostrar lo siguiente:

Texto de entrada arriba

  Aquí es donde pone los ejecutables en cuestión. En nuestro caso, debería ser /usr/local/bin/tidy porque es donde guardé tidy.

Ahora vamos con las pestañas Entrada/Salida/Error.

Pestaña Entrada

Ninguno (botón de radio)

  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.

Texto seleccionado (botón de radio)

  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.

Documento actual (botón de radio)

  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.

Ahora haga clic sobre la pestaña Salida. Aquí es donde decidiremos nuestra redirección para la salida de sus scripts.

Ninguna

  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.

Insertar en la posición del cursor

  Lo que dice. Tenga claro dónde quiere que se inserte el texto. No es bueno para tidy.

Reemplazar el documento actual

  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.

Crear un documento nuevo

  La salida va a un documento nuevo en la ventana de edición. Esta es la mejor opción para tidy.

Ventana de mensajes

  La salida va a la ventana de mensajes &Ctrl;M . 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 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.