Joel de Guzman wrote:
I fear that over reliance on PHP will either 1) make the offline docs virtually useless or 2) fork a different online and offline version of the docs, hence double the effort and scatter the focus.
I'd think it would be appropriate to use PHP to add functionality to the online docs as long as it follows the same principle as javascript: it doesn't make information inaccessable when it doesn't work (in this case, when browsing offline). Of course, it would be great to have sorting capability offline too, but I don't see why that must be a prerequisite for implementing it in the online docs.
That would be ideal, but in reality is difficult to achieve. I'd hate to see pages that are disabled because it requires a server. While it's fun to have all the bells and whistles, a keep-it-simple design can also potentially give you much of the needed functionality with less fat and less fuss. The thing to keep in mind is that in our case (boost docs) information is mostly static.
It shouldn't really be that difficult to avoid the pitfalls. When the website is updated for a new release, just run wget (http://www.gnu.org/software/wget/) on it. It will hit each page (or the pages you select) and save the results to an identical directory structure. That way the dynamic, online pages produce the static, offline ones, so there's no risk of forking and no double work.