Estudiando org-page
Sobre org-page
Son varios los que me han preguntado por el hecho de que utilizo
org-page
para escribir este blog y el chismático se ha quedado
sin soporte. Es decir, que el autor no va a hacerle más casito al tema
y no habrá mantenimiento ni corrección de bugs, ni nada. ¿Eso
asusta? A mí no (es la respuesta fácil). Pero no porque sea yo
especialmente valiente o porque crea que soy mejor que otros que
corren a refugiarse en otras alternativas ante el caos y el abandono.
Simplemente el chismático funciona y si funciona ¿para qué
cambiarlo? Ahora bien, ¿esto implica que te recomiendo la herramienta?
Pues dicho así: no, pero un no con matices.
Entiendo que hay quien le teme al barbecho informático percibiéndolo como un retroceso para el uso de una herramienta. No creo yo que sea tan malo, sobre todo en un sistema que está funcionando correctamente. Y no es por no recomendarlo, pero entiendo que es un motivo para pensárselo dos veces antes de lanzarse a iniciar un proyecto con una tecnología que puede que no evolucione.
A ver si soy capaz de explicarme. Cada uno tiene derecho a utilizar el
software libre que considere oportuno, pero hay que advertir que el
camino no siempre es fácil. He visto quienes se desesperaban con
org-page
por sus peculiaridades y no terminaban de entender cómo
funcionaba, quizás influenciados por los modos de otros chismáticos
que generan webs estáticas. He de reconocer que, aunque al final
parece que lo he dominado, me costó al principio entender cómo
gestionar todo. Yo, a estas alturas, me encuentro cómodo utilizándolo
y he encontrado la manera de hacerlo funcionar sin excesivo
esfuerzo. Pero ¿es así en todos los casos? No, por esto no te lo
recomiendo a no ser que estés dispuesto a hacer un esfuerzo que quizá
otros sistemas te ahorran. Además la documentación es más bien escasa
y algunas cosas no quedan demasiado claras en esa documentación.
¿Cómo funciona?
Mi intención al escribir esto es también profundizar un poco más en
cómo funciona. Mi objetivo es comprenderlo suficientemente por si
hiciera falta algo de mantenimiento y me tuviera que buscar las
habichuelas. La última actualización de org-page
fue el 7 de agosto
de 2017, hace más de dos años. Todavía no me he encontrado con la
necesidad de arreglar o cambiar nada, pero nunca se sabe. El
chismático funciona.
Básicamente, el código fuente se apoya también en otros ficheros que
componen las páginas html
: las plantillas y lo formatean con
css
. Para actualizar el blog de forma progresiva, se apoya en
git
. Todas esas opciones hay que configurarlas adecuadamente para
que funcione, pero como ya lo he contado en otros artículos, no voy a
hacerlo de nuevo.
Ficheros
No voy a entrar en las plantillas, que al final es lo que proporciona la uniformidad visual al blog. La idea de este artículo es meterse más en el funcionamiento y por ello me quedaré en el código fuente que mueve gestiona todo. El código está distribuido en los siguientes ficheros:
op-enhance.el
obtiene el tema configurado o utiliza el definido por defecto,mdo
.op-export.el
comprueba los cambios en el repositorio y genera loshtml
que formarán el sitio.op-git.el
gestiona todo el repositoriogit
.op-template.el
genera cadahtml
en base a las plantillas definidas que luego utilizaráop-export.el
para generar el sitio.op-util.el
agrupa funciones útiles para el resto de módulos, como el formateo de fechas o emails.op-vars.el
contiene las definiciones de las constantes y variables de todo el sistemaorg-page.el
aquí está el meollo del código fuente y lo que gestiona todo el proceso mediante los comandos o funciones interactivas que se definen aquí.org-page-pkg.el
define el nombre del paquete, la versión y las dependencias.
Configuración
Dentro del fichero org-page.el
nos encontramos una función
fundamental que comprueba que todo esté configurado correctamente:
(defun op/verify-configuration () "Ensure all required configuration fields are properly configured, include: `op/repository-directory': <required> `op/site-domain': <required> `op/personal-disqus-shortname': <optional> `op/personal-duoshuo-shortname': <optional> `op/export-backend': [optional](default 'html) `op/repository-org-branch': [optional] (but customization recommended) `op/repository-html-branch': [optional] (but customization recommended) `op/site-main-title': [optional] (but customization recommanded) `op/site-sub-title': [optional] (but customization recommanded) `op/personal-github-link': [optional] (but customization recommended) `op/personal-google-analytics-id': [optional] (but customization recommended) `op/theme': [optional] `op/highlight-render': [optional](default 'js)" ...)
Las variables para una correcta configuración las encontramos ahí. Hay otras que se pueden definir, pero básicamente las necesarias son esas:
;;; Para el blog en org-mode (require 'org-page) (setq op/repository-directory "~/proyectos/blog-org-page/") (setq op/site-domain "https://notxor.nueva-actitud.org") (setq op/site-main-title "Notxor tiene un blog") (setq op/site-sub-title "Defenestrando la vida") (setq op/theme-root-directory "/home/notxor/proyectos/themes-org-page") ;; Temas propios (setq op/theme (quote notxor)) ;; Ajustes personales del tema (setq op/tag-rss t) ;; Hacer que se creen los feed por etiquetas. (setq op/hashover-comments t) (setq op/personal-github-link "") (setq op/site-preview-directory "~/public_html") (setq op/confound-email nil) ;; Evitar el ofuscado del email, porque lo hace mal.
Si comparamos los dos listados se puede apreciar que hay algunas
variables que son fundamentales que no están en el listado que luego
configuro en mi sitio. Al contrario, hay otras que el creador
considera fundamentales, como op/personal-google-analytics-id
, que
yo no configuro (y de hecho he eliminado los enlaces al
correspondiente javascript en las plantillas sin que el sistema se
vea perjudicado. Además configuro el sistema de comentarios
hashover
.
Interacción
Pero lo fundamental del código son los comandos que se definen y que son los que el usuario termina utilizando y los que disparan todos los automatismos para generar el sitio final:
Comandos
op/do-publication
realiza la publicación de los cambios en el repositoriogit
para actualizar el sitio.op/new-repository
inicia un repositorio y nuevo blog.op/insert-options-template
establece una cabecera estándar para el artículo que se está escribiendo. Normalmente no es necesario, a no ser que se quiera convertir en post un ficheroorg
que no se ha iniciado como tal.op/new-post
crea una nueva entrada para el blog.op/do-publication-and-preview-site
además de generar el sitio con los cambios realizados levanta el servidorhttp
para pruebas que viene con emacs.
Funciones no interactivas:
op/verify-configuration
comprueba la configuración mínima y lanza los errores que encuentre.op/generate-readme
genera un ficheroreadme
para el blog nuevo.op/generate-index
genera un ficheroindex
para el blog nuevo.op/generate-about
genera un ficheroabout
para el blog nuevo.
Básicamente, el usuario sólo utiliza el comando new-repository
cuando inicia el blog y después, para cada actualización utilizará
op/new-post
y op/do-publication
... y no hay nada más.
Conclusión
Un primer vistazo superficial al código fuente de org-page
te da una
idea de lo sencillo que es su funcionamiento. Mirando detenidamente el
código he podido apreciar cierta tendencia al código choricero con
funciones muy largas y no demasiado bien documentadas, por lo que
espero que me costará trabajo terminar de entender qué hacen algunas
de ellas.
Mi intención es mantenerme yo el código para mi uso personal. De
momento, no tengo intención de iniciar un fork ni nada parecido, no
me han ocurrido errores y tampoco veo que haya características que
necesite de forma perentoria. Mientras el código funcione no creo que
lo toque, pero si lo hago, me plantearía el hecho de publicarlo
continuando con org-page
, poniéndome en contacto con el creador para
actualizar mediante patch y recurriendo al fork sólo en caso de
que no haya más remedio para publicar los cambios.
Espero que los que me han preguntado sobre el futuro de org-page
y
de mi blog como usuario, hayan quedado satisfechos con la
explicación de mi postura.