Documenting Crossbow

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.
[[EDIT from the future: it is nowadays on dacav.org, where you're reading
this entry]]

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