CoffeeBrain-UserGuide
|
[[File:{{{image}}}|280px]] |
Descripción: Este documento presenta una guía básica a tener en cuenta para crear y editar artículos en la Wiki-CoffeeBrain. A lo largo del texto se describen los pasos necesarios para la utilización de las extensiones dispuestas en la Wiki. Así mismo, se presenta una breve descripción de herramientas html con la finalidad de facilitar el desarrollo y organización de la documentación. Por último, se presentan las normas que cada editor debe cumplir en relación al manejo de extensiones y al estilo de la Wiki-CoffeeBrain. |
|
Autor: Fredy E. Segura-Quijano (fsegura@uniandes.edu.co )
|
La Wiki-CoffeeBrain está estructurada sobre MediaWiki, un software libre basado en lenguaje de programación PHP. En particular, este software permite el uso de extensiones o plug-ins para extender la funcionalidad de la misma. Adicionalmente, permite la utilización de elementos html así como elementos propios que en este caso son empleados para soportar el estilo e imagen de Wiki-CoffeeBrain. A continuación se presentan las instrucciones y reglas para interactuar con dichos elementos. IMPORTANTE: para la edición de documentos en la Wiki-CoffeeBrain se necesita de un usuario con los permisos correspondientes. Para solicitar la creación de un usuario contactar a:
Edición general de artículos
MediaWiki provee algunas herramientas para la edición básica de artículos, las más relevantes son presentadas a continuación.
Editor de artículos
Un vez otorgado el usuario con los permiso correspondientes, el editor puede proceder a la edición de documentos de la siguiente manera. En primer lugar, se debe seleccionar la opción "Edit" en la barra de acciones en la parte superior de la página.
El editor de documentos ofrece una serie de herramientas para dar estilo y funcionalidad al texto redactado.
También se puede usar la opción "Edit source" al lado de la opción "Edit", que permite editar directamente el código fuente.
Secciones y sub-secciones
MediaWiki permite la estructuración de documentos en secciones y sub-secciones. Éstas se ven delimitadas por encabezados que determinan la división de los documentos. Para incluir una estructura de encabezados, se define la categoría de cada texto empleando el signo "=" en código Wiki de la siguiente manera:
|
Código |
Resultado |
|---|---|
|
=Sección 1 = |
|
NOTA: La generación de la tabla de contenidos (Table of contents "TOC") se realiza automáticamente cuando se incluyen más de tres encabezados en un documento.
Vínculos
El código MediaWiki permite la inclusión de vínculos internos y externos en la edición de artículos. La referencia a enlaces externos se realiza por medio de corchetes cuadrados simples: []. El formato en el que se referencia este tipo de vínculos es el siguiente: [http://www.ejemplo.com Título del enlace]. En este caso, el contenido dispuesto en el campo "Título del enlace" será el texto objetivo del hipervínculo a la página. En caso de no especificar un contenido para este campo, el objetivo del hipervínculo será una enumeración genérica.
Para el caso de vínculos internos, la inclusión se realiza por medio de corchetes cuadrados dobles: [[]]. El formato en el que se referencia este tipo de vínculos es el siguiente: [[Pagina de Prueba]]. En este caso, el texto objetivo del hipervínculo será, por defecto el título de la página referenciada. Sin embargo, si se desea disponer un contenido diferente para corresponder al objetivo del hipervínculo se puede definir este parámetro por medio de la separación con una barra vertical de la siguiente manera: [[Pagina de Prueba|Título alternativo]]. Varias aplicaciones de vínculos externos internos y externos son presentadas a continuación.
|
Código |
Resultado |
|---|---|
|
[https://cmua.uniandes.edu.co/ CMUA] |
Imagenes
Para subir imágenes, y archivos en general, a la Wiki TTDE, se deben seguir los siguientes pasos. En primer lugar, se debe seleccionar la opción "Subir un archivo", situada en la barra de herramientas en la parte inferior de la página.
Posteriormente, se debe seleccionar la opción "Seleccionar archivo" para examinar el directorio correspondiente que será subido a la Wiki TTDE. En particular se debe tener en cuenta que el tamaño máximo permitido para subir archivos es 1MB. También se recomienda que en el campo "Nombre del archivo de destino" se use el siguiente formato: AAMMDD-seccion-imagen.ext, donde "AAMMDD" hace referencia a la fecha en la cual se sube el archivo, "sección" corresponde a un término descriptivo del uso general del archivo e "imagen" corresponde a una descripción más específica.
Por último, se debe verificar que la extensión del archivo sea la correcta. Todas estas consideraciones deben ser tenidas en cuenta debido a que este nombre será empleado para referenciar al archivo subido en todos los documentos de la wiki.
Por último, con la finalidad de referenciar un archivo en un artículo dado, se puede emplear una notación similar a la empleada para realizar vínculos a páginas internas. A pesar de que Media Wiki ofrece varias opciones para la disposición de imágenes en los artículos, para la Wiki TTDE se empleará únicamente esta alternativa:
[[File:200714-USUARIO-ejemplo.JPG|none|750px|thumb|Pie de imagen]]
Bajo esta notación, el primer campo corresponde al nombre bajo el cual se referenció el archivo en el paso anterior, el tercer campo hace referencia al tamaño con le cual se mostrará la imagen en el artículo (este valor se da en pixeles, acompañado del sufijo "px"). El último campo corresponde al resumen de la imagen que será mostrado en el pie de la misma. El segundo y el cuarto campo con los parámetros "none" y "thumb" respectivamente no deben ser modificados. Un ejemplo del uso de imágenes será presentado a continuación.
|
Código |
Resultado |
|---|---|
|
[[File:200714-USUARIO-ejemplo1.JPG|none|200px|thumb|Pie 1]] |
|
|
[[File:200714-USUARIO-ejemplo2.JPG|none|250px|thumb|Pie 2]] |
Tablas
MediaWiki permite el uso de tablas, el cual puede resultar provechoso para presentar datos de una forma concisa y organizada. Sin embrago, en la medida de lo posible, se debe evitar su uso debido a que la aplicación de estos elementos dificulta la edición de la página. Para la estructuración de tablas se emplean los siguientes elementos mencionados a continuación.
|
Símbolo |
Función |
|---|---|
|
{| |
Este símbolo es empleado para realizar la apertura de la tabla. |
|
! |
Este símbolo es empleado para enunciar los encabezados de las columnas. |
|
|- |
Este símbolo es empleado para realizar la separación entre filas. |
|
| |
Este símbolo es empleado para enunciar el contenido de cada columna en cada fila. |
|
|} |
Este símbolo es empleado para realizar la clausura de la tabla. |
A continuación se describe un ejemplo del uso de las tablas provistas por la Media Wiki.
|
Código |
Resultado |
||||||||
|---|---|---|---|---|---|---|---|---|---|
|
{| |
|
Si se desea, se puede emplear una adición de estilo para adicionar un borde sólido a la tabla. Este se puede adicionar agregando el parámetro "border="a"" luego del símbolo de apertura de la tabla. El valor de a determina el grosor del borde correspondiente. A continuación se presenta un ejemplo del uso de este parámetro.
|
Código |
Resultado |
||||||||
|---|---|---|---|---|---|---|---|---|---|
|
{| border="1" |
|
Extensiones
El software MediaWiki permite a los usuarios el uso de plug-ins para extender la funcionalidad de la misma. En particular, los siguientes componentes han sido instalados para la aplicación en edición de artículos.
Video YouTube
Esta extensión permite la inclusión de videos embebidos de YouTube en artículos. Para incluir un elemento de este tipo se debe hacer uso del tag <youtube> de la siguiente manera: <youtube>id</youtube> donde id es el identificador del video correspondiente en el sitio web. Por ejemplo, el identificador correspondiente al video https://www.youtube.com/watch?v=CpO1mSeHMHE es: CpO1mSeHMHE. A continuación se muestra un ejemplo del uso de esta extensión.
|
Código |
Resultado |
|---|---|
|
<youtube>eYzF8DEpNDs</youtube> |
|
Resaltador de código
Esta extensión permite resaltar las palabras reservadas en un lenguaje de programación dado por medio del software GeSHi. Para incluir un elemento de este tipo se debe hacer uso del tag <syntaxhighlight lang="xxx"> de la siguiente manera: <syntaxhighlight lang="xxx">
codigo
</syntaxhighlight> donde el campo "código" corresponde al contenido que será resaltado según el lenguaje de programación "xxx". A continuación se muestra un ejemplo del uso de esta extensión.
|
Código |
Resultado |
|---|---|
|
<syntaxhighlight lang="verilog"> |
module hab
(
input wire clk,
input wire [7:0] dato,
output wire [7:0] final,
output wire listo
);
reg [7:0] fin;
reg ok;
always @(posedge clk)
begin
if(dato==8'b00000000)
begin
fin=fin;
ok=1'b0;
end
else
begin
ok=1'b1;
fin=dato;
end
end
assign final = fin;
assign listo = ok;
endmodule |
En particular, se puede aplicar la adición de parámetros en el tag <syntaxhighlight> para utilizar funcionalidades añadidas que ofrece esta extensión. En este caso se mencionan line start="x", en el cual se enumeran las líneas de código, siendo x el valor de conteo inicial y highlight="z", que resalta la línea de código correspondiente al valor z. A continuación se muestra un ejemplo del uso de dichas funciones.
|
Código |
Resultado |
|---|---|
|
<syntaxhighlight lang="verilog" line start="5" highlight="10"> |
module hab
(
input wire clk,
input wire [7:0] dato,
output wire [7:0] final,
output wire listo
);
reg [7:0] fin;
reg ok;
always @(posedge clk)
begin
if(dato==8'b00000000)
begin
fin=fin;
ok=1'b0;
end
else
begin
ok=1'b1;
fin=dato;
end
end
assign final = fin;
assign listo = ok;
endmodule |
Instalación de extensiones
Además de las extensiones presentadas anteriormente, Mediawiki ofrece un sinnúmero de plug-ins y aplicaciones que pueden tener potencial en el desarrollo de Wiki TTDE. La lista de extensiones puede ser encontrada en la página oficial de la MediaWiki [2]. Para solicitar la instalación de una extensión debe comunicarse con alguno de los siguientes contactos.
Encabezados de artículos
Con la finalidad de establecer un formato para los artículos presentados en la mediawiki se dispuso de una plantilla que se debe situar al inicio de cada documento con información básica del mismo. Este encabezado debe contener una imagen referente al tema que será tratado en el artículo, una breve descripción del contenido e información de autores, editores y revisores. En particular, se hace uso de la plantilla {{EncabezadoArticulo}}, la cual tiene por parámetros: info, descripción e imagen, haciendo referencia a los elementos mencionados anteriormente. A continuación se presenta un ejemplo del uso adecuado de dicha plantilla:
|
Código |
Resultado |
|---|---|
|
{{ |
Reglas y restricciones
El mantenimiento del estilo propio de la línea debe ser un objetivo fundamental para todos los editores de artículos de la Wiki TTDE. Para este propósito, se enuncian las siguientes reglas y restricciones que cada autor debe seguir en la creación, edición y revisión de artículos:
- El uso de elementos de estilo html debe ser autorizado por parte de los administradores de la wiki. No está permitido su uso en caso de no recibir la aprobación correspondiente.
- Para la aplicación de gráficas, recuadros, comentarios y demás elementos, se deben tener en cuenta los colores institucionales de la línea.
- Cada archivo comprimido que se suba debe contener únicamente la información importante del proyecto. Se debe evitar subir información que no es relevante, eso ocupa espacio y dificulta el mantenimiento de la Wiki.
- No subir PDFs que se puedan direccionar y bajar de internet.
- La referenciación de archivos debe basarse en la asignación de nombres claves que ayuden a identificar el propósito de los elementos subidos en la Wiki TTDE.
- La referenciación de imágenes en artículos debe realizarse mediante la opción indicada: [[File:200714-USUARIO-ejemplo.JPG|none|750px|thumb|Pie de imagen]] indicando un pie de imagen adecuado para cada elemento y un tamaño que no distorsione la estética del artículo y de la página en general.
- Cada artículo debe ser encabezado por la plantilla mencionada previamente. En esta se debe documentar con claridad la información relacionada con los autores, editores, revisores y con el propósito del documento en general.
- El uso de fuentes internas y externas a la Wiki TTDE debe ser claramente referenciado y citado.
IMPORTANTE: El incumplimiento de las reglas mencionadas anteriormente puede ser causal de la eliminación de artículos que no sigan estas especificaciones por parte de los administradores de la wiki.
Plantilla para la documentación de proyectos
Con la finalidad de dar un formato a la documentación de proyectos, se debe hacer uso del siguiente formato o plantilla para este propósito.
