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.elobtiene el tema configurado o utiliza el definido por defecto,mdo.op-export.elcomprueba los cambios en el repositorio y genera loshtmlque formarán el sitio.op-git.elgestiona todo el repositoriogit.op-template.elgenera cadahtmlen base a las plantillas definidas que luego utilizaráop-export.elpara generar el sitio.op-util.elagrupa funciones útiles para el resto de módulos, como el formateo de fechas o emails.op-vars.elcontiene las definiciones de las constantes y variables de todo el sistemaorg-page.elaquí 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.eldefine 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-publicationrealiza la publicación de los cambios en el repositoriogitpara actualizar el sitio.op/new-repositoryinicia un repositorio y nuevo blog.op/insert-options-templateestablece 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 ficheroorgque no se ha iniciado como tal.op/new-postcrea una nueva entrada para el blog.op/do-publication-and-preview-siteademás de generar el sitio con los cambios realizados levanta el servidorhttppara pruebas que viene con emacs.
Funciones no interactivas:
op/verify-configurationcomprueba la configuración mínima y lanza los errores que encuentre.op/generate-readmegenera un ficheroreadmepara el blog nuevo.op/generate-indexgenera un ficheroindexpara el blog nuevo.op/generate-aboutgenera un ficheroaboutpara 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.
Comentarios