Differences

This shows you the differences between two versions of the page.

--- mkreadmes [2012/03/12 23:39] – ConradSabatier
+++ mkreadmes [2012/05/04 21:07] (current) – ConradSabatier
@@ Line 1: / Line 1: @@
-**mkreadmes** is a tool I wrote in C to speed up building the README.html files for the **%%FreeBSD%% Ports Collection**.  The latest, "finalized" version (1.2) is now available in ports as **ports-mgmt/mkreadmes**.
+**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.
+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
+Conrad J. Sabatier\\
 conrads@cox.net