PHP Documentation Team Meeting
March 8th - 10th in Stuttgart/Germany

The participants and the PHP Documentation team like to thank
* Six Offene Systeme GmbH, feuersee Software GmbH and corbitconnect AG
  for sponsoring this event. 
* German PHP Verein for organizing this event.
* Hartmut Holzgraefe, Mark Kronsbein and Georg Richter for their hospitality
* Watzlav, the waiter from Pub Step In for the good food and drinks

Participants:
Zak Greant (Canada), Simone Cortesi (Italy), Gabor Hojtsy (Hungary),
Derick Rethans (Netherlands), Sterling Hughes (USA), Dr. Egon Schmid,
Hartmut Holzgraefe, Sebastian Bergmann, Mark Kronsbein, Jan Lehnardt,
Hakan Kuecuekyilmaz, Georg Richter (Germany). 

1. Using PHP CLI for scripting
With the latest developments regarding the PHP Command Line Interface
we decided to get rid of some of the shell script/ sed / awk stuff
used by configure and make and replace it with PHP scripts for
performance and maintainance reasons. So the phpdoc build system will
rely on a working PHP executable
to be installed in the future. It is very likely that someone working
on PHP documentation has PHP installed, so this new requirement should
be easy to meet ;) 

9.6.2002: finished (hartmut)

2. File split
We like to propose to split up the XML files in the phpdoc/functions
subdirectory into an  introduction part and seperate small files for
each function.

