Miroirs/jorge
1
0
Fork 0
mirror of https://github.com/facundoolano/jorge.git synced 2024-12-25 21:58:28 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions

cleanup change of plans post

Browse source
This commit is contained in:
facundoolano 2024-03-04 12:58:09 -03:00
parent 17c75c0228
commit edf8eda4dc
1 changed files with 20 additions and 20 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

40
docs/src/blog/a-change-of-plans.org
View file

@ -5,46 +5,46 @@ layout: post
lang: en
tags: [project, emacs]
draft: true
excerpt: The project concept, as I originally planned it, had a few problems, but they went away when I found out I could parse org-mode files in Go.
---
#+OPTIONS: toc:nil num:nil
#+LANGUAGE: en
Before I started to code, when I was scribbling [[project-outline][usage examples]] in my notebook,
I summarized my idea of the project with a couple of slogans:
Before I started coding, while still scribbling [[project-outline][usage examples]] in my notebook,
I summarized the idea I had for the project in a couple of slogans:
#+begin_quote
~golb~ is a small, opinionated static site generator written in Go and inspired by Jekyll.
The ~golb~ blog is a blog about learning go by implementing a blog generator.
- ~golb~ is a small, opinionated static site generator written in Go and inspired by Jekyll.
- The ~golb~ blog is a blog about learning Go by implementing a blog generator.
#+end_quote
There were some problems with this concept:
This concept had a few problems:
1. The ~golb~ name stank.
2. Apart from stinking, the name choice revealed that the project lacked personality: its remarkable features were that it would be written in Go (an implementation detail) and that it would offer some blogging facilities (as was the case for every other static site generator).
3. It was actually two projects in one: a site generator and a development blog. Previous experience has showed me that trying to keep a devlog while I work on a project distracts me from the actual work on that project.
2. Apart from stinking, it was evidence that the project lacked personality: its remarkable features were that it would be written in Go (an implementation detail) and that it would offer some blogging facilities (as was the case with every other static site generator).
3. It was actually two projects in one: a site generator and a development blog. I knew from past experience that trying to keep a devlog while working on a project distracted me from the actual work on that project.
/Wait/, you may ask, /isn't this the devlog of the project?/ It is, but I cheated: I'm writing this retrospectively, based on a few notes I took during development, offloading ideas I've been carrying in my head for days, after finishing most of the work I had planned for.
/Wait/, you may ask, /isn't this the devlog of the project?/ It is, but I cheated: I'm writing this retrospectively, after finishing most of the work I had planned for, based on a few notes I took during development and dumping thoughts I carried in my head for days.
I love writing as much as software building and, because of that, I'm always inclined to write about what I build; but writing is as absorbing and demanding as programming to me: if I attempt both in parallel, the writing suffers and the programming suffers.
I enjoy writing as much as building software so I'm always inclined to write about what I build; but writing is as absorbing and demanding as programming is to me: if I attempt both in parallel, the writing suffers and the programming suffers.
Not only does it take time and mental real estate away from the programming; writing as I build feels off for the same reasons why I don't like to introduce abstractions or factor the code early on, or why test-driven development isn't appealing to me: it forces me to focus on, and get attached to specific solutions before being confident that they work ---before fully understanding the problem I'm trying to solve.
Not only does it take time and mental real estate away; writing as I build feels off for the same reasons that I don't like to introduce abstractions or factor the code early on, or why test-driven development isn't appealing to me: it forces me to focus on and get attached to specific solutions before being confident that they work ---before fully understanding the problem I'm trying to solve.
-----
Those problems went away when I discovered that parsing org-mode files was feasible in Go. I had thrown in /org-mode support/ as an optional, nice to have feature in my preliminary plan, not knowing what kind of work it entailed. But some googling revealed that Hugo supports the org-mode syntax, relying on an [[https://github.com/niklasfasching/go-org][external library]] that I could use myself.
But those problems that made me hesitant to start coding went away when I discovered that parsing org-mode files was feasible in Go. I had thrown in /org-mode support/ as an optional, nice-to-have feature in my preliminary plan, not knowing what kind of work it entailed. But some googling revealed that Hugo already supports the org-mode syntax, relying on an [[https://github.com/niklasfasching/go-org][external library]] that I could use too. First-class support of org-mode posts made a lot of sense for my project:
- It would make the static site generator feel less "generic", as confirmed by the name changes it prompted, first to ~blorg~ ---which I dropped because it was already taken--- then to ~jorge~ ---which I liked because it had /org/ in it, sounded like it could be Hugo's distant cousin, and paid homage to two of my [[https://en.wikipedia.org/wiki/Jorge_Luis_Borges][favorite]] [[https://en.wikipedia.org/wiki/Jorge_Garcia][artists]].
- It would make the project useful to me, beyond its learning purposes, since I blog by writing org-mode files in Emacs. (In fact, the few rough edges of my current blogging workflow come precisely from forcing org-mode exports into Jekyll[fn:1]). I could make it a project goal to support my workflow out of the box.
- I could use my [[https://olano.dev/][current website]] as a reference and as test input, planning to "dogfood" by ultimately migrating it to ~jorge~. This would, in turn, remove the pressure to write a devlog to test the site generator.
First-class support of org-mode posts made a lot of sense for my project:
- It would make the static site generator feel less "generic". This was confirmed by the name changes it prompted, first to ~blorg~ ---which I dropped because it was already taken--- then to ~jorge~ ---which I liked because it had /org/ in it, sounded like it could be Hugo's distant cousin, and paid homage to two of my [[https://en.wikipedia.org/wiki/Jorge_Luis_Borges][favorite]] [[https://en.wikipedia.org/wiki/Jorge_Garcia][artists]].
- It would make the project useful to me, beyond its learning purposes, since I blog by writing org-mode files in Emacs. In fact, the few rough edges of my current blogging workflow came precisely from forcing org-mode exports into Jekyll[fn:1]. I could make ~jorge~ support my workflow out of the box.
- I could use my current website as a reference and as test input, planning to "dogfood" by ultimately migrating it to ~jorge~. This would, in turn, remove the pressure to write a devlog as an excuse to test the site generator.
If I succeeded in making a tool that I wanted to use myself, maybe other people would find it useful too. There were [[https://orgmode.org/worg/org-blog-wiki.html][plenty of methods]] to blog with org-mode already, and I imagined most Emacs hackers would prefer writing some elisp than using an external program, but there could be some value in a tool that allowed to:
If I succeeded in making a tool I wanted to use myself, maybe other people could find it useful too. There are [[https://orgmode.org/worg/org-blog-wiki.html][plenty of methods]] to blog with org-mode already, and I imagine most hackers would prefer to write some emacs-lisp to installing an external program, but there may be some value in a tool that:
1. Start an org-mode-centric blog with a single command.
2. Add org-mode to a pre-existing Jekyll blog with low configuration effort.
1. Allows you to start an org-mode-centric blog with a single command.
2. Allows you to add org-mode to a pre-existing Jekyll blog with low configuration effort.
With this new goal in mind, I jumped into the work.
*** Notes
[fn:1] Namely: I had to define an org project in my configuration to instruct Emacs how to export my org files; since the default org to HTML export produces an awkward HTML structure (on that, for instance, is not properly parsed by browser readers), I had to export org to markdown and let Jekyll convert the markdown to HTML; I had to manually publish my org files before for ~jekyll serve~ to pick up the changes; renaming, changing dates and moving out of draft required updating both the .org and the .md file names.
[fn:1] Namely: I had to define an org-publish project in my configuration to instruct Emacs how to export my org files; since the default org export produces documents of unconventional HTML structure (that, for example, are not properly parsed by browser readers), I had to export org to markdown and let Jekyll convert the markdown to HTML; I had to publish my org files separately for ~jekyll serve~ to pick up the changes; frequent operations like changing post titles and dates, and moving them out of draft required me to update two different filenames.