Re: Livedocs, the future

Hi Sorry for the delay but I was busy :/

Hi!

4 hours in the train, enough to dream...

Hehe :)

I've tried to imagine the best evolution for livedocs, and I've seen one major modification needed : Separation Actually, we have three main parts : - Build - XML parsing - HTML rendering When livedocs was available through CVS, I've checked it out and started to adapt its design for my own website. While doing this, I fixed some bugs (BAD ID:..) and added some features like showing the available languages in the Index, and so on. When I wanted to commit my changes, I've seen that the noise caused by my design stuff was to huge. So I was unable to commit it.

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.) 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,..).

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. 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.

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

      error handling, language fallback)

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

-> integarate with website design

CSS and header() footer() customization in a skin.

-> 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 ?

-> 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.

-> handle user notes display

plugin too

- generated HTML files for offline viewing -> livedocs need to be able to generate the 'multiple HTML files'

      and 'one big HTML file' version of the manual for download

plugin again :)

- offline personalized manual -> this is an old idea, and livedocs need to mature much to fulfill

      the expectation I have written down, but livedocs will fulfill
      those sometime and we ned to keep in mind that livedocs should
      work with a prebuilt envrionment, and need to support settings
      based personalization

-> again, this is along term goal, so included here just for the

      records

-> See also: http://marc.theaimsgroup.com/?l=phpdoc&m=105251292424018

seen, but as you are saying, it's a bit too futuristic atm ;)

- other PHP.net projects (PEAR, PHP-GTK, Smarty, etc.) -> reuse some of the XML parsing, but add their own extensions to

      it

see below

-> different presentation due to different website environment

themes

I beleive that if we keep these in mind, the resulting livedocs framework will be so extensible and so flexible that anybody will be able to set up his own docbook project and start displaying it with livedocs... So we need to think about allowing the extensions on livedocs on multiple levels: - input XML parsing and TOC generation (build stage) - presentation (big HTML, mutiple HTMLs:

    phpweb view, simple view, customized viwe)

- performance (caching, no caching) - additional components (ex. user notes) From the structure you presented it is not clear to me, what separation is done on the XML parsing and HTML presentation. The PHP subprojects for example will significantly overlap in their XML -> HTML conversion, so there should be some feature to present a common ground for them. Their styelsheets however might be more different, and due to performance reasons, the style information should be contained in as few files as possible.

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) 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/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 ? Thanks a lot for your reply ;) didou