So we are on making the phpdoc workers life
easier... One of the biggest problems is for starters, that many tools are
needed. There has been some discussion on dropping the required unix tools,
and base the whole build system on PHP. That would mean that Windows
people would not need to have cygwin, which is a huge step forward.
Huh? What is so difficult w/ installing Cygwin? AFAICT I had not seen people who had try installing that had much problem, assuming that they've read the documentation for Cygwin beforehand.
Cygwin takes long to download. The developers put more and more stuff in there, and we have not been able to compile a list of tools needed by the PHP documentation, since the simple tools depend on each other, so those starting to download cygwin only have the option to download it all (including Apache, PostreSQL, etc.). I used to download my first cygwin years ago on a dialup connection and I know there are people still using dialup...
I would expect that someone writing code in PHP, that can read/understand C, and is thus helping in documenting the language would have a simpler time.
From practice I must point out that most of the people working for the translations of the documentation know nearly nothing about C, and mostly use Windows.
The main concerns I've seen here (and in PEARDOC) where related to the complexity of Docbook, which is initially true, as it has a high learning curve if you have never used a structured document format (e.g. Latex).
The visual editor idea is aimed at solving the complexity of DocBook for authors and translators. But currently it is a more critical problem, that new updates take months to get on to the website (which does decrease the motivation of translators).
I have only found http://phing.tigris.org/ so far,
which is a PHP based ready-to-use build system. It could do the tasks we
require, *but* it needs PHP 5 to run, so it might not be the best idea
to employ.
Phing is based on Ant, so it can be a nice building system, and if it follows the Ant approach, you just have to write the code for the appropriate task yu want to accomplish, in this case, build the (X)HTML version of the manual (or the PDF, etc.)
Requiring a Java system on the users machine is nearly that problematic as requiring the unix tools... Since unix system users (including macosx users) already have the unix tools, and not neccessarily have a jvm, that would be a step backward. Having PHP is a reasonable requirement from people working on the PHP documentation (one of the requirements of the current build system is PHP).
The question is up, whether:Could be but that would require re-inventing the wheel
- we should use our own PHP based build scripts (rewrite configure.in in PHP)
and handle all dependencies and cross-referencing that
make was built to handle. Unless there is a clear
advantage for the task I am not sold on the idea: "We
should only use PHP for all PHP related tasks
(documentation in this case) even if they do are a
step back in functionality". That is a very
shortsighted approach, just because I have a hammer I
don't think every problem looks like a nail.
It is interesting that although there are DSSSL and XSLT based solutions for transforming DocBook to HTML, still we have seen two PHP based solutions evolving for the same problem, one by Damien for the French manual, and one from Wez (+ Derick and Ilia) as a general DocBook tool. This is because customizing the already made tools seemed to be a harder task then creating a new converter from scratch. Damien's problem was that he needed better presentation for the manual, Wez's problem was that he needed a quick look at XML files from the manual without waiting for the long build process... This was met by the need of deploying the new manuals to the mirror sites quickly.
Implementing the build system with PHP (either with Phing or with a custom solution) might need some work, but it would have a benefit on the other side of lowering the barrier of contributions for the documentation. The documentation SDK idea from Jan Fabry also helps in this case, packaging only the needed cygwin tools without the bunch of stuff not needed...
- we should use some "packaged" build system (Phing or a better / more portable one)
Perhaps we should keep this in mind for when PHP 5 is stable, released and in wide use. BTW, why not use Ant and create the appropriate .jar files w/ the tasks? What about that Borges Project that Rasmus mentioned many moons ago?
http://www.linux-mandrake.com/en/doc/project/Borges/
(BTW, that project uses "make" and is not PHP based)
Hehe... As Steph said, it would be better if we would not change all things at once which would mean hard work for those who would like to contribute to more than one PHP documentation subproject. If we would change to some tool like this, it would mean that all subprojects should migrate to it... I had no time to look into this I must admit, and we would need some testing for this to evaluate... There are some completely different approaches there comparing to the PHP documentation, like they use generated revision numbers on paragraphs to track the changes in paragraphs, and let translators have better following on what was changed... There seem to be some impressive stuff there, but it needs examination...
Right now the livedocs adoption is my #1 priority, since it would solve the onsite search problem on mirror sites, as well as some presentation issues, the RTL problems, the XHTML standars compatibility, the time-to-market of the documentation... Until livedocs is moved into cvs.php.net, I thought about getting this subject of dropping unix tools up, because it seemed to have some backing before, and with livedocs itself dropping some of the tools naturally, this was a good point to start discussinf the topic...
I am for using the "appropriate tool for the task at
hand". If the OS that someone uses does not handle it
natively but there are extensions to accomplish the
task, then use the extensions (Cygwin in this case),
or pick a more appropriate environment (e.g. OS).
Well you cannot only measure the appropriateness of something by what it was intended to do... A PHP solution might be appropriate here because PHPdoc contributors already have PHP installed and that would be the lowest barrier possible, while more people would be able to contribute to the system. There are few people here with practice in XSLT and even few with experience with DSSSL, so this stops us from going further with the speed we would like to (with OO based docs for example). Having these requirements on Windows (cygwin, jade, etc.) holds the translations back from having more members...
Of course, my opinion is biased as I tend to use command line programs more than GUI ones, and (fortunately) have to deal with mostly Unix/Linux at home and work.
So, a big "no" for dropping the Unix tools, until someone comes with a replacement that has the same flexibility, functionality, modularity and simplicity of the configuration/building system we use now. I do not care if such hypothetical replacement is written in PHP, Java, or assembly, just that it works and that can be used for the other documentation efforts in the PHP community.
The idea is to make the build system useable (and hopefully unified) for all projects. Our needs are converging, since the PHP documentation just needs to accomodate OO docs, long time after the PHP-GTK and PEAR docs needed that. So the needs are increasingly the same, and we would like to keep the door open for all contributors to put effort in any PHP documentation project they like to add their freetime to. This means keeping the build system simple and keeping the vairous build systems as close as possible.
Goba
