[PHP-DOC] Re: [PHP-DEV] Re: [PHP-DOC] Re: [PHP-DEV] Re: [PHP-DOC] [DOC] Commit messages dead?
On Thu, Oct 2, 2008 at 03:57, Kalle Sommer Nielsen [EMAIL PROTECTED] wrote: Hi Hannes 2008/10/1 Hannes Magnusson [EMAIL PROTECTED]: 1) cvs -d:pserver:[EMAIL PROTECTED]/repository co phpdoc 1b) cd phpdoc 2) php configure.php 3) pear channel-discover doc.php.net pear install doc.php.net/phd-beta Actually this isn't always as easy on Windows, mainly because the go-pear seems to not like Windows at all, I still havn't been able to install pear with go-pear. Why not? Getting any errors? I thought it was installed by default by the installer? -Hannes
[PHP-DOC] Re: Commit messages dead?
Hello all, An online editing mechanism was discussed and started[1] but let's be honest here and stare at the larger problem. The documentation team is on extended holiday and why? I don't know... maybe it's cyclical? Or maybe we need a larger marketing budget. But really if making it easier to inject words into the manual is seen as the main problem here then great, that sounds easy to fix, but writing good documentation is time consuming and I guess many humans prefer not doing it at all even though it's an art too. But maybe removing the I don't have time to setup/test yet another tool chain excuse is a good start. The new doc build system has gone a long way to do this. We recently reviewed the doc TODO situation and one of the first tasks is streamlining the HOWTO because it's a bit lengthy and dated. As for the required tool chain it's not too difficult anymore, and DocBook knowledge and special tools are not needed except to know XML para is like a p in HTML. Basically. Almost. The online editor thread with demo: [1] http://markmail.org/message/xchvvhk4hlvg33a3 Regards, Philip
Re: [PHP-DOC] [DOC] Commit messages dead?
2008/10/1 Greg Beaver [EMAIL PROTECTED]: Elizabeth M Smith wrote: [snip] Many of us - 'documentors' - (if not all) are programmers and used to use CVS and other versioning system. But this takes some extra time that IMHO it shouldn't. If you want to spread the word and get lots of people to help in docs, I believe this kind of thing that Launchpad uses is a go. I'm very well aware that this takes time and not every contributor may actually help with good docs, but it could be moderated. [snip] 100% yes - the initial hurtle to getting new people writing docs is teaching them docbook and cvs. You can whine all you want about how easy it is - but it is NOT a zero learning curve and there are no good (free) docbook tools on the systems most people use on the desktop (yes, I mean Windows - and no people are not going to switch OS's for docbook tools). Writing in XML is not a natural thing. An online interface where people can edit docs would seriously boost people helping out. Why do you think there are so many user notes in the PHP manual ;) However...you will have to wade through the bad docs too. And I have no solution for dealing with the three million tools issues. Hi, I think Hannes was also talking about the fact that committers to CVS are not using [DOC] in their commit messages. I agree with Liz's appraisal of setting up docs for documenting. This could actually be solved with a minimal VMWare appliance that is pre-setup with everything we need to do the docs (not sure how hard that is to do). VMware works great on windows and the version we would need is free. An online interface would be useful, but would it really occur to the developers committing to php's cvs to use it? I'm not so sure. It takes me almost as long, sometimes twice as long to document the things that I write, this is the main problem from a coder's perspective: free time. I would almost rather have short summaries inside /* */ of how things work close to the lines that implement them, it would make it easier to debug other people's code as well as make documenting small changes easier. Big changes perhaps should be documented with either quick README.DOCUMENTING files, or some other quick-and-dirty situation in the source repo for those who are not yet comfortable in docbook, or in English (as both native and non-native speakers can attest, it's hard to translate PHP into English :). This was done with namespaces, and it made documenting easier, right? Greg Hi, I know I'm a small voice here, but try to follow my reasoning. The core devs write C code. The compile C code. They test it. Now, in my mind they are going to be using PHP code to test it (yes?). So, these tests are the best documentation you can get. They show you HOW it works, not from the internals perspective, but from the userland perspective (how do I use this function/method). Having to test it works requires an understanding of how it works. So, MAYBE, the core-devs could write userland code examples. Covering all the methods/parameters. I'm SURE (ahem) they already have this otherwise, how do they know there code works. A few additional comments to the code would help everyone. Not reams like I seem to produce on such a small topic (I'm wordy, get over it). I'm not talking about code coverage or unit tests here, they serve a different function. Knowing how your code will behave with broken data is one thing, but making sure it works with valid data is just as valid test. Is there a way to get just examples for all the functions? If the core-devs tests are good enough to make sure the code works, then it should be good enough for users to work from. Richard. -- - Richard Quadling Zend Certified Engineer : http://zend.com/zce.php?c=ZEND002498r=213474731 Standing on the shoulders of some very clever giants!
[PHP-DOC] PHP doc XML layout conventions - tool available?
Hi, has anyone out there written a script that will help reformat an XML doc to the PHP doc style? I have a large(ish) table in particular that I don't want to reformat by hand if I can get away with it. Many thanks, Tony
Re: [PHP-DOC] CHM manuals
On Wed, Oct 1, 2008 at 23:52, Álvaro G. Vicario [EMAIL PROTECTED] wrote: 2008/9/26 Richard Quadling [EMAIL PROTECTED]: $ cd /path/to/your/phpdoc/checkout $ php configure.php $ phd -f xhtml -t chmsource -d .manual.xml # Microsoft magic here.. :) [...] The MS Magic is as simple as running the php_manual_en.hhp that is created in your output folder. I've followed your instructions and the regular CHM file builds correctly [1]. May I assume that the download section features a December 2007 manual only because the release process is not automated and nobody did it manually? Correct One more question... In the source code there's a make_chm.bat script that seems part of this process: 1. Generate *.html files from DocBook XML 2. Transform the *.html files with regular expressions 3. Compile into *.chm It looks like the only way to generate the extended (aka fancy) manual with user notes. Is it an old build process that no longer works because the regular expressions do not match the new manual TOC? Don't know why it doesn't work, but I suppose you are right. The problem we are facing is that noone understands it well enough (and has the time) to implement it into our current rendering application (PhD) :( -Hannes
Re: [PHP-DOC] PHP doc XML layout conventions - tool available?
On Thu, Oct 2, 2008 at 13:06, Anthony Bedford [EMAIL PROTECTED] wrote: Hi, has anyone out there written a script that will help reformat an XML doc to the PHP doc style? I have a large(ish) table in particular that I don't want to reformat by hand if I can get away with it. Nope :( The closes you can get are the various scripts (CVSROOT/phpdoc/scripts/) that generate phpdoc XML from c sources or reflection. -Hannes
Re: [PHP-DOC] PHP doc XML layout conventions - tool available?
On 02.10.2008 15:06, Anthony Bedford wrote: Hi, has anyone out there written a script that will help reformat an XML doc to the PHP doc style? I have a large(ish) table in particular that I don't want to reformat by hand if I can get away with it. Should be doable with regexps, I guess. -- Wbr, Antony Dovgal
Re: [PHP-DOC] PHP doc XML layout conventions - tool available?
On Oct 2, 2008, at 12:10 PM, Hannes Magnusson wrote: On Thu, Oct 2, 2008 at 13:06, Anthony Bedford [EMAIL PROTECTED] wrote: Hi, has anyone out there written a script that will help reformat an XML doc to the PHP doc style? I have a large(ish) table in particular that I don't want to reformat by hand if I can get away with it. Nope :( The closes you can get are the various scripts (CVSROOT/phpdoc/scripts/) that generate phpdoc XML from c sources or reflection. This project has a stylesheet that converts the PHP docs to clippings (used by BBEdit) and _might_ be a foundation upon which you can use to develop a stylesheet that will do what you want: http://tinyurl.com/4bhctg Check out bbedit_php_glossary_v2.xsl Sincerely, Ted Stresen-Reuter http://tedmasterweb.com
[PHP-DOC] Re: [PHP-DEV] Re: [PHP-DOC] Re: [PHP-DEV] Re: [PHP-DOC] [DOC] Commit messages dead?
2008/10/2 Hannes Magnusson [EMAIL PROTECTED]: On Thu, Oct 2, 2008 at 03:57, Kalle Sommer Nielsen [EMAIL PROTECTED] wrote: Hi Hannes 2008/10/1 Hannes Magnusson [EMAIL PROTECTED]: 1) cvs -d:pserver:[EMAIL PROTECTED]/repository co phpdoc 1b) cd phpdoc 2) php configure.php 3) pear channel-discover doc.php.net pear install doc.php.net/phd-beta Actually this isn't always as easy on Windows, mainly because the go-pear seems to not like Windows at all, I still havn't been able to install pear with go-pear. Why not? Getting any errors? I thought it was installed by default by the installer? I do not use the installer, I simply just extra php to the folder I want to use it from. When I use: C:\PHP_5_2\go-pear It asks me to install a system or local wide install, then it comes up with some configuratives where the path to CLI php.exe always is missing. If I press Enter to continue it just shows the same list of paths, if I type all after have configured path 12 (to CLI php.exe), it will end up with this error: 1-12, 'all' or Enter to continue: all Installation base ($prefix) [Inputfejl: Der er ikke noget filtypenavn i C:\Users\Kalle.] : (Input error: There is no filetype name in C:\Users\Kalle) I guess its because the installer doesn't support folders with spaces as the directory is called C:\Users\Kalle Sommer Nielsen\ So you cannot get further or atleast I can't because my username has spaces. I had to edit the phd.bat manually to make it work, not that it was any major but anyway. -Hannes -- Kalle Sommer Nielsen
Re: [PHP-DOC] PHP doc XML layout conventions - tool available?
Hannes Magnusson wrote: On Thu, Oct 2, 2008 at 13:06, Anthony Bedford [EMAIL PROTECTED] wrote: Hi, has anyone out there written a script that will help reformat an XML doc to the PHP doc style? I have a large(ish) table in particular that I don't want to reformat by hand if I can get away with it. Nope :( The closes you can get are the various scripts (CVSROOT/phpdoc/scripts/) that generate phpdoc XML from c sources or reflection. :( C-x h C-M \ in nxml-mode does a pretty good job of tidying up the file - but it's not quite good enough I think. If I can I'll work out a better way to do this. Thanks, Tony
[PHP-DOC] patch for phd
Hi all, Attached is a small patch for phd which supresses a warning with invalid xml files and tells you explicitely when an id is missing instead of throwing notices. -- Regards/Mit freundlichen Grüßen Christian Weiske -= Geeking around in the name of science since 1982 =- peartheme.php.orig Description: Binary data signature.asc Description: PGP signature
[PHP-DOC] Re: patch for phd
Hi again,
Attached is a small patch for phd which supresses a warning with
invalid xml files and tells you explicitely when an id is missing
instead of throwing notices.
Err, wrong file. Here is the real patch.
--
Regards/Mit freundlichen Grüßen
Christian Weiske
-= Geeking around in the name of science since 1982 =-
--- /home/cweiske/Dev/cvs/pear/instpear/share/pear/phd/themes/pear/peartheme.php.orig 2008-10-02 22:31:59.0 +0200
+++ /home/cweiske/Dev/cvs/pear/instpear/share/pear/phd/themes/pear/peartheme.php 2008-10-02 22:37:33.0 +0200
@@ -214,6 +214,7 @@
}
public function format_chunk($open, $name, $attrs, $props) {
+$id = null;
if (isset($attrs[PhDReader::XMLNS_XML][id])) {
$this-CURRENT_ID = $id = $attrs[PhDReader::XMLNS_XML][id];
}
@@ -277,6 +278,9 @@
}
public function format_root_chunk($open, $name, $attrs, $props) {
+if (!array_key_exists('id', $attrs[PhDReader::XMLNS_XML])) {
+trigger_error('No xml:id attribute found in tag ' . $name, E_USER_ERROR);
+}
$this-CURRENT_ID = $id = $attrs[PhDReader::XMLNS_XML][id];
if ($open) {
return div class=\{$name}\;
signature.asc
Description: PGP signature