Having a lot of small files will especially ease translators work as
it is easier to translate small files (a single function can usually
be done in less than 10 minutes) and to track changes to the english
originals that need to be applied. Fallbacks for untranslated stuff
(which work on the file level) will now be possible for single
functions instead of just complete extensions (right now functions
added to english originals will not show up with already translated
extensions until the new stuff is translated too. As positive
sideeffects we will also finally have automatic alphabetic sorting for
function lists. 

The increased number of files does not noticeably slow down processing
(only about 1%), and we believe that CVS performance won't be an issue, too.
There will be a new subdirectory phpdoc/reference which will have a
single subdirectory for each documented extension, this will also
allow for local entities files for extensions in the future, making
the transition of documentation for extensions that get moved to PEAR/PECL easier.

9.6.2002: finished (hartmut)
          works fine now, just our (my?) assumption about CVS scaleability
          were totally wrong ... we've now created aliases allowing to
          check out the english version only or combined with exactly
          one translation, as this is what the usual author or translator
          needs (we discussed this during the meeting, but somehow this
          topic didn't make it into the protocol)
          

3. Zend API doc integration
The ZendAPI documentation is not yet well integrated into the
manual. It should at least be an appendix instead of a regular
chapter, or even stay a of its own within a PHP manual (see
http://www.docbook.org/tdg/en/html/set.html) consisting of e.g. the
PHP manual, the ZendAPI documentation and the PEAR/PECL manual(s). 

The Zend API documentation is also mostly outdated and needs to be
rewritten in parts to become up to date again. There is no need to
wait for ZendEngine 2 here because the extension API won't be affected
by the engine changes to much. 

4. License issues
(Note: we can only offer suggestions here, the actual decisions have
to be taken by the current copyright holders which are listed on the
frontpage of the english manual. of these only egon took part in this
meeting. we will write up our suggestions and findings in a proposal
to the current copyright holders) 

The current manual license (GPL) doesn't really cover documentation
issues as it's primary focus is on sourcecode only. We compared some
open documentation licenses and found that the OPL including options A
and B fits us best (http://opencontent.org/openpub/). We don't want to
be very restrictive regarding option B, so we'll publish a "permission
granting policy" that will make our decision process regarding 3rd
party publishing transparent. 

One thing we still have to check is whether the OPL including both
options is compatible with the debian guidelines, we want to make sure
we are in compliance to them. Another thing is that option B seems to
especially refer to printed material and not other forms of
publications like eBooks, we would like to have general protection
here instead of paper-only restrictions. 

And finally we have to check the license and our goals against US and
(at least) European copyright law. Regarding the manual infrastructure
and tools (configure, makefile, stylesheet customizations, scripts
...) we suggest to put them under the PHP License for consistancy
reasons. (we might even consider creating a seperate project for them
as they are usable for other documentation projects and phpGTK and SRM
already do so) 

For the future we'd suggest that each substantial contributor keeps
the copyright to his contributions (espec. important for extension
documentation) while we elect a small group of two or three people
that are in charge of copyright related issues like dealing with
option B related requests (copyright & license bitches). 

13.01.2002 : Take in consideration the  PHP Functions Essential
             Reference book, and that it's license is also under
             the OPL. http://fooassociates.com/phpfer/

5. Role definitions
We'd like to extend the list of people mentioned in the manual. The
position of names on the list should not only be defined by historical
reasons but also reflect the amount of work put into the project by
current contributors. We do not want to degrade the work done by the
founders of this project, but give the newer contributors a fair share of fame, blame and shame ;)

6. Indexes
We want to introduce additional indexes besides the current function
index that we have now. This includes special indexes for examples,
tables, figures, configure options, ini settings, resource types and
predefined constants. All these indexes can be autogenerated from C or
XML source files. A general index using s shall be built up and will
contain some meta-information to ease serach. The auxiliary text files
like funclist.txt and quickref.txt will be made available in
XML-format for download on www.php.net as they might be usefull for
tool makers (editors, IDEs, ...) 

7. FAQ
We'll try to get the FAQ more modularized so that we can link
extension-specific questions against the intro part of extensions. We
might even try to distribute the FAQ files over the newly created
extension reference directories and reassemble them when building the
manual so that extension-specific information is local to the related
extension and can be moved between PHP and PECL manual together with
the extensions doc directory.

8. man pages
UNIX style manpage generation is currently broken as it was hardcoded
against DocBook 3 structure. The current manual page generation script
uses heavy regex magic and is not really maintainable, a switch to
XSLT for man source generation or to available toolchains like
DocBook->TeXinfo->man should be considered instead of the current fix
(PS: seems like derick has fixed the script for now, but it will most
likely break again when the file split is done while an XSLT solution would not ...)

9.6.2002: now working even with splitted files (hartmut)

9. CHM for non-Windows environments
We'd like to have access to the CHMs created by goba on Linux (and
other operating systems) as the CHM format contains some meta
information that makes browsing the manual easier than on a regular
HTML browser. 

Right now we do not know of any working CHM viewer for unix, sterling
will check some options and report his findings. 

(btw: a chm generator for UNIX would be fine too, as it would ease the
build system for the manual formats we make available for download)

10. PDF
There is a lot of room for improved printable versions of the
manual. It would be nice to be able to customize the content for a
printed manual by selecting parts and extensions to be included or
excluded (ncurses interface? ;), and having printed material for
single extensions would be great, too. 
But currently we can generate PDF with the old DSSSL stylesheets
only. Apache FOP does not work for us (yet) and we do not know of any
other free XSL/FO processor ...

11. Documentation of Classes / Object Oriented Stuff
With the switch to DocBook 4 we now have and friends for documenting
classes and their methods and properties. These new tags are not well
supported by the modular stylesheets yet, but derick has already done
some related work for the SRM documentation, we will be able to take
his DSSSL modifications, but we have to do a XSLT port ourselves.

28.12.2007: Finally implemented new OO stuff (bjori)

12. General ZE2 related updates
We have to rewrite parts of the 'language' chapters for ZE2,
especially the object orientation related stuff. For now sebastian and
hartmut will have a look into it ... 

13. Version specific issues / Changelogs
We have version/availability information for functions, but there is
no common format or policy for function parameters and
feature/behaviour changes right now. Some changes are documented in
the text, some are put in special or boxes and some are just added to
the documentation without telling they hadn't been available in previous versions.

We suggest to add special changelog sections or paragraphs instead to
have all version specific stuff in a single place and to be able to
filter them out on output generation if documentation is to be used
for a current release only where nobody cares about older
releases. This will be implemented using a role='changelog' attribute.

In connection with this, we also discussed a restricted and full version availability of the manual
(as at nexen.net), so we only have the most needed parts in the
restricted one, and all parts in the full one. 

14. Stucture of extension reference infos
We'd like to see a more formal structure for the extension reference
intro parts and the actual functions. Extension references should have
different sections for introduction, availability, requirements,
configure and ini options, provided resources, constants and functions
(see ctype, ncurses, ircg or db++ documentation for examples of the
proposed structure).

Function pages should look a little more like UNIX manpages, having
sections like 'returns', 'known bugs', 'changes' and such ...

12.06.2002: work in progress, more and more extensions get changed
            to the new structure suggested

15: Mangagement of user annotiations
This has to be improved, right now we have a lot of wrong and/or
outdated entries in the user notes, and besides some deletions every
once in a while there is not much maintainance going on right
now. Important and helpful entries should be merged into the manual
itself and nonsense should be removed faster or not even show up as 
we have a lot of followup noise notes on them.

"how to do this with PHP 3" entries are not of much use any longer now
that all important ISPs offer PHP 4 and can be deleted. We'd like to
implement some simple filters into the annotation entry
process. Giving a valid email adress should be mandatory, even if it
isn't displayed, this could be done by sending confirmation requests
by email similar to those for list subscriptions. This would also give
annotators a chance to rethink their contributions before they actualy show up ;).

There should also be a delay between posting new entries to the
php-notes list and the notes getting online, so we have a chance to
reject notes *before* other users start to add followups. A rating
system for notes like the one used in the phpGtk manual would be nice
so that more important notes get to the top of the list, but we'd have
to make sure it works nice with the current mirroring setup. 

16. XSLT stuff
Some DSSSL stuff still has to be ported and we still have no working
PDF generation using XSL, so we can't drop DSSSL and jade yet, but it
is at least or long term goal to do so. 
Sterling agreed to code gnome libxslt support for ext/xslt if we
organized some funding (hartmut) or some dancing girls for him. The
current sablotron based implementation is not able to process the
manual sources and modular stylesheets while the standalone version of
libxslt (xsltproc) is. 
With a libxslt based ext/xslt we would be able to process the manual
using php and have native callbacks for things like so syntax coloring
using show_source() would be possible without postprocessing the HTML
output. 
Gabor will volunteer in all XSLT stuff, like the general ports and the
OO stuff (DSSSL => XSLT). 

17. Examples
The examples in the manual should be more consistent and useful. A
draft styleguide alredy exists under
phpdoc/RFC/coding_standards. Additional ideas that came up were syntax
highlighting and linking functions in examples to their manual pages,
which need either post-processing of the HTML output or the ext/xslt 
changes already discussed.

We also talked about having a similar feature as the old pre-Windows
Borland IDEs where it was possible to copy working examples to the
clipboard with a special single keystroke. Possible ways to implement
this for plain HTML and for CHM have to be examined ...

Having an example index and additional code-only pages for examples
might be an alternative to this. 

18. Function tables
hartmut will change the license for the function table generation code
from GPL to PHP License soon and a rewrite will most likely be
integrated into the manual project (in a distant future) 

12.06.2002: work in progess ;)

19. Website
* some small issues regarding the documentation area on php.net: we
  are going to drop text-only versions to save mirroring bandwidth
* size and build date information should be shown in a more obvious
  way, the current 'bubble boxes' are to well hidden 
* revcheck should be run more often (cron? commitlog script?)

20. Online translation tool using OC4 widgets
Sandro Zic from the OC4 project (http://www.oc4home.org/) joined us on
saturday evening to discuss the possibility of using the OC4 DocBook
Widgets for providing a web frontend for simple translation tasks so
that even users without a cvs account or a working docbook
installation can help on translating the manual. 

12.06.2002: work in progress

Stuttgart, March 10th 2002