Introducción

Attention!

Es muy importante que lea este documento antes de ponerse a confeccionar documentación para el proyecto.

Lo más importante es que sea capaz de ubicar donde está la documentacion que pueda necesitar para confeccionar sus documentos y cuáles son las normas y recomendaciones que debe seguir en ellos.

En el proyecto gvSIG se ha decidido usar como herramienta para la gestión de la documentación el Plone, y concretamente el formato RestructuredText.

Esto implica que antes de ponerse a confeccionar la documentación debera familiarizarse con el entorno de Plone, concretamente con la version 2.5.

Esta guía le introducirá en los conceptos básicos de plone junto con las extensiones de este que puede encontrar en la web de gvSIG además de darle las recomendaciones o normas que deberá seguir para confeccionar la documentación dentro de gvSIG.

Redactar correctamente

El proceso de redactar documentación, debe abordarse como un proceso de desarrollo más, no es bastante con sentarse y comenzar a escribir ?a ver que sale?. Como todo proceso de desarrollo debe comenzar por una fase de análisis, para a continuación redactar, y finalmente debe existir una fase de revisión del texto que se ha creado.

Este proceso debe abordarse desde las siguientes premisas fundamentales:

  1. El autor debe tener en todo momento presente qué y para quién escribe. El destinatario del texto es el usuario.
  2. El autor no debe tener ningún protagonismo en la obra en el sentido de que se escribe por y para un tema, no por una recreación artística.
  3. El objetivo primordial del texto es que el lector comprenda la herramienta y cómo usarla.

Fases en la confección de la documentación

A la hora de ponernos a confeccionar la documentación contemplaremos tres fases o momentos a tener en cuenta:

Planificación

El objetivo de esta fase es estructurar las ideas y marcar las directrices del trabajo que se piensa acometer, el redactor debe generar un esquema con esa estructura de ideas de forma jerarquizada. Este esquema proporciona una primera visión del conjunto del trabajo.

Una vez que se han plasmado las ideas generales en el esquema jerarquizado lo siguiente que debe hacerse es completar el esquema con las divisiones y subdivisiones de las entradas generales que permitan exponer claramente las ideas del redactor y desarrollar el tema principal. Este esquema no se debe presuponer inmutable, es decir, podemos añadir ?voces? al esquema que sirvan para completarlo, o suprimir ?voces? porque nos damos cuenta que no vienen al caso, o simplemente modificarlo porque no nos convence el enunciado propuesto.

Redacción

En esta etapa se transforma en texto el esquema que se creó en la fase de planificación. Se debe tener en cuenta el léxico, el orden sintáctico, la concordancia, la cohesión, la puntuación y todos los elementos que aseguren un estilo claro, preciso, conciso y sencillo.

Comunicarse con precisión y claridad significa que el texto se lee y se entiende rápidamente. Un texto es fácil de entender cuando el lenguaje es sencillo, las oraciones están bien construidas y cada párrafo desarrolla su tema siguiendo un orden lógico.

Las oraciones que se utilicen deben ser simples. Las oraciones largas son generalmente más difíciles de entender que las oraciones cortas, porque mientras más larga es la oración mayor es la probabilidad de que el sujeto y el verbo se aparten, o que la oración contenga tanta información que el lector olvide el material importante. No obstante, hay oraciones cortas tan mal construidas que son imposibles de entender y hay oraciones muy largas pero tan bien organizadas y puntuadas que se entienden perfectamente.

Es conveniente alternar párrafos largos con otros más cortos. No se deben utilizar exclusivamente párrafos y oraciones cortas. Una secuencia de varios párrafos cortos, al igual que una secuencia de oraciones cortas, contiene demasiadas pausas y no proporciona una lectura agradable. En el otro extremo, un párrafo que ocupa la página completa es abrumador y no invita a la lectura.

Se debe incluir sólo información pertinente al contenido y comunicar dicha información usando el menor número posible de palabras, el texto innecesario desvía la atención del lector y afecta la claridad del mensaje.

Hay que usar palabras comunes en vez de términos rebuscados, usar aquellas palabras que comuniquen exactamente lo que se quiere transmitir. Si el lector no entiende algo, no puede levantar la mano para aclarar sus dudas, ni puede adivinar cuál era la intención del redactor cuando escribió el texto; para escribir con precisión se tiene que escribir para el lector.

Si se trabaja con prisa y no se revisa cuidadosamente el orden de las palabras, seguramente se escribirán muchas oraciones deficientes. El significado literal de la oración puede ser tan absurdo que el lector sonreirá pero entenderá el mensaje. En otras ocasiones el significado será confuso y el lector deberá retroceder y leer la oración varias veces para intentar entenderla. El significado también puede ser opuesto o totalmente distinto de lo que quieres comunicar

Revisión

Con la revisión lo que se pretende es corregir aquellos errores que se hayan podido cometer asegurando la corrección, la adecuación, la concisión, la precisión, la coherencia, la claridad y la legibilidad del texto. Se examinan tanto las ideas como las oraciones, los párrafos, los apartes y/o los capítulos que se han redactado.

La revisión se hace en dos pasos:

  • Primero: el redactor comprueba que el texto responde a su intención comunicativa y que ha logrado la expresión correcta de lo que ha planeado comunicar a sus lectores potenciales.
  • Segundo: modifica la parte o las partes formales del texto que sea necesario, esto es el léxico, la morfología, la sintaxis, la ortografía, la puntuación, el diseño, etc.

Para llevar a cabo una revisión efectiva del texto, que detecte los problemas tanto formales como de fondo, es conveniente hacerlo de dos maneras: como redactor y como lector.

Abreviaturas

