Docmeeting Protocol

Hello, here a rough summary of the docmeeting which we had at LT, i've no more time to wrap it up nicely before I go on holiday, so perhaps somebody else can do that? I'm cc-ing pear-doc@ as they might be interested in using all of this too, but that will require some restructuring of the PEAR doc system. regards, Derick -- ------------------------------------------------------------------------- Derick Rethans http://derickrethans.nl/ JDI Media Solutions http://www.jdimedia.nl/ International PHP Magazine http://www.php-mag.net/ -------------------------------------------------------------------------

Attending: - Hartmut Holzgraefe - Wez Furlong - Friedhelm Betz - Steph Fox - Sebastian Bergmann (partial) - Marcus Börger - Magnus Määtä - Gabor Hojtsy - Rasmus Lerdorf - Christian Stocker (partial) - Sandro Zic (partial) - Derick Rethans 1. Credits Wez came up with the idea of putting author information into the refentries and sections, which should make it quite easy to give credit. This can be done with a docinfo in a refentry, and a sectioninfo for a section. Both of these take on an authorgroup element which may contain all necessary information. The initial list for translators can be fetched from the maintainer comment. For the original English text, everything not added by Hartmut can be credited to the first committer. For the other stuff, people should just complain that they added it, and it can be done by hand (they provide a link to their commit). For the sections, language, tutorial, etc. it can be done by hand for now. Then there are techincal editors which are not really credited per section. So there should be a (generated) credits file with their details. If there is no author info section for a function (refentry), then the name of the whole refsection is shown. Other groups: - user note maintainers: andrew, meebay, didou, ... check the list. The list can be generated from the archive. Wez is going to do make a script pull it out from archives, and after that we're going to put up guidelines for who is a maintainer and who is not. - techinical editors: hartmut, egon, - authors: stig, philip, But it's kinda hard to put people in a group, thus it will be decided by group consensus. Rendering of author information will be within the documented page, in the footer in small print. There is also going to be a full listing of all authors on one page. For translations, the translators are showed below the authors in the bookinfo page of the given translation. History for functions/sections should be preserved/maintained. 2. Postponed because Sandro isn't here yet 3. User note handling Most people think that the approval system should go back in, but also there should be a possibility to add a note when rejecting a note as to tell the not provider why the note was rejected. If a maintainer of notes doesn't know if the note is appropriate, s/he should ask the maintainer of the extension. The note-handling system can grab the list of authors from php-src/EXTENSIONS, this should also go to the extension's main page (also generated of course). Either Jim or Rasmus will add functionality to allow the general public to subscribe as a "maintainer" for certain note sections, as per ext/section. In otherwords, allow people without cvs accounts to maintain user notes. Add a field that people can mark if they want to have their email address obfuscated online or not. The mirror-distributing should have it mangled (no need to generate the mangled version more than once). We're not adding any rating system because it's not useful. Yes, we will move the usernotes to some form that can be used for offline formats of the manual. 4. Buildsystem SQLite should be pushed to mirrors to support livedocs (and mainsearch). Mnogosearch from the rest doesnt make much sense so we should ask Ilia to add it. Livedocs can only use rsync common, so we generate the index databases and push that. Livedocs requirements are xsltproc and openjade. The openjade requirement will be removed, as it won't be needed to configure phpdoc. For printable manual pages, we use a GET param to turn off the php layout. (Derick) Also, one HTML page per extension should be added to livedocs. (Derick) Add stuff to livedocs to pregenerate all pages for all languages and push that out to mirrors weekly, in addition to pushing out all XML files once every 12 hours. Damien is going to help us with generating PDF straight from HTML to finally get it working. It will still need a full bightml file (generated with XSLT), but we will most likely hack up livedocs to makes this work. For the palm versions, do we really need it? Somebody should check how often they are downloaded. For now we can just use the bightml one. The CHM toc can be generated with another XSL file from the full XML files, just like the livedocs. (Derick) xmlint will replace nsgmls to validate the files. Downloadable files are going to be put on the mirrors too because of the filesize and bandwith for php.net. 2. Livedocs will not update the rsync file if there is a broken file, also we will add a pre-commit check to validate the XML (not validating) BUT not stop the commit. At generation time we won't update the rsync file. In coming up with a way to prevent checking in wrong languages, we can not really find a way of preventing that except for tightening CVS access on a by translation base. To lower tha barrier for working on a webapp to 'fill in the blanks', maybe with bitflux editor. The idea is to put it on some box and just play with it, just to see how it goes. We'll make sure users view a unified diff, and somehow/somewhere run a make test before commit. Also the (livedocs) howto should get shorter and easier. 5. We are going to try to map Marcus' BNF scheme into DocBook for the protos. Rasmus thinks of a script to compare prototypes in source and in the Documentation, but it's already there (bughunter.php). We'll try to put a class like an ext in the docs. For reference grouping, we can only do that with liveocs as it doesnt really care about the DTD. See also's are fine as is, let's not modify it. 6, PHP 5 and PECL The "classes" sections should be split into multiple pages, and just add the version specific changes there. AUthors/credits for PECL can be read from the package.xml file. Examples should be version independent unless it illustrates the differences between those two. Derick/Wez should fix the fopen() page to make it not look like a huge note. About everybody thinks to have PECL docs in the main docs, and as such should follow the PHPDoc structure. We will also come up something to "hide" parts of the TOCs to only show bundled exts, but only in the future when this becomes necessary. 7. What to do with PHP 3 docs - Remove "Extending PHP 3" - Debugging can go out to and for the rest we'll just mark the php 3 sections clearly as "PHP 3" 8. Better experience We will only redirect the shortcuts for PECL and not for PEAR, unless the PEAR people come up , and update, a static list of their own. (Perhaps ask Lukas about it) Goba will merge Derick's note/tip/caution and warning stuff into the HOWTO. 9. Seperation of PHP Manual and Internals Manual Move all development docs into one part (perhaps ditch the ZendDoc cvs) and it would be a good thing to fix the Zend docs by copying over the good stuff from the ZendAPI module. Livedocs should be update to have different "Views" on the TOC, especially for this so have different "directories" for ifferent views. 10. Licenses Group which makes guidelines and decided if stuff might be used and under which conditions. It's either yes or no. That group should also ask the translators in some way. As long as they contribute back after they used a lot it's not really a problem as long as they contribute back or if the stuff they want to use is very little. We'll send a list to all doc people if they are okay with a selected group. The process should on an open mailinglist ... perhaps not select a small group, but just the people who are subscribed to that license list. Rasmus will add doc-license@lists.php.net to ezmlm.