Maquetando documentación en Linux con Markdown

Web OS

3126ª Parte Maquetando documentación en Linux con Markdown

markdown principios básicos

markdown syntax

Si ayer vimos un editor bastante potable para hacer doc basándose en dos lenguages de marcas hoy nos centraremos solo en markdown por lo fácil que es para estos menesteres, por internet hay mucha documentación ( es que yo también sé ser eufemístico) y está en muchos formatos, la podéis encontrar en formato, pdf, lit, doc, html, etc, etc, a veces estará completa y otras no, aseguraros siempre que lo que tenéis es lo que queréis, a veces hay posible arreglo en las bibliotecas públicas cercanas pues lo que falta en el documento se puede obtener de documentación real aunque a veces cambien palabras por ser ediciones distintas de la misma obra. Y eso no es muy oneroso en faena.
Por ejemplo con ayuda de evince a.k.a también como  visor de documentos siempre y cuando el pdf no sea de página doble con un simple seleccionar todo y después copiar se puede pegar en cualquier editor de texto incluido el ReText aunque no hace falta.

Con ayuda del clit se puede abrir un lit en una carpeta y ahí el fichero html que encontraréis lo abrís con un navegador y lo mismo seleccionar todo, copiar y pegar.

Si es un rtf o un doc o un txt pues por ejemplo lo abrís con LibreOffice y lo mismo seleccionar todo, copiar y pegar en un editor mas normalito.

Todo esto es porque probablemente si usáramos el pandoc para convertir directamente a ebook, el epub o el fb2 resultante sería bastante amorfo, sin capitulaciones, probablemente mas amazacotado de lo que nos gustaría en fin haría falta mucha chorra para acertarla a la primera.

Por eso lo de maquetar que viene a ser el dar forma al documento.

Que será:

Capitular a los niveles que toquen os recuerdo que los lectores normales solo llegan, bueno no creo que hayan evolucionado y me dejen mal, hasta nivel 3 en epub, hasta nivel 1 en fb2 incluso con coolreader no pasa del nivel 2 en fb2, eso para los cocinados, así que no os emocionéis poniendo mas niveles de epígrafes o capitulillos debajo de eso aunque los hubiere porque no saldrán ni en coolreader ni el el lector, si los hubiera se puede resolver titulando con negrita.

La documentación que se precie suele poner un índice al principio o al final es mirar el documento original y buscar dónde estamos maquetando y marcar lo que toque.

Es mejor usar la marca # para capitular procurar que toque la marca la primera letra del capítulo que sea.
# es nivel 1    : #Esto es nivel 1 (lo mas grande)
## es nivel 2 : ##Esto es nivel 2 (un poco mas pequeño)
### es nivel 3 : ###Esto es nivel 3 (un poco mas pequeño)
#### es nivel 4
##### es nivel 5
###### es nivel 6

Parrafeando: esto es arreglando los párrafos con markdown después del punto y aparte hay que poner dos espacios y seguirlo con un enter, aunque no hace falta acostumbraros a empezar el párrafo con 3 o cuatro espacios, yo suelo dejar tres, el por qué es que os ayudará a corregir errores de situación de párrafos. En versos no hace falta darle al enter. Pero si los dos espacios. Párrafos son bloques de texto hasta un punto y aparte, no punto y seguido, debido a lo de los dos espacios pueden pasar cosas al convertir sobre todo si vais cambiando de editor de texto y no los preparáis en preferencias al mismo todo: cuantos espacios tendrán los tabs etc, suelen ser estandarts pero mirar primero las preferencias del que habéis estado usando y las que tenga el  nuevo antes de cambiar de editor.

Acotaciones al texto o Blockquotes bloques de texto que están mas a un lado que a otro del párrafo general se usa la marca > y puede ir hasta el nivel >>> cada > es una indentación de 8 espacios por los dos lados así que calculáis primero o mejor veis el resultado usando ReText aunque os sorprenderéis al verlo en vuestro ebook no os fiéis.

