----------------------------------------
Documenting crossbow
July 09th, 2021
----------------------------------------
As I already mentioned in some previous post, I'm
currently on a vacation that turned out to be somewhat
tedious. There's generally not much to do, besides
baby sitting or occasionally hitting the grocery store.
In this situation I'm not really in a vacation mood.
As I would do in my regular life I often seek the
pleasure of a silent and fresh room, where I can be
alone at my terminal. It is in these precious scraps
of time that I've managed to refactor my personal
project, Crossbow.
In case you're wondering, Crossbow is a RSS/ATOM feed
aggregator that follows a minimalist approach, while
adhering to the UNIX philosophy of doing one thing and
doing it well. The project is currently hosted on
GitLab[1], although the idea is to host it somewhere
else (perhaps SourceHut?) eventually. Maybe I'll do a
post on why, in future.
I planned this refactoring since a long time, and now
it is almost done. I'm currently alternating between
writing man-pages[2] and writing testing scripts that
automatically check if the documented features work
correctly.
It is now time to write the manual for the new
configuration file format, and I just realised that I'm
somewhat screwed.
I decided to rely on a configuration library, which
totally sounds like a sensible choice. I chose
libconfuse[3] after verifying it is available to all my
target platform.
The library is easy to use, the configuration file
format is fairly obvious to grasp, even in the pesky
parts such as special characters escaping. Too bad
that the documentation is lacking a proper description
of the grammar!
Of course I'm not particularly scared of figuring out
things, but I'm rather reluctant in pointing people to
a documentation that doesn't exist.
On the other side, the documentation of the
configuration syntax is definitely beyond the scope of
the application's manual!
The right thing to do would be to contribute to the
libconfuse project, and provide them with a proper
syntax documentation. This of course entails a much
higher effort.
I hear a baby crying.
---
[1]
https://gitlab.com/dacav/crossbow
[2] I strongly believe that documentation should be
accessible offline, and I love well written UNIX
manpages. In case you're wondering, I'm using mdoc(7).
[3] github.com/libconfuse/libconfuse
