---
breaks: false
repo: https://mutabit.com/repos.fossil/documentaton/
level: beginner
language: es
sync: 
  - https://docutopia.tupale.co/inkit:r3p:codimd
  - repo://es/capitulos/codimd.md

---

# CodiMD: Escritura síncrona colectiva

En ocasiones queremos escribir a muchas manos.
Puede ser que estemos en un taller y queramos tomar notas de manera colectiva.
O bien estamos trabajando en un documento y quisiéramos reunirnos con coautores
para arrojar ideas, escribir subsecciones o realizar correcciones.
Para ello se han creado varias plataformas que con sólo un enlace web permiten
iniciar la colaboración con todos los que tengan dicho enlace (suponiendo que
tienen los permisos para ello).
Debido a que cuando los coautores se encuentran a través de la web, pueden
escribir al mismo tiempo y ver los cambios de otros, se dice que dichas plataformas
trabajan en "tiempo real".

Por otro lado, a veces queremos facilitar los procesos de escritura desde múltiples
dispositivos y pantallas (incluso las pequeñas de dispositivos móviles) y en este caso 
un lenguaje de etiquetamiento ligero es una mejor opción que un editor pesado como
Google Docs u Office 360, pues permite concentrarse en el contenido y explicitar
ágilmente la estructura con unas marcas sencillas.
Puedes ver más sobre dichas motivaciones en nuestro texto introductorio
sobre [documentación aǵil](./inkit:r3p:agiledoc).

[CodiMD][codimd] es una de tales plataformas para escritura colectiva en
tiempo real, usando lenguages de etiquetamiento ligeros.
Emplea un supraconjunto de [Markdown][markdown], llamado [CommonMark][commonmark],
que permite varias características necesarias en la edición de textos profesionales,
como tablas, avisos (advertencias, consejos), imágenes, videos, notas a pie de página,
entre otros.
El documento que estás leyendo acá, por ejemplo fue escrito colectivamente empleando 
CodiMD.

Una de sus principales ventajas es que permite ver en simultáneo el código
de lo que se escribe, como su previsualización, empleando para ello un sistema
de páneles dobles simultáneos, así las personas pueden enfocarse sólo en la escritura,
sólo en la lectura o en ambas.

![Vista dual de este capítulo en CodiMD, mostrando su código fuente también.](https://i.imgur.com/boCJCX3.png)

## Registro

El registro se puede hacer de dos formas,
usando herramientas externas como GitHub, Google o
Twitter o a través del registro por correo
electrónico.

::: danger
  Revisar definición de las capturas
:::

Luego de elegir una de estas opciones y validar el
registro, es posible editar los documentos.

A diferencia de los Pads que se han venido utizando en  los Data Rodas anteriores,
en donde los documentos quedan públicos y abiertos a la edición de cualquier persona,
en esta oportunidad se ponen en debate la limitacion en la edición de contenidos por
terceras personas agenas al proyecto, con el fin de garantizar la privacidad y seguridad
de la documentación producida.
<!--
Lecciones de Montenegro. Algunos asistentes, según cuenta Offray, pusieron en consideración
esta práctica justamente por la seguridad de la información que se genera de manera colaborativa.
-->

:::success
  <i class="fa fa-wrench fa-fw"></i> Regístrate en un proveedor de CodiMD como [Docutopia][docutopia] o [Heroku][codimd].
:::

## Crear pads

Escencialmente hay dos formas:

- Desde la portada de la instancia de CodiMD.

   A través del botón azul en la esquina superior derecha de la pantalla, como se vé a continuación

  ![](https://docutopia.tupale.co/uploads/upload_53fdcf0006673b98c50920a131db0c3b.png){width=40%}

- A través de un enlace al nuevo documento.

    Durante el proceso de documentación colaborativa podemos incluir enlaces en los documetos
    de manera fluida, para los efectos de esta comunidad se van a relacionar contenidos siguiedo
    la estructura de enlaces de Markdown, con la siguiente convención:

    - se incluirá entre corchetes cuadrados el texto que va a contener el enlace, por ejemplo `[texto]`.
    - Luego se incluirá el complemento de la URL del recurso, determinando la ruta de orignen del nuevo documento 
        entre paréntesis "`()`".
    - El contenido entre paréntesis incluirá la ruta a partir del "./" para referirse al servidor que estamos usando, 
        seguido de dos puntos (`:`) para diferenciar las "carpetas" o secciones del tema relacionadas con el contenido.
    - Finalmente, el resultado será algo como [texto](./tema1:subtema1). Para referenciarlo al ejercicio de esta sesión sería algo como 

        ```
      [texto](./tema:subtema:pad)
    ```

        En donde el texto del enlace "`texto`" refiere al lugar usando en el servidor de Docutopia
        relacionado con los contenidos de la tema y el subtema.

:::success
  <i class="fa fa-wrench fa-fw"></i> Crea un pad en el proveedor en el que te registraste en la actividad previa.
:::

## Descargar pads

Una vez hemos creado nuestros documentos en línea, puede ser necesario descargarlos
para tener una copia de respaldo de los mismos o trabajarlos fuera de línea.
Acá veremos tres métodos para ello.

### Desde el navegador

A través de la vista de escritura, podemos acceder al menú desde el botón en el margen superior derecho, donde se muestran las diferentes opciones de descarga del documento: Markdown, HTML, HTML Raw y PDF.

![](https://docutopia.tupale.co/uploads/upload_8da2970cc744b352322693d929699d7a.png){width=60%}

:::success
  <i class="fa fa-wrench fa-fw"></i> Descarga un pad desde el navegador.
:::

### Con wget

:::info
  Suponemos que para esta parte tienes instalada la terminal o consola,
  o [línea de comandos][w:cli], que sabes cómo abrirla y los elementos
  básicos de escribir y ejecutar comandos en ella.
  También que tienes instalados los programas que se usan habitualmente
  en ella, como `wget`.

  Usaremos los términos terminal, consola o línea de comandos de manera
  intercambiable.
:::

Otra de las maneras de descargar un documento es emplear la terminal.
La ventaja de este procedimiento es que podemos agilizar muchas descargas con
sólo repetir un comando de una línea, lo cual abre a su vez la posibilidad de
automatizarlo.

Para descargar este documento, abre la terminal y escribe:

```bash=
  wget -O codimd.md https://docutopia.tupale.co/inkit:r3p:codimd/download
```

Con esto hemos creado un archivo llamado `codi.md`, en el disco duro, con los contenidos 
guardados en la dirección del pad cuyo enlace es `inkit:r3p:codimd` y está hospedado 
dentro del servidor `https://docutopia.tupale.co`.
Si queremos descargar otros pads con otros enlaces, creados en otro servidor, o guardarlos 
con otros nombres de archivo, deberemos cambiar el comando previo respectivamente.

:::success
  <i class="fa fa-wrench fa-fw"></i> Descarga un pad utilizando `wget`.
:::

### Con Pharo

[Pharo](./pharo) es la plataforma sobre la cual está hecho [Grafoscopio](./grafoscopio),
que a su vez sirve para integrar y automatizar mucho del trabajo sobre investigación
y publicación reproducible y remezclable, así que veremos cómo emplearla en las actividades
de este texto de maneras progresivamente más elaboradas.

(pista: elegant code).

[codimd]: https://hackmd-ce.herokuapp.com/
[commonmark]: http://commonmark.org/
[docutopia]: https://docutopia.tupale.co/
[markdown]: https://es.wikipedia.org/wiki/Markdown
[pharo]: http://pharo.org/
[w:cli]: https://en.wikipedia.org/wiki/Command-line_interface
