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.

• 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:

• Cómo cambiar el tipo de vista de un documento
• Cómo excluir un documento de la navegació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.

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

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.

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.

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

Recent versions

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

Tabla de versiones

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

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.

Página de versiones con vista previa

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

Tabla de versiones

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

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

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

Translate into Tab

The following interface will be shown next

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.

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.

Edit Tab

The following interface will be shown next

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.

• 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:

• How to translate documents to English with Google Translator and how to review them
• How to insert an image in a document

• Translation of a document with Google Translator (Download video-demo - 65.2 MB, View the video at Viddler.com):
  •  Go to the document to translate (in Spanish).
  • Go to the "Estado" option and change it  to "Retirar" (upper right-hand section). It'll change to "Draft".

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

• Supervision of the translated documents (Download video-demo - 24.5 MB, View the video at Viddler.com):
  • Go to the document to check (in Spanish).
  • Go to the "Estado" option and change it  to "Retirar" (upper right-hand section). It'll change to "Draft".

• Change the language to English (press its flag).
• Press the "Edit" tab (upper left-hand section).



• At the opened window:

• 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.
• Press "Save".
• 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

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.

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