RE: [PHP-DEV] FAQ URL updates for next php3 release

On Mon, 7 Jun 1999, Colin Viebrock wrote: > Rasmus and I spoke (a long time ago it seems) about moving > the PHP documentation at least into it's own CVS tree, and at the > most into some web-based database updateable template thingy. > > Obviously we spoke of it in very technical terms. > > I think his thinking was that since the SGML format of the manual > is almost identical page to page (i.e. every function page follows > the same template), why not build a web-interface that that > lets us edit/add/update manual entries through the web, then > parses it into the appropriate SGML and stores it in a CVS tree > or database. > > Someone needs to build this, of course. It may well be me, but > certainly not before the end of August (big holiday coming up). > > Thoughts? It's a very cool idea. The way I see it we can attack this in two ways: 1. Convert the docs to XML and stuff it into a database. The database should in its simplest form deal with elements and attributes, and relate them so we can extract a full XML document. 2. Structure everything in files like now and provide lots of templates for editing each type of file: reference chapters like the ones in functions/, more general chapters like the ones in chapters/ and so on. This would work for both SGML and XML source. Either way we will have to implement some sort of automatic validation, to make sure that the extracted documents are always valid. I think we should go with [1]. Here's a simple version of the database structure I had in mind (it needs some more work to help order elements with the same parent etc.): CREATE TABLE xml_elements ( id INTEGER NOT NULL, name VARCHAR(250), ns VARCHAR(250), parent INTEGER, -- REFERENCES xml_elements(id) cdata_before LONG VARCHAR(16777216), cdata_after LONG VARCHAR(16777217), PRIMARY KEY(id) ); CREATE TABLE xml_attributes ( id INTEGER NOT NULL, element INTEGER REFERENCES xml_elements(id), name VARCHAR(250), ns VARCHAR(250), contents LONG VARCHAR(16777216), PRIMARY KEY(id) ); Right now we have ~23000 elements and ~300000 attributes (defined and implied) in the source, so the amounts of data are well within MySQL's capabilities. This opens up a lot of cool possibilities. One I have in mind is the ability to extract and format an arbitrary part of the manual (getting just the installation chapter as a PDF document, for example). We could also add a "production" column in the tables that lets us flag parts of the manual as "under development", so they can be accessed online only by other developers. Or elements could be connected to the user-contributed notes or even the bugs database. - Stig