Saltar a contenido

Recetas

Markdown

Ejemplos de cómo generar documentación con Markdown.

Incluyo distintos ejemplos de cómo generar documentación a partir de Markdown. Aunque son ejemplos concretos pueden servir para cas cualquier caso.

Los tipos de documentación que genero son:

  • Para imprimir y leer en ordenador:
  • pdf de tamaño a4
  • Para leer en el ereader:
  • epub
  • en caso de que no se pueda generar epub (porque contenga código LaTeX, por ejemplo) se genera un pdf de tamaño a6
    • En el caso de música tengo que instalar el paquete lilyglyphs: 1. Se copia el directorio en tex/latex del MKITEX (la instalación puede estar en Archivos de Programa o en AppData\Roaming 2. Se copia el subdirectorio fonts en fonts/opentype cambiando el nombre a `‘emmentaler’ 3. Se actualiza la base de datos (MikTeX Console -> Tools)
  • Para incluir como nota en Synology Note Station
  • genero un html standalone (para que se copien bien las imágenes) y lo hago con copy-paste
  • en el caso de que no se pueda generar html (porque contenga código LaTeX, por ejemplo) se genera un pdf y se divide en imágenes

Los ficheros incluidos son los necesarios para hacer la compilación. Utilizo dos casos:

  • cuestiones Jcyl: con el que genero pdf a4, epub y html
  • musica: con el que genero pdf a4 y pdf a6 (con el LaTeX incluido no consigo hacer ni epub ni html)
  • Tengo que seguir probando, pero de momento me apaño. Ver pruebas.txt

Los documentos los hago con Markdown (utilizo para la edición vscode), las imágenes principalmente en png (con el svn no se genera correctamente el epub) y la generación se hace con pandoc y LaTeX.

Añadir código LaTeX dentro de Markdown

Para poder usar código LaTeX en Markdown sin tener que meterlo dentro de se puede añadir directamente y luego hacer la compilación con pandoc añadiendo la opción:

pandoc -f markdown+raw_tex ....

Añade una imagen, de forma que no sea flotante si se convierte a pdf mediante pandoc y latex

![Estructura de Solicitudes](SolicitudesActuales.png)
\

Nota: es importante añadir un espacio después de \ -->

Comandos para generar la documentación

pdf a4

pandoc -N a4.yaml cuestiones.md --highlight-style pygments --pdf-engine=xelatex -o cuestiones.pdf

html (para copiarlo al Synology Note Station)

pandoc -s --mathjax  -c cuestiones.css --self-contained --highlight-style pygments --metadata-file=html.yaml cuestiones.md -o cuestiones.html

epub

pandoc -s --mathjax  --highlight-style pygments --metadata-file=epub.yaml cuestiones.md -o cuestiones.epub

pdf a6

pandoc -N --pdf-engine=xelatex musica.md -f markdown+raw_tex -o musicaReader.pdf

Corregir líneas de código que no caben en la página (Markdown)

Añadir lo siguiente a las cabeceras latex:

\lstset{breaklines=true}
\lstset{language=[Motorola68k]Assembler}
\lstset{basicstyle=\small\ttfamily}
\lstset{extendedchars=true}
\lstset{tabsize=2}
\lstset{columns=fixed}
\lstset{showstringspaces=false}
\lstset{frame=trbl}
\lstset{frameround=tttt}
\lstset{framesep=4pt}
\lstset{numbers=left}
\lstset{numberstyle=\tiny\ttfamily}
\lstset{postbreak=\raisebox{0ex}[0ex][0ex]{\ensuremath{\color{red}\hookrightarrow\space}}}

y compilar con pandoc añadiendo --listings --latex-engine=xelatex

Escapar caracteres en Markdown

Los siguientes caracteres se pueden escapar añadiendo delante \

\ backslash
` backtick
* asterisk
_ underscore
{} curly braces
[] square brackets
() parentheses
# hash mark
+ plus sign
- minus sign (hyphen)
. dot
! exclamation mark

Para escapar la barra vertical en una tabla se puede usar el código ascii en html:

|

Cabecera yaml para ereader 6 pulgadas

---
title: Lenguaje musical
author: Roberto Hernando
fontsize: 14pt

header-includes:
  #- \AtBeginDocument{\let\maketitle\relax}
  - \usepackage{atbegshi}
  - \AtBeginDocument{\AtBeginShipoutNext{\AtBeginShipoutDiscard}} #Borra la página de título (uso portada propia)
  - \usepackage[papersize={3.6in,4.8in},hmargin=0.1in,vmargin={0.1in,0.1in}]{geometry}
  - \usepackage[utf8]{inputenc}
  - \usepackage{fontspec}
  - \usepackage{lilyglyphs}
  - \setmainfont{Cambria}
  - \usepackage{microtype}
  - \usepackage[spanish]{babel} #español
  - \usepackage[font=small,labelformat=simple,]{caption}
  - \usepackage{fancyhdr}
  - \pagestyle{fancy}
  - \fancyhead{}
  - \fancyfoot{}
  - \setlength{\abovecaptionskip}{2pt}
  - \setlength{\belowcaptionskip}{0pt}
  - \setlength{\textfloatsep}{2pt}
  - \setlength{\floatsep}{2pt}
  - \setlength{\intextsep}{2pt}
---

Pandoc

Usar la plantilla eisvogel para LaTeX con pandoc

Copiar el fichero eisvogel.latex en C:\Users\USERNAME\AppData\Roaming\pandoc\templates.

LaTeX

Para que LaTeX divida líneas largas de textt (código)

El problema es que por defecto el tipo de letra textt (el que se usa para código) no tiene hyphenation definido.

Se hace incluyendo el paquete:

\usepackage[htt]{hyphenat}

No parece que funcione :-(

Corregir error LaTeX Error: Too deeply nested al exportar un markdown a pdf

\usepackage{enumitem}
   \setlistdepth{9}

   \setlist[itemize,1]{label=$\bullet$}
   \setlist[itemize,2]{label=$\bullet$}
   \setlist[itemize,3]{label=$\bullet$}
   \setlist[itemize,4]{label=$\bullet$}
   \setlist[itemize,5]{label=$\bullet$}
   \setlist[itemize,6]{label=$\bullet$}
   \setlist[itemize,7]{label=$\bullet$}
   \setlist[itemize,8]{label=$\bullet$}
   \setlist[itemize,9]{label=$\bullet$}
   \renewlist{itemize}{itemize}{9}

   \setlist[enumerate,1]{label=$\arabic*.$}
   \setlist[enumerate,2]{label=$\alph*.$}
   \setlist[enumerate,3]{label=$\roman*.$}
   \setlist[enumerate,4]{label=$\arabic*.$}
   \setlist[enumerate,5]{label=$\alpha*$}
   \setlist[enumerate,6]{label=$\roman*.$}
   \setlist[enumerate,7]{label=$\arabic*.$}
   \setlist[enumerate,8]{label=$\alph*.$}
   \setlist[enumerate,9]{label=$\roman*.$}
   \renewlist{enumerate}{enumerate}{9}

Cómo añadir entrada en bibliografía sin cita

\nocite{libro}

Corregir error SSL al al actualizar o instalar paquetes

Añadir la variable de entorno MIKTEX_MPM_REMOTESERVICE6210=multiplexor

(de StackExchange)

Hugo

Como añadir un enlace en Hugo para que me funcione correctamente en servidor y en local

El truco es añadir los enlaces (por ejemplo a imágenes) con la ruta absoluta en vez de relativa.

Por ejemplo:

![Pantalla de Búsqueda de Casos](/hipe/log/reuniones/20180316/hipe_informe_borrado_prov.png)
\ 

Imágenes en Hugo con caption

single.html y list.html

{{ partial "header.html" . }}

 <!-- Convierte las imágenes con alt (las que se etiquetan en markdown
 en figuras añadiendo como pie de imagen el alt -->

 {{ $reIn1 := "<p><img src=\"(.*)\" alt=\"(.*)\"></p>" }}
 {{ $reOut1 := "<figure><img src=\"$1\" alt=\"$2\"> <figcaption>$2</figcaption></figure>" }}
 {{ $finalContent := .Content | replaceRE $reIn1 $reOut1 |safeHTML }}
 {{ $finalContent }}


<!-- {{ .Content }} -->

Lilypond

Dibujar acordes de piano

%% http://lsr.di.unimi.it/LSR/Item?id=791
%% see also http://lilypond.org/doc/v2.18/Documentation/snippets/keyboards


#(define KEY-POS-LIST '(       
   (c    .    1) (cis  .  1.5) (des . 1.5) (d    .    2) (dis  .  2.5) (ees  .  2.5) (e   .  3) 
   (f    .    4) (fis  .  4.5) (ges . 4.5) (g    .    5) (gis  .  5.5) (aes  .  5.5) (a   .  6) 
   (ais  .  6.5) (bes  .  6.5) (b   .   7) (c'   .    8) (cis' .  8.5) (des' .  8.5) (d'  .  9) 
   (dis' .  9.5) (ees' .  9.5) (e'  .  10) (f'   .   11) (fis' . 11.5) (ges' . 11.5) (g'  . 12) 
   (gis' . 12.5) (aes' . 12.5) (a'  .  13) (ais' . 13.5) (bes' . 13.5) (b'   .   14) (c'' . 15)))

#(define (black-key? num )
   (member num '(cis  des  dis  ees  fis  ges  gis  aes  ais  bes 
                     cis' des' dis' ees' fis' ges' gis' aes' ais' bes')) )

