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.
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:
- El autor debe tener en todo momento presente qué y para
quién escribe. El destinatario del texto es el usuario.
- 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.
- El objetivo primordial del texto es que el lector comprenda
la herramienta y cómo usarla.
A la hora de ponernos a confeccionar la documentación contemplaremos
tres fases o momentos a tener en cuenta:
- La planificación
- La redacción.
- La revisió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.
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
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.
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:
- No deben usarse abreviaturas en el título ni en el resumen.
- No se deben abreviar términos cortos.
- No se deben abreviar términos que se usan pocas veces.
- No inventes abreviaturas
- No comiences las oraciones con abreviaturas.
Tampoco comiences las oraciones con números.
- 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.
- Abrevia las unidades de medida cuando están precedidas de
dígitos, pero no cuando son sustantivos.
- 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.
When you insert a picture or diagram in a document, it should be
into account certain considerations.
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.
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:
- 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.
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.
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.
- 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.
- 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.
- Never number the headings or sections within a document.
- 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 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:
Folders. There are 2 types of folders:
Folder is used for content that can not or
should not be translated into other languages. They are primarily used for
group images, documents generated by CASE tools,
diagrams, and generally any supplementary file to the documentation
textual.
Sometimes it is necessary to be able to differentiate this type of content
depending on the language, for example with the images that accompany textbooks.
As already mentioned this content can not be translated so that the mechanism
to have different content depending on the language to create different folders
one per language.
Folders containing pictures, diagrams, ..., and in general those that
have content to be printed should be checked
property excluded from the navigation. To enable this feature select
properties tab and check the check exclude from nav.
Folders (i18n) are used to house those contained susceptible
be translated into other languages ??so that it is itself which manages Plone
which is displayed at any given time. These folders have the advantage of maintaining
teachers linked documents and their translations.
**Pages **. The pages must be written as ReStructuredText.
System Message: WARNING/2 (<string>, line 56); backlink
Inline strong start-string without end-string.
System Message: WARNING/2 (<string>, line 56); backlink
Inline strong start-string without end-string.
Link. Allows link to a page or folder on or off
Plone site.
Image. This type of document is the use
to store our images.
Archive. It is a kind of general document that we
will attach additional documents to images or
textual documentation. In general we will not use this document type.
Note
Although using this type of content allows us to * raise * any
gvsig.org * file * is not recommended to upload files as binary
OpenOffice and Zip files. ** The website is not a system gvsig.org
file sharing **. This type of content overload the DB
content manager and to locate these documents using
search the site. Minimize the use of such
content.
System Message: WARNING/2 (<string>, line 72); backlink
Inline strong start-string without end-string.
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:
- borrador. Es el estado en el que está un documento recién
creado. En este estado, el documento es sólo visible para los
usuarios registrados.
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.
publicado. En este estado el documento es visible a cualquier
usuario, registrado o no, pero no puede ser modificado. Sólo el
administrador puede modificar un documento publicado directamente.
Para modificar un documento que se encuentra publicado, este debe
ser retirado, lo que provoca que el documento pase a estado
borrador.
privado. En este estado el documento únicamente es accesible por
el usuario que lo creo o aquellos a los que este ha dado permiso
para acceder a él. El resto de usuarios no pueden acceder al documento
tanto para su visualización como para su modificación.
Los usuarios con permiso de acceso a un documento en estado privado
podrán tanto ver como modificar el documento.
pendiente. Este estado es un estado de transición. El creador
del documento ha dado por finalizada la confección de él y desea que
pase a estado publicado. Envía el documento para ser publicado
y se queda en estado pendiente hasta que un revisor da por bueno
el documento y lo publica. Mientras el documento está en estado
pendiente, este es visible por cualquier usuario.
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:
- borrador, aparecen de color verde.
- publicado, aparecen de color azul.
- privado, aparecen de color rojo.
- pendiente, aparecen de color naranja.
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.
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:
Para contenidos de tipo página normalmente usaremos gvSIG document view,
que es la vista por defecto para estos en gvsig.org, y no deberemos cambiarla.
- gvSIG document view. Es la presentación usada para mostrar un documento
en gvsig.org.
- Document view. Se trata de la visualización standard de Plone para
este tipo de documento. Normalmente no la usaremos.
- gvSIG document and parent folder listing. Se trata de una visualización que
nos mostrará el contenido del documento igual que gvSIG document view, añadiendo
al final el listado de documentos que hay en la carpeta contenedora de este.
Para contenidos de tipo carpeta existen mas opciones en gvsig.org, y
deberemos tener en cuenta qué es lo que queremos obtener para elegir la opción que más
nos interese en cada momento. Las vistas de que disponemos son:
gvSIG folder listing (internationalizable support). Es la vista por
defecto de una carpeta en gvsig.org. Esta vista nos muestra los
contenidos de la carpeta uno tras otros con su título, resumen, estado y
tipo y autor. Además se encarga de mostrar la mejor opción posible en
cuanto a idioma disponible de cada documento.
gvsig_folder_listing_exclude_from_nav, es similar a la anterior, pero
no muestra los elementos que están excluidos de la navegación.
gvSIG folder TOC. Esta es la vista de tabla de contenidos de una carpeta y
sus subcarpetas. Se muestran todos los títulos de los documentos de la carpeta
y subcarpetas en forma de tabla de contenidos, con la posibilidad de pedir que
además del índice, nos confeccione un documento con todos los contenidos de la
carpeta.
Esta vista es útil para la visualización de manuales y guías, ya que nos
mostrará un índice de éstos, permitiéndonos ver todo el manual en una única
página. Muy útil si queremos descargarnos el contenido para imprimirlo o insertarlo en
un documento de OpenOffice para una maquetación más refinada.
Vista tabular, muestra el listado de documentos en formato tabla.
gvSIG work group space view, se trata de una vista utilizada para la
gestión de las carpetas que actúan como carpeta raíz para un grupo de trabajo.
Normalmente no la usaremos nunca cuando estemos confeccionando documentación.
Además de estos tipos de vista dispondremos de la posibilidad de usar como vista por
defecto de una carpeta un documento de ésta. Normalmente un documento de tipo página.
Esto causará que cuando naveguemos a la carpeta se muestre automáticamente el
documento de tipo página seleccionado.
Cuando se haya seleccionado este tipo de vista, podremos acceder a los documentos de la
carpeta a través de la pestaña contenidos.
Para los contenidos de tipo Archivo también contamos con un par de vistas.
- View File, es la vista standard de plone. Si tenemos problemas con este
contenido o dudas sobre qué vista utilizar usaremos ésta.
- View Freemind File, usaremos esta vista en archivos de tipo FreeMind.
Esta vista nos permitirá una visualización preliminar del documento utilizando
un plugin de flash.
- gvSIG file view. Esta es la vista que usaremos por defecto para los
archivos en gvsig.org. Se encargará de realizar una previsualización del
archivo. Normalmente nos permitirá previsualizar archivos de tipo OpenOffice Writer
y Gantt Project.
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:
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.
Para crear una versión de un documento hay que marcar el check "Save as new version" cuando se guarda el documento.
Una vez que se marca aparece un área de texto que permite la introducción de un comentario de la nueva versión.
A continuación lo único que hay que hacer es guardar el documento y tendremos una nueva versión del mismo generada.
Cuando un documento tiene versiones aparece en la cabecera del documento una entrada llamada "Recent versions"
Si se despliega pulsando sobre el símbolo "+" se muestra una tabla con las últimas versiones que se han realizado del documento.
También puede accederse a la tabla de versiones desde la pestaña "Versions"
La tabla muestra:
- Version: Número de versión
- Performed by: Usuario que ha creado la nueva versión del documento
- Date and Time: Cuándo se ha realizado la nueva versión del documento
- Comment: Comentario que se puso cuando se creó la nueva versión
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.
Desde la página de versiones de un documento pueden realizarse varias acciones.
- Diff to previous version: Muestra las diferencias entre el estado del documento actual y la última versión guardada. Esta posibilidad aparece cuando el documento ha sido modificado pero no se ha generado una nueva versión.
- Diff to current: Al contario que la acción anterior muestra las diferencias entre una versión guardada y el estado actual del documento.
- Diff from last: Muestra las diferencias entre una versión de un documento y su versión inmediatamente anterior.
- revert: Deja el documento en el estado en el que estaba en la versión que se ha seleccionado. Si se utiliza esta acción hay que tener cuidado porque la copia de trabajo se pierde.
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.
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.
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)".
The first step before translating a page is to withdraw the following pages:
- The source page to be translated from (source language)
- The page of the master language (generally it's the Spanish in the user and developer manuals), that is the language of the first version of the document.
- The page of the target language to be translate to (in case the target language page already exist and some translation is to be done).
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".
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".
The following interface will be shown next
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.
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.
The following interface will be shown next
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.
The user's and developer's manuals are groups of documents.
The accesses to the user's documentation from the index of the manual are only links to the different documents (sections of the manual).
The documents mustn't be copied to another folders to translate them. To do the translation, it has to be done from the documents directly.
The document of the master language (the language of the first version of the document) and the document in the origin language that is going to be translated to the new one have to be retracted previously, so they won't be available for the users in that time. It's interesting that if the translation will be long, the text is translated in a text file separately and when the translation is finished, the documents of the web portal are retracted, coping the translation to the column of the new language (keeping the format of the text) and then sending the documents to publish.
- To translate a document:
- If it hasn't been translated to the destination language yet, the document of the origin language and the master language will have to be retracted first. Then the Translate to tab will be selected and then the destination language.
- If it was translated previously, the documents of the origin, master and destination languages will have to be retracted. Then the destination language will be selected through the corresponding flag, and clicking the Edit command finally.
If the document of the origin language and the master language are rejected to do the translation to the destination language but the translation hasn't been finished, the changes can be saved in the destination language, and then only the document of the origin language and the master one must be sent to publish. The document of the destination language mustn't be sent until its finishing. Another day the translation can be continued rejecting the origin language and the master one another time.
The manuals of the web portal are made in reStructured text. When the translation is going to be made, there are two columns (the origin language and the destination one). First of all, the "Text format" box has to be changed to "reStructured text" (not HTML).
It can be useful to consult the next documents:
- Select "Traducir a" ---->English
- At the opened window:
- Translate the title at the right section.
- Change the "Text Format" option to "reStructured Text".
- At the right row, write the following text at the first line:
- **Direct translation from Google translator**
- Select the text at the left column (at the "Body text" box), and copy it in Google Translator.
- Translate it from Spanish to English and copy the results to the right column at the gvSIG website, after the sentence written previously.
- Do the following corrections in order that the format is the same than the text in Spanish:
- Remove the spaces around the asterisks.
- Check the spaces at the beginning of the line.
- For every image, remove the space existing before the word "align" (the results will be ":align")
- Press "Save".
- Chek if there are format errors (orange boxes).
- To correct the errors, press the "Edit" tab (upper left-hand section)
- Check the spaces existing at the English text are the same than in Spanish. Once corrected, press Save again.
- Finally, Spanish language must be selected (press its flag), and then "Estado"----->"Enviar". The English document won't be sent at the moment. A supervisor will chek the translation.
- Change the language to English (press its flag).
- Press the "Edit" tab (upper left-hand section).
- Check the translation of the title at the right section.
- Check the translation of the English text at the right row, and correct it.
- Once corrected, remove the text "**Direct translation from Google translator**" at the first line.
- Check if the text is good, othewise edit again.
- Once saved the document, the "Estado" option must be changet to "Submit".
- Finally, change to Spanish, and then press "Estado"----->"Enviar".
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
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
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.
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:
- Manager. Cuando un usuario tiene asignado este perfil para
un documento, podrá realizar cualquier operación sobre él como
si se tratase del administrador del sitio.
- Revisor, al asignar a un usuario este perfil para un documento,
el usuario podrá revisar y aceptar peticiones de publicación del documento.
- Propietario, dará la opción de modificar el documento a los usuarios
que tengan asignado este perfil, además podrán otorgar permisos y cambiar el estado del documento.
- Miembro, se trata del perfil más bajo que podemos asignar a un
usuario para un documento, y haremos que sólo pueda ver el documento
y no modificarlo.
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.
Cuando damos de alta un documento en org.gvsig de tipo Página,
deberemos indicar:
- Nombre corto. Se trata del nombre del documento
usado en la URL de acceso a él. Normalmente no se muestra
en la web, excepto para crear enlaces al mismo.
- Título. Se trata del nombre que normalmente se muestra
al aparecer el documento en un listado, por ejemplo en
una búsqueda o al mostrarse los contenidos de una carpeta.
- Description. Se trata de una pequeña descripción que podemos
asociar al documento. Esta se ve al mostrarse los contenidos
de una carpeta bajo el título del documento.
- Cuerpo del texto. Constituye el cuerpo del documento. Normalmente
compuesto en formato ReStructuredText.
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:
- id
- plone
- search
- forum
- description
- web
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.
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.
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:
``\*``
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í):
- números
Letras mayúsculas
y que se dividan en varias líneas
con dos párrafos y todo
- letras en minúscula
- Con una sublista que comienza con un número diferente
- asegurate que los números están en la secuencia correcta
- números romanos en mayúscula
- números romanos en minúscula
- números otra vez
- 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:
- una viñeta usando "*"
- una sub lista usando "-"
- otro elemento
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
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`_".
- Los hipervínculos explícitos tienen 2 partes; la etiqueta y el nombre del "objetivo" del enlace.
- Delimita la etiqueta del enlace rodeandolo de comillas simples inversas "`" y finalizalo con un subrayado "(`etiqueta`_)".
- Si no hay espacios en blanco ni signos de puntuación puedes finalizarlo con un subrayado y olvidar las comillas.
- (FIXME) Label of link regex representation (approx.): [^s]_|`.+`_
- El objetivo estará cumplido empezando por 2 '.', espacio en blanco, y un '_', la etiqueta del enlace, un ':' y un espacio en blanco (.. _label:).
- Los objetivos son neutrales al espacio en blanco y no distinguen entre mayúsculas y minúsculas.
- (FIXME) Target of link regex representation (approx.): ..w+_.+:w+
- Una vez que el objetivo es definido, lo está para todo el documento y puede ser ubicado en cualquier lugar del documento.
- Los objetivos deben ser separados por líneas en blanco de cualquier cosa que no sea un objetivo. Los objetivos pueden ser listados uno detrás de otro.
- Redefinir el objetivo dará un error
- Si un objetivo no tiene una dirección dada coge la del siguiente objetivo, permitinedo cambios (para abreviados y versiones largas, por ejemplo).
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.
- Los hipervínculos implícitos no necesitan que sus objetivos se nombren como los hipervínculos explícitos.
- Los hipervínculos implícitos pueden definirse de 2 maneras, en línea y no en línea
- La etiqueta de un hipervínculo 'no en línea' está marcada como la etiqueta de un hipervínculo explícito excepto que '__' es usado en vez de '-'.
- Non-inline hyperlink regex representation (approx.): [^s]__|`.+`__
- El objetivo para un hipervínculo implícito no en línea se caracteriza por '..', espacio en blanco, '__:', y un espacio en blanco (.. __: ); el subrayado son 2 guiones bajos y un espacio en blanco (__ ).
- Non-inline target regex representation (approx.): __s+.+|..s+__:s+.+
- No es necesario tener definido el objetivo antes que el siguiente vínculo anónimo, se resuelven en orden
- La etiqueta de un hipervínculo 'en línea' tienen la forma `etiqueta <hipervínculo>`__ .
- Inline hyperlink regex representation (approx.): `.+s+<.+>`__
- Se cuiadadoso con los hipervínculo en línea porque pueden volverse muy largos.
- Cuando tengas errores sobre que tienes más vínculos que objetivos, trata de solucionarlo buscando __ y comprueba que esto significa que debe ser implícito y que si es en línea que el vínculo está escrito.
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.
Observaciones a tener en cuenta.
- Aunque se centre el texto en la celda de la tabla, éste no se visualizará centrado, a no ser que sea el título, en este caso si surte efecto.
- Para hacer una lista enumerada no utilices sangrías, utiliza números o letras para los apartados y para los subapartados guiones "-"
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.
Las principales directivas usadas en gvsig.org son:
contents. Permiten insertar una tabla de contenidos en el
documento. Su uso seria:
.. contents:: Titulo de la tabla de contenidos.
Aunque es muy útil esta directiva, en el contexto de la generación de
documentación en gvsig.org, hay que llevar especial cuidado con ella,
ya que es normal que luego un documento pase a formar parte de otro
documento mayor, y si este tiene insertada alguna tabla de contenidos
nos la encontraremos en medio del documento que lo contenga.
figure. Permite insertar imágenes dentro del documento.
Una figura consiste en datos de imagen (archivo de imagen),
un pie de imagen (un párrafo), y opcionalmente una leyenda
La sintaxis para insertar una imagen sería
.. figure:: imagenes_src/picture.png
:align: center
Este es el pie de la imagen (sólo un párrafo).
La leyenda consiste en los elementos posteriores al pie. en este caso,
la leyenda es este párrafo.
y el resultado sería
Es recomendable dejar una línea en blanco por encima y por debajo de la
figure que se quiere insertar y no indentar la línea.
Correcto
Párrafo anterior a la figure
..figure:: images_src/picture.png
Párrafo posterior a la figure
No recomendado
Párrafo anterior a la figure
..figure:: images_src/picture.png
Párrafo anterior a la figure
..figure:: images_src/picture.png
list-table. Nos permite insertar una tabla definiéndola como
una lista de dos niveles, donde el primer nivel define las lineas y
el segundo los valores de las celdas de la linea.
Veamos un ejemplo:
.. list-table:: Frozen Delights!
:widths: 15 10 30
:header-rows: 1
* - Treat
- Quantity
- Description
* - Albatross
- 2.99
- On a stick!
* - Crunchy Frog
- 1.49
- If we took the bones out, it wouldn't be
crunchy, now would it?
* - Gannet Ripple
- 1.99
- On a stick!
Donde cada '*' indica el comienzo de una fila y cada '-' el comienzo de una celda.
El resultado sería
Frozen Delights!
Treat
|
Quantity
|
Description
|
|---|
Albatross
|
2.99
|
On a stick!
|
Crunchy Frog
|
1.49
|
If we took the bones out, it wouldn't be
crunchy, now would it?
|
Gannet Ripple
|
1.99
|
On a stick!
|
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:
include-document.
Esta directiva permite invocar un documento para que sea incluido en el documento en el que se invoca la directiva.
La sintaxis de la directiva es
.. include-document:: ruta-de-la-pagina-a-incluir
:formato:
El formato es opcional, si no se indica nada se entiende que debe renderizarse como 'rest'.
Ejemplo
.. include-document:: ./documentacion-adicional
:rest:
Contenido incluido
Podemos encontrar documentacion adicional sobre ReStructuredText en:
Fin contenido incluido
code-block
Esta directiva permite "colorear" el código fuente que sigue a la directiva. La sintaxis es la siguiente
.. code-block:: languaje
My code goes here.
Por ejemplo si nuestro código es python:
.. code-block:: python
class Test:
def TestFunction(self):
pass
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)
|
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:
- Que estén completas. Si son capturas de pantalla deberemos asegurarnos
que estas son de la versión de la aplicación adecuada y que las cadenas
que aparecen en ella están correctamente traducidas al menos a inglés.
- Dónde dejarlas, qué estructura de carpetas debemos usar para almacenarlas
en gvsig.org.
- Cómo nombrarlas, criterio de nombrado de las imágenes que debemos utilizar.
- Calidad de estas, resolución y profundidad de color que debemos
utilizar.
A la hora de incluir imágenes en la documentación tenderemos a estructurar las carpetas
de una de las dos siguientes formas:
Agrupando las imágenes en una sola carpeta. Si estamos documentando una funcionalidad
concreta, crearemos una carpeta para albergar la documentación de esa funcionalidad,
y dentro de ella crearemos una carpeta images en la que dejaremos todas las
imágenes que precise nuestra documentación (en algunos casos en la documentación
de desarrollo data, ya que es común subir junto con las imágenes los archivos
fuentes de los modelos que se documenta)
Agrupando las imágenes en una carpeta por documento que creemos.
Normalmente las imágenes que se capturan se dejan en una carpeta
llamada como el documento que tiene la descripción de la funcionalidad
añadiendo el sufijo "img". Dentro de esta carpeta imágenes, se crea
una carpeta por cada idioma del que se dispongan imágenes, añadiendo
el sufijo indicado para el idioma de que se trate según lo especificado en la iso639.
Ejemplo:
(D) introduccion a gvSIG
(F) introduccion a gvSIG
(D) introduccion a gvSIG.img
(D) es
(F) img1-24-es.png
(F) img1-es.png
(D) en
(F) img1-24-en.png
(F) img1-en.png
Nota:
(D) Directorio/Carpeta
(F) Archivo
Sea uno u otro el caso tendremos que tener en cuenta las siguientes consideraciones:
- La carpeta donde se dejan caer las imágenes no será de tipo carpeta
(i18n).
- Si las imágenes han de ser dependientes del idioma, se creará una carpeta en,
es en la que se dejaran caer las imágenes correspondientes al idioma.
- La carpeta de imágenes se excluirá de la navegación (ver
Cómo excluir un documento de la navegación ).
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
Normalmente cuando estemos capturando imágenes para la aplicación almacenaremos dos o
tres archivos:
- Una captura de pantalla de buena calidad con una paleta de colores de 24 bits o verdadero color
en formato PNG. Esta imagen será la imagen principal, de gran tamaño y servirá de
respaldo en cualquier momento.
- En el caso de que sea necesario, se adjuntara el archivo ODG de OpenOffice Draw con
la composición gráfica realizada con la imagen original de calidad.
El documento del Draw debe tener una página de tamaño A4 sobre la que se
monta la composición.
Para realizar la exportación a PNG se deben seleccionar los elementos de la composición
y exportarla. De esta forma se generará un imagen del tamaño necesario para contener el montaje.
- Una imagen a partir de la imagen principal o de la imagen del montaje, pero de menor calidad
y por lo tanto de menor peso también en formato PNG. En este caso se debe utilizar
una paleta de colores lo más baja posible, siempre y cuando no se produzcan pérdidas
significativas en la resolución. Estas imágenes son las que se insertarán en la documentación.
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.
En la ventana podemos seleccionar el número de colores que queremos y el modo de optimización.
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.
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".
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
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.
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:
Como procesador de textos.
Se usará OpenOffice Writer version 2 o superior. En caso de que se
utilice otro procesador de textos, los documentos que se entreguen al proyecto
deberan estar en formato ODT.
Como editor de imagenes (bitmap)
Se usará Gimp, usandose preferiblemente formatos PNG con paleta de colores
y JPG para color RGB, Existe versión de esta herramienta tanto para plataforma
Linux como Windows.
Como editor de gráficos vectoriales
Se usara el InkScape usando formato SVG.
Como editor de diagramas
A la hora de confeccionar diagramas de uso general se prefiere el uso
de OpenOffice Draw, y para diagramas especificos UML el ArgoUML.
Como herramientas alternativas, se podrían usar:
Herramientas de gestion de proyecto
Se usará preferentemente OpenProject y como alternativa GantProject.
Herramienta de Mind Mapping
Se usará la herramienta FreeMind version 0.9.
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.
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
- Carpeta y Carpeta i18n
- Pagina
- Imagen
- Archivo
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.
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.
Una vez tengamos en el contenido pulsaremos en el botón guardar al final
de la página.
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 :
- codeblock.py
- codeblock.pyc
- markuppreview.gedit-plugin
- markuppreview.py
- markuppreview.pyc
a ella. Extraemos del zip los archivos :
- reSt.gedit-plugin
- reStPlugin
En ~/.gnome2/gedit/plugins
Y con esto habremos sustituido el plugin que viene con la distribución por la nueva versión.
- El proceso lógico en la redacción, http://www.arrakis.es/~serprof/redac.html
- Manual de Redacción Científica, http://www.emagister.com/manual-redaccion-cientifica-cursos-312647.htm
- Textos cinetíficos, humanísticos y técnicos, http://www.auladeletras.net, http://www.auladeletras.net/material/ciencia.PDF
- A ReStructuredText Primer, http://docutils.sourceforge.net/docs/user/rst/quickstart.html
- Quick reStructuredText, http://docutils.sourceforge.net/docs/user/rst/quickref.html
- reStructuredText Directives, http://docutils.sourceforge.net/docs/ref/rst/directives.html
- reStructuredText Markup Specification, http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html
- ISO 639, http://es.wikipedia.org/wiki/ISO_639-1
Cached time 11/21/13 16:09:59 
