RFC: Self-Hosted PHP Documentation

Hi! [I hope this will be a nice reading for those getting back from the Intl. conference :)] Problems, preliminary experinece: - The new my php.net feature showed, that users would like to see more personalisation, while this would probably be very hard to code without one central session server. Things like favorites, or mostly used functions, etc. - The current search features on the php.net site are far from satisfactory, it is not easy to focus the search on something the user is really interested in. - The CHMs are quite good in searching, but they are very limited to what Microsoft provides for customization, and many ugly JS hacks were needed to allow searching in the notes separately for example. Also proper update of the documentation can only be done by hand. Otheriwse the CHM format contains many good stuff we can build on in future formats. - We continually receive requests to provide the 'phpweb' format for download with a stipped down version of the site's manual handling code. - We discussed at the 2002 doc meeting that some CHM-like format would be nice for non-Windows systems too. Considering all the above, it would be nice to see a format, with which the CHM features are available [Tree TOC, Full Text Search, Index, Favorites], and which provides extreme customizability options. What I have come up with so far in my mind considering the above problems is the 'Self-Hosted PHP Documentation' or 'PHP Documentation Central'. I hope at the end it will also prove to deserve the latter name ;) The idea is based on the assumption, that most of those demanding advanced help have a web server and a PHP installed at least with default options. Those who have not own such a server can use the online documentation anyway. So the requirements to set up a self-hosting documentation for a user are: web server, php. This would work without an internet connection, but it would provide much more feature with connection. The basic goal for the first version is to replicate what CHM already has (mentioned above) with content files probably in HTML or XML, and the TOC in XML. Full text search shuold be done without a DB backend, so file based native PHP search engines should be taken into account. There are some out there with quite great speed, see some script sites [I am not going to name names yet]. The index can be done using the Full Text Search database or using page titles as we do it now. Implemented in a frameset, this would provide what is already provided by the CHM version, but with platform and browser independence. BUT we can go much furthen than this. Some ideas: - Automatic install and update. This would be easy to install using some PEAR install tools, if we require PEAR to be on the user's own server. Automatic updates can also be done using PEARs update tool [probably, I have not checked...]. - Subset selection. Users would be able to select a subset of the manual, which they use. Searches will be performed in this subset (or results outside this subsite will appear below those from the selected nodes). Automatic update would only need to update the nodes the user actually reads in his everyday work, when new documentation is ready. - Multiple book support. This system woul be able to support multiple books. Imagine to have PHP, PEAR and PHP-GTK docs all at one place. PHP-GTK developers would find this extremely useful. Searches would be made in all books, if asked for. This is the point where my idea become 'PHP Documentation Central ;)'. This also opens up the possibilty of third party projects providing books for this system, eg. Smarty, ADODB, etc. - PHP version dependant behaviour. The manual would be able to warn users with a given PHP version number that some functions are not available in that version. It would be nice to search in only those function pages that are available in the version the user has. - PDF generation. In case we provide the documentation pages in some XML format (presented in HTML on the fly), then we can also provide the ability for users to create PDF files on the fly (in case of some PDF functions are installed or using a bundled native PHP PDF generator lib). This would at it's extreme provide the ability to the user to arrange a whole big PDF for himself/herself with those pages he is interested in (eg. with only the ODBC docs, if [s]he is not going to use anything else). - Tight website integration. We can also warn users that an updated version of PHP is available, as we know the used version. Or we can deliver news to his browser as part of this app. - Skinning. I am perfectly sure that the CHM layout will be annoying for many developers, as it gives too much space for the navigation, and not enough for the content. So this system needs to be designed to be skinnable via some templates. - Intranet user handling. Let's imagine some company develops using PHP. It is obvious that there should be no need for every guy to install this doc system. The system should be at one place on an intranet server. However preferred skins of users, favorite pages, etc. will probably differ, so it would be nice to throw in some authentication and session handling for this case. Who would use such a documentation? - I think this would simply obsolote CHMs, and we would generate this format, instead of the CHMs because it's advantages. - Those who now have local mirror sites for browsing the docs, and getting updates ASAP. If we can convince these users that this solution is better, then they won't rsync our server, as there will be no point in it. This means less load on rsync.php.net and more load on mirrors, as every mirror will be a possible 'autoupdate server' for this format - with the obvious exception of www.php.net itself. - Those tired with the online search feature of our site. They will definitely swicth to this format ASAP. I have done some research on the needed components and whether there are already written libs for this. There are some questions in my mind about this stuff: - Should this be fully implemented in PEAR, so it would be available for installation from there, and it would be able to update itself and/or the docs through PEAR update mechanism. Is PEAR capable of such thing? - Is it ok to use third party tools here (for file based full text search indexing or templating for example). It is obvious that all the above stuff cannot be done at once. I think simulating the CHM interface and features would be the first goal, writing the app as extensible as possible, not with the CHM system in mind when building the internal structure of course. Then adding the above convinience features step by step would be nice. If 'PHP Documentation Central' becomes reality, we would have an open version of something like Microsoft's MSDN, but with much more extensibilty and customizability features. The question is if you think that guys would be interested in this, and that can anyone from here volunteer to start the project. I won't have much time for this until after my exam time. But I thought it would be nice to start a discussion now, so the picture will be cleaner then. Waiting for comments, Goba