Acciones

Guia de usuario

De CoffeeBrain-Wiki

Logo-cuadrado-ttde.jpg

Descripción:

Este documento presenta las consideraciones básicas que se deben tener en cuenta al momento de crear y editar artículos en la WikiTTDE. 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 artículos. Por último, se presentan las normas que cada editor debe cumplir en relación al manejo de extensiones y al estilo de la WikiTTDE.

Autor:


La WikiTTDE 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 la línea TTDE. A continuación se presentan las instrucciones y reglas para interactuar con dichos elementos. IMPORTANTE: para la edición de artículos en la WikiTTDE se necesita de un usuario con los permisos correspondientes. Para solicitar la creación de un usuario contactar a:


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

1.1 Editor de artículos

Un vez otorgado el usuario con los permiso correspondientes, el editor puede proceder a la edición de artículos de la siguiente manera. En primer lugar, se debe seleccionar la opción editar en la barra de acciones en la parte superior de la página.

Opción de edición en barra de acciones

El editor de artículos ofrece una serie de herramientas para dar estilo y funcionalidad al texto redactado.

Herramientas de edición

1.2 Secciones y sub-secciones

MediaWiki permite la estructuración de artículos en secciones y sub-secciones. Éstas se ven delimitadas por encabezados que determinan la división de los domumentos. 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 =
Contenido de la sección 1
==Subsección 1.1 ==
Contenido de la sección 1.1
==Subsección 1.2 ==
Contenido de la sección 1.2
=Sección 2 =
Contenido de la sección 2
==Subsección 2.1 ==
Contenido de la sección 2.1
==Subsección 2.2 ==
Contenido de la sección 2.2
===Subsección 2.2.1 ===
Contenido de la sección 2.2.1
=Sección 3 =
Contenido de la sección 3

100714-GuiaUsuario-Secciones.jpg


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.

Tabla de contenidos

1.3 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]

[https://cmua.uniandes.edu.co/]

[[Pagina de Prueba]]

[[Pagina de Prueba|Título alternativo]]

CMUA

[1]

Pagina de Prueba

Título alternativo


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

Vínculo para subir archivo

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.

Menú para subir archivo

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]]

Pie 1

[[File:200714-USUARIO-ejemplo2.JPG|none|250px|thumb|Pie 2]]

Pie 2

1.5 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

{|
! Ángulo lanzamiento
! Distancia
|-
|15°
|15m
|-
|30°
|20m
|-
|45°
|25m
|}

Ángulo lanzamiento Distancia
15° 15m
30° 20m
45° 25m



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"
! Ángulo lanzamiento
! Distancia
|-
|15°
|15m
|-
|30°
|20m
|-
|45°
|25m
|}

Ángulo lanzamiento Distancia
15° 15m
30° 20m
45° 25m

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

2.1 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>

2.2 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
</syntaxhighlight>

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
</syntaxhighlight>

  1. module hab
  2.    (
  3.     input wire clk,
  4.     input wire [7:0] dato,
  5.     output wire [7:0] final,
  6.     output wire listo
  7.    );
  8.    reg [7:0] fin;
  9.    reg ok;
  10.    always @(posedge clk)
  11.    begin
  12. 	if(dato==8'b00000000)
  13. 	begin
  14. 	fin=fin;
  15. 	ok=1'b0;
  16. 	end
  17. 	else
  18. 	begin
  19. 	ok=1'b1;
  20. 	fin=dato;
  21. 	end
  22.    end
  23. assign final = fin;
  24. assign listo = ok;
  25. endmodule



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


3 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

{{
EncabezadoArticulo
|info=<b>Autores: </b>
<p>{{FirmaArticulo|nombreapellido=Josnelihurt Rodriguez Barajas|login=j.rodriguez52}}</p>
<p>{{FirmaArticulo|nombreapellido=David Santiago Flechas García|login=ds.flechas72}}</p>
|descripcion=El proyecto SHARKBoard nace como una plataforma de bajo costo que permite a estudiantes interesados en el desarrollo de aplicaciones sobre lógica programable diseñar y probar de manera rápida sus aplicaciones.
|imagen=120918 NEWS-shark.jpg
}}

210714-GuiaUsuario-Encabezado.jpg



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

5 Plantilla para la documentación de proyectos de cursos

Con la finalidad de dar un formato a la documentación de proyectos soportados por la línea, se debe hacer uso de los siguientes formatos o plantillas planteadas para este propósito.