Re: [PHP-DOC] PECL Doc questions
Philip Olson wrote: Downloads should be smaller somehow like only include bundled extensions. What about building two manual versions - one with PECL and one without? IMHO it's not necessary nowadays as there are only a few PECL extensions documented but will be more important when the majority of 314 extensions (instantly growing) are documented. It's similar as with PHP 5 Windows binaries - PECL is in separate download. Jakub Vrana
Re: [PHP-DOC] PECL Doc questions
Downloads should be smaller somehow like only include bundled extensions. What about building two manual versions - one with PECL and one without? IMHO it's not necessary nowadays as there are only a few PECL extensions documented but will be more important when the majority of 314 extensions (instantly growing) are documented. This is only theoretical now, but without changing the file structure, we can make any number of books around our files, so we can separate PECL and core extensions in the far future, it need be. Goba
Re: [PHP-DOC] PECL Doc questions
On Fri, 30 Jul 2004, Philip Olson wrote: Here are some questions/concerns about having all PECL docs inside of phpdoc: Builds: Will all or just bundled PECL docs be in phpdoc manual builds? All. Meaning, will a separate PECL manual ever exist? No As PECL grows the manual will grow and like we discussed having a separate developers manual this is a *similar* issue. PECL is going to be huge one day and contain many specialized extensions. So? What's wrong with that? I think all PECL exts should be documented in the PHP Manual. regards, Derick
Re: [PHP-DOC] PECL Doc questions
decision how to handle the move. Thanks! I can also help you, but commit the files first :) Nuno Nuno, Nuno, please work on the windows install stuff first and as soon as possible. The other Windows server instructions will be based on the general Windows suggestions (Sambar server specifically :), and I will try to build a new extended CHM once the windows stuff is in and the notes are back. So please concentrate on the windows part now if possible :) Goba
Re: [PHP-DOC] PECL Doc questions
decision how to handle the move. Thanks! I can also help you, but commit the files first :) Nuno Nuno, Nuno, please work on the windows install stuff first and as soon as possible. The other Windows server instructions will be based on the general Windows suggestions (Sambar server specifically :), and I will try to build a new extended CHM once the windows stuff is in and the notes are back. So please concentrate on the windows part now if possible :) Goba :-) I didn't know you were expecting me to handle the win32 installation... I'll write the docs this afternoon and post the patch somewhere, in order you to review it first. Nuno
Re: [PHP-DOC] PECL Doc questions
On Sunday 01 August 2004 13:21, Gabor Hojtsy wrote: I just run Hartmuts split script (/scripts/reference-split.php) on PECL extension in peardoc. As Hartmuts script is a bit dated, the structure of the files does not fit in the current phpdoc style (configure.xml, constants.xml etc.) and the id's and filenames are with leading pecl., which probably is not what we want? Beside the points mentioned above entities/urls need some polish. apd.xml, paradox.xml and ps.xml are currently worked on, all other docs have last change times from 2003 and only few files have been translated. I can take care of the move and polish the files for phpdoc after we made a decision how to handle the move. What should be decided on. What are the questions? Not really questions. But we/I should inform the pear doc people ( cc'ed) and maintainers about the move. apd (last change 2 months, 1 week ago by danielc) paradox (last change 8 weeks, 2 days ago by steinm) ps (last change 4 days, 18 hours ago b steinm) Probably those people working on pecl-docs in peardoc should granted phpdoc karma. Also the few translators for those pecl docs? Thats all. I will start witrh those pecl-extensions with last change some time in the past. The files need to be made to look like our current scheme. It is probably not worth it to tweak the split script to generate the new formats, as it would be more work, and we are not expecting anymore split needs in the future. ACK Friedhelm -- http://www.jungle-world.com/
Re: [PHP-DOC] PECL Doc questions
I didn't know you were expecting me to handle the win32 installation... I remember you offered to continue work on the Windows part after you get back from your deserved holiday :) Goba
Re: [PHP-DOC] PECL Doc questions
I can take care of the move and polish the files for phpdoc after we made a decision how to handle the move. What should be decided on. What are the questions? Not really questions. But we/I should inform the pear doc people ( cc'ed) and maintainers about the move. apd (last change 2 months, 1 week ago by danielc) paradox (last change 8 weeks, 2 days ago by steinm) ps (last change 4 days, 18 hours ago b steinm) Probably those people working on pecl-docs in peardoc should granted phpdoc karma. Also the few translators for those pecl docs? Thats all. I will start witrh those pecl-extensions with last change some time in the past. I would be happy to grant Karma, if I get a list of peardoc contributors / translators, who need that. Goba
Re: [PHP-DOC] PECL Doc questions
I'm more referring to the future than today as at somepoint every PECL extension will have documentation. I'll stop worrying about it then as I most likely won't be downloading or building downloads for the PHP manual :) The upcoming index format looks nice, and intuitive; and will indeed help a great deal. I thought a bit about the issues. Let me clear up a few things: Having PECL docs in the manual is cool for authors: - we have a ready made infrastructure (translation groups, language dependant mailing lists, a complete build system, revhcecks, fallbacks, distribution system, etc.) - livedocs is primarily tested and developed on phpdoc, so PECL docs have better testing Having PECL docs in the manual is good for readers: - they don't care where a function comes from, they may install an extension, or their hosting provider does that for them, and after that they just want to use it. this provides a central place to get docs - the phpdocs have the best access infrastructure (shortcuts, search facilities, panels, etc) The MB size of the manual is not a problem for our users IMHO. The only problem is that the manual might get even harder to use with more extensions documented. We need to improve on useability anyway, this just emphasizes the need. It does not matter how big the manual is if it easy to navigate and find stuff in it. Goba
Re: [PHP-DOC] PECL Doc questions
On Friday 30 July 2004 23:14, Gabor Hojtsy wrote: [...] Doc moves: When (or if) will the Hartmut split script be run on all PECL extensions currently in peardoc? Ref: http://marc.theaimsgroup.com/?l=phpdocm=107374866303330 Anytime someone sits down and does it :) It is a TODO item, but noone grabbed it yet. I just run Hartmuts split script (/scripts/reference-split.php) on PECL extension in peardoc. As Hartmuts script is a bit dated, the structure of the files does not fit in the current phpdoc style (configure.xml, constants.xml etc.) and the id's and filenames are with leading pecl., which probably is not what we want? Beside the points mentioned above entities/urls need some polish. apd.xml, paradox.xml and ps.xml are currently worked on, all other docs have last change times from 2003 and only few files have been translated. I can take care of the move and polish the files for phpdoc after we made a decision how to handle the move. Raw output sources from the split: http://www.holliwell.de/phpdoc/ Friedhelm -- http://www.jungle-world.com/
Re: [PHP-DOC] PECL Doc questions
I just run Hartmuts split script (/scripts/reference-split.php) on PECL extension in peardoc. As Hartmuts script is a bit dated, the structure of the files does not fit in the current phpdoc style (configure.xml, constants.xml etc.) and the id's and filenames are with leading pecl., which probably is not what we want? nop. the IDs should be changed from pecl.xxx to ref.xxx the functions IDs should also be changed to function.xxx (and the files shouldn't have pecl prepended) Beside the points mentioned above entities/urls need some polish. apd.xml, paradox.xml and ps.xml are currently worked on, all other docs have last change times from 2003 and only few files have been translated. The files need a big polish :) (including WS fixes). Later we should also agree on the entities (I haven't read the Philip's email yet) to include in these files. I can take care of the move and polish the files for phpdoc after we made a decision how to handle the move. Thanks! I can also help you, but commit the files first :) Nuno
Re: [PHP-DOC] PECL Doc questions
Builds: Will all or just bundled PECL docs be in phpdoc manual builds? Meaning, will a separate PECL manual ever exist? As PECL grows the manual will grow and like we discussed having a separate developers manual this is a *similar* issue. PECL is going to be huge one day and contain many specialized extensions. The decision was to now build all PECL docs with php docs, as - users will not be aware of where the extension comes from anyway (lot of people use shared hosting) - php.net and mirror sites provide good ways to search and shortcut the manual - this will promote PECL extensions better, they will not be burried deep Since livedocs will be the future presentation system, we can do all kinds of special marks on PECL extension pages. What will the functions reference look like? Or quickref? Is the index going to simply be a package search form? Like this: http://pecl.php.net/packages.php And what about the downloadable manuals, what will their indexes look like? And what size will they be, 100MB or more? There are already 314 PECL extensions and this number increases almost daily. I'm a little worried but maybe I'm [likely] missing something here. Downloads should be smaller somehow like only include bundled extensions. Not sure how to package the other ones but maybe they can be in their own downloadable manual. Ideally someone could simply update their downloaded manual like add the extensions they need but that doesn't sound like a simple task especially for the printable one-page manual or CHM. And just think how much more size all the user comments will add! My main point of worry here is dl size and what the indexes will look like, what's online or not isn't really a concern. People need downloads for various things like IDE integration, printing, going on a trip, etc. Regards, Philip
Re: [PHP-DOC] PECL Doc questions
There is very limited documentation for PECL extensions currently as far as I see. So I am not that much worried. We need to implement the extension categorization system (phpdoc/RFC/manual.xml) either with that markup or a different one, so the extensions will be easier to locate in the manual. The manual will not be 100MB if we include all the PECL extension docs (currently available in the PEAR manual). Goba What will the functions reference look like? Or quickref? Is the index going to simply be a package search form? Like this: http://pecl.php.net/packages.php And what about the downloadable manuals, what will their indexes look like? And what size will they be, 100MB or more? There are already 314 PECL extensions and this number increases almost daily. I'm a little worried but maybe I'm [likely] missing something here. Downloads should be smaller somehow like only include bundled extensions. Not sure how to package the other ones but maybe they can be in their own downloadable manual. Ideally someone could simply update their downloaded manual like add the extensions they need but that doesn't sound like a simple task especially for the printable one-page manual or CHM. And just think how much more size all the user comments will add! My main point of worry here is dl size and what the indexes will look like, what's online or not isn't really a concern. People need downloads for various things like IDE integration, printing, going on a trip, etc. Regards, Philip
Re: [PHP-DOC] PECL Doc questions
I'm more referring to the future than today as at somepoint every PECL extension will have documentation. I'll stop worrying about it then as I most likely won't be downloading or building downloads for the PHP manual :) The upcoming index format looks nice, and intuitive; and will indeed help a great deal. Regards, Philip On Fri, 30 Jul 2004, Gabor Hojtsy wrote: There is very limited documentation for PECL extensions currently as far as I see. So I am not that much worried. We need to implement the extension categorization system (phpdoc/RFC/manual.xml) either with that markup or a different one, so the extensions will be easier to locate in the manual. The manual will not be 100MB if we include all the PECL extension docs (currently available in the PEAR manual). Goba What will the functions reference look like? Or quickref? Is the index going to simply be a package search form? Like this: http://pecl.php.net/packages.php And what about the downloadable manuals, what will their indexes look like? And what size will they be, 100MB or more? There are already 314 PECL extensions and this number increases almost daily. I'm a little worried but maybe I'm [likely] missing something here. Downloads should be smaller somehow like only include bundled extensions. Not sure how to package the other ones but maybe they can be in their own downloadable manual. Ideally someone could simply update their downloaded manual like add the extensions they need but that doesn't sound like a simple task especially for the printable one-page manual or CHM. And just think how much more size all the user comments will add! My main point of worry here is dl size and what the indexes will look like, what's online or not isn't really a concern. People need downloads for various things like IDE integration, printing, going on a trip, etc. Regards, Philip
