Blog

Hace una semana llegó a mis manos un artículo de Nature.com sobre redacción colaborativa mediante un software llamado Manubot [zotpressInText item=”{6612042:4ZV38YIM}”]. El artículo explica la posibilidad de redactar de forma abierta manuscritos científicos. La idea central es implementar un sistema de control de versiones (Git) online (GitHub) para organizar la redacción de documentos. Este método propone un cambio de paradigma a la forma habitual de trabajar de un investigador, ya que el sistema permite visualizar en todo momento el avance del documento. Al trabajar en la plataforma GitHub es posible administrar la colaboración de un grupo de participantes numeroso. Además, existe la posibilidad de que cualquier persona con conocimientos del tema pueda proponer cambios al proyecto, en caso de ser aceptados dichos cambios, estos pueden ser integrados al manuscrito final.

En el artículo Open Collaborative with Manubot se muestra la descripción completa del software [zotpressInText item=”{6612042:3HQ9UM3P}”]. Esta plataforma cuenta con una cantidad importante de características para el trabajo colaborativo, entre ellas destaca la posibilidad de citar documentos mediante el uso de los identificadores digitales (DOI – Digital object identifier), esto quiere decir que se evita la confusión por el uso de base de datos personales de cada miembro. En la Figura 1, podemos observar la comparación de características entre las distintas plataformas que permiten redactar documentos de forma colaborativa. Sin duda alguna, la propuesta que ofrece Manubot es excelente. Sin embargo, para poder utilizarla se requiere de habilidades básicas de programación.

Para trabajar en Manubot se requiere conocimientos básicos de programación: Git + GitHub + Markdown

El principio de funcionamiento de Manubot se muestra en la Figura 2. Se ingresa código mediante lenguaje Markdown y se obtiene como resultado un manuscrito en distintos formatos (.html, .pdf, .docx.) que son utilizados para someter a publicación en una revista científica.

Después de leer las bondades del sistema Manubot, me he aventurado a implementar (clonar) el sistema para producir mi propio manuscrito online. Ahora que he logrado instalarlo, quiero compartir la experiencia contigo. Pero, antes de iniciar debo advertir que no fue fácil configurar el sitio ya que primero tuve que aprender sobre el funcionamiento de la plataforma GitHub.com.

---

Metodología

Mi experiencia en la instalación de Manubot ha sido desde el sistema operativo macOS. Sin embargo, también es posible implementarlo desde sistemas operativos como Windows y Linux. A continuación presento de forma general la metodología que seguí para lograr generar el manuscrito.

Yo tardé un par de días en lograr instalar el sistema, por lo tanto quiero facilitarte este trabajo. Sigue la guía de instalación paso a paso. Al final sólo habrá que editar el manuscrito e invitar (retar) a tus colegas a trabajar con Manubot.

---

Guía de Instalación de Manubot

Antes de iniciar es necesario contar con una terminal-shell en nuestro sistema operativo e ir a la carpeta en la cual queremos instalar el proyecto. En mi caso, al instalar GitHub desktop se ha creado una carpeta en Documentos/GitHub. Es en este lugar donde iniciaremos el terminal. Nota: Mac y Linux cuentan por defecto con un terminal-shell mientras que en Windows se debe instalar (Git Bash o Windows Subsystem for Linux).

1. Personalizar configuración

Ejecutaremos los siguientes comandos en la terminal para personalizar la configuración. No olvides colocar tus datos, nombre de usuario y nombre del repositorio.

# GitHub usuario (cambia a tu nombre de usuario )
OWNER=jesuscapistran

# Nombre de repositorio (proyecto nuevo)
REPO=mymanuscript

2. Clonar repositorios

Al clonar el repositorio rootstock tendremos una carpeta con nombre mymanuscript dentro de la carpeta Documentos/GitHub. Además, ejecutamos las siguientes instrucciones para configurar los remotes.

# Clone manubot/rootstock
git clone --single-branch https://github.com/manubot/rootstock.git \$REPO
cd \$REPO

# Configure remotes
git remote add rootstock https://github.com/manubot/rootstock.git

# Option A: Set origin URL using its web address
git remote set-url origin https://github.com/\$OWNER/\$REPO.git

3. Crear repositorio en GitHub