Las abreviaturas son convenientes porque ahorran espacio y aligeran la lectura, pero pueden confundir al lector si sus significados no están claros. Las normas siguientes ayudan a usar las abreviaturas correctamente:

  1. No deben usarse abreviaturas en el título ni en el resumen.
  2. No se deben abreviar términos cortos.
  3. No se deben abreviar términos que se usan pocas veces.
  4. No inventes abreviaturas
  5. No comiences las oraciones con abreviaturas. Tampoco comiences las oraciones con números.
  6. Para definir una abreviatura se escribe el término completo la primera vez que se usa y a continuación la abreviatura entre paréntesis.
  7. Abrevia las unidades de medida cuando están precedidas de dígitos, pero no cuando son sustantivos.
  8. Representa los números con dígitos cuando se refieren a unidades de medida (4 gr., 18 m.) y cuando se usan para expresar horas y fechas. Representa los números con palabras cuando se usan como sustantivos (nosotros cuatro). Usa las abreviaturas del Sistema Internacional (SI) para todas las unidades de medida.

Documentación adicional

Standards and recommendations

Inclusion of pictures or diagrams

When you insert a picture or diagram in a document, it should be into account certain considerations.

  1. Adjust the size of the images that you want to show them. That is, to show an entry in the menu bar probably not be needed an image of 1400 px.

    In general we will not use images larger than 800x600 pixels.

    A very common practice in the making of the manuals is capture screens at high resolutions, eg 1200x1024 pixels, and then reduce them using manipulation images tools for their inclusion in the documentation. This practice does not should be never used. The resulting images haven't a acceptable quality and these texts could not read or are read with great difficulty. We will capture images to the size with which they are to be included in the documentation for avoid loss of quality in them, or limit cut the area of ??interest without altering the resolution of these.

  2. If the text is the reference to a button, window, dialogue, it must be clearly identified. This does not mean you need to take a screenshot individual of all the buttons, most of the time simply an image of the interface that is where you identify the elements of interest.

    For example:

    images/es/GestorDeProyectosCompleto.png

    Project Management Composition window

    • 1. Select document type "Views".
    • 2. "New" button. Enables the creation of a new document.
    • 3. Document titles "Views" created. By default, "Untitled - 0".
    • 4. "Rename" button. Change the name of the "View" selected.
  3. The color depth of the image must be in accordance with this, ie if an image contains little variety of color, use a depth of low color, and if you use a very high color depth, use a hight color palette. This usually reflected image using a color palette for those with little variety and color in RGB format for those with lots of variety.

    In addition to using images with color palette, we try to have the number of palette colors as low as possible while maintaining good visual quality.

  4. The format of the images to use go hand in hand with the color depth of this. For images with color palette use the PNG format, and images use in RGB JPEG format.

Other Recommendations

  1. We should not assume that users know things of the tool, is preferable to have much information that has not necessarily than missing information because it was considered something that is obvious.
  2. Never number the document titles. It is easy sometime insert or delete a document and we mismatch all numbering or even from another part of the web is made Reference to any member of our documents and the numbering established is not correct in the context in which the document falls.
  3. Never number the headings or sections within a document.
  4. Never use a manual to simulate bullets numbering numbered. If you need to use bullets numbered only use the ReStructuredText tools for it, even if we lose the possibility of nested bullets numbering (1.1.1, 1.1.2, 1.2.1 ,...).

Plone basics

Content types

Plone is a content manager, CMS capable of maintaining different types of objects. Normally use 2 types of objects. On one hand the folders, which are merely containers other objects, just like the directories / folders we have in our computer. Then there are the pages these are the ones with the content. The pages support multiple text formats for writing content, we will use RestructuredText format.

When creating content within the Plone we have into account the following considerations:

Estados y flujo de trabajo

A lo largo de la vida de un documento en la web de gvsig.org, éste pasa por varias fases. Para gestionar el estado en que se encuentra un documento el Plone dispone de un mecanismo de control de flujo del documento.

En la web de gvsig.org nos encontraremos los siguientes estados:

Tip

Recuerde que si no le aparece la pestaña de editar un documento y cree que debe poder hacerlo, puede ser que antes tenga que retirar el documento.

El Plone utiliza un código de colores para identificar el estado en que se encuentra un documento cuando se muestra este en un listado de documentos, por ejemplo cuando nos muestra los resultados de una búsqueda o los contenidos de una carpeta. Este código es:

En ocasiones puede que no se utilice este código de color. Normalmente esto sucederá en partes en las que se haya usado una visualización de los documentos particular de gvsig.org, en cuyo caso no se hará distinción entre los estados de un documento. Este tipo de situaciones se irán corrigiendo paulatinamente para utilizar en todas partes el código de colores standard de Plone.

Vistas

A la hora de presentar un documento, éste puede disponer de varias formas de hacerlo. Normalmente cuando estemos trabajando con documentos de tipo página, la presentación por defecto sea la adecuada. Sin embargo cuando estemos trabajando con otros contenidos como carpetas o archivos podemos disponer de varias alternativas en función del resultado que queramos obtener.

Las distintas formas de visualización de los contenidos que podemos encontrar son:

Una consideración final sobre las vistas. La asignación de una vista a un documento no es dependiente del usuario. Si cambiamos la vista de un documento, la cambiamos para todos los usuarios. En caso de que no sea nuestra responsabilidad un documento, no cambiemos las vistas de estos y si lo hacemos comuníqueselo al responsable del documento o al administrador del sitio para que esté enterado del cambio.

Puede ser útil consultar los documentos:


Versiones

Introducción

