We have talked about some things on the linuxtag docmeeting aboutWhile we are talking about this. I have thinked about using something
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.
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 ?
Are you talking about the paragraph "2. Visual editing" ofWhile 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
/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:Should be commited to the virtual "src/" directory ;)
-> integrate with the websites functionality (shortcut handling,
error handling, language fallback)
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 theI don't really get it here. Isn't this feature available already ?
static cache
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 prebuiltWe can find a way to only need to update the $lang.sqlite files I think.
manual, with all the langauges behind
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
