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
[EMAIL PROTECTED] to ezmlm.
--
PHP Documentation Mailing List (http://www.php.net/)
To unsubscribe, visit: http://www.php.net/unsub.php