Cuando edite documentación en gvsig.org, cualquier proceso de guardado que realice será contra la documentación original. Por lo tanto, de entrada, no podrá recuperar el estado anterior de la documentación una vez guardada. Sin embargo el Plone ofrece la posibilidad de guardar versiones de los documentos de forma similar a como lo hace un repositorio de código.

El guardar versiones de los documentos permite recuperar, en un momento dado, un documento que ha sido modificado y restituirlo al estado en el que se encontraba antes de hacer los cambios. También permite hacer comparativas de la evolución de los documentos y comprobar los cambios que se han realizado de una versión a otra.

Generar una versión de un documento

Para crear una versión de un documento hay que marcar el check "Save as new version" cuando se guarda el documento.

images/es/check.png

Check Save as new version

Una vez que se marca aparece un área de texto que permite la introducción de un comentario de la nueva versión.

images/es/active-check.png

Check Save as new version. Active

A continuación lo único que hay que hacer es guardar el documento y tendremos una nueva versión del mismo generada.

Consultar las versiones de un documento

Cuando un documento tiene versiones aparece en la cabecera del documento una entrada llamada "Recent versions"

images/es/recent-versions.png

Recent versions

Si se despliega pulsando sobre el símbolo "+" se muestra una tabla con las últimas versiones que se han realizado del documento.

images/es/tabla-de-versiones.png

Tabla de versiones

También puede accederse a la tabla de versiones desde la pestaña "Versions"

images/es/pestana-versiones.png

Pestaña Versions

La tabla muestra:

La vista de versiones

Existen 2 medios de llegar a la vista versiones.

Desde el desplegable "Recent versions" pulsando el enlace de la versión que deseemos o desde la pestaña "Versions". La diferencia está en que si se accede por el primer camino se muestra una vista previa de la versión seleccionada, accediendo desde la pestaña "Versions" no se muestra la vista previa.

images/es/pagina-de-versiones.png

Página de versiones con vista previa

Acciones

Desde la página de versiones de un documento pueden realizarse varias acciones.

images/es/acciones.png

Tabla de versiones


Internationalization

Introducción

El Plone soporta internacionalización de sus contenidos. Con esto no nos referimos a la internacionalización del interface web que presenta el Plone, si no a la internacionalización de cada uno de los documentos que forman parte de los contenidos de gvsig.org. Así un usuario podría acceder a un documento en castellano y otro al mismo documento en inglés.

Los idiomas neutral y canónico

Cuando creamos un documento en la web de gvsig.org, este no tiene asignado ningún idioma. Con esto no quiere decir que no este escrito en un idioma en concreto, simplemente, el Plone, no sabe en qué idioma está y decide que está en neutral, y que no importa en qué idioma esté navegando el usuario lo verá. De esta forma, un usuaro puede navegar a una página, y aunque no exista una versión de esa página para el idioma que tenga seleccionado podrá verla en el idioma en que fue redactada originariamente.

Así pues, siempre que creemos documentos, los dejaremos en neutral, sin asignar un idioma en concreto a nuestros documentos.

Sólo cuando vayamos a realizar una traducción de un documento del que no existía previamente una traducción tendremos que asignarle un idioma. Así si tenemos nuestro documento, que hemos redactado en castellano, y que para el Plone se encontraba en idioma neutral, cuando vayamos a traducirlo, por ejemplo al inglés, lo primero que deberemos hacer es decirle que se encuentra en idioma castellano, para así poder hacer la traducción de castellano a inglés.

En la configuración standard de Plone, al hacer esto, el documento desaparecerá para el resto de idiomas, ya que ha dejado de disponer del documento en idioma neutral, y únicamente lo dispone en castellano e inglés. Sin embargo, en gvsig.org, se intentará mostrar siempre el documento en el mejor idioma disponible para el usuario. Esto puede ocasionar que según en qué ocasiones un documento pueda desaparecer para algunos idiomas, al traducirlo a un idioma especifico desde el neutral. Concretamente observaremos este comportamiento en la pestaña contenidos de las capetas que no ha sido modificada en gvsig.org. Las vistas de carpeta de gvSIG folder listing (internationalizable support) y gvSIG folder TOC, mostrarán los documentos, aunque no exista versión neutral de este.

El idioma canónico es aquel en el que se redacta el documento originalmente. Es decir, cuando se redacta un documento, este está escrito en algún idioma, pero para el Plone mientras no existan traducciones, el idioma del documento es neutral, en el momento en que se decide establecer un idioma concreto para este documento, pasará a tratarse como idioma canónico.

Carpetas (i18n)

Dentro de gvsig.org, podemos encontrarnos dos tipos distintos de carpetas, las carpetas standard del Plone y las "carpetas (i18n)". Para gestionar correctamente las traducciones de los documentos es muy importante que estos se encuentren siempre dentro de carpetas de tipo "carpetas (i18n)".

Note

Es muy importante traducir sólo documentos que se encuentran en "carpetas (i18n)".

How to translate a document

The first step before translating a page is to withdraw the following pages:

To retract every page, this must be done by first selecting the language from the corresponding flag and then selecting "retract" from the drop-down list showing "state".

images/en/images.pestanya-retirar_4.png

State Tab

If a translation of a document is to be done for the first time, after you have withdrawn the page with the language from which you will be translating (source) and the page of the master language, you must select the language you want to translate to (target) from the drop-down list "translate into".

images/en/images.pestanya-traducir-a_4.png

Translate into Tab

The following interface will be shown next

images/en/images.interface-traduccion_4.png

Translation Interface

In the left frame there is the text content which is intended to be translated in the written format (usually srt). In the right frame is where the translation is done. On one hand there is the page title and in some cases a description which need to be translated. On the other, the frame of "Text format" needs to be changed to "reStructured Text". The text from the left frame should be copied to the right frame and the text should be translated there observing the original formats.

