Building RPMs

So is it just me or did no one ever bother to write actual documentation for building RPMs, and in particular, for the spec file?

I got a really nice contributed spec file for kstart (based on the spec file for Nagios plugins apparently). It used lots of macros and RPM variables and I thought "gee, that's rather neat, nice to provide automation like that." It still didn't hold a candle to the Debian packaging tools, but hey.

So today, I go to integrate a co-worker's spec file for remctl into the new package I'm working on, and I noticed that it didn't use most of those nice macros. Huh. So off I went to learn more about what all those macros and variables meant and did.

Er, well, not so much. It's possible that my Google-fu has simply failed me, but as near as I can tell, there is no actual manual for RPM building anywhere. There's a HOWTO (at several locations), which mentions about 10% of these macros and variables. There's a book, Maximum RPM, which is available on-line (nice) and essentially worthless (not so nice). I suppose it's okay if you've never done this before, but again it doesn't document any of the stuff that people actually use and didn't answer any of my questions. All the links to it point out that it's horribly out of date, which inspires a great deal of confidence. Oh, and there's www.rpm.org, which is, I dunno, adequate I guess if RPM were some average free software project maintained by people who know nothing about effectively organizing web sites, but which doesn't help you find anything. At least if, like me, you're looking for detailed information about the spec format.

Or, to sum this all up, what the fuck? Millions of people actually use this shit? By preference?

I've got to be missing some awesome killer documentation resource or something, since this would otherwise just be silly. I knew that Debian Policy was a killer advantage for Debian, but I thought that was just in all the areas that it specified the use of metadata and the rules it creates for packages to follow that Debian packages actually follow. I didn't think that the sheer existence of documentation about basic tools was also a major advantage. Yeesh.

So, I have a remctl spec generated via 100% pure unadulterated cargo-cult poking with a stick. It builds on a RHEL 4 system. If I had some documentation of spec file formats, I'd have some idea if it built on any of the other myriad of RPM-based systems that I don't personally have access to. As is, not a clue. Maybe I used some Red-Hat-specific feature somewhere. Who could tell?

PS: Dear RPM developers, your man pages suck. Please (a) learn how to write nroff or (b) teach your tools how to write nroff that doesn't look like crap. Little known fact: man pages do not actually have to be full of extraneous and pointless blank lines, nor do they have to be full of badly wrapped command examples. While you're at it, you may want to actually add useful content, like, say, anything whatsoever of use about your programs besides their command-line options.

Oh, and don't get me started on how rpmbuild requires that you run it as root and let it spew all over system directories and the documented and preferred way around that is to download a bunch of random local configuration files from someone's personal web site that you can copy into your home directory. 'cause, you know, what kind of weird person would not want to build RPM packages as root?

The mind, it boggles.