Re: PEAR Guide/Docs

<tuupola@appelsiini.net> wrote : > On Thu, 27 Mar 2003, Bertrand Mansion wrote: > >> I've tried for the fourth time to get my hand on Docbook XML and PEARDOC.. >> Now, I think all this is just a piece of shit. It made me loose many hours >> just to write some ugly documentation. > > Only hard part about peardoc(2) docbook was to install > a working build enviroment. Even harder when you don't know what to install. There seems to be many different versions of docbook around and peardoc is using something like a "simple" implementation. Which version ? I don't know. What's the difference between peardoc and peardoc 2 ? Why was it decided to change versions ? Is documentation in peardoc 2 really peardoc 2 formatted ? I did look at XML_Tree in peardoc 2 and I didn't get this feeling. Almost every packages are documented in different ways, some have tutorials, others have only method description, is this normal ? I would like to make doc for the new Config package but it is actually composed of 2 main classes Config and Config_Container. I thought that if I look at the way XML_Tree is documented, I could find a template for documenting Config because there is XML_Tree and XML_Tree_Node. But XML_Tree_Node is not documented and I couldn't figure out how to insert Config_Container in peardoc structure. I am sorry but I find this too confusing and initiatives like pearfr.org don't help make things clearer. Should I just start documenting my packages on my own website or on pearfr.org, which is much more flexible IMO ? > Docbook is being used in numerous > projects as a standard documentation method. So I wouldn't > call it piece of shit. It is just a bit annoying first > when you dont't understand how it works. I was not talking about docbook by itself but the way it is used in conjunction with peardoc. Writing documentation should be made easy and that's not currently the case, look at the number of packages without proper documentation. Packages change more often than php functions. IMO, it should be made easier to update documentation in peardoc. >> So my conclusion is that I am not going to write any docs for my packages as >> long as there is no proper tool to write it. It already takes enough time to >> add code comments PHPdoc style. I might write documentation some day but >> certainly not with docbook. > > I'd suggest you read the "Requirements for contributing code" > in pearweb: > > http://pear.php.net/manual/en/developers.contributing.php > > "Documentation in an appropriate format (plain text, docbook) > > Your code has to come with appropriate documentation in one of the > following formats: > > Docbook XML > Plain Text" > > So you just decided you wont write any docs? I already wrote a tutorial for HTML_Table a long time ago. I started one about HTML_QuickForm a few month ago, sent the beginning to Alexander Merz and never had any feedback. It was actually written directly in docbook. I just wish I could spend less time documenting my code than actually coding it. I am sorry about my first post, I guess I am just getting upset by the useless time I spent trying to document my packages with no success. Bertrand Mansion Mamasam