Once the translation is finished, the document should be saved and submitted to be published by selecting "submit" from the "state" tab. The status of the master language and source language needs to be changed by clicking ?submit? from the ?state? tab.

images/en/images.pestanya-enviar_4.png

State Tab

If you are only going to modify some text in a page previously translated, after withdrawing the page of the source language, the master language and that of the target language, you will select the flag of the target language and also will select the "edit" tab.

images/en/images.pestanya-editar_4.png

Edit Tab

The following interface will be shown next

images/en/images.interface-edicion_4.png

Editing Interface

The text to be translated it is shown on the left frame in the format that is written (usually srt). On the right frame is where the original text must be edited to do the translation. If you would like to change the source language (left frame), you will change it in the menu located on the upper left and then you will click the "Refresh" button. After the text is edited in the right frame, changes must be saved to be preserved by clicking the "save" button at the end of the page. Then the document should be submitted to be published by selecting "submit" from the "state" tab. The status of the source language and the master one need to be changed by clicking ?submit? from the ?state? tab.

Important things to consider

It can be useful to consult the next documents:

Translation with Google Translator

 

 

 

Estado de las traducciones

Para consultar el estado en el que se encuentra la traducción de los contenidos de una carpeta, se ha creado una "vista" que muestra la estructura de contenidos de la carpeta y los idiomas en los que se encuentran disponibles. Esta vista puede invocarse pulsando el botón

web.png

Una vez pulsado el botón nos aparecerá una vista en la que se detallan los contenidos de la carpeta y las traducciones disponibles de cada uno de esos contenidos

./images/es/vista-estado-traduciones.png

Ejemplo vista de estado de traduciones

Los idiomas en los que se encuentra disponible el documento aparecen con las banderas a color, mientras que los idomas a los que se puede iniciar la tradución se muestran con las banderas en colores apagados.

Permisos

El Plone, dispone de un sistema de permisos que nos permite ajustar éstos en función del perfil que tenga un usuario respecto a un documento.

De esa forma podremos restringir el acceso a un documento o darle acceso a algún usuario concreto, indicando además, qué perfil desempeña ese usuario en relación a cada documento.

Para alterar los permisos de un documento lo haremos a través de la pestaña de compartir. Si no nos aparece ésta, es que no tenemos permisos para hacer esta operación, y en caso de que nos interese deberemos pedirla al administrador del sitio.

Los perfiles que podemos encontrarnos en gvsig.org son:

Un par de consideraciones más. Cuando asignamos un perfil a un usuario para una carpeta, el usuario adquirirá ese perfil para todas las subcarpetas de ésta. Es decir, los perfiles de los usuario son heredados por las subcarpetas.

En caso de que no queramos que una carpeta herede la asignación de perfiles de los usuario de sus carpetas padre, deberemos indicarlo de forma explicita, y sólo podremos indicarle que no herede ningún perfil, nunca un perfil en concreto. Para hacer esta operación acudiremos a la pestaña compartir y al final, en la sección de "Configuración avanzada", desmarcaremos el check "Heredar roles de niveles más altos", pulsando seguidamente el botón de "Aplicar configuración".

La aplicación de permisos a una carpeta puede ser costosa en tiempo y recursos del servidor dependiendo del número de subcarpetas y documentos que tenga la carpeta sobre la que lo aplicamos.

Nombre y título en los documentos

Cuando damos de alta un documento en org.gvsig de tipo Página, deberemos indicar:

Es importante tener en cuenta que así como en el título del documento se puede emplear cualquier combinación de caracteres siempre que no exceda de un tamaño máximo, en el nombre corto, deberemos introducir sólo caracteres alfanuméricos y el '_' y '-'. Tendremos especial precaución de no introducir espacios en el nombre corto. Además hay una serie de nombres que no deberemos emplear. Entre estos estarían:


El formato ReStructuredText

Qué es ReStructuredText

ReStructured Text es un lenguaje de marcas ligero creado para escribir textos de manera cómoda y rápida. A la hora de crear un documento en formato ReStructuredText, disponemos de dos grandes bloques de marcas. Por un lado tenemos una serie de marcas orientadas al párrafo y al formatoe de este y su contenido, y por otro lado una serie de marcas o directivas que extienden las posibilidades de formato que nos ofrecen las primeras.

Vamos a ver estas dos marcas por separado, realizando un repaso breve por las más comúnmente usuadas dentro de la documentacion de gvsig.org.


Formateo básico de un documento

Estructura

La estructura más básica reconocida es el párrafo, que no es más que texto separado por líneas en blanco. Los párrafos deben tener la misma indentación o aparecerán sangrados.

Por ejemplo:

Esto es un párrafo. Es un poco corto.

    Este párrafo producirá como resultado un bloque indentado de texto, 
    usado típicamente para citar otro texto

Este es otro párrafo.

El resultado es:

Esto es un párrafo. Es un poco corto.

Este párrafo producirá como resultado un bloque indentado de texto, usado típicamente para citar otro texto

Este es otro párrafo.

Estilos de texto

Dentro de los párrafos y otros cuerpos de texto, puedes querer marcas de texto adicionales para itálica con "*italica*" o negrita con "**negrita**".

Si quieres que algo aparezca literalmente utiliza comillas dobles. Nota que no se interpreta el contenido de las comillas dobles así los asteríscos "*" etc. se quedan sólos