Enfatizando frases o Enfatizando frases o palabras
Para enfatizar en negrita se usa **negrita**  esto es **lo que sea**
Para itálica se usa *itálica* esto es *lo que sea*
Procurar que las marcas * toquen siempre la primera letra y la última ya sea en negrita o itálica pues se puede extender a párrafos enteros se usa mucho en las acotaciones al texto, es mejor primero usar el enfatizado antes que el acotado esto es mejor dejarlo para el final pero es imprescindible tener claras las acotaciones (o donde ponerlas) de este modo yo suelo usar la itálica.

Limpiar texto no necesario normalmente lo que se pasa desde un pdf viene con todo: números de página, encabezados, errores de OCR y una cantidad de errores de todo tipo que pueden echaros hacia atrás en vuestra decisión, pero la verdad es que se suelen repetir y es simplemente buscar con editor y es casi un trabajo automático, esto si vais viendo se hace a cada pasada que se dá.

Notas  se usa de esta forma [^n] para marcar donde está (suele haber un número que se sustituye por ese formato o una marca de algo si hay error de ocr) y [^n:] hay un espacio en blanco antes del texto de la nota que sea y se pone en la primera línea libre que haya después del párrafo donde esté si hay varias pues se van poniendo una detrás de otra y dejar siempre líneas en blanco entre ellas y entre ellas y el siguiente párrafo normal del documento porque es peligroso que se mezclen las notas con el texto normal.

Donde n es un número o un número y una letra son secuenciales esto es a lo mejor el documento tiene muchas como 1000, pero empieza desde 1 en cada capítulo que es lo normal pues con markdown no, se sigue la numeración hasta el final, ejemplo que cada capítulo tenga 100 notas, el primer capitulo iría del 1 al 100 pero en el segundo vosotros pondrías 101 no 1, lo mismo para las notas de pié de página aquellas que aparte de las normales señaladas con un número se marcan con un * o vete a saber qué en el documento original pues seguís la numeración secuencial si queréis distinguirlas para vosotros podéis poner también una letra, pero no hace falta. Lo que pasa con estas notas a pié de página es que las tendréis que buscar en el mismo texto y cortar pegar al nuevo sitio, las notas finales suelen ponerse en el apartado notas del documento original que tendréis que ir copiando a donde toque. Tienen algo de limpieza de texto.

Los errores son fácilmente subsanables al convertir pandoc avisa diciéndote el error y el número de línea del documento maquetado lo que ayuda a corregir las notas, es conveniente en textos amazacotados de notas ir convirtiendo de cuando en cuando para ver si hay errores a todo esto os lo tenéis que tomar como hobby no hay prisa y no os estreséis yo incluso lo recomendaría para geriátricos con pasta o club de jubilados como entretenimiento o clubs de lecturas para ama/os de casa ilustrados aunque todo/as podéis participar.

Imágenes pues ![]() ó ![]() con esto os quiero decir que al menos estos dos formatos sé que funcionan y que vale tanto para poner la portada o cualquier tipo de imagen que tenga el documento pdftohtml funciona bien para extraer las imágenes si usáis pdfs de base, yo suelo trabajar en carpeta por proyecto y os recomiendo hacer lo mismo, quiero decir que el documento se llama llama pues abrís la carpeta o directorio llamado llama y dentro ponéis el documento base ya sea el pdf, el html o lo que sea y ahí vais poniendo lo que va a conformar todo el proyecto, imágenes, portada, la matriz que es falla.md y el falla.txt que será una copia exacta de lo que habéis copiado al principio del todo, si os dais cuenta el falla.md ha ido cambiando y en el hay cosas que para un ebook tipo epub o fb2 no hacen mucha falta, por ejemplo las notas como están originalmente, el índice tampoco hará mucha falta, menos un índice temático ahora que si tenéis ganas, en fin.

Bueno markdown se puede usar en cualquier SO así que muchas de las cosas son aplicables a ellos. Yo es que son las cosas que mas he usado, las otras cosas que no he tocado, listas, tablas es que no las he tocado y lo de convertir pues mejor a la semana que viene. :) Ximo