#(define (key-to-pos key ypos)
  (let ((keypos (assq key KEY-POS-LIST)))
   (if (not keypos)
    (ly:error (_ "keyboard diagram error - unkown note '~a'") key)
    (cons (- (cdr (assq key KEY-POS-LIST)) 0.5) ypos))))

#(define (make-keys l1 width off height fill)
   (if (null? l1) 
       empty-stencil
       (ly:stencil-add 
          (ly:stencil-translate
            (make-line-stencil 0.1 0 0 0 height) 
             (if fill
               (cons (- (car l1) (/ width 2)) off) ;
               (cons (- (car l1) 1)  off)))
          (make-keys (cdr l1) width off height fill))))

#(define (make-keys-black l1 width off height fill)
   (if (null? l1) 
       empty-stencil
       (ly:stencil-add 
          (ly:stencil-translate
            (ly:round-filled-box `(0 . ,width) `(0 . ,height) 0) 
             (if fill
               (cons (- (car l1) (/ width 2)) off) ;
               (cons (- (car l1) 1)  off)))
          (make-keys-black (cdr l1) width off height fill))))

#(define (make-dot key)
  (if (black-key? key)
    (ly:stencil-in-color 
      (ly:stencil-translate (make-circle-stencil  0.27 0 #t) (key-to-pos key 2.5)) 1 1 1)
    (ly:stencil-translate (make-circle-stencil  0.32 0 #t) (key-to-pos key 0.8)) ))

#(define (make-dot-list l1)
   (if (null? l1) 
       empty-stencil
       (ly:stencil-add 
          (make-dot (car l1))
          (make-dot-list (cdr l1)))))

#(define-markup-command (keys layout props arg1) (list?) 
    (ly:stencil-add
      (make-line-stencil 0.1 0 0 14 0)
      (make-line-stencil 0.1 0 6 14 6)
      (make-keys '(1 2 3 4 5 6 7 8 9 10 11 12 13 14 15) 1   0 6 #f)
      (make-keys-black '(1 2   4 5 6   8 9    11 12 13      ) 0.65 2 4 #t)
      (make-dot-list arg1 )))


cnine=\markup\keys #'(c e  g bes d' ) 
cmnine=\markup\keys #'(c ees  g bes d') 
cmninealt=\markup\keys #'(c bes d' ees' g') 

\relative c' {
  <c e g bes d>4^\cnine^"C9" r r2 r1
  <c ees g bes d>4^\cmnine^"Cm9" r r2 r1
  <c bes' d ees g>4^\cmninealt^"Cm9" r r2
}

Dibuja un teclado en lilypond

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% LSR workaround:
#(set! paper-alist (cons '("snippet" . (cons (* 190 mm) (* 155 mm))) paper-alist))
\paper {
  #(set-paper-size "snippet")
  tagline = ##f
  indent = 0
}
\markup\vspace #1
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\language "deutsch"

%% often people think that the black keys are centered to the white keys
%% even in piano teaching books keyboards are drawn this way
%% this is not the case, black keys are positioned surprisingly excentric
%% http://lsr.di.unimi.it/LSR/Item?id=791 inspired me
%% to draw a keyboard with following features:
%% - scalable
%% - correct positioning of the black keys
%% - entering of notes which are represented by dots

%% created by Manuela
%% feel free to modify and distribute

%% all values are measured by myself on my piano

#(define white-key-width 23.5) %% the width of a white piano key
#(define white-key-height 150) %% the height of a white piano key
#(define black-key-width 15)   %% the width of a black piano key
#(define black-key-height 95)  %% the height of a black piano key
#(define black-key-y-start (- white-key-height black-key-height)) %% the y-coordinate of black keys

%% left coordinate of black keys cis/des fis/ges
%% n=0 oder n=3 (index number of global default scale)

#(define black-key-cis-start 13)
%% left coordinate of centered black keys gis/as
%% n=4 (index number of global default scale)
#(define black-key-gis-start 16)
%% left coordinate of right black keys dis/es ais/b
%% n=1 oder n=5 (index number of global default scale)

#(define black-key-dis-start 19)
#(define octav-distance (* 7 white-key-width))
%% define circle diameter for the dots
%% just try what looks fine
#(define kreis-dm (* black-key-width 0.5)) %% circle diameter

%% routine to move and scale a markup
#(define-markup-command (move-and-scale layout props mymark faktor x-offset)
   (markup? number? number?)
   (ly:stencil-translate-axis
     (ly:stencil-scale
       (interpret-markup layout props mymark)
       faktor faktor)
       x-offset X))

%% single white key
wh-taste =
#(make-connected-path-stencil
  ;; creates a square which is transformed
  ;; according to width and height of a white key
  '((0 0) (1 0) (1 1) (0 1))
  0.1 ;; thickness
  white-key-width
  white-key-height
  #t  ;; close path
  #f  ;; do not fill path
  )

w-tasten=
#(apply
   ly:stencil-add
   wh-taste
   (map
     (lambda (i) (ly:stencil-translate-axis wh-taste (* i white-key-width) X))
     (iota 6 1 1)))

%% combining two octaves
dos-w-octavas=
#(ly:stencil-add
   w-tasten
   (ly:stencil-translate-axis w-tasten octav-distance X))

%% defining single black key
bl-taste=
#(make-connected-path-stencil
  '((0 0) (1 0) (1 1) (0 1) )
  0.1
  black-key-width
  black-key-height
  #t  ;; close path
  #t  ;; fill path
  )