Si necesitas usar un carácter "especial" en el texto, generalmente estará bien, --reStructuredText es muy inteligente. Por ejemplo, este * asterísco está bien puesto. Si quieres que el /texto esté rodeado de asteríscos y que no se "italicen", entonces necesitas indicar que el asterisco no es especial. Esto se indica anteponiendo una barra invertida justo antes de él, del siguiente modo "\*", o rodeándolo dobles comillas, del siguiente modo:

``\*``
Listas

Los elementos de la lista pueden definirse de tres modos: enumerated, viñetas o símbolos y definiciones (nosotros hablaremos de los 2 primeros).

Las listas deben empezar siempre en un párrafo nuevo como éste y después de una línea en blanco.

Lista numerada (números, letras o números romanos)

Comienza un línea con un número o una letra seguida de un punto ".", un paréntesis de cierre ")" o entre paréntesis "( )" lo que resulte más cómodo. Todas las formas siguientes están reconocidas:

1. números 

A. Letras mayúsculas
   y que se dividan en varias líneas

   con dos párrafos y todo

a. letras en minúscula

   3. Con una sublista que comienza con un número diferente
   4. asegurate que los números están en la secuencia correcta

I. números romanos en mayúscula   

i. números romanos en minúscula

(1) números otra vez    

1) y otra    

el resultado es (aviso: los diferentes estilos de enumerado de listas no son soportados siempre por todos los navegadores, así puede que no surta efecto aquí):

  1. números
  1. Letras mayúsculas y que se dividan en varias líneas

    con dos párrafos y todo

  1. letras en minúscula
    1. Con una sublista que comienza con un número diferente
    2. asegurate que los números están en la secuencia correcta
  1. números romanos en mayúscula
  1. números romanos en minúscula
  1. números otra vez
  1. y otra

Al igual que las listas enumeradas, las listas con viñetas comienzan con un carácter símbolo que puede ser "-", "+" o "*":

* una viñeta usando "*"    

  - una sub lista usando "-" 

    + otra sub lista 

  - otro elemento

El resultado es:

Preformateado (ejemplos de código)

Para incluir fragmentos de texto preformateado, nunca podrá mezclarse con texto, finaliza el párrafo precedente con "::". El bloque preformateado terminará cuando el texto vuelva al mismo nivel de indentación que el párrafo anterior que no esté preformateado. Por ejemplo:

Un ejemplo::

  Espacios en blanco, líneas nuevas, líneas en blanco, y todo tipo de marcas 
    (como *esta* o \esta) serán mantenidas por los bloques preformateados o literales.
  Mira aquí, he incluido un nivel más de indentación (pero no muy lejos)

fin del ejemplo

El resultado es:

Un ejemplo:

Espacios en blanco, líneas nuevas, líneas en blanco, y todo tipo de marcas 
  (como *esta* o \esta) serán mantenidas por los bloques preformateados o literales.
Mira aquí, he incluido un nivel más de indentación (pero no muy lejos)

fin del ejemplo

Observa que si un párrafo consiste sólo en "::", entonces es borrado por la salida:

::

    Esto es texto preformateado, y el 
    último párrafo "::" es borrado

El resultado es:

Esto es texto preformateado, y el 
último párrafo "::" es borrado
Secciones

Para dividir textos largos en secciones, debes usar cabeceras de sección. Estas son líneas individuales (una o más palabras con un adorno): un subrayado sólo, o un subrayado y una línea superpuesta juntos, con guiones "-----", símbolos de igual "=====", tildes "~~~~~" o cualquier caracter no alfanumérico = - ` : ' " ~ ^ _ * + # < > con el que te sientas cómodo. Un subrayado sólo es distinto a un subrayado y superpuesto usando el mismo carácter. El subrayado o el superposicionado debe ser al menos tan largo como el texto. Se consistente, todas las secciones marcadas con el mismo símbolo estarán situadas al mismo nivel:

Capítulo 1 Título
=================

Sección 1.1 Título
-------------------

Subsección 1.1.1 Título
~~~~~~~~~~~~~~~~~~~~~~~~

Sección 1.2 Título
-------------------

Capítulo 2 Título
=================

El resultado se muestra en la siguiente estructura, ilustrada para simplificar en un seudo XML:

<section>
    <title>
        Capítulo 1 Título
    <section>
        <title>
            Sección 1.1 Título
        <section>
            <title>
                Subsección 1.1.1 Título
    <section>
        <title>
            Sección 1.2 Título
<section>
    <title>
        Capítulo 2 Título

(Seudo XML usa la indentación como muestra y no tiene tags finales. Es imposible mostrar la salida actual procesada, como en otros ejemplos, porque las secciones no pueden existir dentro de bloques. Para un ejemplo concreto, compara la estructura de las secciones de este documento en el texto fuente y procesa la salida)

Nota que las cabeceras de sección están disponibles como destinos de un link, sólo usando su nombre. Para vincular a la cabecera de las 'Listas', escribo "Listas_". Si la cabecera tiene espacios en ella como 'estilos de texto', necesitamos acotar la cabecera "`estilos de texto`_".

Hipervínculos
Hipervínculos con destinos explicitos

Ejemplos:

This sentence has simple link_ in it.

  .. _link: http://www.google.com./

This sentence has a `long link`_ in it.
This one has a link that has an address that's the `same as the long link`_ .

.. _same as the long link: 
.. _long link: http://makeashorterlink.com./

Remember, `link targets`_ are case-insensitive and whitespace-neutral.

.. _LINK   TARGETS: http://pythonowns.blogspot.com/

El resultado es:

This sentence has simple link in it.

This sentence has a long link in it. This one has a link that has an address that's the same as the long link .

Remember, link targets are case-insensitive and whitespace-neutral.

Hipervínculos con destinos implicitos

Por ejemplo

Here is an `implicit link`__ .

.. __:   http://www.python.org./

Shorthand target is used__ below.

__ http://www.kbb.com/

This link has an `inlined <http://www.python.org./>`__ link.

