Re: Documentation Update

Hey Goba, I've been tinkering with something that I call "livedocs"; instead of generating everything in one pass, it indexes the phpdoc sources and stores information about the entities and node ids (eg: refsect1="function.fopen"), and in which files they can be found. This process takes about 2 minutes (storing information into an sqlite database ;-) Once done, you can call up the docs for a given node id and it will transform the XML to clean HTML on the fly (using ext/xml and a couple of queries to the sqlite database) - it transforms only the file that you requested, so the process is quite fast. The main goals I had in mind were: 1.) I didn't want to wait 45 minutes for the build when I wanted to preview doc changes. 2.) I wanted to maintain a local, up-to-date copy of the docs, without having to run the build. 3.) I wanted fast access to the docs for a particular function (something like the unix man command), and wasn't particularly interested in the other functions in the same section. This makes it very easy for people maintaining the docs to focus on the content rather than what they want to spend the next 45 minutes or more doing while waiting to see if their changes look right :). It currently makes no attempt at section/example/figure numbering, nor at generating a TOC. You can see an example of a generated page at http://www.php.net/~wez/fopen.html When I get a little more time, I'll clean it up so that it can handle multiple languages and so on. It might be feasible to deploy this for the online documentation if we use some kind of content caching (or the 404 trick, as Rasmus calls it :). It might also be the case that generating the docs in advance with this code might be significantly faster than the regular dsssl or xsltproc builds, as the transformation is quite simple; need to do some benchmarks. --Wez. On Fri, 30 May 2003, Gabor Hojtsy wrote: > >>>What's the status on getting the docs regularly generated again? > >> > >>IMHO as the current build makes the building server be on 100% processor > >>load for days, it is not a happy thing to do automatically. ;(( > > > > It's 5 hours for a single language on my box, and that's "make > > html". > > One language, one make target. We have quite some languages, and quite > some make targets. I had some suggestions on improving this, by having > an intermediate format [without TOC]. So there would be no need to > rebuild parts in the translated versions which are English. That would > only work with some PHP postprocessing work and with the XSL sheets. But > that would definitely reduce the time for building. It would also use > the same source files for phpweb/html and probably CHM output. So it > would cut on the multiple outputs and multiple languages times'. But > that is just a dream solution now. > > James also suggested to prioritize the languages for a short term "kind > of solution". That would mean proper building for the EN manual at least > weekly I guess. > > Goba > > >