Re: Whoa! News..Time for a little bit planning of architecture?

Hi t

1. DocBook --> PHPBook While DocBook offers a great set of ready to use doc building system for customization I would prefer to start from a small and limited set of tags and minimum of templates to build up later template functionality using some kind of CookBook. The process should include not only selection of the set, but documentation of its tags from the point of PHPDOC developer. Like DocBook definitive guide reference [1], but specifically aimed at PHP community with tags easily comprehended by people without publishing experience at all. Moreover this documentation should contain basic design principles of output elements - how tags should be rendered - to also be a reference for people, who design templates and will support them in the future.

[1]: http://www.docbook.org/tdg5/en/html/pt02.html    "DocBook: The

Definitive Guide" CookBook with XSL techniques is essential in this process. It must contain recipes on how to achieve features the most projects expect from DocBook. Namely: - cross-linking with validation and additional information from the link-end - pagination - table of content - footnotes - additional pages based on document structure (examples, title page, credits) Clear definition of these features and recipes will allow to see how could we map semantically based DocBook or PHPBook tags to presentation and how could we provide backward transition, which is even more important as most of us would like to use convenient web-interface with familiar wiki markup (with different meaning though) for editing PHP Manual. DocBook developers may recall something similar to the CookBook desired [2]

[2]: http://www.sagehill.net/docbookxsl/    "DocBook XSL: The Complete Guide"

I agree 100% here and have been thinking about it for a while now. It does however not score high on my priority list at the moment though.

2. Web-Interface for PHPBook I would like to say that I know exactly how to make it work. Unfortunately, no, but I don't see any obstacles to make this unfeasible either. Unless nobody is interested or no one has enough time or ... to contribute. So, the interface conception..

This has already been descussed and we really really want web-based interface and are hoping to get a student to work on it during next SOC. The idea is you can add/remove/change document on, for instance, http://doc.php.net. After the changes have been made you will push "show me diff" and download the cvs diff output where you will then need to manually apply it.

3. Final KISS Without proper organization of the work the whole project is impossible or very hard to maintain. If we want to make documentation editing process more convenient and easy, if we want to attract contributors - we need to increase SIMPLICITY and reduce CONFUSION. SIMPLICITY At last I propose to use SCONS for build automation. It is written in Python. Ahhh.. I can only imagine the kind of feeling some of us could experience after these words. =) But then ask yourself - why do we use Perl for our build system? You may say that we use Autotools not Perl, but does that really matters - are autotools simple? are they cross-platform? are they easy to customize?

If it will make you feel any better someone already rewrote it in PHP, I think. .oO(Hmh. No. Maybe I am confusing it with the docweb build script?)

I am not defending SCONS in any way - I just want to say that if we have a choice - it is better to use tools that are easier for everyone - not just for Linux/Unix hackers. Although it was a chance for me to learn "autotools" and "make" quirks I want to stress that our audience are manual editors with a little or no experience in that stuff.

The process can't be that complicated to understand? autoconf ./configure make test test_xml html_xsl if you don't understand that process I don't want you writing technical docs :)

CONFUSION Look here - http://news.php.net/group.php?group=php.doc.chm It is our beautiful list dedicated to xCHM development. Before Gabor left we have already agreed that it should be closed and a new list PHPDOC-TOOLS created to discuss everything concerned DOC.PHP.NET, Livedocs, manual building tools and all additional instrumentation. http://beeblex.com/lists/index.php/php.doc.chm/1260?s= After the post we had asked systems@ to do the switch, but unfortunately no action was taken.

If it was agreed upon then it was. Great. Now the only thing we need to do is find someone willing to implement the change. Well. That kinda is the point of it all, isnt it? We can descusse things like this and make executive decissions.. but who is going to implement it? :)

4. Conclusion At first the idea was simple - to develop simplified DocBook-like XML format with as less tags as possible for pagination and

phpbook (simplified docbook) is on my todo.

cross-referencing specialized for PHP Manual, but it turned out that we need a little bit more. I thought about making ordinary PHP+SQL web-app to work with custom and simple wiki-like, but structural format for editing of manual, but complicated PHP and SQL system will experience a lack of visibility to gain appropriate level of support from specialized open source folks we've got here. With a lot of PHP code it eventually will be a problem to distinguish between various parts or components of application. Using combination of technologies we could draw clear borders to make various system parts separated from each other without sacrificing flexibility and control over the whole.

WYSIWYG editor in the spirit of livedocs is all we need. It's not rocket scince. -Hannes