You do not need to have the link__ target before__ the next anonymous link.

__ http://www.w3.org./
__ http://www.archive.org/

produce como resultado

Here is an implicit link .

Shorthand target is used below.

This link has an inlined link.

You do not need to have the link target before the next anonymous link.

Tablas

Observaciones a tener en cuenta.

1. Enumeramos de la siguiente manera
 - Los subapartados los ponemos con guiones, el método es: (espacio, guión, espacio).
 - Escriba el texto que desee.

2. La sintaxis para insertar una tabla sería:

  +-----------------------------------------------------------+
  | **Control de versiones del manual de usuario de gvSIG**   |
  +==========================+================================+
  |                          |1. Se ha incluido la documen    |
  |                          |tación sobre la nueva ventana   |
  |                          |de salvar proyecto de gvSIG.    |
  |Manual Usuario gvSIG 1.1  |                                |
  |Versión 4                 |2. Se ha incluido documentación |
  |                          |sobre la herramienta de         |
  |                          |exportar a ráster.              |
  |                          |                                |
  |                          |3. Se ha dos errores conocidos: |
  |                          |                                |
  |                          |  - Fallo en los resultados de  |
  |                          |    las funciones de agrupamien |
  |                          |    to en el geoproceso disolver|
  |                          |  - Error conocido de la herra  |
  |                          |    mienta "Exportar a raster"  |
  +--------------------------+--------------------------------+

El resultado sería:

Control de versiones del manual de usuario de gvSIG
Manual Usuario gvSIG 1.1 Versión 4

1. Se ha incluido la documen tación sobre la nueva ventana de salvar proyecto de gvSIG.

2. Se ha incluido documentación sobre la herramienta de exportar a ráster.

3. Se han añadido dos errores conocidos:

  • Fallo en los resultados de las funciones de agrupamien to en el geoproceso disolver
  • Error conocido de la herra mienta "Exportar a raster"

Además de esta forma de crear tablas en ReStructuredText, existen otras basadas en directivas. En muchas ocasiones es mas cómodo trabajar con la forma de creación de tablas basada en la directiva list-table. Consulte esto en la siguiente sección.

Directivas standard

Las principales directivas usadas en gvsig.org son:

Directivas especificas de gvsig.org

Note

En construcción

Falta incluir ejemplos y una breve descripción de cada directiva.

En el proyecto gvSIG, se han elaborado algunas directivas que pueden resultar de utilidad en la confección de la documentación. Las más usadas son:

Contenido incluido

Podemos encontrar documentacion adicional sobre ReStructuredText en:

Fin contenido incluido

Se vería así

class Test:

  def TestFunction(self):
     pass

Esta directiva también permite que se muestren los números de línea del código.

.. code-block:: python
  :linenos:
  
  # -*- coding: utf-8 -*-
  """
      The Pygments reStructuredText directive
      ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  
      This fragment is a Docutils_ 0.4 directive that renders source code
      (to HTML only, currently) via Pygments.
  
      To use it, adjust the options below and copy the code into a module
      that you import on initialization.  The code then automatically
      registers the ``code-block`` directive that you can use instead of
      normal code blocks like this::
  
          .. code-block:: python
  
              My code goes here.
  
      If you want to have different code styles, e.g. one with line numbers
      and one without, add formatters with their names in the VARIANTS dict
      below.  You can invoke them instead of the DEFAULT one by using a
      directive option::
  
          .. code-block:: python
              :linenos:
  
              My code goes here.
  
      Look at the `directive documentation`_ to get all the gory details.
  
      .. _Docutils: http://docutils.sf.net/
      .. _directive documentation:
        http://docutils.sourceforge.net/docs/howto/rst-directives.html
  
    :copyright: 2007 by Georg Brandl.
                2008 by Sergio Talens-Oliag (adaptation for the RstCodeBlock)
    :license: BSD, see LICENSE for more details.
  """
  
  # Options
  # ~~~~~~~
  
  # Set to True if you want inline CSS styles instead of classes
  INLINESTYLES = True
  
  from pygments.formatters import HtmlFormatter
  
  # The default formatter
  DEFAULT = HtmlFormatter(noclasses=INLINESTYLES)
  
  # Add name -> formatter pairs for every variant you want to use
  VARIANTS = {
      'linenos': HtmlFormatter(noclasses=INLINESTYLES, linenos=True),
  }
  
  from docutils import nodes
  from docutils.parsers.rst import directives
  
  from pygments import highlight
  from pygments.lexers import get_lexer_by_name, TextLexer
  
  def pygments_directive(name, arguments, options, content, lineno,
                        content_offset, block_text, state, state_machine):
      '''Implement the code-block directive for docutils.'''
      try:
          lexer = get_lexer_by_name(arguments[0])
      except ValueError:
          # no lexer found - use the text one instead of an exception
          lexer = TextLexer()
      # take an arbitrary option if more than one is given
      formatter = options and VARIANTS[options.keys()[0]] or DEFAULT
      parsed = highlight(u'\n'.join(content), lexer, formatter)
      return [nodes.raw('', parsed, format='html')]
  
  pygments_directive.arguments = (1, 0, 1)
  pygments_directive.content = 1
  pygments_directive.options = dict([(key, directives.flag) for key in VARIANTS])
  
  directives.register_directive('code-block', pygments_directive)

