Re: RFC: Self-Hosted PHP Documentation

Hi Gabor et al, --- Gabor Hojtsy <gabor@hojtsy.hu> 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. I agree with these first two points :) Although noted below as a db-free site, why would this be the case? I realize that with mirrors, things can get complicated, but I think an architecture with some sort of DB usage, at least at it's core, is vital. You just won't get the speed and flexibility otherwise, IMHO. I have the resources to provide some production sites for such an endeavour, or for testing/development. Also as I've mentioned, I'd be happy to do some of the backend/logic coding; just throw some function/class specs my way and I'll code it out, SQL or otherwise. Happy to help, H > - 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 >