mkreadmes is a tool I wrote in C to speed up building the README.html files for the FreeBSD Ports Collection. The latest version (1.3) is now available in ports as ports-mgmt/mkreadmes.
The program builds the README.html files orders of magnitude times faster than the standard "make readmes", typically clocking in at 30 seconds or less for a rebuild of the files for the entire ports tree. A number of command line options are provided to make this as flexible and useful a tool as possible.
Note to ports committers:
Part of mkreadmes' search optimization strategy is based on the assumption that the SUBDIR entries in a category's Makefile will always be properly sorted. When building for a category, each successful port search within that category will advance next_index to point to the next line in the index file, from which the next search within that category will begin. One unexpected happy side benefit of this approach is that mkreadmes effectively turns out to be a handy tool for detecting missorted Makefile entries!
Example (this really happened just recently; I did a send-pr afterwards re: the missorted item):
Let's say that lang/Makefile contains the following series of entries:
SUBDIR += perl5.8
SUBDIR += perl5.10
SUBDIR += perl5.12
SUBDIR += perl5.14(the perl5.8 item is missorted, and should come after the other three entries)
The first search, for perl5.8, will succeed, incrementing next_index to point to the next index entry after perl5.8's, which, unfortunately, will not be the entry for perl5.10, but for the port that should have been after perl5.8 in the Makefile (which at the time of this writing is lang/petite-chez). So then, none of the other perl5* ports will be found in the index, as their entries actually precede perl5.8's and have already been passed over by the next_index pointer.
A case could be made for not relying on the sorting of a category's Makefile, but the performance benefit from using this method is substantial, and no real harm results if the assumption turns out to be wrong. Besides which, the Makefiles should be properly sorted, so ports committers may wish to consider using mkreadmes (after running "make index" first, of course) to verify the sorting of a category's Makefile after adding new items.
Please feel free to ask questions, make comments/suggestions.
--
Conrad J. Sabatier
conrads@cox.net