Se vería

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
# -*- coding: utf-8 -*-
"""
    The Pygments reStructuredText directive
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    This fragment is a Docutils_ 0.4 directive that renders source code
    (to HTML only, currently) via Pygments.

    To use it, adjust the options below and copy the code into a module
    that you import on initialization.  The code then automatically
    registers the ``code-block`` directive that you can use instead of
    normal code blocks like this::

        .. code-block:: python

            My code goes here.

    If you want to have different code styles, e.g. one with line numbers
    and one without, add formatters with their names in the VARIANTS dict
    below.  You can invoke them instead of the DEFAULT one by using a
    directive option::

        .. code-block:: python
            :linenos:

            My code goes here.

    Look at the `directive documentation`_ to get all the gory details.

    .. _Docutils: http://docutils.sf.net/
    .. _directive documentation:
       http://docutils.sourceforge.net/docs/howto/rst-directives.html

   :copyright: 2007 by Georg Brandl.
                2008 by Sergio Talens-Oliag (adaptation for the RstCodeBlock)
    :license: BSD, see LICENSE for more details.
"""

# Options
# ~~~~~~~

# Set to True if you want inline CSS styles instead of classes
INLINESTYLES = True

from pygments.formatters import HtmlFormatter

# The default formatter
DEFAULT = HtmlFormatter(noclasses=INLINESTYLES)

# Add name -> formatter pairs for every variant you want to use
VARIANTS = {
    'linenos': HtmlFormatter(noclasses=INLINESTYLES, linenos=True),
}

from docutils import nodes
from docutils.parsers.rst import directives

from pygments import highlight
from pygments.lexers import get_lexer_by_name, TextLexer

def pygments_directive(name, arguments, options, content, lineno,
                       content_offset, block_text, state, state_machine):
    '''Implement the code-block directive for docutils.'''
    try:
        lexer = get_lexer_by_name(arguments[0])
    except ValueError:
        # no lexer found - use the text one instead of an exception
        lexer = TextLexer()
    # take an arbitrary option if more than one is given
    formatter = options and VARIANTS[options.keys()[0]] or DEFAULT
    parsed = highlight(u'\n'.join(content), lexer, formatter)
    return [nodes.raw('', parsed, format='html')]

pygments_directive.arguments = (1, 0, 1)
pygments_directive.content = 1
pygments_directive.options = dict([(key, directives.flag) for key in VARIANTS])

directives.register_directive('code-block', pygments_directive)

Documentacion adicional

Podemos encontrar documentacion adicional sobre ReStructuredText en:


Imágenes en la documentación

Introducción

A la hora de elaborar documentación es muy normal la inclusión de imágenes en ella. Las imágenes suelen ayudar a comprender la utilización de una herramienta o nos muestran un esquema que aclara la utilización de una librería.

A la hora de incluir esas imágenes en la documentación hay que tener en cuenta:

Estructura de carpetas

A la hora de incluir imágenes en la documentación tenderemos a estructurar las carpetas de una de las dos siguientes formas:

Sea uno u otro el caso tendremos que tener en cuenta las siguientes consideraciones:

Nombrado

El nombre que se le de a la imagen debe ser descriptivo.

Ejemplo:

No vale Boton1, debe ser botonAñadirNuevaCapa

A la imagen que no tienen la paleta de colores optimizada se la identifica con un sufijo "-24". La imagen con la paleta optimizada no llevará sufijo.

Ejemplo:

botonAñadirNuevaCapa-24.png

También se le añade un sufijo que haga referencia al idioma de la interface de usuario cuando se capturó la imagen, usando la nomenclatura de la iso639.

Ejemplo:

Un imagen que haya sido capturada con la interface de usuario en castellano debe ir acompañada del sufijo "es"

botonAñadirNuevaCapa-es.png

Calidad

Tip

Es recomendable que lea el apartado "Inclusion de imágenes o diagramas" del documento Normas y recomendaciones

Normalmente cuando estemos capturando imágenes para la aplicación almacenaremos dos o tres archivos:

El utilizar archivos PNG cuya paleta de colores está optimizada se debe a que la exportación de la documentación a formatos PDF es capaz de optimizar mucho mejor el almacenamiento de imágenes en paleta de colores que en color de 24 bits.

El programa que utilizamos para la captura de imágenes es Gimp Con él, una vez capturada la imágen se optimiza la paleta de colores, adecuándola al número de colores necesario para que la imágen no pierda calidad. El criterio es visual. Como regla puede decirse que un botón por ejemplo "Cancelar" se ve bien con una paleta de 8 o 16 colores y una imágen de 3D con mucho colorido no suele necesitar más de 64.

El menú de optimización de la paleta de colores está en Imagen -> Modo -> Indexado.

images/en/gimp-menu-image-mode.png

Menú optimizar paleta de colores

En la ventana podemos seleccionar el número de colores que queremos y el modo de optimización.

images/en/gimp-dialog-indexed-color-conversion.png

Ventana optimización de la paleta de colores.

Como ya se ha comentado, es recomendable dejar accesibles los 2 archivos (el de la imágen optimizada y el que no tiene la paleta optimizada). La razón es que si luego se quiere realizar algún tratamiento a la imágen, por ejemplo resaltar un área, recortarla o escalarla, ... la imágen con la paleta optimizada no tiene la misma calidad que la imágen que no tiene la paleta optimizada.

Como nota final, tener en cuenta que la imagen debe guardarse sin compresión.

Subir y enlazar una imagen en un documento

