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
