Hi, > > > > Yes, there are part like this, which still need much manual writing, on > > these other side a lot of > > http://perl.apache.org/release/docs/2.0/api/mod_perl-2.0/APR/Table.html can > > be autogenerated (comapre the output I send and your $table->add) > > most of the doc is still manually created, the function descriptions and > args are usually don't take much space. But I do agree that it helps a > lot. At least to create the basic docs and extend them afterwards as > time allows. >
I done some quick comparing and a lot of text seems just to be copy&paste... Of course any autogenerated doc need to be reviewed and will need manual modfications. .... > > Two problems here: > > 1. the pods will be read by people, and perldoc won't know how to handle > autodoc. Or even worse those reading the source will have to get through > a lot of noise. > perldoc will just ignore any =for which is not for the current translator. I agree to you that you get some noise in the source. > 2. I don't believe it's possible to use the generated docs without > manual adjustments. You forget that at the maps level we change > arguments, for which there is no docs. Also we don't want to be stuck > with whatever comments httpd people have written, because they might be > not good enough or for some other reason we will want to change them. > Restricting us to a use as-is doesn't sound like a good idea to me. > I don't want to do any retricting here. I want to be able to change any single lettter if necessary, but I also want to autogenerate as much as possible. XSBuilder knows about all the changes that are done for the Perl API, because it creates this Perl API. There are some few functions, where XSBuilder doesn't know anything because they are totaly handcoded, but they have to be documented manualy anyway. > > No, you maintain a single copy of each file. The autogenerated copies > are autogenerated and you want to keep the previous copy so you can run > the diff. ok, when I wrote maintain I don't mean maintain the content, but keep them somewhere at a public place, so more people are able to do that job. > Notice that you will have to diff only when you update the > maps (running source_scan), and the diff will be autogenerated and files > automatically replaced. > You have to review the result anyway, but you also have to copy&paste (and maybe modify) the diffs to the "real" document. I would like to automate this copy&paste work too. For now I don't have an idea that is really better then your diff method, so I think we should start with it and maybe we come up with something better later on. > > >>>For the XS genaration stuff there some issue with pTHX_ parameters left, > >>>which I hope to resolve soon. Also the whole stuff for generating > >> > > Why not expanding this as a macro, which PPPort supplies. Does your > version of source scan support macros expansions? I don't use a C preprocsessor for this, so it don't have the full capabilities of the C preprocessor, but of course you can do macro expansions (and you need them for example for the Apache HOOK macros) > So shouldn't this > happen automatically? Actually you don't need PPPort for this, just > including the right perl header files. > That was my first thought too, but when you do this you loose the information that it originaly was pTHX_, it's now just like any other parameter. Since the you don't know on which Perl versions the generated XS code will be compiled, it's still necessary that the generated XS code uses the xTHX macros, so expansion will happen at compile time and not at generation time. So PPPort should be included in the generated output, which makes sure that the output also works with older version of Perl, like 5.005. > > What do you mean by "discuss the template"? The template for the pods you > > are talking about above? > > If you look at the existing 2.0 API docs, I've tried to follow the same > layout (i.e. template), but I'm not entirely satisfied with it yet. > For that reason it is maybe a good idea to keep some more information in the generated docs (maybe they have then to be postprocessed before they get into the distribution), but when we keep what are the function defeintion, parameters, comment, we will be able to convert it to any layout. There is some idea at the p5ee project (http://www.officevision.com/pub/p5ee/software/htdocs/P5EEx/Blue/podstyle.ht ml), not sure if this helps anything. For example for a method you have something like: # Every method (each if applicable) =head2 <Method-Name>() * Signature: <Sample-Usage-Illustrating-The-Signature> * Param: <Param-Name> <Type> <In/Out> <Undef-OK> * Return: <Return-Name> <Type> <Undef-OK> * Throws: <Exception-Name> * Deprecated: <Since-Version> <Planned-Discontinue-Version> * Since: <Version-Number> If you use this schema you will be able to transform it any layout later, because you keep this extra informations you need in the keywords like "*Param:" Gerald ------------------------------------------------------------- Gerald Richter ecos electronic communication services gmbh Internetconnect * Webserver/-design/-datenbanken * Consulting Post: Tulpenstrasse 5 D-55276 Dienheim b. Mainz E-Mail: [EMAIL PROTECTED] Voice: +49 6133 925131 WWW: http://www.ecos.de Fax: +49 6133 925152 ------------------------------------------------------------- --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