Para subir una imagen, se deberá acceder al directorio previo al del documento y acceder a la carpeta "images" (si no está creada se deberá crear con el menú "agregar un nuevo ítem"-->"carpeta"). Dentro de la carpeta "images" deberá haber una carpeta por cada idioma al que esté traducido el documento (es: español, en: inglés, it: italiano, de:alemán...), y dentro de cada carpeta de cada idioma deberá haber el mismo número de imágenes. Si la carpeta no está creada se creará como se ha comentado anteriormente. Después se entrará en la carpeta del idioma correspondiente, y se seleccionará la pestaña "agregar un nuevo ítem"-->"imagen".

images/es/pestanya_agregar_imagen_8.png

Pestaña Agregar imagen

En la siguiente ventana se pondrá el título y con el comando "Examinar" se buscará la imagen a subir al servidor. Finalmente se ejecutará el comando "Guardar".

Para enlazar una imagen desde la traducción del documento, si por ejemplo el idioma desde el cual se está traduciendo es el español, se dispondrá del siguiente texto:

.. figure:: images/es/pestanya_agregar_imagen_1.png
   :align: center

donde "es" es el nombre de la carpeta correspondiente al español. Se deberá sustituir el nombre de dicha carpeta por el de la carpeta donde están las imágenes del nuevo idioma, así como el nombre de la imagen que se ha subido previamente al servidor en el nuevo idioma. Por ejemplo, en la traducción a inglés podría ser:

.. figure::images/en/add_image_tab_1.png
   :align: center

Maquetación de la documentación

Note

En construcción

Aquí habría que ver de implementar la cosa que a partir de un freemind te permita verlo como un TOC y navegar por él igual que por el toc normal de los documentos. Tambien habría que ver algún tipo de herramienta para exportar cosas al freemind y contar como trabajar con estas cosas.

Herramientas a utilizar

Note

Esta página está en construcción están pendientes de actualizar todos los enlaces.

También habría que repasar a ver que otras herramientas se recomiendan para su uso. Seguro que me he dejado algunas.

De cara a confeccionar la documentación podemos precisar de herramientas específicas. Normalmente siempre utilizaremos herramientas de libre distribución, preferentemente bajo licencia GPL o LGPL, y que sean multiplataforma, habiendo versiones de estas al menos para Linux (Ubuntu y derivados) y MS Windows.

Hay que tener en cuenta que no sólo se confecciona documentación de cara a ser publicada o entregada sin más. Además de la documentación final se debe entregar toda la documentación intermedia que se ha usado para confeccionar la documentación final, y hay que pensar que el documento que ha entregado hoy un equipo de trabajo puede tener que ser actualizado dentro de un año por otro grupo de trabajo distinto y debe disponer de toda la información necesaria para hacerlo, así como de las herramientas adecuadas.

Esto nos lleva a que las herramientas a utilizar deben ser homogéneas a lo largo de todo el proyecto y sus distintos grupos de trabajo, y que deben ser de libre distribución y multiplataforma, ya que si no obligaría a adquirir un software especifico al equipo de trabajo que tuviese que mantener en un futuro esa documentación.

Desde el proyecto las herramientas que se recomiendan son las siguientes:

En caso de que se precisase una herramienta diferente a estas para realizar las tareas que en otras partes de gvSIG se están haciendo con una de estas, deberá ser aprobado por el responsable de esa seccion en la EPg o el responsable del área de infraestructura de la EPg.


Apéndices

Cómo subir un archivo HTML al Plone

Los tipos de documentos más comunes en la web de gvsig.org son:

Tip

Puede encontrar más informacion relacionada con los distintos tipos de documentos en la web de gvSIG en el documento Tipos de contenidos

Normalmente para trabajar usaremos los tipo de carpeta y el de página.

Si tenemos un archivo HTML y queremos subirlo a la web, crearemos un documento de tipo Página.

como-subir-un-archivo-html-al-plone.data/es/additempage.png

Creando un documento de tipo página

Una vez estemos en la página de edición del documento, seleccionaremos el formato del documento como HTML e insertaremos en la caja de texto Body Text el contenido HTML que queramos subir.

como-subir-un-archivo-html-al-plone.data/es/inserthtml.png

Seleccionar Text Format como HTML

Una vez tengamos en el contenido pulsaremos en el botón guardar al final de la página.

Como instalar el plugin de ReST en gedit

La versión de Ubuntu sobre la que vamos a trabajar es:

$ lsb_release -a
No LSB modules are available.
Distributor ID:       Ubuntu
Description:  Ubuntu 10.04 LTS
Release:      10.04
Codename:     lucid

Instalaremos las dependencias:

$ sudo apt-get install gedit gedit-plugins python-pygments python-docutils libgtkhtml2-0 
$ cd /tmp
$ wget http://launchpadlibrarian.net/33347197/python-gtkhtml2_2.25.3-3ubuntu1_i386.deb
$ sudo dpkg -i python-gtkhtml2_2.25.3-3ubuntu1_i386.deb

Y con esto ya estará disponible para usar el plugin en el gedit. Habrá que ir a preferencias y en complementos activar el plugin Markup preview.

Para poder acceder a la funcionalidad deberemos activar en el menú ver la opción Panel inferior, y luego en el menú Herramientas usaremos la opción Markup preview para previsualizar nuestro documento.

Si se quiere una versión mas moderna del plugin ir a http://kib2.alwaysdata.net/GEdit/ y descargar lo en /tmp .

Luego creamos una carpeta en la que sacar una copia de respaldo del plugin que venia con el sistema:

~/.gnome2/gedit/plugins/save/restplugin-system

Y movemos de ~/.gnome2/gedit/plugins los archivos :

a ella. Extraemos del zip los archivos :

En ~/.gnome2/gedit/plugins

Y con esto habremos sustituido el plugin que viene con la distribución por la nueva versión.

Bibliografia

Cached time 11/21/13 16:09:59 Clear cache and reload