Browse Source

Añade el formato dokuwiki a los formatos de salida

Añade también una indicación de que hay que tener LaTeX instalado para
generar salida pdf
master
Sergio Alvariño 3 years ago
parent
commit
897e2d2fcb
  1. 6
      README.md
  2. 12
      makefile
  3. BIN
      out/documento.docx
  4. 323
      out/documento.dw
  5. BIN
      out/documento.epub
  6. 1
      out/documento.mw
  7. BIN
      out/documento.pdf
  8. 96
      out/documento.tex
  9. 2
      src/documento.md

6
README.md

@ -74,6 +74,8 @@ con un simple comando. @@ -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 @@ -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

12
makefile

@ -21,10 +21,10 @@ pdf_opt := --from markdown --standalone --variable geometry:a4paper --variable l @@ -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) @@ -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: @@ -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

BIN
out/documento.docx

Binary file not shown.

323
out/documento.dw

@ -0,0 +1,323 @@ @@ -0,0 +1,323 @@
====== ¿Cómo usar esto? ======
===== Muy rápido =====
Clona el repo en un directorio :
<code>
git clone https://bitbucket.org/salvari/pandoc_basico
</code>
Renombra el directorio:
<code>
mv pandoc_basico miProyecto
</code>
Elimina la info de git
<code>
rm -rf miProyecto/.git
</code>
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//
<code>
00_Comienzo.md
10_Capitulo_01.md
20_Capitulo_02.md
30_Conclusion.md
40_apendices.md
</code>
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:
<code>
target := documento
</code>
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:
<code>
cd
mkdir .pandoc
cd .pandoc
git clone https://github.com/jgm/pandoc-templates templates
</code>
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
<code>
% título
% autor(es) (separados por :)
% fecha
</code>
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.
)).
<code>
---
title: Título
author:
- Autor Uno <autor.uno@correo.com>
- Otro autor <otroautor@correo.com>
tags: [nothing, nothingness]
date: enero-2016
lang: es-ES
abstract: |
Este es el resumen.
Con dos párrafos.
...
---
</code>
===== 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 =====
<code>
*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~.
</code>
===== TeX matemático o código incrustado en linea =====
<code>
El TeX matemático va entre signos$: $2 + 2$.
El código en linea va entre comillas invertidas: `echo 'hello'`
</code>
===== Enlaces e imágenes =====
<code>
<http://example.com>
<foo@bar.com>
[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"
</code>
===== Notas al pie de página =====
<code>
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.
</code>
===== Citas =====
<code>
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.
</code>
===== Encabezados =====
<code>
Encabezado 1
========
Encabezado 2
--------
# Encabezado 1 #
## Encabezado 2 ##
</code>
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 ===
<code>
1. example
2. example
A) example
B) example
</code>
=== Listas desordenadas ===
Los items de la lista deben ir marcados con ‘*’, ‘+’, or ‘-’.
<code>
+ example
- example
* example
</code>
Las listas se pueden anidar de la forma usual:
<code>
+ example
+ example
+ example
</code>
=== Listas de definición ===
<code>
Term 1
: Definition 1
Term 2
: Definition 2
Second paragraph of definition 2.
</code>
===== Blockquotes =====
<code>
> blockquote
>> nested blockquote
</code>
Es necesario añadir lineas en blanco antes y después de los bloques-cita.
===== Tablas =====
<code>
Right Left Center Default
------- ------ ---------- -------
12 12 12 12
123 123 123 123
1 1 1 1
Table: Demonstration of simple table syntax.
</code>
(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>
~~~~~~~
{code here}
~~~~~~~
</code>
Opcionalmente, se puede especificar el lenguaje que corresponde al bloque de código:
<code>
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ {.haskell .numberLines}
qsort [] = []
qsort (x:xs) = qsort (filter (< x) xs) ++ [x] ++
qsort (filter (>= x) xs)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
</code>
===== Lineas horizontales =====
3 o mas guiones o asteriscos en una linea (se permiten espacios intercalados)
<code>
---
* * *
- - - -
</code>
===== Bloques verbatim =====
Todo el texto identado cuatro espacios
<code>
Ejemplo Esto es un bloque verbatim y por ejemplo *esto* aparece
tal cual y no en itálica.
</code>
===== Notas a pie de página =====
<code>
Referencia[^1], y una nota[^larga]
[^1]: Cobbled together from
<http://daringfireball.net/projects/markdown/syntax> and
<http://johnmacfarlane.net/pandoc/README.html>.
[^larga] Una nota que tiene.
Varias lineas
{incluso código}
Mas lineas
Esto ya no es de la nota larga
</code>
====== 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)

BIN
out/documento.epub

Binary file not shown.

1
out/documento.mw

@ -51,6 +51,7 @@ Lo que nos permite Pandoc a la hora de documentar un proyecto es mantener la doc @@ -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 ==

BIN
out/documento.pdf

Binary file not shown.

96
out/documento.tex

@ -1,72 +1,67 @@ @@ -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}} @@ -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 @@ -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

2
src/documento.md

@ -89,6 +89,8 @@ etc) con un simple comando. @@ -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

Loading…
Cancel
Save