Re: RFC: Self-Hosted PHP Documentation

I have one thing to say on this subject, and that is portability, not between platforms, but between devices. Specifically PDAs and such. The CHM format works on all the new winCE machines (ipaqs for example), I believe. For that reason alone I don't think you should obsolete the CHM manual... perhaps make a function reference only CHM, so theres less to generate? As for placing it in PEAR, there is already a CLI version of the manual being written as a PEAR package, and so I think there is definately a place for this... I like the idea, I just think that you shouldn't concentrate on obsoleteing the CHM so much as offering a viable alternative for other platforms and for people who don't want the CHM. Or... perhaps you could obsolete the CHM that is generated for php.net and simply link to the extended CHM created by a third party (sorry, I can't remember who you are!) Also, you might think about using XML as the docs format because transformation from XML -> (X)HTML is possible using client-side XSLT in Mozilla (though theres a JS bug before 1.2.x) and IE6 (and for the most part IE5.5, that support the working draft at its time of publication, little changed from that to the final recomendation). could CVS be used to keep the manual itself up-to-date? Rather than releasing a PEAR package for every major (or minor?) change to the docs themselves... rather just release packages for changes in the scripts, and not the docs. These are just IMO, make of them what you will... - Davey On a side note, this might make the adoption of PEAR go up too, which is a good thing! Gabor Hojtsy wrote:

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