%% combining 5 black keys for one octave
b-tasten =
#(ly:stencil-add
  (ly:stencil-translate
   bl-taste
   (cons black-key-cis-start black-key-y-start))
  (ly:stencil-translate
   bl-taste
   (cons (+ black-key-dis-start white-key-width ) black-key-y-start))
  (ly:stencil-translate
   bl-taste
   (cons (+ black-key-cis-start (* white-key-width 3) ) black-key-y-start))
  (ly:stencil-translate
   bl-taste
   (cons (+ black-key-gis-start (* white-key-width 4) ) black-key-y-start))
  (ly:stencil-translate
   bl-taste
   (cons (+ black-key-dis-start (* white-key-width 5) ) black-key-y-start)))

%% combining to octaves black keys
dos-b-octavas=
#(ly:stencil-add
   b-tasten
   (ly:stencil-translate-axis b-tasten octav-distance X))

complete-keyboard-two-octaves=
#(ly:stencil-add
  dos-w-octavas
  dos-b-octavas)

#(define (music-name x)
   (if (not (ly:music? x))
       #f
       (ly:music-property x 'name)))

#(define (naturalize-pitch p)
   (let ((o (ly:pitch-octave p))
         (a (* 4 (ly:pitch-alteration p)))
         ;; alteration, a, in quarter tone steps,
         ;; for historical reasons
         (n (ly:pitch-notename p)))
     (cond
      ((and (> a 1) (or (eq? n 6) (eq? n 2)))
       (set! a (- a 2))
       (set! n (+ n 1)))
      ((and (< a -1) (or (eq? n 0) (eq? n 3)))
       (set! a (+ a 2))
       (set! n (- n 1))))
     (cond
      ((> a 2) (set! a (- a 4)) (set! n (+ n 1)))
      ((< a -2) (set! a (+ a 4)) (set! n (- n 1))))
     (if (< n 0) (begin (set! o (- o 1)) (set! n (+ n 7))))
     (if (> n 6) (begin (set! o (+ o 1)) (set! n (- n 7))))
     (ly:make-pitch o n (/ a 4))))

#(define (white-key? p)
   (let
    ((a (ly:pitch-alteration (naturalize-pitch p))))
    (if (= a 0)
        #t
        #f)))

#(define (start-point-key p)
   ;; calculation the starting point of a key
   ;; depending on the pitch p
   ;; result (x . y)
   (let*
    ((m (naturalize-pitch p))
     (o (ly:pitch-octave m))
     (a (ly:pitch-alteration m))
     ;; we must naturalize pitch otherwise wrong result for eis e.g.
     ;; we subtract the alteration from the notename and add a half
     ;; so we end up at the same note despite flat oder sharp
     ;; cis is drawn the same as des e.g.
     (n  (ly:pitch-notename m))
     (n1 (+ n a -0.5))
     (x-shift (* o 7 white-key-width))
     )
    (cond
     ((eq? a 0)
      ;; alteration eq 0
      ;; no alteration ==> white key
      (cons (+ (* n white-key-width) x-shift) 0 ))
     ((or (= n1 0) (= n1 3))
      ;; "left" black keys cis/des and fis/ges
      ;; notename=0 or 3 and alteration
      ;; n=0 oder n=3
      (cons (+ (* n1 white-key-width) black-key-cis-start x-shift ) black-key-y-start ))
     ((or (= n1 1) (= n1 5))
      ;; "right" black keys dis/es and ais/b
      ;; notename=0 or 3 and alteration
      ;, n=1 oder n=5
      (cons (+ (* n1 white-key-width) black-key-dis-start x-shift ) black-key-y-start ))
     (else
      ;; only one left, the centered black key gis/as
      (cons (+ (* n1 white-key-width) black-key-gis-start x-shift) black-key-y-start )))))

#(define (make-dot p)
   (let* ((start-p (start-point-key p)))
     (if (white-key? p)
         (ly:stencil-in-color
           (ly:stencil-translate
             (make-circle-stencil kreis-dm 0 #t)
             (cons
               (+ (car start-p) (/ white-key-width 2 ))
               (+ (cdr start-p) (/ (- white-key-height black-key-height) 1.5))))
           0.2 0.5 0.5) ;; color petrol
         (ly:stencil-in-color
           (ly:stencil-translate
             (make-circle-stencil kreis-dm 0 #t)
             (cons
               (+ (car start-p) (/ black-key-width 2 ))
               (+ (cdr start-p) (/ black-key-height 5))))
           0.4 0.7 0.7) ;; color slightly lighter petrol than above
         )))

%% creating a single stencil of multiple dots for a list of pitches
#(define (make-dot-list l1)
  (if (every ly:pitch? l1)
      (apply ly:stencil-add (map make-dot l1))
      empty-stencil))

#(define-markup-command (complete layout props the-chord)
  (ly:music?)
  (ly:stencil-scale
   (ly:stencil-add
    dos-w-octavas
    dos-b-octavas
    (make-dot-list 
      (map
        (lambda (m) (ly:music-property m 'pitch))
        (extract-named-music the-chord 'NoteEvent)))) 
    0.035 0.035))

ChordwithKeyboard=
#(define-music-function (parser location the-chord)
  (ly:music?)
  #{ <>^\markup \complete #the-chord $the-chord #})

twoOctaves=
\markup {
  \combine \stencil \dos-w-octavas
  \combine \stencil \dos-b-octavas
  \null
}

\markup "Draw a correct Keyboard with 2 octaves"
\markup \move-and-scale \twoOctaves #0.3 #0

\markup { \null \vspace #4 "Draw a correct Keyboard with 2 octaves (approx. one staff high) and a chord" }

\score {
  <<
    \new Staff \ChordwithKeyboard \chordmode { b:sus4 }
    \new ChordNames \chordmode { b:sus4 }
  >>
}

Última actualización: October 4, 2021