I'm at work, and I can't think. Too little sleep leads to too much coffee, and self-induced ADD is the result.
The past few weeks have been strange. I had run out of my sanity-inducing drugs, which seemed okay. It seemed like time, but, soon enough, my geek-related-pseudo-OCD, or GREP OCD for short, has returned.
Needing an outlet for my Grep OCD energy, I turned to a problem that didn't need solving, fixing the bit-rotted NCurses bindings for Guile. (The future of the past, today!) And I decided that, for once, I was going to finish a project to a standard that would make it useful for others, instead of just myself. By "useful", I mean completely unimportant, but, ultimately compilable.
To do something GNU, there is a tremendous amount of domain knowledge required. Some of the tools were old hat to me: make, tar, guile, C. But, just to put together my package, I've had to read up on m4, autoconf, automake, libtool, texinfo, and the GNU coding standards. Thousands of pages of documentation overall. Plus, I've had to go from a facile knowledge of curses to something more in depth.
Also, to make it a program that is out there for the people to see, I've got it up on Sourceforge, which required getting my CVS tools together, as well as finally generating an SSH key for myself.
Programming to the GNU coding standards has interesting problems, beyond the ugly indentation style. I've taken it as a challenge to actually follow them completely. As such, there are two minor points that create major work.
Please put a comment on each function saying what the function does, what sorts of arguments it gets, and what the possible values of arguments mean and are used for.
...
Also explain the significance of the return value, if there is one. [GCS 5.2]
Since this is an API binding, should I take this at face value? Curses has over 200 functions and 100 constants, and in wrapping them, they will each appear more than once: in the C-wrapper and in the Guile frontend. I didn't to the wrapping by hand. I tried to use g-wrap, but, it wouldn't compile on my Cygwin box. To the extent possible, I used an awk script to do the wrap coding, but I might move that to m4, because it is less line dependent.
Another headache from the standards is this: it is explicitly forbidden to generate documentation by accumulating docstrings.
Some programming systems, such as Emacs, provide a documentation string for each function, command or variable. You may be tempted to write a reference manual by compiling the documentation strings and writing a little additional text to go around them—but you must not do it. That approach is a fundamental mistake. The text of well-written documentation strings will be entirely wrong for a manual.
I totally agree. The main reason I've never managed to work my way through GTK, GNOME, g-wrap, or Guile-Gnome, aside from lack of energy, is the lack of tutorial documentation as well as the self-referential Docstring/Doxygen style of what remains.
And yet, now faced with putting a manual together, I can totally see the appeal of manual-by-docstring-concatenation. It would be quick.
I did eschew Doxygen for that very reason: it would make it all too easy.
I find GNU's stubborn insistence on Texinfo to be crazy, given the amount of better options out there, be it simpler (HTML) or more complete (DocBook). Even so, I will do it so I can be at least make my tiny contribution to the GNU cause.
I hope to learn enough in the process to put out an updated GuileBook for the 1.8.X series. It is my internet claim-to-fame, I guess.
It basically works now in a private build, but, to wrap it up legit, I need have answered a few fundamental questions.
How can libtool be used to reliably generate a Cygwin DLL?
For now, I'm going to move all this stuff to a Slackware GNU/Linux box. If I can get it working on the reference platform first, I can fix the porting problems later: Cygwin, OpenBSD, GNU Hurd.
Grep OCD is the reason for my success as a techie and my failure as a human being.
