**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:

<code>
SUBDIR += perl5.8
SUBDIR += perl5.10
SUBDIR += perl5.12
SUBDIR += perl5.14
</code>

(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