diff --git a/README.md b/README.md index e432007..d874017 100644 --- a/README.md +++ b/README.md @@ -74,6 +74,8 @@ con un simple comando. - git (no es imprescindible pero muy recomendable) - Las plantillas de Pandoc (o *templates*) - Un buen editor de texto + - *LaTeX* para la salida a *pdf* El proceso de instalar *LaTeX* + dependerá de tu sistema. ## Instalación de Pandoc @@ -95,8 +97,8 @@ cd .pandoc git clone https://github.com/jgm/pandoc-templates templates ``` -Esto dejará las plantillas en el directorio *~/.pandoc/templates* que es -uno de los directorios donde Pandoc busca las plantillas. +Esto dejará las plantillas en el directorio *\~/.pandoc/templates* que +es uno de los directorios donde Pandoc busca las plantillas. No hay inconveniente en dejar las plantillas en otro directorio, o incluso en el arbol de nuestro proyecto, pero habría que retocar el diff --git a/makefile b/makefile index 63ea264..a3b22bc 100644 --- a/makefile +++ b/makefile @@ -21,10 +21,10 @@ pdf_opt := --from markdown --standalone --variable geometry:a4paper --variable l ## Recipes for targets # These targets are not files -.PHONY: clean pdf latex mediawiki epub github +.PHONY: clean pdf latex mediawiki dokuwiki epub github # all -- This target try to build every thing -all: pdf latex mediawiki epub github docx +all: pdf latex mediawiki dokuwiki epub github docx # reset -- This target deletes every target and then tries to build everithing reset: clean all @@ -52,6 +52,13 @@ $(output)/$(target).mw: $(sources) --output=$(output)/$(target).mw \ $(sources) +# dokuwiki -- buid dokuwiki file into output directory +dokuwiki: $(output)/$(target).dw $(sources) +$(output)/$(target).dw: $(sources) + pandoc --from markdown --to dokuwiki \ + --output=$(output)/$(target).dw \ + $(sources) + #epub -- buid epub file into output directory epub: $(output)/$(target).epub $(sources) $(output)/$(target).epub: $(sources) @@ -84,6 +91,7 @@ clean: rm -f $(output)/*.pdf rm -f $(output)/*.tex rm -f $(output)/*.mw + rm -f $(output)/*.dw rm -f $(output)/*.odt rm -f $(output)/*.docx rm -r README.md diff --git a/out/documento.docx b/out/documento.docx index 25301c9..6e2c3c2 100644 Binary files a/out/documento.docx and b/out/documento.docx differ diff --git a/out/documento.dw b/out/documento.dw new file mode 100644 index 0000000..fc389d5 --- /dev/null +++ b/out/documento.dw @@ -0,0 +1,323 @@ +====== ¿Cómo usar esto? ====== + +===== Muy rápido ===== + +Clona el repo en un directorio : + + +git clone https://bitbucket.org/salvari/pandoc_basico + +Renombra el directorio: + + +mv pandoc_basico miProyecto + +Elimina la info de git + + +rm -rf miProyecto/.git + +Edita el fichero miProyecto/src/documento.md con tu editor de texto favorito. + +Ejecuta: + + * **make** Para generar todos los ficheros de salida y el fichero README.md (equivale a //make all//) + * **make clean** Para borrar todos los ficheros de salida + * **make reset** Equivale a //make clean all// + +===== Más detalles ===== + +El makefile está preparado para procesar **todos** los ficheros con extensión //.md// que haya en el directorio //src//. Esto permite escribir documentos largos y dividirlos en secciones, por ejemplo podríamos tener los siguientes documentos en el directorio //src// + + +00_Comienzo.md +10_Capitulo_01.md +20_Capitulo_02.md +30_Conclusion.md +40_apendices.md + +Al ejecutar make nos crearía **un solo documento de salida** concatenando todos los ficheros. El orden en que los concatena es el orden en el que aparecen al hacer un //ls// por eso se nombran con una numeración al principio que permita ordenarlos a gusto del autor. + +Si quieres cambiar el nombre del fichero de salida (//documento//) tendrás que editar el makefile y cambiar la línea: + + +target := documento + +Otras líneas que puedes tocar en el makefile son las que especifican el idioma y los tipos de letra usados. + +====== ¿Qué es Pandoc? ====== + +Como explican en http:%%//%%pandoc.org, Pandoc es una librería en Haskell para hacer conversión de documentos de un formato markup a otro. Y también es una herramienta de terminal de comandos que usa esa librería. + +Lo que nos permite Pandoc a la hora de documentar un proyecto es mantener la documentación en un formato abierto y sencillo (markdown) y generar salidas en distintos formatos (pdf, mediawiki, epub, html, etc) con un simple comando. + +====== ¿Qué necesitas tener instalado? ====== + + * Pandoc + * make + * git (no es imprescindible pero muy recomendable) + * Las plantillas de Pandoc (o //templates//) + * Un buen editor de texto + * //LaTeX// para la salida a //pdf// El proceso de instalar //LaTeX// dependerá de tu sistema. + +===== Instalación de Pandoc ===== + +Los paquetes de Pandoc están disponibles en la [[http://pandoc.org/installing.html|página de descargas del proyecto]]. En el caso de Ubuntu se instala sin más que descargar el paquete y abrirlo con el Centro de Software. + +===== Instalación de plantillas de Pandoc ===== + +Hay muchas plantillas para generar documentación con Pandoc, puestas a disposición de la comunidad. De momento nos hemos limitado a las plantillas del creador de Pandoc: + + +cd +mkdir .pandoc +cd .pandoc +git clone https://github.com/jgm/pandoc-templates templates + +Esto dejará las plantillas en el directorio //~/.pandoc/templates// que es uno de los directorios donde Pandoc busca las plantillas. + +No hay inconveniente en dejar las plantillas en otro directorio, o incluso en el arbol de nuestro proyecto, pero habría que retocar el //makefile// para que Pandoc las encontrara sin problemas. + +====== Chuletario de Pandoc ====== + +===== Backslash Escapes ===== + +Salvo que estemos dentro de un bloque de código o de “código en linea”, **cualquier carácter de puntuación o espacio** precedido de contrabarra se tratará de forma literal, incluso si ese carácter normalmente indique algún formato. + +===== Bloque de título ===== + +Es una forma rápida de indicar el título el autor o autores y la fecha. Tiene que ir al principio del documento + + +% título +% autor(es) (separados por :) +% fecha + +Alternativamente se puede usar otro estilo para el bloque de título, mucho más completo, en formato [[https://en.wikipedia.org/wiki/YAML|YAML]], especificando variables. No puede usarse simultáneamente con el anterior, hay que escoger entre los dos estilos. + +Se pueden especificar todo tipo de variables ((Ojo por que en el makefile propuesto se especifica el lenguaje, asi que la variable del bloque de título no va a tener efecto en este caso. +)). + + +--- +title: Título +author: +- Autor Uno +- Otro autor +tags: [nothing, nothingness] +date: enero-2016 +lang: es-ES +abstract: | + Este es el resumen. + + Con dos párrafos. +... +--- + +===== Incrustar TeX y HTML ===== + + * Los comandos TeX se pasan de forma transparente al Markdown, y afectan solo a la salida de LaTeX y ConTeXt; en el resto de casos se borran + * El código HTML pasará a la salida sin cambios, pero el Markdown dentro de los bloques HTML se procesa como Markdown + +===== Párrafos y retornos de línea ===== + + * Un párrafo es una o más líneas de texto separadas por una linea en blanco del resto + * Una línea que termina con dos espacios, o una línea que termina con un fin de linea escapado (contrabarra seguida de retorno de linea) indica un cambio de linea manual + +===== Itálica, negrita, superescrito, subesctrito, tachado ===== + + +*Itálica* and **negrita** se indican con asteriscos. + +Para ~~tachar~~ texto usa tildes dobles. + +Superscrito se indica así: 2^ndo^. + +Subescrito con tildes simples, así: H~2~O. + +Los espacios en el superescrito y el subescrito tienen que ir escapados, +p.ej., H~esto\ es \ un\ subescrito~. + +===== TeX matemático o código incrustado en linea ===== + + +El TeX matemático va entre signos$: $2 + 2$. + +El código en linea va entre comillas invertidas: `echo 'hello'` + +===== Enlaces e imágenes ===== + + + + +[inline link](http://example.com "Title") +![inline image](/path/to/image, "alt text") + +[reference link][id] +[implicit reference link][] +![reference image][id2] + +[id]: http://example.com "Title" +[implicit reference link]: http://example.com +[id2]: /path/to/image "alt text" + +===== Notas al pie de página ===== + + +Las notas en linea son como +esta.^[Nótese que las notas en linea no pueden tener más de un párrafo.] +Las notas de referencia son como esta.[^id] + +[^id]: Las notas de referencia pueden contener varios párrafos. + + Los parámetros a continuación deben estar identados. + +===== Citas ===== + + +Blah blah [see @doe99, pp. 33-35; also @smith04, ch. 1]. + +Blah blah [@doe99, pp. 33-35, 38-39 and *passim*]. + +Blah blah [@smith04; @doe99]. + +Smith says blah [-@smith04]. + +@smith04 says blah. + +@smith04 [p. 33] says blah. + +===== Encabezados ===== + + +Encabezado 1 +======== + +Encabezado 2 +-------- + +# Encabezado 1 # + +## Encabezado 2 ## + +Las almohadillas de cierre # son opcionales. Es necesario añadir una línea en blanco antes y después de cada cabecera. + +===== Listas ===== + +=== Listas Ordenadas === + + +1. example +2. example + +A) example +B) example + +=== Listas desordenadas === + +Los items de la lista deben ir marcados con ‘*’, ‘+’, or ‘-’. + + ++ example +- example +* example + +Las listas se pueden anidar de la forma usual: + + ++ example + + example ++ example + +=== Listas de definición === + + +Term 1 + +: Definition 1 + +Term 2 + +: Definition 2 + Second paragraph of definition 2. + +===== Blockquotes ===== + + +> blockquote +>> nested blockquote + +Es necesario añadir lineas en blanco antes y después de los bloques-cita. + +===== Tablas ===== + + + Right Left Center Default +------- ------ ---------- ------- + 12 12 12 12 + 123 123 123 123 + 1 1 1 1 + +Table: Demonstration of simple table syntax. + +(Para tablas más complejas consulta la [[http://pandoc.org/README.html#tables|documentación de Pandoc]].) + +===== Bloques de código ===== + +Los bloques de código empiezan con tres o más tildes; y acaban por lo menos con el mismo número de tildes: + + +~~~~~~~ +{code here} +~~~~~~~ + +Opcionalmente, se puede especificar el lenguaje que corresponde al bloque de código: + + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ {.haskell .numberLines} +qsort [] = [] +qsort (x:xs) = qsort (filter (< x) xs) ++ [x] ++ + qsort (filter (>= x) xs) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +===== Lineas horizontales ===== + +3 o mas guiones o asteriscos en una linea (se permiten espacios intercalados) + + +--- +* * * +- - - - + +===== Bloques verbatim ===== + +Todo el texto identado cuatro espacios + + +Ejemplo Esto es un bloque verbatim y por ejemplo *esto* aparece +tal cual y no en itálica. + +===== Notas a pie de página ===== + + +Referencia[^1], y una nota[^larga] + +[^1]: Cobbled together from + and + . + +[^larga] Una nota que tiene. + + Varias lineas + + {incluso código} + + Mas lineas + +Esto ya no es de la nota larga + +====== En que me he basado (o copiado si lo prefieres) ====== + + * En la [[http://pandoc.org/README.html|guia de usuario de Pandoc]] Importante leersela para sacarle todo el jugo a esta herramienta + * En la [[https://github.com/dsanson/Pandoc.tmbundle/blob/master/Support/doc/cheatsheet.markdown|chuleta de Pandoc]] de [[https://github.com/dsanson|David Sanson]], perfecta para referencia rápida + * Para hacer el makefile me he leido varios tutoriales y copiado descaradamente de varios sitios que olvidé apuntar (lo siento) diff --git a/out/documento.epub b/out/documento.epub index 8a6e63d..b514586 100644 Binary files a/out/documento.epub and b/out/documento.epub differ diff --git a/out/documento.mw b/out/documento.mw index 989ebc0..9ac1d84 100644 --- a/out/documento.mw +++ b/out/documento.mw @@ -51,6 +51,7 @@ Lo que nos permite Pandoc a la hora de documentar un proyecto es mantener la doc * git (no es imprescindible pero muy recomendable) * Las plantillas de Pandoc (o ''templates'') * Un buen editor de texto +* ''LaTeX'' para la salida a ''pdf'' El proceso de instalar ''LaTeX'' dependerá de tu sistema. == Instalación de Pandoc == diff --git a/out/documento.pdf b/out/documento.pdf index a80946a..27f74cb 100644 Binary files a/out/documento.pdf and b/out/documento.pdf differ diff --git a/out/documento.tex b/out/documento.tex index 91c6946..d725b5b 100644 --- a/out/documento.tex +++ b/out/documento.tex @@ -1,72 +1,67 @@ -\PassOptionsToPackage{unicode=true}{hyperref} % options for packages loaded elsewhere +% Options for packages loaded elsewhere +\PassOptionsToPackage{unicode}{hyperref} \PassOptionsToPackage{hyphens}{url} \PassOptionsToPackage{dvipsnames,svgnames*,x11names*}{xcolor} % -\documentclass[12pt,spanish,]{article} +\documentclass[ + 12pt, + spanish, +]{article} \usepackage{lmodern} \usepackage{amssymb,amsmath} \usepackage{ifxetex,ifluatex} -\usepackage{fixltx2e} % provides \textsubscript \ifnum 0\ifxetex 1\fi\ifluatex 1\fi=0 % if pdftex \usepackage[T1]{fontenc} \usepackage[utf8]{inputenc} - \usepackage{textcomp} % provides euro and other symbols -\else % if luatex or xelatex + \usepackage{textcomp} % provide euro and other symbols +\else % if luatex or xetex \usepackage{unicode-math} - \defaultfontfeatures{Ligatures=TeX,Scale=MatchLowercase} - \setmainfont[]{Ubuntu} - \setmonofont[Mapping=tex-ansi]{Ubuntu Mono} + \defaultfontfeatures{Scale=MatchLowercase} + \defaultfontfeatures[\rmfamily]{Ligatures=TeX,Scale=1} + \setmainfont[]{Ubuntu} + \setmonofont[]{Ubuntu Mono} \fi -% use upquote if available, for straight quotes in verbatim environments +% Use upquote if available, for straight quotes in verbatim environments \IfFileExists{upquote.sty}{\usepackage{upquote}}{} -% use microtype if available -\IfFileExists{microtype.sty}{% -\usepackage[]{microtype} -\UseMicrotypeSet[protrusion]{basicmath} % disable protrusion for tt fonts +\IfFileExists{microtype.sty}{% use microtype if available + \usepackage[]{microtype} + \UseMicrotypeSet[protrusion]{basicmath} % disable protrusion for tt fonts }{} -\IfFileExists{parskip.sty}{% -\usepackage{parskip} -}{% else -\setlength{\parindent}{0pt} -\setlength{\parskip}{6pt plus 2pt minus 1pt} -} +\makeatletter +\@ifundefined{KOMAClassName}{% if non-KOMA class + \IfFileExists{parskip.sty}{% + \usepackage{parskip} + }{% else + \setlength{\parindent}{0pt} + \setlength{\parskip}{6pt plus 2pt minus 1pt}} +}{% if KOMA class + \KOMAoptions{parskip=half}} +\makeatother \usepackage{xcolor} -\usepackage{hyperref} +\IfFileExists{xurl.sty}{\usepackage{xurl}}{} % add URL line breaks if available +\IfFileExists{bookmark.sty}{\usepackage{bookmark}}{\usepackage{hyperref}} \hypersetup{ - pdftitle={Usando Pandoc}, - pdfauthor={Sergio Alvariño salvari@gmail.com}, - colorlinks=true, - linkcolor=Maroon, - citecolor=Blue, - urlcolor=Blue, - breaklinks=true} -\urlstyle{same} % don't use monospace font for urls + pdftitle={Usando Pandoc}, + pdfauthor={Sergio Alvariño salvari@gmail.com}, + pdflang={es-ES}, + colorlinks=true, + linkcolor=Maroon, + filecolor=Maroon, + citecolor=Blue, + urlcolor=Blue, + pdfcreator={LaTeX via pandoc}} +\urlstyle{same} % disable monospaced font for URLs \usepackage[a4paper]{geometry} -\setlength{\emergencystretch}{3em} % prevent overfull lines +\setlength{\emergencystretch}{3em} % prevent overfull lines \providecommand{\tightlist}{% \setlength{\itemsep}{0pt}\setlength{\parskip}{0pt}} \setcounter{secnumdepth}{5} -% Redefines (sub)paragraphs to behave more like sections -\ifx\paragraph\undefined\else -\let\oldparagraph\paragraph -\renewcommand{\paragraph}[1]{\oldparagraph{#1}\mbox{}} -\fi -\ifx\subparagraph\undefined\else -\let\oldsubparagraph\subparagraph -\renewcommand{\subparagraph}[1]{\oldsubparagraph{#1}\mbox{}} -\fi - -% set default figure placement to htbp -\makeatletter -\def\fps@figure{htbp} -\makeatother - -\ifnum 0\ifxetex 1\fi\ifluatex 1\fi=0 % if pdftex - \usepackage[shorthands=off,main=spanish]{babel} -\else - % load polyglossia as late as possible as it *could* call bidi if RTL lang (e.g. Hebrew or Arabic) +\ifxetex + % Load polyglossia as late as possible: uses bidi with RTL langages (e.g. Hebrew, Arabic) \usepackage{polyglossia} \setmainlanguage[]{spanish} +\else + \usepackage[shorthands=off,main=spanish]{babel} \fi \title{Usando Pandoc} @@ -186,6 +181,9 @@ instalado?}\label{quuxe9-necesitas-tener-instalado}} Las plantillas de Pandoc (o \emph{templates}) \item Un buen editor de texto +\item + \emph{LaTeX} para la salida a \emph{pdf} El proceso de instalar + \emph{LaTeX} dependerá de tu sistema. \end{itemize} \hypertarget{instalaciuxf3n-de-pandoc}{% @@ -212,7 +210,7 @@ git clone https://github.com/jgm/pandoc-templates templates \end{verbatim} Esto dejará las plantillas en el directorio -\emph{\textasciitilde{}/.pandoc/templates} que es uno de los directorios +\emph{\textasciitilde/.pandoc/templates} que es uno de los directorios donde Pandoc busca las plantillas. No hay inconveniente en dejar las plantillas en otro directorio, o diff --git a/src/documento.md b/src/documento.md index c008391..9fa6646 100644 --- a/src/documento.md +++ b/src/documento.md @@ -89,6 +89,8 @@ etc) con un simple comando. * git (no es imprescindible pero muy recomendable) * Las plantillas de Pandoc (o *templates*) * Un buen editor de texto +* _LaTeX_ para la salida a _pdf_ El proceso de instalar _LaTeX_ + dependerá de tu sistema. ## Instalación de Pandoc