S1: Lenguajes de marcado. Markdown
- Tiempo: 2h (50 + 50min)
- Fecha: Martes, 1-Febrero-2021
-
Objetivos de la sesión:
- Entender porqué hay lenguajes de marcado
- SGML y definición de lenguajes de marcado
- Lenguaje simplificado: markdown
- Aprender markdown y practicarlo con VSCode
- Lenguajes y metalenguajes
- Lenguajes de marcado
- Sintáxis del marcado: Etiquetas
- SGML: Lenguaje de marcado generalizado
- Lenguajes de marcas simplificados o ligeros
- Markdown
- Practicando markdown con VSCode
- Generar un fichero PDF a partir de markdown
- Ejercicios
- Autor
- Licencia
- Enlaces
Para describir o explicar un proyecto en ingeniería utilizamos un lenguaje humano, como por ejemplo el Español (pero podría ser también el Inglés). Usando este lenguaje podemos escribir un documento técnico
Imaginemos que estamos escribiendo un documento técnico para describir nuestro último proyecto hecho con node.js. Antes de entrar en materia escribimos una breve introducción sobre node.js:
Observamos varias cosas:
- El documento tiene una estructura. Tiene un apartado, numerado como 1, y dentro hay un sub-apartado, denotado por 1.1 y a su vez, dentro de este hay un párrafo
- Hay palabras especiales, que se han resaltado frente a otras. Aparecen con un estilo diferente: negrita o cursiva
- Una misma palabra, por ejemplo node.js, aparece con estilos diferentes según si está en el texto o forma parte del título del apartado
- El apartado y el subapartado están numerados. Además de establecerse un orden, estos números nos permiten referenciar esos elementos. Así, en otras partes del documento podemos mencionar el apartado 1, el sub-apartado 1.1, etc...
Imaginemos ahora que este documento lo queremos escribir a través de otra persona, dictándoselo, o a través de una máquina con reconocimiento de voz, como Alexa. Si queremos obtener un resultado similar al anterior, no podemos meramente leer el texto tal cual. Es decir, NO funcionaría si decimos esto:
"Uno punto node punto js uno punto uno punto introducción node punto js es un entorno multiplataforma y de código abierto basado en el lenguaje de programación Javascript"
No funciona porque tenemos que añadir más información, no sólo el texto a escribir. Tenemos que explicar o indicar a qué categoría pertenece cada palabra (apartado, sub-apartado, párrafo), o qué atributos tiene esta palabra (negrita, cursiva) por ejemplo
Cuando usamos un lenguage para describir otro lenguaje o hablar sobre él, lo denominamos metalenguaje. Así, para obtener un documento como nosotros queremos tendríamos que decir algo como lo siguiente. Entre paréntesis se incluyen las palabras nuevas, que NO forman parte del texto que queremos escribir. Son las palabras del metalenguaje
"(Alexa comienza un documento nuevo) (Apartado 1) Node punto js (Sub-apartado 1.1) Introducción (Párrafo) (Activa cursiva) Node punto js (Desactiva cursiva) es un entorno (activa negrita) multiplataforma (desactiva negrita) y de (activa negrita) código abierto (desactiva negrita) basado en el lenguaje de programación (activa negrita) Javascript (desactiva negrita)"
Las nuevas palabras que hemos añadido, NO tienen nada que ver con el documento técnico. No forman parte de este documento técnico. No se usan para describir cualidades de node.js ni aportar información técnica. Se usan para describir cómo representar las palabras del documento técnico: cada una, según su posición, con un estilo diferente
Así, las palabras y frases que hemos tenido que añadir para que una persona o una máquina (Alexa) nos escriba el documento técnico por nosotros son:
- Comienza un documento nuevo
- Apartado x
- Sub-apartado x
- Párrafo
- Activa cursiva
- Desactiva cursiva
- Activa negrita
- Desactiva negrita
Estas palabras forman nuestro Metalenguaje. Es nuestro LENGUAJE DE MARCADO, que nos permite hablar sobre el texto de nuestro interés. Con este ejemplo del dictado hemos visto que ESTAMOS OBLIGADOS a que existan estos metalenguajes, o de lo contrario no podríamos tener la posibilidad de desarrollar tecnología para que una máquina escriba o procese documentos por nosotros
Definimos un Lenguaje de marcado o lenguaje de marcas como un metalenguaje que usamos para aportar información adicional sobre la estructura de un texto o su presentación
La manera de realizarlo es incluyendo en el texto unas marcas especiales, que aportan información a las diferentes partes del texto. En el ejemplo anterior, nuestras marcas eran comentario en español situados entre paréntesis (Ej. Activa negrita)
Una vez realizado el marcado, el documento adquiere una estructura, que típicamente es jerárquica: Hay una serie de elementos, y dentro de estos elementos, a su vez, hay otros elementos. Esto lo podemos representar mediante cajas, unas metidas dentro de otras. Cada caja dentro de otra tiene un nivel de profundidad mayor
Así, el documento de ejemplo sobre node.js lo representamos mediante marcado como se indica en la parte superior de la figura, y la estructura que proporciona sería la indicada en la parte inferior:
Esta representación de la estructura la denominaremos diagrama de contenedores o diagrama de cajas, y lo que se resalta es que algunos elementos contienen otros elementos, que a su vez contienen otros elementos. Hay contenedores y elementos terminales o no contenedores
Esta es una representación en árbol. Las estrucutras en árbol nos permite ver fácilmente cómo navegar por la estructura para alcanzar las diferentes partes. Estos árboles se implementan como estructuras de datos en la memoria para escribir programas que realicen un procesamiento automático de la información
Disponer de un documento descrito con un lenguaje de marcado nos permite crear una estructura de datos en árbol para representarlo. Esto permite que otros programas puedan recorrer este árbol para analizar todas sus partes y procesarlas
En una primera fase, un analizador síntáctico lee el documento y crea la estructura de árbol, siempre y cuando la sintáxis del documento sea correcta. En caso de no serlo el analizador reporta un error
En una segunda fase, este árbol se le pasa a otro programa para que lo recorra y procese la información. Ejemplos de procesado automático sería la generación de una tabla de contenidos, la traducción a otro lenguaje (como HTML, PDF...), su representación en un dispositivo, etc.
Una parte muy importante del procesamiento es la presentación. Al tener la estructura del documento los algoritmos pueden asignar diferentes formas de representar los elementos del árbol. Es lo que se denomina el estilo. Así, para la representación en la pantalla de un ordedor, por ejemplo, se tendrá un estilo definido para el título del documento, el texto de los apartados, de los subapartados, etc... También será posible tener diferentes estilos (o temas) para un mismo medio: tema claro, tema oscuro, tema de alto contranste...
La sintaxis usada para dotar de estructura a los documentos depende del lenguaje de marcado empleado. En lenguajes como GML, SGML, XML, HTML, XHTML, etc se utilizan etiquetas para delimitar las zonas del documento. Típicamente las etiquetas (tags) se escriben usando una palabra situada entre los símbolos "<" y ">". Hay una etiqueta para comenzar el nuevo bloque, y otra para terminarlo:
- Etiqueta de comienzo de bloque:
<nombre> - Etiqueta de final de bloque:
</nombre>
Para dar estructura a nuestro ejemplo, podríamos definir las siguientes etiquetas:
-
Documento:
<documento>y</documento> -
Apartado:
<apartado>y</apartado> -
Sub-apartado:
<subapartado>y</subapartado> -
Párrafo:
<parrafo>y</parrafo> -
Cursiva:
<cursiva>y</cursiva> -
Negrita:
<negrita>y</negrita>
Usando estas etiquetas, nuestro documento ejemplo lo escribiríamos así:
<documento>
<apartado>1. Node.js
<subapartado>1.1 Introducción
<parrafo>
<cursiva> Node.js </cursiva> es un entorno
<negrita> multiplataforma </negrita> y de <negrita> código abierto </negrita>
basado en el lenguaje de programación <negrita> Javascript </javascript>
</parrafo>
</subapartado>
</apartado>
</documento>En el apartado anteior hemos definido nuestro propio lenguaje de marcado, usando etiquetas con la sintáxis <nombre> </nombre>. Hemos definido nuestras propias etiquetas: <documento>, <apartado>, <subapartado>, ...
Esto es precisamente lo que permite el lenguaje SGML: Nos permite crear nuestro propio lenguaje de marcado adaptado a nuestras necesidades. Especifica la sintáxis de las etiquetas y nos permite difinir sus nombres y su estructura como nosotros queramos. El fichero donde definimos qué etiquetas son válidas y su sintáxis, se denomina definición del tipo de documento y su extensión es .dtd (DTD = Document Type Definition)
Las siglas de SGML significan Standard Generalized Markup Language: Lenguaje de marcado General Normalizado
Siguiendo con el ejemplo anterior, voy a definir mi propio lenguaje de marcado, al que voy a bautizar con el nombre OBML: OBijuan's Markup Languges (Lenguaje de marcado de Obijuan)
Usando SGML escribimos la definición de nuestro lenguaje en el fichero obml.dtd. No vamos a entrar en detalles sobre SGML ni en cómo se definen lenguajes. Simplemente tenemos que saber que la definición de las etiquetas del lenguaje OBML está en ese fichero
Una vez definido el nuevo lenguaje OBML, ya podemos crear nuevos documentos con este lenguaje. La primera línea tiene la etiqueta especial DOCTYPE (definida en SGML) que sirve para indicar el fichero donde está la definición del lenguaje usado (en este caso OBML)
En el fichero nodejs.obml escribimos lo siguiente:
<!-- Esto son comentarios en SGML -->
<!-- Se trata de un documento de tipo OBML
que está definido en el fichero obml.dtd -->
<!DOCTYPE obml SYSTEM "obml.dtd">
<!-- Comienzo del documento -->
<obml>
<apartado>1. Node.js
<subapartado>1.1 Introducción
<parrafo>
<cursiva> Node.js </cursiva> es un entorno
<negrita> multiplataforma </negrita> y de <negrita> código abierto </negrita>
basado en el lenguaje de programación <negrita> Javascript </javascript>
</parrafo>
</subapartado>
</apartado>
</obml>La etiqueta que antes usábamos como <documento> se ha redefinido a <obml> para indicar que es un documento de tipo obml. Todo lo demás es igual que en el ejmplo del apartado anterior
En SGML también se define la etiqueta <!-- --> para incluir comentarios
Usando obml podemos escribir un segundo documento, que llamamos test.obml. La primera línea es la misma que en el documento nodejs.obml, para indicar que es también del tipo obml. Pero el contenido es diferente
<!DOCTYPE obml SYSTEM "obml.dtd">
<obml>
<apartado>1. Esto es el apartado 1</apartado>
<apartado>2. Esto es el apartado 2
<parrafo> Parrafo que forma parte del apartado 2 </parrafo)
</apartado>
<apartado>3. Esto es el apartado 3
<subapartado 3.1> Tiene un subapartado </subapartado>
<subapartado 3.2> Otro subapartado </subapartado>
</apartado>
</obml>En este esquema se resume lo anterior. Usando SGML, hemos definido un nuevo lenguaje de marcado, el OBML, que tiene sus propias etiquetas. Esta definición se encuentra en el fichero obml.dtd. En este lenguaje hemos creado dos documentos: nodejs.obml y test.obml. Ambos documentos tienen una cabecera (DOCTYPE) en la que se indica que son de tipo obml, de forma que la herramienta que procece esos ficheros puede comprobar su validez
SGML es en realidad una fábrica de lenguajes de marcado. A partir de él podemos definir otros lenguajes de marcado, como por ejemplo HTML. A partir del SGML se ha creado una versión simplificada: XML, también pensada para crear lenguaje de marcado. A partir de XML se definen otros lenguajes
El lenguaje XML lo veremos más adelante en la asignatura
Muchas veces utilizamos los lenguajes de marcado (XML o HTML) para escribir documentación. Es decir, les damos una estructura para poder modificar su presentación: que aparezca letras resaltadas en negritas, que las letras de los títulos sean más grandes, etc... En estos casos suele ocurre que los lenguajes de marcado se hacen pesados y oscuros. Y no aportan apenas ventajas su uso
Por ello, han aparecido los lenguajes de marcas ligeros. Son los que usan por ejemplo en la Wikipedia, o en el texto que estás leyendo en esta wiki. El lenguaje que vamos a utilizar es markdown
Es el formato utilizado en los ficheros Readme.md de github, y también para escribir documentos en su wiki (Esto lo haremos en las praćticas). Su sintáxis es muy ligera y espartana, lo que hace que se aprenda MUY RÁPIDAMENTE. Es un lenguaje que se ha popularizado muchísimo para escribir las documentaciones e instrucciones de nuestros programas
Los encabezados se escriben con el caracter #. Se pueden tener hasta 6 niveles:
# Encabezado nivel 1
## Encabezado de nivel 2
### Encabezado de nivel 3
#### Encabezado de nivel 4
##### Encabezado de nivel 5
###### Encabezado de nivel 6Este es el resultado que producen en su presentación
El texto se escribe normalmente y se renderiza siempre en la misma línea. Para comenzar un párrafo nuevo hay que introducir dos saltos de línea. También se pueden tener texto en líneas separadas si al final de cada línea se introducen dos espacios y un salto de línea
# Prueba de texto
Este es un texto que está en
la misma línea, aunque en el
editor se escribe en líneas separadas
Esto comienza en un párrafo nuevo
porque se han puesto dos saltos de línea
Y esto está en líneas sepadas
porque tras cada linea hay
dos espacios y un salto de líneaAl renderizarlo vemos el efecto que tiene
Las listas sin numeración se crean con un asterisco * al comienzo de la línea. Se pueden anidar colocando dos espacios delante del asterisco
# Listas no ordenadas
* Elemento 1
* Otro elemento
* Más elementos
* Elemento anidado
* Anidado 2
* Anidado 3 Se renderizan así:
Podemos crear listas ordenadas escribiendo directamente los números seguidos de un punto
# Listas ordenadas
Estos son los puntos a seguir:
1. Leer la documentación
2. Practicar
3. Practicar más
4. Y seguir practicando más y másY este es el renderizado:
El texto se puede resaltar en cursiva colocando un * al comienzo y otro al final. Para resaltar en negrita se colocan dos asteriscos consecutivos **
# Resaltado de texto
Ejemplo de *texto en cursiva*
Ejemplo de **texto en negrita**Renderizado:
Cuando queremos insertar texto que represente código, utilizamos tres apóstrofos para indicar el comienzo (```) y otros tres para indicar el final
```
# -- Ejemplo de código en python
a = 2
print("Programa en python")
print(f"La variable a vale {a}")
```Esto se renderiza así:
Si tras el los tres apóstrofos iniciales indicamos el lenguaje de programación usado, se realizará un resaltado de sintáxis básico. Así, como el código anterior es python, lo podríamos poner así:
```python
# -- Ejemplo de código en python
a = 2
print("Programa en python")
print(f"La variable a vale {a}")
```y se renderizaría así:
También podemos insertar código dentro de la línea, poniéndolo entre apóstrofos (`)
En python la expresión `print(f" a + b = {2 + 1} ")` produce como resultado `a + b = 3` Se renderiza así:
Los enlaces a una página web externa se define utilizando esta notación: [Texto enlace](URL página). También podemos poner enlaces a cualquier encabezado definido en nuestro documento con esta sintáxis: [Texto enlace interno](#encabezado)
En este ejemplo se definen dos enlaces, uno externo y otro interno, al encabezado Enlaces
# Enlaces
## Enlaces externos
En wikipedia encontramos más información sobre [markdown](https://es.wikipedia.org/wiki/Markdown)
## Enlaces internos
Aquí hay información sobre [los enlaces](#Enlaces) en markdwonEsto es lo que se ve en el renderizado:
Las imágenes se introducen en el documento con la siguiente sintáxis:  donde imagen puede ser bien el nombre del fichero dentro de nuestro sistema de ficheros local o bien una URL de una imagen de internet
# Imágenes
## Imagen en fichero local
## Imagen en URL
Si tenemos el fichero Logo-urjc.png en la misma carpeta donde está guardado este fichero en markdown, el renderizado sería el siguiente:
Las citas se pone con el carácter > al comienzo:
# Citas
Un par de citas de Isaac Asimov:
> Escribo por la misma razón por la que respiro, porque si no lo hiciera, moriría
> Estoy convencido de que la autoeducación es el único tipo de educación que existeEste es el renderizado:
Se pueden hacer tablas muy básicas. El formato es el que utilizariamos si las quisieramos construir usando caracteres ASCII en un archivo de texto:
| | Col 1 | Col 2| Col 3| Col4 |
|---------|-------|------|------|------|
| Fila 1 | 1 | 2 | 3 | 4 |
| Fila 2 | 2 | 4 | 6 | 8 |
| Fila 3 | 3 | 6 | 9 | 12 |El renderizado queda así:
Esta es otra tabla que incluye texto y enlaces. Fijate que la cantidad de espacios usados no influye. Las celdas pueden estar descuadradas. Es el renderizador el que dibuja la tabla con el tamaño exacto:
| | node.js | Django | Flask | Electron |
|----------|-----------|--------|-------|----------|
| Lenguaje | Js | Python | Python| js |
| URL | [link](https://nodejs.org/es/) | [link](https://www.djangoproject.com/) | [Link](https://flask.palletsprojects.com/en/1.1.x/) | [Link](https://www.electronjs.org/) |
| Versión | 14.15.5 | 3.1.6 | 1.1.2 | 11.2.3 |Al renderizarlo queda así:
En visual studio Code podemos escribir muy fácilmente documentos en markdown y renderizarlos. Para probar su funcionamiento abrimos el proyecto LTAW-PRACTICAS que ya tenemos creado y abrimos el fichero README.md dentro de la carpeta P0
En la superior derecha vemos un icono (Open preview to the side) para abrir una previsualización del fichero markdown que está abierto. Lo pulsamos y vemos el renderizado del REAME.md. Si hemos hemos los ejercicios de la práctica 0-1, saldrá algo parecido a esto:
Creamos un archivo nuevo: S1.md, dentro de la carpeta P0, donde practicaremos con el markdown. En él vamos a escribir los ejemplos que se han visto en el apartado anterior. En la parte inferior derecha vemos que pone: Markdown. Como hemos guardado el fichero con la extensión .md, VSCode sabe que es markdwon, y por tanto se activa el resaltado de sintaxis y todas las opciones disponibles para trabajar con markdown
Abrimos la previsualización y ocultamos la parte izquierda donde está el explorador:
El previsualizador se actualiza según añadimos el código markdown, lo que resulta muy útil. Empezamos definiendo un encabezado y escribiendo un texto
y ahora vamos añadiendo todos los elementos descritos en la sección anterior, para aprender y practicar (Se deja como ejercicio). El documento final será parecido a este:
A partir de un documento en markdown se pueden generar documentos en PDF y html. Desde VSCode hay muchas extensiones que nos permiten trabajar con markdown. Para realizar conversiones podemos usar por ejemplo la extensión Markdown PDF
Para instalarla nos vamos a parte de las extensiones en VSCode y escribirmos Markdown en el buscador. Seleccionamos Markdown PDF y le damos a install
Abrimos el documento S1.md y pulsamos con el botón derecho del ratón. Se nos desplegará un menú que tiene las opciones para exportar a los diferentes formatos. Pinchamos en Export (PDF)
Al cabo de unos segundos se nos habrá generado el fichero S1.pdf
Ejercicios para asimilar las ideas y practicar
Dado este documento descrito en SGML, usando el tipo de documento urjc_ml definido en el fichero urjc_ml.dtd
<!DOCTYPE urjc_ML SYSTEM "urjc_ml.dtd">
<urjc_ml>
<!-- include URL URJC -->
<campus>
<nombre>Campus de Fuenlabrada</nombre>
<escuela>
<nombre>ETSI Telecomunicación</nombre>
<grado>
<nombre>Ingeniería en Sistemas Audiovisuales y Multimedia </nombre>
<asignatura>Laboratorio de Tecnologias Audiovisuales en la Web</asignatura>
<asignatura>Construcción de servicios y Aplicaciones Audiovisuales en Internet</asignatura>
</grado>
</escuela>
</campus>
</urjc_ml>- a) Explica para qué sirve la primera línea del documento y por qué es necesaria
- b) Si se omitiese esta línea, ¿Qué piensas que ocurriría?
- c) Sin conocer el contenido del fichero urjc_ml.dtd, ¿el documento es sintácticamente correcto?
- d) ¿Qué hace la tercera línea?
- e) ¿Cuantas etiquetas de apertura hay? ¿Cuantas de cierre?
- f) Dibuja el diagrama de contenedores de este documento
- g) Dibuja la estructura en árbol que define este documento
Este arbol representa la estructura del tipo de documento universidad, que está definido en el archivo llamado universidad.dtd. Los nombres de las etiquetas de cada elemento del árbol están escritos en los nodos. Estos nombres son válidos y se encuentra definidos dentro del documento DTD
- a) Escribe el documento en SGML que representa esa estructura
- b) ¿Cuántos elementos contenedores hay? Indica sus nombres
- c) ¿Cuantos elementos terminales hay? Indica sus valores
- d) ¿Cuantos elementos hay en el nivel 3?. Escribe sus nombres
Este arbol representa la estructura del tipo de documento generic, que está definido en el archivo llamado generic.dtd. Los nombres de las etiquetas de cada elemento del árbol están escritos en los nodos. Estos nombres con válidos y se encuentra definidos dentro del documento DTD
- a) Escribe el documento en SGML que representa esa estructura
- b) ¿Cuantos elementos hay en total?
- c) ¿Cuantos elementos terminales hay?. Indica sus valores
- d) ¿Cuantos elementos no terminales hay?. Indica cuántos hay en cada nivel
- e) ¿Cuantos elementos hay en el nivel 5?.Indica sus nombres
Dado el siguiente documento escrito en markdown, dibuja:
# FPGAs
## FPGAs libres
### Familias
* ice40
* UP5K
* ECP5
### Placas
1. Alhambra II
2. Icestick
3. ULX3S
4. iceBreaker
5. TinyFPGA- a) Su diagrama de contenedores
- b) Su estructura en árbol
Realizar la actividad pedida en el apartado Practicando markdown con VSCode (Si es que no se ha realizado ya):
- a) Crea el fichero S1.md dentro de la carpeta P0 de tu repositorio de prácticas (LTAW-PRACTICAS). Mete todos los ejemplos descritos en la sección: Markdown. Personaliza los textos, para que sean diferentes (Cada estudiante debe terer textos distintos). Súbelo al repositorio. Deberás realizar un commit por cada subapartdo probado del markdown (uno para encabezados, otro para texto y salto de línea, otro para Listas...)
- b) Genera el fichero S1.pdf. Súbelo al repositorio
- Juan González-Gómez (Obijuan)
