Re: Livedocs, the future

Gabor Hojtsy wrote:

We have talked about some things on the linuxtag docmeeting about developing plugins for it. This is only possible however if livedocs allows plugins :) Separation of different parts is essential to enable livedocs to handle plugins.

While we are talking about this. I have thinked about using something like squirrelmail does. (It could be cool BTW to have something like their dynamic configuration interface too.)

There is no need for a dynamic interface since the build and presentation options will be project specific (or decided at build-time). So it would be quite pointless to build a visual configuration interface yet. Maybe for the now-too-futuristic self-hosted manual :))

right ;)

As for the I'm okay with Derick, we shouldn't slow down the system. What do you suggest as monitoring method ? We should benchmark the different process (build, sql calls, xml rendering,..).

ApacheBench is a good tool to measure the overall speed of the display of one page... Otherwise very simple microtime() based time measurements are also fine without requireing sophisticated tools like xdebug...

We need to choose a box to do this. Derick, do you have this ?

While we split up the logic it needs to be kept in mind that we try to solve a lot of issues with livedocs: - translators quickview of modified files -> no special requirement

Are you talking about the paragraph "2. Visual editing" of /phpdoc/RFC/2003_meeting_findings.txt ? If so, I've been thinking about this when playing with livedocs for the first time.

I am not really talking about this in connection with the visual editing part. Livedocs was developed initially to fulfill this need. A translator needed to wait a lot of time to get a new generated version of the XML... A lot of people are unable to imagine how that XML will look like in HTML...

erm, so you want something like a WYSIWYG tool ? It could be cool if we find a way to ./build.sh only_this_file

My purpose was to 'open' a CVS checkout to anyone who wanted to correct a typo on the manual. This can be done with some wiki system, or a home made solution including features like a javascript make test, a spell checker, etc. It can ask the user for a nick (or a MAGIC_COOKIE on php.net) and a comment, and build the commit message with this information.

Since Nuno already started a project to do a similar thing, IMHO we should join forces and see what it can do. But a working livedocs alone helps translators much, and first we need to solve the issue of the manuals not updateing often enough on the website AFAIS.

- php website manual presentation: -> integrate with the websites functionality (shortcut handling,

     error handling, language fallback)
     

Should be commited to the virtual "src/" directory ;)

If livedocs (or the phpweb plugin) calls the functions defined in phpweb than it is fine. Or if those functions are not defined, then define some defaults.

I was thinking about making this functionalities the default

-> cache pages so often visited pages will be pushed from the

     static cache
     

I don't really get it here. Isn't this feature available already ?

It should be configurable on php.net mirror sites, where that cache is stored. Some cache flushing need to be done when files are updated, etc. These are not yet present in livedocs as far as I know.

-> livedocs need to work without the build part with a prebuilt

     manual, with all the langauges behind
     

We can find a way to only need to update the $lang.sqlite files I think.

The idea is to build the livedocs files on the rsync server and let down the files with rsync to the mirror sites. As I have described in a previous letter, how could all the languages be built by the same time is an interesting question, since builds share the same files (file-entities.ent, and stuff).

If the build is done on the rsync server, then the rsync server will have two CVS checkouts (livedocs and phpdoc-all). The administrator will cvs up both of them and then configure with the phpweb line and finally run the build. The CVS checkouts will not be rsynced directly, will simply rsync the $OUTPUT_DIR content to the mirrors.

As I said, it was a first draft. After reading all your injections, I'm asking myself if we need to have a system to switch between : 1 - differents input formats (do we really need it ?) 2 - different outputs (livedocs could be able to generate more then just some HTML)

Yes, we need 'different' input formats, since the PEAR or PHP-GTK manuals need to use more or different tags then what we use. XML is the absolute base, but what XML tags are used might be quite different across projects... Derived from this fact, different outputs are also needed. PHP-GTK docs need to document and generate output for signals, which might need indexing (build process - input) and custom display (output).

I'm also okay with the fact that a fixed built-in XML => HTML mapping is just cool (instead of allowing the creation of the $map array in a theme), but maybe we can change it so that avery different dockbook tag is transformed to a specific HTML element with a specific CSS class name. (for example <foo></foo> => <div class="foo"></div>). This will allow a better CSS personnalization and control of the rendered HTML.

Livedocs already does something quite similar to this :)

oops :))

livedocs/themes/foo/ will then only contain two files : 1 - livedocs.css 2 - headers and footers definitions So, do we mkdir plugins and go on developping this way ?

I am not sure yet :) I would better move the 'theme' parts out of livedocs first. I have for example, that HTML headers and footers are emitted at multiple places in the source files, and this makes harder to see what is happening...

As we need to fix the issue with the php.net manual first, I'm preparing a patch that will do the following : - adds a --with-theme=THEME_NAME to configure. This value will default to the "phpweb" theme. - substitute @THEMENAME@ in config.php.in to define a PHP constant called THEME_NAME For the moment, I will only introduce this constant to define $css_url this way : -$css_url = WEBBASE . CSSURL; +$css_url = WEBBASE . 'themes/' . THEME_NAME . '/' . CSSURL; and to include the headers and footers definitions (I'll group them in a file and move it to skins/phpweb/) Are you ok with this ? didou