En esta etapa crearemos un repositorio público nuevo en GitHub (https://github.com/new) con el nombre propuesto (REPO), en mi caso mymanuscript. Nota: En caso de querer un proyecto privado se debe pagar una cuota, esto se debe a que GitHub es una plataforma que promueve el código abierto.

4. Subir contenido

Una vez creado el repositorio procedemos a subir el contenido de mymanuscript al repositorio creado en GitHub con el siguiente comando:

git push -u origin main

5. Implementar GitHub actions

En este momento, el proyecto completo de Manubot ya se encuentra en nuestro repositorio de GitHub.com. Por lo tanto, ahora borraremos los siguientes archivos (travis.yml, appveyor.yml, install.sh ) para activar de forma automática la funcionalidad de GitHub Actions. Al utilizar GitHub Actions, se activará la compilación del código cada vez que se aprueben cambios en el manuscrito.

# remove Travis CI config
git rm .travis.yml

# remove AppVeyor config
git rm .appveyor.yml

6. Actualizar README.md

Otro cambio necesario, es actualizar el archivo README.md del proyecto con nuestros datos de nombre usuario (OWNER) y repositorio (REPO). Usa el siguiente código en la terminal para hacerlo.

# Perform substitutions
sed "s/manubot\/rootstock/\$OWNER\/\$REPO/g" README.md > tmp && mv -f tmp README.md

sed "s/manubot\.github\.io\/rootstock/\$OWNER\.github\.io\/\$REPO/g" README.md > tmp && mv -f tmp README.md

7. Finalizar instalación de Manubot

Como hemos realizado dos cambios después de subir los archivos de Manubout, es importante actualizar nuestro repositorio en GitHub.com https://github.com/jesuscapistran/mymanuscript . Esto se logra al ejecutar los siguientes comandos.

git add --update

git commit --message "Brand repo to \$OWNER/\$REPO"

git push -u origin main

Una vez realizados los cambios podemos ir a la sección Actions de nuestro repositorio, aquí podremos ver que Manubot procede a ejecutar una acción continua (compilar el proyecto completo) para generar la nueva versión de nuestro manuscrito en forma de pagina web dinámica HTML o documento PDF.

8. Activar y configurar GitHub-Pages

Para mostrar el manuscrito en forma de página web dinámica, es necesario indicar a nuestro repositorio (mymanuscript) el lugar donde se encuentra el código fuente (contenido). En la sección de configuración de nuestro repositorio (https://github.com/jesuscapistran/mymanuscript/settings) iremos al apartado GitHub Pages e indicaremos que la fuente será proporcionada por la rama(Branch) llamada gh-pages. Observa la siguiente imagen.

---

Editar el manuscrito (Online)

Al haber actualizado el archivo README.md y guardar los cambios se obtendrán dos links personalizados que nos dirigen a nuestro manuscrito generado.

• HTML at https://jesuscapistran.github.io/mymanuscript/
• PDF at https://jesuscapistran.github.io/mymanuscript/manuscript.pdf

Para editar el manuscrito existen diversas formas (GitHub Desktop, GitHub.com y Git). Por motivos de prueba usaremos la versión online GitHub.com. El contenido del manuscrito lo encontraremos en la carpeta content de nuestro repositorio.

Como ejemplo editaremos el archivo metadata.yaml . Este archivo contiene nuestros datos personales. En mi caso, agregué el siguiente código donde expongo el título de un posible manuscrito, las palabras clave, etc.

---
title: "Buffer layer analysis in copper antimony sulfide solar cell: A SCAPS-1D numerical simulation"
keywords:
  - CAS
  - thin-film
  - solar cells
  - scaps-1d
lang: en-US
authors:
  - github: jesuscapistran
    name: Jesús Capistrán-Martínez
    initials: JCM
    orcid: 0000-0001-8555-5440
    twitter: capis
    email: capistran@gmail.com
    affiliations:
      - Renewable Energy Institute, National Autonomous University of Mexico - UNAM
    funders:
      - Grant XXXXXXXX

El potencial de Manubot se encuentra en el control de versiones. Al guardar los cambios realizados, GitHub le enviará al administrador una propuesta de cambios (commit). Es importante que los co-autores envíen la modificación mediante una nueva rama (branch) para generar una versión alterna del documento completo que incluya los cambios propuestos.

Al agregar un cambio del texto (o codigo) mediante una nueva rama ( jesuscapistran-patch-1) se le solicita al administrador de proyecto revisar y en su caso aceptar el cambio. Una vez aprobado, Manubot ejecutará una vez más la compilación del documento. Dando como resultado una actualización que todos podríamos ver online, ver pagina web.

En este punto ya cuentas con un sistema de colaboración, sólo queda editar el contenido. Para lograrlo se tienen que modificar los archivos 01.abstract y 02.delete-me.md. Puedes agregar secciones independiente creando un nuevo archivo, ejemplo 03.introduccion.md, 04.metodologia.md. Recuerda que la redacción se debe realizar mediante el lenguaje Markdown. Yo recomiendo primero editar online mediante la extensión web para Chrome que ofrece https://hackmd.io/. Si buscas algun editor de Markdown, aquí los puedes encontrar (https://www.markdownguide.org/tools/). Espero hayas tenido éxito, no olvides dejar tus comentarios, observaciones y recomendaciones. Hasta pronto.

¿Haz logrado implementar tu sistema Manubot?

Referencias

[zotpressInTextBib]