You are viewing a plain text version of this content. The canonical link for it is here.
Posted to docs-dev@perl.apache.org by Gerald Richter <ri...@ecos.de> on 2002/06/12 09:35:21 UTC
Autogenerating XS code and Docs
Hi,
as some of you may know, last fall I have started a project that splits out
the XS autogenerating stuff from mod_perl 2.0 and generalize it to make it
useable also outside of mod_perl. I have converted the C parser from C::Scan
to a more flexible approach with Parse::RecDescent (which needs no C
Compiler anymore), abtracted the Apache/mod_perl specific stuff into it's
own subclass and added some other features. The result runs as
ExtUtils::XSBuilder. I use this currently to build the Perl <-> C interface
of Embperl 2.0 and for generating a mod_dav 1.0 interfaces (which I hope to
release soon). Then, of course, I have tried to use it for mod_perl itself,
but due to my limited time the process of makeing it run with mod_perl has
been stalled since some time. I had a mail exchange with Stas some time ago
and we though it will be the best to make the effort public, so maybe
somebody can join in. Also I have some time now available, so I want to
continue to work on it. There are two parts:
1.) generating code
2.) generating docs
While the first requires some knowledge of XS and mod_perl / Apache
internals, the second could be done without such a need. My current version
already splits out the comments that included in the Apache header files, so
we end up with something like:
'perl_name' => 'apr_table_add',
'comment_parsed' => {
'doxygen_param' => [
't',
'key',
'val'
],
'doxygen_param_desc' => {
'val' => 'The value to add.',
'key' => 'The key to use',
't' => 'The table to add to'
},
'func_desc' => 'Add data to a table, regardless of whether there is
another element with the same key.',
'doxygen_remark' => 'When adding data, this function makes a copy of
both the key and the value.'
},
more stuff, like mapping form C to Perl arguments etc. follows here....
Since the whole Apache API is well documented in this way, it should be
possible to autogenerate most of the mod_perl API documentation from this
informations. It would be necessary that somebody writes a tool that takes
this informations, brings it together with some manualy maintained pod and
generates the pods out of it. This shouldn't be to hard to do.
For the XS genaration stuff there some issue with pTHX_ parameters left,
which I hope to resolve soon. Also the whole stuff for generating constants
is missing yet.
I would be very happy if anybody likes to join this project, either the docs
part or help me with the XS part!
I have put the current version on my ftp server
(ftp://ftp.dev.ecos.de/pub/perl/xsbuilder/), ExtUtils-XSBuilder is the
general module, mpbuilder contains the mod_perl specify classes and wrapxs
is what is generated for mod_perl right now. The pdd files inside of wrapxs
contains the parsed comments. The ExtUtils-XSBuilder also contains a
XSBuilder.pod, which describes how the current stuff works, I append it for
convenience below. Also I append a list of changes that I have made, since I
have forked off from mod_perl.
Gerald
CHANGES:
- structs that are contained in another struct are now handled correctly.
When reading the struct memeber a new object is returned, which can be
used
to access the members of the contained struct. The contained struct cannot
be set directly.
- In class name in xxx_types.map can end with :: to use single level
classnames
(e.g. request_rec * | Apache:: for mod_perl 1.x)
- Argspec of xxx_functions.map can specify argument as return only by
prefixing
it with < e.g.
dav_open_lockdb | | r, ro, <lockdb
will be called as ($error get the return value of the C function)
($error, $lockdb) = $r -> open_lockdb (0) ;
The return argument (e.g. lockdb) will always be passed by address
to the function.
- xs/xxxx_sv_convert.h now also contains macros to convert C data types to
Perl
for non object types e.g. IV
- better handling for structs that for which a typedef doesn't exist.
- method checkmaps & writemaps creates new_*.map with all
functions/structures/types/callbacks that are not already in a map file.
- ParseSource now scans for callbacks and generates a CallbackTable.pm
with similar format as FunctionTable.pm
- WrapXS generates callbacks for struct members as method calls when the
struct doesn't contains any field where to store some userdata. An
optimized
version which passes the perl object in some user data field need still to
be done.
- Extra include files now given in xs/maps/foo_types instead of hardcoded
in TypeMap.pm
- prefixes for conversion macros and other generated functions are now
set via an overrideable method
- support for passing structure by value as function argument / return type
- macros in xxx_sv_convert.h now correctly convert NULL to undef and
viceversa
- Structure members can have a different name in Perl and C. Controlled via
the map file.
- %convert_alias has been moved into types.map
- typemap ids (e.g. T_APACHEOBJ) has been moved into types.map
- it possible to configure the way how memory for strings is allocated
via map files, by giveing a malloctype in type map file and allocation
code in structure map file.
- a dispatch argspec can now given in the map file, this allows to pass
$r to the xs function and r -> pool to the C function by writing:
ap_make_array | ap_make_array(r->pool, nelts, elt_size) | request_rec *:r,
nelts, elt_size
- handle conversion from package name to directory correctly when more then
two
levels of namespaces e.g. Apache::DAV::Resource ->
Apache/DAV/Resource/Resource_pm
DOCS
=head1 Basics
ExtUtils::XSBuilder is a set modules to parse C header files and create XS
glue code and documentation out of it. Idealy this allows to "write" an
interface to a C library without coding a line. Since no C-API is ideal,
some adjuments are necessary most of the time. So to use this module you
must still be familar with C and XS programming, but it removes a lot of
stupid work and copy&paste from you. Also when the C API changes, most
of the time you only have to rerun XSBuilder to get your new Perl API.
The creation process takes place in the following steps:
=over 4
=item Derive a class from ExtUtils::XSBuilder::ParseSource
This class must override some methods to tell XSBuilder which C header files
to parse and some other necessary parameters. You need at least to override
the
methods C<package> to give the name of the package you want to create and
either the method C<find_includes> and return all C header files to parse or
the method C<include_dirs> to return a list of all directories which should
be scanned for C header files.
Of course there are more methods you can overide. See
L<ExtUtils::XSBuilder::ParseSource> for a list of overrideable methods.
=item Scan the source files
If your derived class is called MyClass::ParseSource you simply start the
source scan with
perl -MMyClass::ParseSource -e 'MyClass::ParseSource->run'
You may also put this into a small script to ease usage and maybe set the
Perl libpath etc.
After you run the source scan XSBuilder has created a set of tables, which
contains the result of the parseing. If you don't have changed the defaults
in your class, the tables are created under C<xs/tables/current> and then
appended
the name of the module you want to create as given with the method
C<package>.
There will be a C<FunctionTable.pm> which holds all the function
declarations,
a C<StructureTable.pm> which holds the structures, a C<ConstantTable.pm>,
which
contains alls constants found in the header files and a C<CallbackTable.pm>
which contains definitions for callback types.
The main reason why we not directly create XS code, but first these
intermediate
tables is, that source scanning may take some time. As we save the result,
we can
avoid rescanning the sources as long as they don't change.
=item Derive a class from ExtUtils::XSBuilder::WrapXS
The WarpXS class is resonsible for takeing the tables which contains the
information
about the scanned sources and from the map files (see below) and create the
XS code.
As with the ParseSource class, you have to override this call with your own
implementaion,
to tell WrapXS what to do.
See L<ExtUtils::XSBuilder::WarpXS> for a list of overrideable methods.
=item Create map files
XSBuilder will not automaticly create XS functions for all C function and
structure. You
have to give some hints. This is basicly done via the map files. If you
don't change the
default they live under C<xs/maps>. There four map types. For each type
there could
multiple files prefixed with C<foo_>:
=over 4
=item foo_types.map
Contains the mapping from C type to Perl classes
=item foo_functions.map
Contains the mapping form C functions to Perl functions. Can be used to
reorder arguments, tell XSBuilder which arguments are actualy return values
and in which Perl package the function will be created.
=item foo_structures.map
Contains the mapping from C structures to Perl classes and defines for which
members a access methods should be created. You can also specify if you want
a
C<new> method for the class.
=item foo_callbacks.map
Contains the mapping form C callback functions to Perl callback functions.
Can be used to
reorder arguments, tell XSBuilder which arguments are actualy return values
and in which Perl package the function will be created.
=back
For a detailed description of the format of the map files see below.
To have a starting point XSBuilder is able to create default map files,
which simply
include all types, functions and structures. You can rerun this map file
creation
everytime and XSBuilder will append all items, that are not already in the
maps files.
If your derived class is called MyClass::WarpXS you simply start the
createing/update
of the maps files with
perl -MMyClass::WarpXS -e 'MyClass::WarpXS->checkmaps(" ")'
The the argument to checkmaps give the character that should be at the first
column
of the new map entries. If you give no argument at all, no map files are
written,
but checkmaps will only compare what is missing. (You need to print the
result somehow
e.g. by using Data::Dumper).
You may also put this into a small script to ease usage and maybe set the
Perl libpath etc.
After you have created your default maps, you have at least to edit the
C<xs/maps/new_type.map>
file, which contains all types that found in the sources. Simply append the
class or the typename
to the line spearated by a C<|> e.g.
int | IV
struct request_rec | Apache::RequestRec
=item Create the XS files
Now we can create the code. By starting
perl -MMyClass::WarpXS -e 'MyClass::WarpXS->run'
XSBuilder will create the XS, pm and Makefile.PL files for every module that
is mentioned in the maps. The result is placed as a directory hierarchy
under
WrapXS. To control the content of the C<Makefile.PL> and the C<pm> file, you
can override the methods C<makefilepl_text> and C<pm_text>. You can include
addtional code in the XS files, by writing an include file which is included
at the top of the XS file. This file can contain helper functions that can't
automaticly generated. The files must be placed under the C<xs> directory,
with the correct path and name. E.g. to have a header file included for the
module Apache::DAV, create a file C<xs/Apache/DAV/Apache__DAV.h>. The same
can be done for inclusion in the pm file. The name for the above example
would be C<xs/Apache/DAV/DAV_pm>.
=head1 Format of the maps files
For all map files blank lines are ignored and lines starting with a C<#> are
treaded as comments and also ignored.
=head2 foo_types.map
Contains the mapping from C type to Perl classes.
Format is the name of the C type followed by the name of the Perl class
or the XS type specifier, separated by a |. Example:
int | IV
struct request_rec | Apache::RequestRec
If you have a Perl class with a single name namespace (e.g. Apache) you
need to postfix it with two colons (e.g. Apache::). Structures always
needs to be written as "struct foo", also when a typedef for "foo"
exists.
Addionaly you can give the id for the typemap if you need a special
conversion and one or more other names for the struct:
struct request_rec | Apache::RequestRec | T_APACHEOBJ | r
an optional fivth parameter specifies that the data needs to be copied
when assigned to a struct member and selects the way how memory is
allocated:
char * | PV | | | strdup
The actual code for memory allocation is provided inside the structure map
e.g.
MALLOC=strdup:$dest = ($type)ap_pstrdup(obj -> pool, $src)
MALLOC=malloc:ap_palloc(obj -> pool, $src, sizeof($type)) ;
memcpy($dest,$src,sizeof($type))
This gives two ways to allocate memory and copy the data into it. The fives
parameter in the type map selects which of these two should be used.
$src, $dest and $type are replaced by the source, the destionation and the
type.
C<obj> is a pointer to the C-structure.
=head2 foo_functions.map
Contains the mapping form C functions to Perl functions. Can be used to
reorder arguments, tell XSBuilder which arguments are actualy return values
and in which Perl package the function will be created.
There are some keywords which affects all functions follwing that keyword
until a new values for that keyword is given:
=over 4
=item MODULE
the module name (file name) where the function should be placed in
e.g. Apache::Connection -> Apache/Connection.{pm,xs}
=item PACKAGE
the package name functions belong to, defaults to MODULE
value of 'guess' indicates that package name should be
guessed based on first argument found that maps to a Perl class
fallsback on the prefix (ap_ -> Apache, apr_ -> APR)
=item PREFIX
prefix to be stripped
defaults to PACKAGE, converted to C name convention, e.g.
APR::Base64 -> apr_base64_
if the converted prefix does not match, defaults to ap_ or apr_
=back
The format of entries is:
C function name | dispatch function name (dispatch argspec) | argspec |
Perl alias
Dispatch function name (the C function that is actually called) defaults
to C function name
if the dispatch name is just a prefix (mpxs_, MPXS_)
the C function name is appended to it
the return type can be specified before the C function name,
defaults to return_type in {foo}::FunctionTable as generated by
the ParseSource module.
The dispatch argspec is optional, if given you can use it to pass differnt
parameters to the dispatch function then to the xs function.
If the function name beginns with DEFINE_ a new function is defined,
(for defining function that are not parsed from the source). argsec
must be given also. For the real function name the DEFINE_ is removed.
The argspec defaults to arguments in {foo}::FunctionTable as generated by
the ParseSource module
argument types can be specified to override those in the FunctionTable
default values can be specified, e.g. arg=default_value
Example:
ap_get_client_block | mpxs_ | r, SV *:buffer, bufsiz
ap_setup_client_block | | r, read_policy=REQUEST_CHUNKED_ERROR
ap_make_array | ap_make_array(r->pool, nelts, elt_size) | request_rec
*:r, nelts, elt_size
argspec of '...' indicates passthru, calling the function with
(aTHX_ I32 items, SP **sp, SV **MARK)
To mark an argument as return only you can prefix it with < e.g.
dav_open_lockdb | | r, ro, <lockdb
will be called as ($error get the return value of the C function)
($error, $lockdb) = $r -> open_lockdb (0) ;
The return argument (e.g. lockdb) will always be passed by address
to the function.
the alias will be created in the current PACKAGE
function names that do not begin with /^\w/ or space are skipped.
You can prefix each function name with the following symbols:
'!' => 'disabled or not yet implemented',
'~' => 'implemented but not auto-generated',
'-' => 'likely never be available to Perl',
'>' => '"private" to apache',
'?' => 'unclassified',
=head2 foo_structures.map
Contains the mapping from C structures to Perl classes and defines for which
members a access methods should be created. You can also specify if you want
a
C<new> method for the class.
The format looks like the following:
<struct_name>
member1
member2
new
</struct_name>
An optional module name can be given, so the module name specifies in which
file the code should be placed, which the package name is determinated from
the type map file. Example:
<struct_name MODULE=My::Module>
For all members that are listed here, XSBuilder will generate an access
method
to read and write it's content. If you want to name the perl access method
different than the C member, you can write
cMemberValue | member_value
this will map the C<cMemberValue> structure member to the access function
C<member_value>. Default is to use the same name in Perl as in C.
If you give the C<new> member XSBuilder will
create a new method for that class, which can be used to create a new
instance
of that class and initialize it with initial data.
=head2 foo_callbacks.map
same format as function map, but contains the callbacks
=back
-------------------------------------------------------------
Gerald Richter ecos electronic communication services gmbh
Internetconnect * Webserver/-design/-datenbanken * Consulting
Post: Tulpenstrasse 5 D-55276 Dienheim b. Mainz
E-Mail: richter@ecos.de Voice: +49 6133 925131
WWW: http://www.ecos.de Fax: +49 6133 925152
-------------------------------------------------------------
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org
Re: Autogenerating XS code and Docs
Posted by Per Einar Ellefsen <pe...@skynet.be>.
At 19:21 12.06.2002, Stas Bekman wrote:
>>>>Furthermore, I think my example could still beneficially be used to
>>>>insert things like function sysopsis, which aren't dependent on writing
>>>>style, just on arguments etc.
>>>
>>>
>>>That's for the template that will be used for creating the auto-docs, no?
>>
>>No, for the final docs (must be run through a template engine though).
>>API changes will then reflect automatically in the function synopsis,
>>although manual addition of description might be needed. I'm not sure if
>>this method is better/worse than your diff method though. My point was
>>just that whatever we do, the only thing remaining from the
>>auto-generation will probably be the function synopsis, as descriptions
>>will be modified to Perl jargon. Like this we would only go through a
>>make.pl (or something like that) stage, not the "update, diff, patch" sequence.
>
>The function synopsis will be needed to be adjusted for certain functions.
>We change certain C API the Perl way, so I think this idea simply won't
>work and cause more trouble than help.
:( Forgot about that.
--
Per Einar Ellefsen
per.einar@skynet.be
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org
Re: Autogenerating XS code and Docs
Posted by Stas Bekman <st...@stason.org>.
>>> Furthermore, I think my example could still beneficially be used to
>>> insert things like function sysopsis, which aren't dependent on
>>> writing style, just on arguments etc.
>>
>>
>> That's for the template that will be used for creating the auto-docs, no?
>
>
> No, for the final docs (must be run through a template engine though).
> API changes will then reflect automatically in the function synopsis,
> although manual addition of description might be needed. I'm not sure if
> this method is better/worse than your diff method though. My point was
> just that whatever we do, the only thing remaining from the
> auto-generation will probably be the function synopsis, as descriptions
> will be modified to Perl jargon. Like this we would only go through a
> make.pl (or something like that) stage, not the "update, diff, patch"
> sequence.
The function synopsis will be needed to be adjusted for certain
functions. We change certain C API the Perl way, so I think this idea
simply won't work and cause more trouble than help.
__________________________________________________________________
Stas Bekman JAm_pH ------> Just Another mod_perl Hacker
http://stason.org/ mod_perl Guide ---> http://perl.apache.org
mailto:stas@stason.org http://use.perl.org http://apacheweek.com
http://modperlbook.org http://apache.org http://ticketmaster.com
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org
Re: Autogenerating XS code and Docs
Posted by Per Einar Ellefsen <pe...@skynet.be>.
At 18:21 12.06.2002, Stas Bekman wrote:
>Per Einar Ellefsen wrote:
>>At 14:17 12.06.2002, Stas Bekman wrote:
>>>As I've explained in my reply to Gerald, I doubt it'll be possible to
>>>automatically modify docs which were manually adjusted, because we want
>>>to be able to adjust parts that were autogenerated.
>>
>>Yes, I understand what you mean. After some thought, here's what I think:
>>we build some tool to auto-generate docs the first time around. Like that
>>we can get instant documentation now, without writing it ourselves. Then,
>>we just take those, and restructure them to they become manually edited.
>>That'll need to be done, but atleast we'll have something upfront.
>
>That's exactly what I was suggesting. Plus we continue to use this script
>to generate fresh sets of docs everytime we update the API. Then we make a
>diff with the previous autogenerated set (which we have wisely stored
>away) and voila we get only the changes that need to be manually
>integrated to the real docs.
Yes, sounds like a fair solution now that I think of it.
>>Furthermore, I think my example could still beneficially be used to
>>insert things like function sysopsis, which aren't dependent on writing
>>style, just on arguments etc.
>
>That's for the template that will be used for creating the auto-docs, no?
No, for the final docs (must be run through a template engine though). API
changes will then reflect automatically in the function synopsis, although
manual addition of description might be needed. I'm not sure if this method
is better/worse than your diff method though. My point was just that
whatever we do, the only thing remaining from the auto-generation will
probably be the function synopsis, as descriptions will be modified to Perl
jargon. Like this we would only go through a make.pl (or something like
that) stage, not the "update, diff, patch" sequence.
--
Per Einar Ellefsen
per.einar@skynet.be
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org
Re: Autogenerating XS code and Docs
Posted by Stas Bekman <st...@stason.org>.
Per Einar Ellefsen wrote:
> At 14:17 12.06.2002, Stas Bekman wrote:
>
>> Per Einar Ellefsen wrote:
>>
>>> At 12:04 12.06.2002, Gerald Richter - ecos gmbh wrote:
>>>
>>>> That's only a rought idea, maybe somebodyelse has another idea how
>>>> to handle
>>>> this?
>>>
>>>
>>> Might not be the best idea, but what I was thinking about was making
>>> it template-like, having the auto-fetches things inserted in the
>>> manual edited POD. Like.
>>> [% ap_table_add %] <---- inserts POD with function synopsis etc.
>>> Manually added notes go here......
>>> The problem is that new functions won't be picked up automatically,
>>> except if we have some special mark at the EOF where new functions
>>> can be inserted. However, I think that new functions will need to be
>>> handled manually anyway, as they need to have some
>>> order/classification that automatic generation can't do.
>>
>>
>> As I've explained in my reply to Gerald, I doubt it'll be possible to
>> automatically modify docs which were manually adjusted, because we
>> want to be able to adjust parts that were autogenerated.
>
>
> Yes, I understand what you mean. After some thought, here's what I
> think: we build some tool to auto-generate docs the first time around.
> Like that we can get instant documentation now, without writing it
> ourselves. Then, we just take those, and restructure them to they become
> manually edited. That'll need to be done, but atleast we'll have
> something upfront.
That's exactly what I was suggesting. Plus we continue to use this
script to generate fresh sets of docs everytime we update the API. Then
we make a diff with the previous autogenerated set (which we have wisely
stored away) and voila we get only the changes that need to be manually
integrated to the real docs.
> Furthermore, I think my example could still beneficially be used to
> insert things like function sysopsis, which aren't dependent on writing
> style, just on arguments etc.
That's for the template that will be used for creating the auto-docs, no?
__________________________________________________________________
Stas Bekman JAm_pH ------> Just Another mod_perl Hacker
http://stason.org/ mod_perl Guide ---> http://perl.apache.org
mailto:stas@stason.org http://use.perl.org http://apacheweek.com
http://modperlbook.org http://apache.org http://ticketmaster.com
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org
Re: Autogenerating XS code and Docs
Posted by Per Einar Ellefsen <pe...@skynet.be>.
At 14:17 12.06.2002, Stas Bekman wrote:
>Per Einar Ellefsen wrote:
>>At 12:04 12.06.2002, Gerald Richter - ecos gmbh wrote:
>>
>>>That's only a rought idea, maybe somebodyelse has another idea how to handle
>>>this?
>>
>>Might not be the best idea, but what I was thinking about was making it
>>template-like, having the auto-fetches things inserted in the manual
>>edited POD. Like.
>>[% ap_table_add %] <---- inserts POD with function synopsis etc.
>>Manually added notes go here......
>>The problem is that new functions won't be picked up automatically,
>>except if we have some special mark at the EOF where new functions can be
>>inserted. However, I think that new functions will need to be handled
>>manually anyway, as they need to have some order/classification that
>>automatic generation can't do.
>
>As I've explained in my reply to Gerald, I doubt it'll be possible to
>automatically modify docs which were manually adjusted, because we want to
>be able to adjust parts that were autogenerated.
Yes, I understand what you mean. After some thought, here's what I think:
we build some tool to auto-generate docs the first time around. Like that
we can get instant documentation now, without writing it ourselves. Then,
we just take those, and restructure them to they become manually edited.
That'll need to be done, but atleast we'll have something upfront.
Furthermore, I think my example could still beneficially be used to insert
things like function sysopsis, which aren't dependent on writing style,
just on arguments etc.
>>> > And of course we need to discuss the template, but this can be done
>>> > later when and if we start deploying ExtUtils::XSBuilder.
>>
>>I think he meant the data structure...
>
>No, I meant the template for the Apache::Foo manpage. Template in a sense
>of how the manpage should be constructed to keep docs consistent and
>intuitive. Check the existing manpages to see what I mean.
Ok, I see what you mean now.
--
Per Einar Ellefsen
per.einar@skynet.be
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org
Re: Autogenerating XS code and Docs
Posted by Stas Bekman <st...@stason.org>.
Per Einar Ellefsen wrote:
> At 12:04 12.06.2002, Gerald Richter - ecos gmbh wrote:
>
>> That's only a rought idea, maybe somebodyelse has another idea how to
>> handle
>> this?
>
>
> Might not be the best idea, but what I was thinking about was making it
> template-like, having the auto-fetches things inserted in the manual
> edited POD. Like.
>
> [% ap_table_add %] <---- inserts POD with function synopsis etc.
>
> Manually added notes go here......
>
> The problem is that new functions won't be picked up automatically,
> except if we have some special mark at the EOF where new functions can
> be inserted. However, I think that new functions will need to be handled
> manually anyway, as they need to have some order/classification that
> automatic generation can't do.
As I've explained in my reply to Gerald, I doubt it'll be possible to
automatically modify docs which were manually adjusted, because we want
to be able to adjust parts that were autogenerated.
>> > And of course we need to discuss the template, but this can be done
>> > later when and if we start deploying ExtUtils::XSBuilder.
>
>
> I think he meant the data structure...
No, I meant the template for the Apache::Foo manpage. Template in a
sense of how the manpage should be constructed to keep docs consistent
and intuitive. Check the existing manpages to see what I mean.
__________________________________________________________________
Stas Bekman JAm_pH ------> Just Another mod_perl Hacker
http://stason.org/ mod_perl Guide ---> http://perl.apache.org
mailto:stas@stason.org http://use.perl.org http://apacheweek.com
http://modperlbook.org http://apache.org http://ticketmaster.com
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org
Re: Autogenerating XS code and Docs
Posted by Per Einar Ellefsen <pe...@skynet.be>.
At 12:04 12.06.2002, Gerald Richter - ecos gmbh wrote:
>That's only a rought idea, maybe somebodyelse has another idea how to handle
>this?
Might not be the best idea, but what I was thinking about was making it
template-like, having the auto-fetches things inserted in the manual edited
POD. Like.
[% ap_table_add %] <---- inserts POD with function synopsis etc.
Manually added notes go here......
The problem is that new functions won't be picked up automatically, except
if we have some special mark at the EOF where new functions can be
inserted. However, I think that new functions will need to be handled
manually anyway, as they need to have some order/classification that
automatic generation can't do.
> > And of course we need to discuss the template, but this can be done
> > later when and if we start deploying ExtUtils::XSBuilder.
I think he meant the data structure...
--
Per Einar Ellefsen
per.einar@skynet.be
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org
Re: the API pod template
Posted by Stas Bekman <st...@stason.org>.
Gerald Richter - ecos gmbh wrote:
>>Great, I understand what you mean and agree with you. Let me sum things
>
> up:
>
>
> I agree 100% to your summary :-)
"Das ist groß" says the fish :)
>>p.s. if you have better names for stage{1,2,3} say so, I don't seem to
>>have any imagination today :)
>>
>
>
> Maybe auto, edit and final? Does this sound better?
sounds cool!
__________________________________________________________________
Stas Bekman JAm_pH ------> Just Another mod_perl Hacker
http://stason.org/ mod_perl Guide ---> http://perl.apache.org
mailto:stas@stason.org http://use.perl.org http://apacheweek.com
http://modperlbook.org http://apache.org http://ticketmaster.com
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org
Re: the API pod template
Posted by Gerald Richter - ecos gmbh <ri...@ecos.de>.
>
> Great, I understand what you mean and agree with you. Let me sum things
up:
>
I agree 100% to your summary :-)
>
> p.s. if you have better names for stage{1,2,3} say so, I don't seem to
> have any imagination today :)
>
Maybe auto, edit and final? Does this sound better?
Gerald
-------------------------------------------------------------
Gerald Richter ecos electronic communication services gmbh
Internetconnect * Webserver/-design/-datenbanken * Consulting
Post: Tulpenstrasse 5 D-55276 Dienheim b. Mainz
E-Mail: richter@ecos.de Voice: +49 6133 925131
WWW: http://www.ecos.de Fax: +49 6133 925152
-------------------------------------------------------------
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org
Re: mod_perl logo
Posted by Stas Bekman <st...@stason.org>.
Per Einar Ellefsen wrote:
> At 04:51 15.06.2002, Stas Bekman wrote:
>
>> Per Einar Ellefsen wrote:
>>
>>> At 04:01 14.06.2002, Stas Bekman wrote:
>>>
>>>> Hmm, I've looked closely at the new logos, there is a problem with
>>>> them: they don't have a "safe" margin and the logo ends at the edges
>>>> without white/transparent border :( Jonathan, can this be fixed?
>>>> This looks quite bad.
>>>
>>>
>>> I guess we can just insert them into a bigger background if that's
>>> what you mean; shouldn't be a problem.
>>
>>
>> I'm talking about images themselves, not HTML background. I think it's
>> a bad idea to suggest images which are overcropped.
>
>
> Yes, I was talking about the images themselves.It isn't too hard to just
> copy the image over to a bigger canvas (is that the name?).
sure
>> That's a lot of manual work to get the cropped margin back on all
>> images. Michael Demers has probably done most of the formats
>> converting automatically. Jonathan, can you contact him or give us his
>> email address? Thanks!
>
>
> That would of course be best...but are we prepared to wait?
Well, I don't know his email address. Of course we don't know anything
before we ask.
__________________________________________________________________
Stas Bekman JAm_pH ------> Just Another mod_perl Hacker
http://stason.org/ mod_perl Guide ---> http://perl.apache.org
mailto:stas@stason.org http://use.perl.org http://apacheweek.com
http://modperlbook.org http://apache.org http://ticketmaster.com
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org
Re: mod_perl logo
Posted by Per Einar Ellefsen <pe...@skynet.be>.
At 04:51 15.06.2002, Stas Bekman wrote:
>Per Einar Ellefsen wrote:
>>At 04:01 14.06.2002, Stas Bekman wrote:
>>>Hmm, I've looked closely at the new logos, there is a problem with them:
>>>they don't have a "safe" margin and the logo ends at the edges without
>>>white/transparent border :( Jonathan, can this be fixed? This looks quite bad.
>>
>>I guess we can just insert them into a bigger background if that's what
>>you mean; shouldn't be a problem.
>
>I'm talking about images themselves, not HTML background. I think it's a
>bad idea to suggest images which are overcropped.
Yes, I was talking about the images themselves.It isn't too hard to just
copy the image over to a bigger canvas (is that the name?).
>That's a lot of manual work to get the cropped margin back on all images.
>Michael Demers has probably done most of the formats converting
>automatically. Jonathan, can you contact him or give us his email address?
>Thanks!
That would of course be best...but are we prepared to wait?
--
Per Einar Ellefsen
per.einar@skynet.be
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org
RE: mod_perl logo
Posted by "Jonathan M. Hollin" <ne...@digital-word.com>.
I'm talking about images themselves, not HTML background. I think it's a
bad idea to suggest images which are overcropped.
That's a lot of manual work to get the cropped margin back on all
images. Michael Demers has probably done most of the formats converting
automatically. Jonathan, can you contact him or give us his email
address? Thanks!
Yikes - sorry for the delay guys. Here's Michael's email address: mike
[at] inteo.com.
Jonathan - WYPUG
http://wypug.pm.org/
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org
Re: mod_perl logo
Posted by Stas Bekman <st...@stason.org>.
Per Einar Ellefsen wrote:
> At 04:01 14.06.2002, Stas Bekman wrote:
>
>> Per Einar Ellefsen wrote:
>>
>>> At 19:01 13.06.2002, Stas Bekman wrote:
>>>
>>>> Stas Bekman wrote:
>>>>
>>>>> What are the new images?
>>>>
>>>>
>>>>
>>>> apologies, they were at the attached tar. You posted the URL, so I
>>>> was looking for them there :)
>>>>
>>>> Very nice, I'll later add them to the site's cvs. Or may be Per
>>>> Einar is already working on this :)
>>>
>>>
>>> I'll do this. Should I replace the current buttons I made from the
>>> logo with the new ones? I guess I won't incorporate his new versions
>>> of the logo, as that one's already being used. ?
>>
>>
>> Hmm, I've looked closely at the new logos, there is a problem with
>> them: they don't have a "safe" margin and the logo ends at the edges
>> without white/transparent border :( Jonathan, can this be fixed? This
>> looks quite bad.
>
>
> I guess we can just insert them into a bigger background if that's what
> you mean; shouldn't be a problem.
I'm talking about images themselves, not HTML background. I think it's a
bad idea to suggest images which are overcropped.
That's a lot of manual work to get the cropped margin back on all
images. Michael Demers has probably done most of the formats converting
automatically. Jonathan, can you contact him or give us his email
address? Thanks!
__________________________________________________________________
Stas Bekman JAm_pH ------> Just Another mod_perl Hacker
http://stason.org/ mod_perl Guide ---> http://perl.apache.org
mailto:stas@stason.org http://use.perl.org http://apacheweek.com
http://modperlbook.org http://apache.org http://ticketmaster.com
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org
Re: mod_perl logo
Posted by Per Einar Ellefsen <pe...@skynet.be>.
At 04:01 14.06.2002, Stas Bekman wrote:
>Per Einar Ellefsen wrote:
>>At 19:01 13.06.2002, Stas Bekman wrote:
>>
>>>Stas Bekman wrote:
>>>
>>>>What are the new images?
>>>
>>>
>>>apologies, they were at the attached tar. You posted the URL, so I was
>>>looking for them there :)
>>>
>>>Very nice, I'll later add them to the site's cvs. Or may be Per Einar is
>>>already working on this :)
>>
>>I'll do this. Should I replace the current buttons I made from the logo
>>with the new ones? I guess I won't incorporate his new versions of the
>>logo, as that one's already being used. ?
>
>Hmm, I've looked closely at the new logos, there is a problem with them:
>they don't have a "safe" margin and the logo ends at the edges without
>white/transparent border :( Jonathan, can this be fixed? This looks quite bad.
I guess we can just insert them into a bigger background if that's what you
mean; shouldn't be a problem.
--
Per Einar Ellefsen
per.einar@skynet.be
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org
Re: mod_perl logo
Posted by Stas Bekman <st...@stason.org>.
Per Einar Ellefsen wrote:
> At 19:01 13.06.2002, Stas Bekman wrote:
>
>> Stas Bekman wrote:
>>
>>> What are the new images?
>>
>>
>> apologies, they were at the attached tar. You posted the URL, so I was
>> looking for them there :)
>>
>> Very nice, I'll later add them to the site's cvs. Or may be Per Einar
>> is already working on this :)
>
>
> I'll do this. Should I replace the current buttons I made from the logo
> with the new ones? I guess I won't incorporate his new versions of the
> logo, as that one's already being used. ?
Hmm, I've looked closely at the new logos, there is a problem with them:
they don't have a "safe" margin and the logo ends at the edges without
white/transparent border :( Jonathan, can this be fixed? This looks
quite bad.
__________________________________________________________________
Stas Bekman JAm_pH ------> Just Another mod_perl Hacker
http://stason.org/ mod_perl Guide ---> http://perl.apache.org
mailto:stas@stason.org http://use.perl.org http://apacheweek.com
http://modperlbook.org http://apache.org http://ticketmaster.com
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org
Re: mod_perl logo
Posted by Per Einar Ellefsen <pe...@skynet.be>.
At 19:01 13.06.2002, Stas Bekman wrote:
>Stas Bekman wrote:
>
>>What are the new images?
>
>apologies, they were at the attached tar. You posted the URL, so I was
>looking for them there :)
>
>Very nice, I'll later add them to the site's cvs. Or may be Per Einar is
>already working on this :)
I'll do this. Should I replace the current buttons I made from the logo
with the new ones? I guess I won't incorporate his new versions of the
logo, as that one's already being used. ?
--
Per Einar Ellefsen
per.einar@skynet.be
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org
Re: mod_perl logo
Posted by Stas Bekman <st...@stason.org>.
Stas Bekman wrote:
> What are the new images?
apologies, they were at the attached tar. You posted the URL, so I was
looking for them there :)
Very nice, I'll later add them to the site's cvs. Or may be Per Einar is
already working on this :)
__________________________________________________________________
Stas Bekman JAm_pH ------> Just Another mod_perl Hacker
http://stason.org/ mod_perl Guide ---> http://perl.apache.org
mailto:stas@stason.org http://use.perl.org http://apacheweek.com
http://modperlbook.org http://apache.org http://ticketmaster.com
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org
Re: mod_perl logo
Posted by Stas Bekman <st...@stason.org>.
Jonathan M. Hollin wrote:
> Michael Demers has emailed me some more work he has done on the mod_perl
> logo and I attach his file here for anyone who might find a use for these
> new items. I will, of course, add these to the galleries at
> http://wypug.digital-word.com/mod_perl/ in the near future.
Strange, I cannot see any images with mozilla-1.0/linux from your site.
Works fine with Galeon. And I can see images from other sites with
mozilla. Just the names, but no images.
What are the new images?
> P.S. I apologise for my absence from the list for such a long time. It's
> not that I've lost interest in the project or anything - just that I am
> extremely busy with work at the moment.
no prob, busy is good :)
p.s. btw, it's a very bad idea to post 500k size messages to the list. I
know I've sent a bunch of snapshots before, but 500k is probably a big
pain for somebody with a slow connection. The URL should be just fine.
__________________________________________________________________
Stas Bekman JAm_pH ------> Just Another mod_perl Hacker
http://stason.org/ mod_perl Guide ---> http://perl.apache.org
mailto:stas@stason.org http://use.perl.org http://apacheweek.com
http://modperlbook.org http://apache.org http://ticketmaster.com
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org
mod_perl logo
Posted by "Jonathan M. Hollin" <ne...@digital-word.com>.
Michael Demers has emailed me some more work he has done on the mod_perl
logo and I attach his file here for anyone who might find a use for these
new items. I will, of course, add these to the galleries at
http://wypug.digital-word.com/mod_perl/ in the near future.
Kindest regards to all...
Jonathan M. Hollin - WYPUG
http://wypug.pm.org/
P.S. I apologise for my absence from the list for such a long time. It's
not that I've lost interest in the project or anything - just that I am
extremely busy with work at the moment.
Re: the API pod template
Posted by Stas Bekman <st...@stason.org>.
> As I said, I think we should create an intermediate pod, that is
perfectly
> good for editing and information transport and then a small script that
> converts to the final pod with the correct layout/design. In this way you
> separate the informations and the layout and you are able to make a new
> layout anytime you feel it's necessary without haveing to rewrite
anything.
>
Great, I understand what you mean and agree with you. Let me sum things up:
So the following is suggested for the intermediate POD, right? let's
call it stage2 template.
> To make things easier to parse I would slightly modify this and suggest
> something like
>
> =head2 *func: function()
>
> ($foo, $bar) = function($a, \@b)
>
> =over
>
> =item *param: $a
>
> is ...
>
> =item *param: @b
>
> is ...
>
> =item *return: $foo
>
> is ...
>
> =item *since: 2.0.1
>
> =back
>
> Text/Note goes here
I'd rather use @key instead of *key, the same way Apache headers use. So
we may even be able to deploy doxygen or a similar tool :)
And in the final POD those *{func|param|...} will be rewritten as I
suggested (let's call it stage3 template):
---
=head2 function()
($foo, $bar) = function($a, \@b)
Arguments:
=over
=item $a
is ...
=item @b
is ...
=back
Return values:
=over
=item $foo
is ...
=item $bar
is ...
=back
Since: 2.0.1
---
right?
So we agree on the following:
1) Stage1: The autogenerator will generate chunks of API docs conforming
to the stage2 template format.
2) Stage2:
- first time the stage1 doc is copied over to stage2 and manually edited.
- afterwards the stage2 doc is synced with stage1 doc, (currently using
the diffing approach with the older version of the stage1 doc).
This is the only doc that is ever touched manually. This doc includes
Rich information that makes it easy to parse for datastructures.
At this stage we use use stage2 template.
3) Stage3: The autoconvert converts stage2 doc into the final
representation POD for user consumption. The stage3 template is used
here. This stage's doc isn't edited manually.
This is the doc that will be distributed to user
4) Stage2 or Stage3 can be used for converting into other formats (xml,
html, pdf, etc.).
Stage3 actually falls into the Stage4 category but it's special, because
the rendered results are required to be distributed with the mod_perl
source distribution.
---
As I said I'm more interested in the final POD layout (stage3 template),
because that's what the users will see, but as you said we can always
change this layout without manual work, so I guess I'll start with the
template that I've suggested (stage3 template) and then we will see if
we change it.
p.s. if you have better names for stage{1,2,3} say so, I don't seem to
have any imagination today :)
__________________________________________________________________
Stas Bekman JAm_pH ------> Just Another mod_perl Hacker
http://stason.org/ mod_perl Guide ---> http://perl.apache.org
mailto:stas@stason.org http://use.perl.org http://apacheweek.com
http://modperlbook.org http://apache.org http://ticketmaster.com
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org
Re: the API pod template
Posted by Gerald Richter <ri...@ecos.de>.
>
> I was talking about the same thing as a final *source* doc, not final
> presentation.
ok, even better. I just though since you had pointed to the final html that
it is the same for you
> But it must be in POD. Other html, pdf are generated from
> POD and we aren't discussing these now.
>
> And please let's leave XML out of this.
>
XML is just an option for generating html, pdf etc. , but that's not the
discussion right now as you said.
>
> func is already in the =item/=head (I prefer head so it'll be in the
> TOC).
I prefer =head too
>Do you want to duplicate it?
no, my idea was that while the the editing document should still be pod, it
is maybe not the pod which will be delivered in the distribution (this pod
will be generated like html etc.), so we can add some more keywords in the
editing document, to make automatic conversion easier later on. There are
other =head's in the document and how should we detected that this is a
start of function definition. If you like to render any function definition
special later on, you will need this information.
>
> 'since:' is fine.
>
> I don't think we really need 'note:', since the rest of the section is
> one big note.
>
> So currently I see it as:
>
> ---
> =head2 function()
>
> ($foo, $bar) = function($a, \@b)
>
> param: $a is ...
> param: $b is ...
> return: $foo is ...
> return: $bar is ...
> since: 2.0.1
>
> The rest is one big note with examples and what not, so the
> autogenerator will simply copy the note from C header file as is,
> without any headers. no?
To make things easier to parse I would slightly modify this and suggest
something like
=head2 *func: function()
($foo, $bar) = function($a, \@b)
=over
=item *param: $a
is ...
=item *param: @b
is ...
=item *return: $foo
is ...
=item *since: 2.0.1
=back
Text/Note goes here
> ---
>
> notice that the first element of the section is an example of usage. See
> http://perl.apache.org/release/docs/2.0/api/mod_perl-2.0/APR/Table.html
> and you will see that there are different ways to invoke the same
> function and they should all be presented and each be followed by the
> spec of params, return values (e.g. called in scalar context, list
> context, etc). Therefore we may end up with a few sections for the same
> =head2 (without repeating the =head2 tag). Of course this will never be
> created by the autogenerator, because only Perl can make functions
> behave differently in different circumstances :)
>
ok, that sounds fine
> Now as you understand the suggested format has a problem. perldoc will
> smash all the param/return things into one para, so it's not good.
>
> Putting each entry on a separate line seems to be a big waste of space
> (though probably the only solution). And it also allows us to have
> multilined entries which wrap around.
>
That's why I suggest the =item syntax, you need some more newline, but
that's pod. Just buy a screen with more lines ;-)
> we could make these entries into quoted text, but then it makes it
> harder to wrap multilines and I'm not sure if it's a good idea.
>
I don't think quoted text is a good idea
>
> may be we don't need these tags at all? or use them differently? e.g.:
>
That comes close to my suggestion, but you loose some informations here,
that I like to preserve
>
> this is a lot of noise in the source, but will make any rendered doc
> look very good. So it seems that I prefer the latter format if thinking
> towards the final product.
>
As I said, I think we should create an intermediate pod, that is perfectly
good for editing and information transport and then a small script that
converts to the final pod with the correct layout/design. In this way you
separate the informations and the layout and you are able to make a new
layout anytime you feel it's necessary without haveing to rewrite anything.
Gerald
-------------------------------------------------------------
Gerald Richter ecos electronic communication services gmbh
Internetconnect * Webserver/-design/-datenbanken * Consulting
Post: Tulpenstrasse 5 D-55276 Dienheim b. Mainz
E-Mail: richter@ecos.de Voice: +49 6133 925131
WWW: http://www.ecos.de Fax: +49 6133 925152
-------------------------------------------------------------
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org
Re: the API pod template
Posted by Stas Bekman <st...@stason.org>.
Gerald Richter wrote:
>>I have already started using something like the following:
>>http://perl.apache.org/release/docs/2.0/api/mod_perl-2.0/APR/Table.html
>>as I said I'm not happy with it, just trying.
>>
>>So as you say we are talking about two different templates:
>>
>>1. for the autogenerated docs, which keeps as much info as possible, if
>>the info that we will not use (e.g. some C side effects, like 'const
>>char *' vs 'char *')
>>
>>2. the template for the final pod.
>>
>
>
> (2) is the final layout, which *I* don't care much about for now. I thinking
> about something between 1 and 2. (1) is what is generated automaticly, then
> we take this and do manualy editing it, so it contains the final content.
> This final content should be independend of the final layout, so we would
> get 1,2,3
>
> 1.) autogenerated
> 2.) editied
> 3.) layout -> pod,html,pdf etc. (autogenerated from 2)
>
> 2 should be something that is still editable by hand (so I perfer not use
> XML here too), but also can be easly parsed (maybe transformed to XML and
> then from there via XSLT to the other output formats)
I was talking about the same thing as a final *source* doc, not final
presentation. But it must be in POD. Other html, pdf are generated from
POD and we aren't discussing these now.
And please let's leave XML out of this.
>>Though we should discuss the (2), again see the URL above for some ideas.
>>
>>actually we have only 2 types of arguments:
>>
>>param
>>return
>>
>
>
> Yes, but for my (2) I also would like to see something like func:, note:,
> since: etc.
func is already in the =item/=head (I prefer head so it'll be in the
TOC). Do you want to duplicate it?
'since:' is fine.
I don't think we really need 'note:', since the rest of the section is
one big note.
So currently I see it as:
---
=head2 function()
($foo, $bar) = function($a, \@b)
param: $a is ...
param: $b is ...
return: $foo is ...
return: $bar is ...
since: 2.0.1
The rest is one big note with examples and what not, so the
autogenerator will simply copy the note from C header file as is,
without any headers. no?
---
notice that the first element of the section is an example of usage. See
http://perl.apache.org/release/docs/2.0/api/mod_perl-2.0/APR/Table.html
and you will see that there are different ways to invoke the same
function and they should all be presented and each be followed by the
spec of params, return values (e.g. called in scalar context, list
context, etc). Therefore we may end up with a few sections for the same
=head2 (without repeating the =head2 tag). Of course this will never be
created by the autogenerator, because only Perl can make functions
behave differently in different circumstances :)
Now as you understand the suggested format has a problem. perldoc will
smash all the param/return things into one para, so it's not good.
Putting each entry on a separate line seems to be a big waste of space
(though probably the only solution). And it also allows us to have
multilined entries which wrap around.
we could make these entries into quoted text, but then it makes it
harder to wrap multilines and I'm not sure if it's a good idea.
What do you think? Any other ideas?
may be we don't need these tags at all? or use them differently? e.g.:
-----
=head2 function()
($foo, $bar) = function($a, \@b)
Arguments:
=over
=item $a
is ...
=item @b
is ...
=back
Return values:
=over
=item $foo
is ...
=item $bar
is ...
=back
Since: 2.0.1
this is a lot of noise in the source, but will make any rendered doc
look very good. So it seems that I prefer the latter format if thinking
towards the final product.
>>so it shouldn't be a problem. I also had 'remark' in the APR::Table doc,
>>but this can probably go into the body of the description of the method.
>>
>
>
> For the final layout it can, for the editited version (my 2) it may not.
fine.
--
__________________________________________________________________
Stas Bekman JAm_pH ------> Just Another mod_perl Hacker
http://stason.org/ mod_perl Guide ---> http://perl.apache.org
mailto:stas@stason.org http://use.perl.org http://apacheweek.com
http://modperlbook.org http://apache.org http://ticketmaster.com
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org
Re: the API pod template
Posted by Gerald Richter <ri...@ecos.de>.
> I have already started using something like the following:
> http://perl.apache.org/release/docs/2.0/api/mod_perl-2.0/APR/Table.html
> as I said I'm not happy with it, just trying.
>
> So as you say we are talking about two different templates:
>
> 1. for the autogenerated docs, which keeps as much info as possible, if
> the info that we will not use (e.g. some C side effects, like 'const
> char *' vs 'char *')
>
> 2. the template for the final pod.
>
(2) is the final layout, which *I* don't care much about for now. I thinking
about something between 1 and 2. (1) is what is generated automaticly, then
we take this and do manualy editing it, so it contains the final content.
This final content should be independend of the final layout, so we would
get 1,2,3
1.) autogenerated
2.) editied
3.) layout -> pod,html,pdf etc. (autogenerated from 2)
2 should be something that is still editable by hand (so I perfer not use
XML here too), but also can be easly parsed (maybe transformed to XML and
then from there via XSLT to the other output formats)
>
> Though we should discuss the (2), again see the URL above for some ideas.
>
> actually we have only 2 types of arguments:
>
> param
> return
>
Yes, but for my (2) I also would like to see something like func:, note:,
since: etc.
> so it shouldn't be a problem. I also had 'remark' in the APR::Table doc,
> but this can probably go into the body of the description of the method.
>
For the final layout it can, for the editited version (my 2) it may not.
Gerald
-------------------------------------------------------------
Gerald Richter ecos electronic communication services gmbh
Internetconnect * Webserver/-design/-datenbanken * Consulting
Post: Tulpenstrasse 5 D-55276 Dienheim b. Mainz
E-Mail: richter@ecos.de Voice: +49 6133 925131
WWW: http://www.ecos.de Fax: +49 6133 925152
-------------------------------------------------------------
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org
the API pod template
Posted by Stas Bekman <st...@stason.org>.
[splitting the dev list off, moving the template discussion into a
separate thread]
Gerald Richter wrote:
>>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:"
I have already started using something like the following:
http://perl.apache.org/release/docs/2.0/api/mod_perl-2.0/APR/Table.html
as I said I'm not happy with it, just trying.
So as you say we are talking about two different templates:
1. for the autogenerated docs, which keeps as much info as possible, if
the info that we will not use (e.g. some C side effects, like 'const
char *' vs 'char *')
2. the template for the final pod.
I don't care much about (1), whichever format is used is fine with me,
as long as it's not xml.
Though we should discuss the (2), again see the URL above for some ideas.
actually we have only 2 types of arguments:
param
return
so it shouldn't be a problem. I also had 'remark' in the APR::Table doc,
but this can probably go into the body of the description of the method.
Is that enough?
__________________________________________________________________
Stas Bekman JAm_pH ------> Just Another mod_perl Hacker
http://stason.org/ mod_perl Guide ---> http://perl.apache.org
mailto:stas@stason.org http://use.perl.org http://apacheweek.com
http://modperlbook.org http://apache.org http://ticketmaster.com
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org
Re: Autogenerating XS code and Docs
Posted by Gerald Richter <ri...@ecos.de>.
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: richter@ecos.de Voice: +49 6133 925131
WWW: http://www.ecos.de Fax: +49 6133 925152
-------------------------------------------------------------
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@perl.apache.org
For additional commands, e-mail: dev-help@perl.apache.org
Re: Autogenerating XS code and Docs
Posted by Gerald Richter <ri...@ecos.de>.
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: richter@ecos.de Voice: +49 6133 925131
WWW: http://www.ecos.de Fax: +49 6133 925152
-------------------------------------------------------------
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org
Re: Autogenerating XS code and Docs
Posted by Stas Bekman <st...@stason.org>.
Gerald Richter - ecos gmbh wrote:
> Hi,
>
>
>>Gerald Richter wrote:
>>
>>
>>>Since the whole Apache API is well documented in this way, it should be
>>>possible to autogenerate most of the mod_perl API documentation from
>>
> this
>
>>>informations. It would be necessary that somebody writes a tool that
>>
> takes
>
>>>this informations, brings it together with some manualy maintained pod
>>
> and
>
>>>generates the pods out of it. This shouldn't be to hard to do.
>>
>>Can you please elaborate on this "merging manually maintained pod with
>>autogenerated pod" part? I don't see how this can be done easily.
>>
>>e.g. for this doc that I've added recently:
>>http://perl.apache.org/release/docs/2.0/api/mod_perl-2.0/Apache/Log.html
>>there is very little to be re-used from the apache docs, may be 5%.
>>
>
>
> 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.
>>When such a
>>doc is created for the first time, it's copied away to the place where
>>the final pod should be and filled in with manual craft. This
>>autogenerated file should be stored somewhere, so the next time the doc
>>is autogenerated again (if the Apache API changes) we will be able to
>>create a diff against docs that were autogenerated before (e.g. on every
>>release) and merge manually the changes (notice that the diff is done
>>against the doc autogenerated in the previous time, not the final pod).
>>That's how I see it working. So we keep in cvs:
>>
>>1) WrapXS/Apache/RequestRec/RequestRec.pod.last
>>2) WrapXS/Apache/RequestRec/RequestRec.pod
>>3) docs/api/mod_perl-2.0/Apache/RequestRec.pod
>>
>>1) autogenerated last time and already merged into 3)
>>2) generated now, so we can diff 2) against 1) and merge into 3)
>>3) the real pod, manualy edited.
>>
>
>
> My idea is a little different. We start with the auto generated pod. The
> generator tool adds some marks to every piecs it does, like
>
> =for autodoc start apr_table_add_blablba
>
> =for autodoc end apr_table_add_blablba
>
> now you do your hand editing. When you rerun the autogeneration, it simply
> replaces the part between the marks and leaves the rest untouched and maybe
> it prints out a list what has changed, so you are able review the changes
> afterwards.
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.
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.
> Maybe your idea with diffs it better, because there isn't so much noise in
> the pod itself, on the other hand you have to maintain serveral copies of
> every file and I am not sure how much work it will be to manualy review
> after the diff.
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. 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.
> That's only a rought idea, maybe somebodyelse has another idea how to handle
> this?
I've explained my vision in this and the previous post ;)
>>>For the XS genaration stuff there some issue with pTHX_ parameters left,
>>>which I hope to resolve soon. Also the whole stuff for generating
>>
> constants
>
>>>is missing yet.
>>
>>Devel::PPPort?
>>
>
> This isn't a issue in the generated XS code (where Devel::PPPort could be
> usefull), but an issue with code parser/generator, because you have a
> function like
>
> foo (pTHX_ int a, char b)
>
> where pTHX_ is an type and an vaiable name and has no comma, so it has to be
> handled special. Parsing now works correct, but I have add the special
> handling in the code generator.
Why not expanding this as a macro, which PPPort supplies. Does your
version of source scan support macros expansions? So shouldn't this
happen automatically? Actually you don't need PPPort for this, just
including the right perl header files.
>>Another question I have:
>>In order to use ExtUtils::XSBuilder we need to have it in mod_perl. So
>>does that mean that we cannot use it before mod_perl replaces its
>>proprietary WrapXS with ExtUtils::XSBuilder?
>
>
> I currently have it installed in parallel, have made a symlink to the
> mod_perl xs directory to get the map files. This way it's easy to let it run
> and genearte the files. That way you can prodcuse the informations for the
> docs and if you want to try out the generated xs code, you just copy over
> the WrapXS directory (which currently compiles, but some functions are
> missing due to the pTHX_ problem, so it will not run)
>
> So no problem to use it before it's fully integrated into mod_perl. If
> anybody wants to try it out, I get give more detailed installation
> instruction, or if there are more then one or two poeple use it, even add
> some automatic way.
I guess the instructions would be great in any case. I hope soon I'll
have time to play with it.
>>And of course we need to discuss the template, but this can be done
>>later when and if we start deploying ExtUtils::XSBuilder.
>>
>
>
> 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.
__________________________________________________________________
Stas Bekman JAm_pH ------> Just Another mod_perl Hacker
http://stason.org/ mod_perl Guide ---> http://perl.apache.org
mailto:stas@stason.org http://use.perl.org http://apacheweek.com
http://modperlbook.org http://apache.org http://ticketmaster.com
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@perl.apache.org
For additional commands, e-mail: dev-help@perl.apache.org
Re: Autogenerating XS code and Docs
Posted by Stas Bekman <st...@stason.org>.
Gerald Richter - ecos gmbh wrote:
> Hi,
>
>
>>Gerald Richter wrote:
>>
>>
>>>Since the whole Apache API is well documented in this way, it should be
>>>possible to autogenerate most of the mod_perl API documentation from
>>
> this
>
>>>informations. It would be necessary that somebody writes a tool that
>>
> takes
>
>>>this informations, brings it together with some manualy maintained pod
>>
> and
>
>>>generates the pods out of it. This shouldn't be to hard to do.
>>
>>Can you please elaborate on this "merging manually maintained pod with
>>autogenerated pod" part? I don't see how this can be done easily.
>>
>>e.g. for this doc that I've added recently:
>>http://perl.apache.org/release/docs/2.0/api/mod_perl-2.0/Apache/Log.html
>>there is very little to be re-used from the apache docs, may be 5%.
>>
>
>
> 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.
>>When such a
>>doc is created for the first time, it's copied away to the place where
>>the final pod should be and filled in with manual craft. This
>>autogenerated file should be stored somewhere, so the next time the doc
>>is autogenerated again (if the Apache API changes) we will be able to
>>create a diff against docs that were autogenerated before (e.g. on every
>>release) and merge manually the changes (notice that the diff is done
>>against the doc autogenerated in the previous time, not the final pod).
>>That's how I see it working. So we keep in cvs:
>>
>>1) WrapXS/Apache/RequestRec/RequestRec.pod.last
>>2) WrapXS/Apache/RequestRec/RequestRec.pod
>>3) docs/api/mod_perl-2.0/Apache/RequestRec.pod
>>
>>1) autogenerated last time and already merged into 3)
>>2) generated now, so we can diff 2) against 1) and merge into 3)
>>3) the real pod, manualy edited.
>>
>
>
> My idea is a little different. We start with the auto generated pod. The
> generator tool adds some marks to every piecs it does, like
>
> =for autodoc start apr_table_add_blablba
>
> =for autodoc end apr_table_add_blablba
>
> now you do your hand editing. When you rerun the autogeneration, it simply
> replaces the part between the marks and leaves the rest untouched and maybe
> it prints out a list what has changed, so you are able review the changes
> afterwards.
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.
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.
> Maybe your idea with diffs it better, because there isn't so much noise in
> the pod itself, on the other hand you have to maintain serveral copies of
> every file and I am not sure how much work it will be to manualy review
> after the diff.
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. 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.
> That's only a rought idea, maybe somebodyelse has another idea how to handle
> this?
I've explained my vision in this and the previous post ;)
>>>For the XS genaration stuff there some issue with pTHX_ parameters left,
>>>which I hope to resolve soon. Also the whole stuff for generating
>>
> constants
>
>>>is missing yet.
>>
>>Devel::PPPort?
>>
>
> This isn't a issue in the generated XS code (where Devel::PPPort could be
> usefull), but an issue with code parser/generator, because you have a
> function like
>
> foo (pTHX_ int a, char b)
>
> where pTHX_ is an type and an vaiable name and has no comma, so it has to be
> handled special. Parsing now works correct, but I have add the special
> handling in the code generator.
Why not expanding this as a macro, which PPPort supplies. Does your
version of source scan support macros expansions? So shouldn't this
happen automatically? Actually you don't need PPPort for this, just
including the right perl header files.
>>Another question I have:
>>In order to use ExtUtils::XSBuilder we need to have it in mod_perl. So
>>does that mean that we cannot use it before mod_perl replaces its
>>proprietary WrapXS with ExtUtils::XSBuilder?
>
>
> I currently have it installed in parallel, have made a symlink to the
> mod_perl xs directory to get the map files. This way it's easy to let it run
> and genearte the files. That way you can prodcuse the informations for the
> docs and if you want to try out the generated xs code, you just copy over
> the WrapXS directory (which currently compiles, but some functions are
> missing due to the pTHX_ problem, so it will not run)
>
> So no problem to use it before it's fully integrated into mod_perl. If
> anybody wants to try it out, I get give more detailed installation
> instruction, or if there are more then one or two poeple use it, even add
> some automatic way.
I guess the instructions would be great in any case. I hope soon I'll
have time to play with it.
>>And of course we need to discuss the template, but this can be done
>>later when and if we start deploying ExtUtils::XSBuilder.
>>
>
>
> 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.
__________________________________________________________________
Stas Bekman JAm_pH ------> Just Another mod_perl Hacker
http://stason.org/ mod_perl Guide ---> http://perl.apache.org
mailto:stas@stason.org http://use.perl.org http://apacheweek.com
http://modperlbook.org http://apache.org http://ticketmaster.com
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org
Re: Autogenerating XS code and Docs
Posted by Gerald Richter - ecos gmbh <ri...@ecos.de>.
Hi,
> Gerald Richter wrote:
>
> > Since the whole Apache API is well documented in this way, it should be
> > possible to autogenerate most of the mod_perl API documentation from
this
> > informations. It would be necessary that somebody writes a tool that
takes
> > this informations, brings it together with some manualy maintained pod
and
> > generates the pods out of it. This shouldn't be to hard to do.
>
> Can you please elaborate on this "merging manually maintained pod with
> autogenerated pod" part? I don't see how this can be done easily.
>
> e.g. for this doc that I've added recently:
> http://perl.apache.org/release/docs/2.0/api/mod_perl-2.0/Apache/Log.html
> there is very little to be re-used from the apache docs, may be 5%.
>
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)
> I guess what we need is sort of a template for the API documentation,
> which will be automatically filled with autogenerated docs.
Yes
> When such a
> doc is created for the first time, it's copied away to the place where
> the final pod should be and filled in with manual craft. This
> autogenerated file should be stored somewhere, so the next time the doc
> is autogenerated again (if the Apache API changes) we will be able to
> create a diff against docs that were autogenerated before (e.g. on every
> release) and merge manually the changes (notice that the diff is done
> against the doc autogenerated in the previous time, not the final pod).
> That's how I see it working. So we keep in cvs:
>
> 1) WrapXS/Apache/RequestRec/RequestRec.pod.last
> 2) WrapXS/Apache/RequestRec/RequestRec.pod
> 3) docs/api/mod_perl-2.0/Apache/RequestRec.pod
>
> 1) autogenerated last time and already merged into 3)
> 2) generated now, so we can diff 2) against 1) and merge into 3)
> 3) the real pod, manualy edited.
>
My idea is a little different. We start with the auto generated pod. The
generator tool adds some marks to every piecs it does, like
=for autodoc start apr_table_add_blablba
=for autodoc end apr_table_add_blablba
now you do your hand editing. When you rerun the autogeneration, it simply
replaces the part between the marks and leaves the rest untouched and maybe
it prints out a list what has changed, so you are able review the changes
afterwards.
Maybe your idea with diffs it better, because there isn't so much noise in
the pod itself, on the other hand you have to maintain serveral copies of
every file and I am not sure how much work it will be to manualy review
after the diff.
That's only a rought idea, maybe somebodyelse has another idea how to handle
this?
> > For the XS genaration stuff there some issue with pTHX_ parameters left,
> > which I hope to resolve soon. Also the whole stuff for generating
constants
> > is missing yet.
>
> Devel::PPPort?
>
This isn't a issue in the generated XS code (where Devel::PPPort could be
usefull), but an issue with code parser/generator, because you have a
function like
foo (pTHX_ int a, char b)
where pTHX_ is an type and an vaiable name and has no comma, so it has to be
handled special. Parsing now works correct, but I have add the special
handling in the code generator.
> Another question I have:
> In order to use ExtUtils::XSBuilder we need to have it in mod_perl. So
> does that mean that we cannot use it before mod_perl replaces its
> proprietary WrapXS with ExtUtils::XSBuilder?
I currently have it installed in parallel, have made a symlink to the
mod_perl xs directory to get the map files. This way it's easy to let it run
and genearte the files. That way you can prodcuse the informations for the
docs and if you want to try out the generated xs code, you just copy over
the WrapXS directory (which currently compiles, but some functions are
missing due to the pTHX_ problem, so it will not run)
So no problem to use it before it's fully integrated into mod_perl. If
anybody wants to try it out, I get give more detailed installation
instruction, or if there are more then one or two poeple use it, even add
some automatic way.
>
> And of course we need to discuss the template, but this can be done
> later when and if we start deploying ExtUtils::XSBuilder.
>
What do you mean by "discuss the template"? The template for the pods you
are talking about above?
Gerald
-------------------------------------------------------------
Gerald Richter ecos electronic communication services gmbh
Internetconnect * Webserver/-design/-datenbanken * Consulting
Post: Tulpenstrasse 5 D-55276 Dienheim b. Mainz
E-Mail: richter@ecos.de Voice: +49 6133 925131
WWW: http://www.ecos.de Fax: +49 6133 925152
-------------------------------------------------------------
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org
Re: Autogenerating XS code and Docs
Posted by Gerald Richter - ecos gmbh <ri...@ecos.de>.
Hi,
> Gerald Richter wrote:
>
> > Since the whole Apache API is well documented in this way, it should be
> > possible to autogenerate most of the mod_perl API documentation from
this
> > informations. It would be necessary that somebody writes a tool that
takes
> > this informations, brings it together with some manualy maintained pod
and
> > generates the pods out of it. This shouldn't be to hard to do.
>
> Can you please elaborate on this "merging manually maintained pod with
> autogenerated pod" part? I don't see how this can be done easily.
>
> e.g. for this doc that I've added recently:
> http://perl.apache.org/release/docs/2.0/api/mod_perl-2.0/Apache/Log.html
> there is very little to be re-used from the apache docs, may be 5%.
>
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)
> I guess what we need is sort of a template for the API documentation,
> which will be automatically filled with autogenerated docs.
Yes
> When such a
> doc is created for the first time, it's copied away to the place where
> the final pod should be and filled in with manual craft. This
> autogenerated file should be stored somewhere, so the next time the doc
> is autogenerated again (if the Apache API changes) we will be able to
> create a diff against docs that were autogenerated before (e.g. on every
> release) and merge manually the changes (notice that the diff is done
> against the doc autogenerated in the previous time, not the final pod).
> That's how I see it working. So we keep in cvs:
>
> 1) WrapXS/Apache/RequestRec/RequestRec.pod.last
> 2) WrapXS/Apache/RequestRec/RequestRec.pod
> 3) docs/api/mod_perl-2.0/Apache/RequestRec.pod
>
> 1) autogenerated last time and already merged into 3)
> 2) generated now, so we can diff 2) against 1) and merge into 3)
> 3) the real pod, manualy edited.
>
My idea is a little different. We start with the auto generated pod. The
generator tool adds some marks to every piecs it does, like
=for autodoc start apr_table_add_blablba
=for autodoc end apr_table_add_blablba
now you do your hand editing. When you rerun the autogeneration, it simply
replaces the part between the marks and leaves the rest untouched and maybe
it prints out a list what has changed, so you are able review the changes
afterwards.
Maybe your idea with diffs it better, because there isn't so much noise in
the pod itself, on the other hand you have to maintain serveral copies of
every file and I am not sure how much work it will be to manualy review
after the diff.
That's only a rought idea, maybe somebodyelse has another idea how to handle
this?
> > For the XS genaration stuff there some issue with pTHX_ parameters left,
> > which I hope to resolve soon. Also the whole stuff for generating
constants
> > is missing yet.
>
> Devel::PPPort?
>
This isn't a issue in the generated XS code (where Devel::PPPort could be
usefull), but an issue with code parser/generator, because you have a
function like
foo (pTHX_ int a, char b)
where pTHX_ is an type and an vaiable name and has no comma, so it has to be
handled special. Parsing now works correct, but I have add the special
handling in the code generator.
> Another question I have:
> In order to use ExtUtils::XSBuilder we need to have it in mod_perl. So
> does that mean that we cannot use it before mod_perl replaces its
> proprietary WrapXS with ExtUtils::XSBuilder?
I currently have it installed in parallel, have made a symlink to the
mod_perl xs directory to get the map files. This way it's easy to let it run
and genearte the files. That way you can prodcuse the informations for the
docs and if you want to try out the generated xs code, you just copy over
the WrapXS directory (which currently compiles, but some functions are
missing due to the pTHX_ problem, so it will not run)
So no problem to use it before it's fully integrated into mod_perl. If
anybody wants to try it out, I get give more detailed installation
instruction, or if there are more then one or two poeple use it, even add
some automatic way.
>
> And of course we need to discuss the template, but this can be done
> later when and if we start deploying ExtUtils::XSBuilder.
>
What do you mean by "discuss the template"? The template for the pods you
are talking about above?
Gerald
-------------------------------------------------------------
Gerald Richter ecos electronic communication services gmbh
Internetconnect * Webserver/-design/-datenbanken * Consulting
Post: Tulpenstrasse 5 D-55276 Dienheim b. Mainz
E-Mail: richter@ecos.de Voice: +49 6133 925131
WWW: http://www.ecos.de Fax: +49 6133 925152
-------------------------------------------------------------
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@perl.apache.org
For additional commands, e-mail: dev-help@perl.apache.org
Re: modperl Windows Build
Posted by Eldon Lewis <pe...@pengyrix.com>.
I get a message that there is a syntax error on line 173 of httpd.conf. It
says it can't find mod_perl.so. This module is in the modules directory
under Apache2. It generates the error and then terminates.
Any suggestions?
Thanks,
Eldon
----- Original Message -----
From: "Randy Kobes" <ra...@theoryx5.uwinnipeg.ca>
To: "Eldon Lewis" <pe...@pengyrix.com>
Cc: <de...@perl.apache.org>
Sent: Wednesday, June 12, 2002 6:54 PM
Subject: Re: modperl Windows Build
> On Wed, 12 Jun 2002, Eldon Lewis wrote:
>
> That is a bit confusing, but Apache for a little while now
> has adopted the convention that the .dll module files are
> to have the .so extension, in part to make the unix and
> win32 documentation less different.
>
> When you say it doesn't work, which part doesn't? Does
> it not start? Are there any helpful error messages reported?
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@perl.apache.org
For additional commands, e-mail: dev-help@perl.apache.org
Re: modperl Windows Build
Posted by Eldon Lewis <el...@pengyrix.com>.
I get a message that there is a syntax error on line 173 of httpd.conf. It
says it can't find mod_perl.so. This module is in the modules directory
under Apache2. It generates the error and then terminates.
Any suggestions?
Thanks,
Eldon
> On Wed, 12 Jun 2002, Eldon Lewis wrote:
>
> > Not sure if this is the right place to post. I downloaded the Apache2
with
> > modperl support for windows. Unfortunately, it doesn't work because the
> > modules are compiled as .so files and under windows they need to be
compiled
> > as .dll files. Can anyone tell me where the best place to report this
is?
> >
> > Thanks,
> >
> > Eldon
>
> That is a bit confusing, but Apache for a little while now
> has adopted the convention that the .dll module files are
> to have the .so extension, in part to make the unix and
> win32 documentation less different.
>
> When you say it doesn't work, which part doesn't? Does
> it not start? Are there any helpful error messages reported?
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@perl.apache.org
For additional commands, e-mail: dev-help@perl.apache.org
Re: modperl Windows Build
Posted by Randy Kobes <ra...@theoryx5.uwinnipeg.ca>.
On Wed, 12 Jun 2002, Eldon Lewis wrote:
> Not sure if this is the right place to post. I downloaded the Apache2 with
> modperl support for windows. Unfortunately, it doesn't work because the
> modules are compiled as .so files and under windows they need to be compiled
> as .dll files. Can anyone tell me where the best place to report this is?
>
> Thanks,
>
> Eldon
That is a bit confusing, but Apache for a little while now
has adopted the convention that the .dll module files are
to have the .so extension, in part to make the unix and
win32 documentation less different.
When you say it doesn't work, which part doesn't? Does
it not start? Are there any helpful error messages reported?
best regards,
randy kobes
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@perl.apache.org
For additional commands, e-mail: dev-help@perl.apache.org
modperl Windows Build
Posted by Eldon Lewis <pe...@pengyrix.com>.
Not sure if this is the right place to post. I downloaded the Apache2 with
modperl support for windows. Unfortunately, it doesn't work because the
modules are compiled as .so files and under windows they need to be compiled
as .dll files. Can anyone tell me where the best place to report this is?
Thanks,
Eldon
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@perl.apache.org
For additional commands, e-mail: dev-help@perl.apache.org
Re: Autogenerating XS code and Docs
Posted by Lyle Brooks <br...@deseret.com>.
At some point it appears that Apache::Build::apxs() is being called,
which does this
98 my $apxs;
99 my @trys = ($Apache::Build::APXS,
100 $self->{MP_APXS},
101 $ENV{MP_APXS});
MP_APXS is not set.
per the instructions in
http://perl.apache.org/release/docs/2.0/user/install/install.html
* MP_APXS
Path to apxs. For example if you've installed Apache 2.0 under /home/httpd/httpd-2.0 as DSO, the default location would be /home/httpd/httpd-2.0/bin/apxs.
META: this option most likely will go away, use MP_AP_PREFIX
So I used MP_AP_PREFIX in my build, but not MP_APXS, perhaps the code
needs to catch up with the docs, as it looks like building with MP_AP_PREFIX
should be sufficient.
102
103 unless (IS_MOD_PERL_BUILD) {
104 #if we are building mod_perl via apxs, apxs should already be known
105 #these extra tries are for things built outside of mod_perl
106 #e.g. libapreq
107 push @trys,
108 Apache::TestConfig::which('apxs'),
109 '/usr/local/apache/bin/apxs';
110 }
and this is where it eventually picks up '/usr/local/apache/bin/apxs'
so I think I can for now define $ENV{MP_APXS}, but later I'll want
to rebuild with MP_APXS defined.
...time passes...
Yup, setting $ENV{MP_APXS} seemed to make things go alot further.
This is good. I'm learning more about modperl-2.0 by debugging than
I ever would by just reading, which is one of the reasons I wanted to
do this.
Quoting Lyle Brooks (brooks@deseret.com):
> Quoting Gerald Richter (richter@ecos.de):
> > > I've been looking for a way to help out in the modperl-2.x development
> > > effort. This sounds interesting.
> > >
> > > Let me know where and how I can contribute my modest skills.
> > >
> >
> > You are very welcome to contribute.
> >
> > I would suggest you start with the part of autogenerating docs. For various
> > reasons:
> >
> > 1.) For the XS code we have a working solutions, docs are missing for large
> > parts of the API.
> > 2.) You will be able to get familar with XSBuilder, without the need to
> > understand all Apache / mod_perl /XS internals right from the start, but you
> > get a good insight how everything works.
> >
> > To start,
> > - check out modperl from the CVS
> > - install mod_perl on your system
> > - download the sources of xsbuilder and mpbuilder from
> > ftp://ftp.dev.ecos.de/pub/perl/xsbuilder/.
> > - Install XSBuilder as usualy (perl Makefile.PL && make install)
> > - Unpack mpbuilder
> > - Make a symlink named xs in the mpbuilder directory to the xs directory in
> > the modperl cvs
> > - adjust the lib paths in the xsbuilder/*.pl files to point to the
> > mpbuilder/lib and your modperl CVS directory
> > - run xsbuilder/source_scan.pl
>
> Got to this point and then I get
>
> :~/src/mpbuilder:138> /opt/perl/bin/perl xsbuilder/source_scan.pl
> !!! '/usr/local/apache/bin/apxs -q INCLUDEDIR' failed:
> !!! apxs:Error: Sorry, no DSO support for Apache available
> apxs:Error: under your platform. Make sure the Apache
> apxs:Error: module mod_so is compiled into your server
> apxs:Error: binary `/usr/local/apache/bin/httpd'.
>
> Search all headers in:
>
> could not find include directory at /opt/perl/lib/site_perl/5.8.0/ExtUtils/XSBuilder/ParseSource.pm line 214.
>
> ExtUtils::XSBuilder::ParseSource::find_includes('Apache::ParseSource=HASH(0x8a677ac)') called at /opt/perl/lib/site_perl/5.8.0/ExtUtils/XSBuilder/ParseSource.pm line 67
> ExtUtils::XSBuilder::ParseSource::parse('Apache::ParseSource=HASH(0x8a677ac)') called at /opt/perl/lib/site_perl/5.8.0/ExtUtils/XSBuilder/ParseSource.pm line 626
> ExtUtils::XSBuilder::ParseSource::run('Apache::ParseSource') called at xsbuilder/source_scan.pl line 13
>
>
> Now I have an apache 1.3 installation in /usr/local/apache, and my
> apache 2.x installation in /usr/local/apache-2.0
>
>
> Any thoughts on what parameters need to be set so it will pick up the
> "right" directory?
>
> Thanks.
>
>
>
>
>
> > - run xsbuilder/xs_generate.pl
> > - Now you have a WrapXS subdirectory which contains the generated XS files
> > - This directory also contains a pdd file for every module, which holds all
> > information avaiable for that module and it's method, this is the source for
> > generating the docs
> >
> > Gerald
> >
> > P.S. Some of the discussion of the autodoc generatation has only taken place
> > on the docs-dev list, so you may join this as well
> >
> > -------------------------------------------------------------
> > Gerald Richter ecos electronic communication services gmbh
> > Internetconnect * Webserver/-design/-datenbanken * Consulting
> >
> > Post: Tulpenstrasse 5 D-55276 Dienheim b. Mainz
> > E-Mail: richter@ecos.de Voice: +49 6133 925131
> > WWW: http://www.ecos.de Fax: +49 6133 925152
> > -------------------------------------------------------------
> >
> >
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@perl.apache.org
> For additional commands, e-mail: dev-help@perl.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@perl.apache.org
For additional commands, e-mail: dev-help@perl.apache.org
Re: Autogenerating XS code and Docs
Posted by Lyle Brooks <br...@deseret.com>.
Quoting Gerald Richter (richter@ecos.de):
> > I've been looking for a way to help out in the modperl-2.x development
> > effort. This sounds interesting.
> >
> > Let me know where and how I can contribute my modest skills.
> >
>
> You are very welcome to contribute.
>
> I would suggest you start with the part of autogenerating docs. For various
> reasons:
>
> 1.) For the XS code we have a working solutions, docs are missing for large
> parts of the API.
> 2.) You will be able to get familar with XSBuilder, without the need to
> understand all Apache / mod_perl /XS internals right from the start, but you
> get a good insight how everything works.
>
> To start,
> - check out modperl from the CVS
> - install mod_perl on your system
> - download the sources of xsbuilder and mpbuilder from
> ftp://ftp.dev.ecos.de/pub/perl/xsbuilder/.
> - Install XSBuilder as usualy (perl Makefile.PL && make install)
> - Unpack mpbuilder
> - Make a symlink named xs in the mpbuilder directory to the xs directory in
> the modperl cvs
> - adjust the lib paths in the xsbuilder/*.pl files to point to the
> mpbuilder/lib and your modperl CVS directory
> - run xsbuilder/source_scan.pl
Got to this point and then I get
:~/src/mpbuilder:138> /opt/perl/bin/perl xsbuilder/source_scan.pl
!!! '/usr/local/apache/bin/apxs -q INCLUDEDIR' failed:
!!! apxs:Error: Sorry, no DSO support for Apache available
apxs:Error: under your platform. Make sure the Apache
apxs:Error: module mod_so is compiled into your server
apxs:Error: binary `/usr/local/apache/bin/httpd'.
Search all headers in:
could not find include directory at /opt/perl/lib/site_perl/5.8.0/ExtUtils/XSBuilder/ParseSource.pm line 214.
ExtUtils::XSBuilder::ParseSource::find_includes('Apache::ParseSource=HASH(0x8a677ac)') called at /opt/perl/lib/site_perl/5.8.0/ExtUtils/XSBuilder/ParseSource.pm line 67
ExtUtils::XSBuilder::ParseSource::parse('Apache::ParseSource=HASH(0x8a677ac)') called at /opt/perl/lib/site_perl/5.8.0/ExtUtils/XSBuilder/ParseSource.pm line 626
ExtUtils::XSBuilder::ParseSource::run('Apache::ParseSource') called at xsbuilder/source_scan.pl line 13
Now I have an apache 1.3 installation in /usr/local/apache, and my
apache 2.x installation in /usr/local/apache-2.0
Any thoughts on what parameters need to be set so it will pick up the
"right" directory?
Thanks.
> - run xsbuilder/xs_generate.pl
> - Now you have a WrapXS subdirectory which contains the generated XS files
> - This directory also contains a pdd file for every module, which holds all
> information avaiable for that module and it's method, this is the source for
> generating the docs
>
> Gerald
>
> P.S. Some of the discussion of the autodoc generatation has only taken place
> on the docs-dev list, so you may join this as well
>
> -------------------------------------------------------------
> Gerald Richter ecos electronic communication services gmbh
> Internetconnect * Webserver/-design/-datenbanken * Consulting
>
> Post: Tulpenstrasse 5 D-55276 Dienheim b. Mainz
> E-Mail: richter@ecos.de Voice: +49 6133 925131
> WWW: http://www.ecos.de Fax: +49 6133 925152
> -------------------------------------------------------------
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@perl.apache.org
For additional commands, e-mail: dev-help@perl.apache.org
Re: Autogenerating XS code and Docs
Posted by Gerald Richter <ri...@ecos.de>.
> > P.S. Some of the discussion of the autodoc generatation has only taken
place
> > on the docs-dev list, so you may join this as well
>
> And it should probably continue only on the docs-dev list. I see no
> reason for cross-posting this to the dev list.
My previous posts contains comment about both XS and docs, so I posted it to
both lists. If we continue with docs only, then of course the docs list, is
the right one.
Gerald
-------------------------------------------------------------
Gerald Richter ecos electronic communication services gmbh
Internetconnect * Webserver/-design/-datenbanken * Consulting
Post: Tulpenstrasse 5 D-55276 Dienheim b. Mainz
E-Mail: richter@ecos.de Voice: +49 6133 925131
WWW: http://www.ecos.de Fax: +49 6133 925152
-------------------------------------------------------------
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org
Re: Autogenerating XS code and Docs
Posted by Stas Bekman <st...@stason.org>.
Gerald Richter wrote:
> P.S. Some of the discussion of the autodoc generatation has only taken place
> on the docs-dev list, so you may join this as well
And it should probably continue only on the docs-dev list. I see no
reason for cross-posting this to the dev list.
__________________________________________________________________
Stas Bekman JAm_pH ------> Just Another mod_perl Hacker
http://stason.org/ mod_perl Guide ---> http://perl.apache.org
mailto:stas@stason.org http://use.perl.org http://apacheweek.com
http://modperlbook.org http://apache.org http://ticketmaster.com
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org
Re: Autogenerating Docs
Posted by Randy Kobes <ra...@theoryx5.uwinnipeg.ca>.
On Mon, 9 Dec 2002, Stas Bekman wrote:
> Randy Kobes wrote:
> > Stas has mentioned that getting the autogenerating of skeleton
> > pods would be useful ...
>
> Gerald works on the generalized WrapXS, which also parses the C headers
> files and based on that will generate the pods. Lyle was/is working on
> the latter functionality.
>
> > Attached is a script that perhaps might
> > be a start in that direction - it takes a pdd file and writes a
> > pod outline of the included methods (name, C definition,
> > description, arguments, and return type).
>
> what's pdd?
It's a file that was in Gerald's WrapXS distribution, generated
by ModPerl::WrapXS for each module, containing information on the
available methods.
--
best regards,
randy
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org
Re: Autogenerating Docs
Posted by Stas Bekman <st...@stason.org>.
Randy Kobes wrote:
> Stas has mentioned that getting the autogenerating of skeleton
> pods would be useful ...
Gerald works on the generalized WrapXS, which also parses the C headers
files and based on that will generate the pods. Lyle was/is working on
the latter functionality.
> Attached is a script that perhaps might
> be a start in that direction - it takes a pdd file and writes a
> pod outline of the included methods (name, C definition,
> description, arguments, and return type).
what's pdd?
> ------------------------------------------------------------------------
>
> use strict;
> use warnings;
> my $pdd = shift || die "Useage: $0 pdd_file";
>
> pdd2pod($pdd);
> sub pdd2pod {
> my $pdd = shift || die "Please supply a pdd file";
> open(PDD, $pdd) or die "Coudn't open $pdd: $!";
> my @lines = <PDD>;
> close PDD;
> my $VAR1;
> my $code = join " ", @lines;
> eval ($code);
> (my $pod = $pdd) =~ s!\.pdd$!.pod!;
> open (POD, ">$pod") or die "Can't open $pod: $!";
> my $module = $VAR1->{module};
> print POD <<"END";
> =head1 $VAR1->{module} documentation
>
> The following methods are available.
>
> =head1 Methods
>
> =over
>
> END
>
> foreach my $hash (@{$VAR1->{functions_detailed}}) {
> my $comment = $hash->{comment_parsed};
> my $desc = $comment->{func_desc} || 'none given';
> my $return = $comment->{doxygen_return} || 'not supplied';
> print POD <<"END";
>
> =item $hash->{name}
>
> I<C Type>:
>
> $hash->{code}
>
> I<Description:> $desc
>
> END
>
> my @keys = keys %{$comment->{doxygen_param_desc}};
> if (@keys) {
> print POD "I<Arguments:>\n";
> foreach my $key (@keys) {
> print POD " \n$key: $comment->{doxygen_param_desc}->{$key}\n";
> }
> }
> else {
> print POD "I<Arguments:>\nnot supplied\n";
> }
> print POD "\nI<Return:> $return\n";
>
> }
>
> print POD "\n=back\n";
> close POD;
> }
>
>
> ------------------------------------------------------------------------
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
> For additional commands, e-mail: docs-dev-help@perl.apache.org
--
__________________________________________________________________
Stas Bekman JAm_pH ------> Just Another mod_perl Hacker
http://stason.org/ mod_perl Guide ---> http://perl.apache.org
mailto:stas@stason.org http://use.perl.org http://apacheweek.com
http://modperlbook.org http://apache.org http://ticketmaster.com
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org
Re: Autogenerating Docs
Posted by Gerald Richter <ri...@ecos.de>.
> Stas has mentioned that getting the autogenerating of skeleton
> pods would be useful ... Attached is a script that perhaps might
> be a start in that direction - it takes a pdd file and writes a
> pod outline of the included methods (name, C definition,
> description, arguments, and return type).
>
Lyle has send me a few days ago his work, which does basicly the same. I
will take a look at both of your work during the week. To avoid duplicating
work, please wait until I have finished this. I try to do this ASAP so work
can continue and to work together on one code base.
Gerald
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org
Autogenerating Docs
Posted by Randy Kobes <ra...@theoryx5.uwinnipeg.ca>.
Stas has mentioned that getting the autogenerating of skeleton
pods would be useful ... Attached is a script that perhaps might
be a start in that direction - it takes a pdd file and writes a
pod outline of the included methods (name, C definition,
description, arguments, and return type).
--
best regards,
randy
Re: Autogenerating XS code and Docs
Posted by Gerald Richter <ri...@ecos.de>.
> I've been looking for a way to help out in the modperl-2.x development
> effort. This sounds interesting.
>
> Let me know where and how I can contribute my modest skills.
>
You are very welcome to contribute.
I would suggest you start with the part of autogenerating docs. For various
reasons:
1.) For the XS code we have a working solutions, docs are missing for large
parts of the API.
2.) You will be able to get familar with XSBuilder, without the need to
understand all Apache / mod_perl /XS internals right from the start, but you
get a good insight how everything works.
To start,
- check out modperl from the CVS
- install mod_perl on your system
- download the sources of xsbuilder and mpbuilder from
ftp://ftp.dev.ecos.de/pub/perl/xsbuilder/.
- Install XSBuilder as usualy (perl Makefile.PL && make install)
- Unpack mpbuilder
- Make a symlink named xs in the mpbuilder directory to the xs directory in
the modperl cvs
- adjust the lib paths in the xsbuilder/*.pl files to point to the
mpbuilder/lib and your modperl CVS directory
- run xsbuilder/source_scan.pl
- run xsbuilder/xs_generate.pl
- Now you have a WrapXS subdirectory which contains the generated XS files
- This directory also contains a pdd file for every module, which holds all
information avaiable for that module and it's method, this is the source for
generating the docs
Gerald
P.S. Some of the discussion of the autodoc generatation has only taken place
on the docs-dev list, so you may join this as well
-------------------------------------------------------------
Gerald Richter ecos electronic communication services gmbh
Internetconnect * Webserver/-design/-datenbanken * Consulting
Post: Tulpenstrasse 5 D-55276 Dienheim b. Mainz
E-Mail: richter@ecos.de Voice: +49 6133 925131
WWW: http://www.ecos.de Fax: +49 6133 925152
-------------------------------------------------------------
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org
Re: Autogenerating XS code and Docs
Posted by Gerald Richter <ri...@ecos.de>.
> I've been looking for a way to help out in the modperl-2.x development
> effort. This sounds interesting.
>
> Let me know where and how I can contribute my modest skills.
>
You are very welcome to contribute.
I would suggest you start with the part of autogenerating docs. For various
reasons:
1.) For the XS code we have a working solutions, docs are missing for large
parts of the API.
2.) You will be able to get familar with XSBuilder, without the need to
understand all Apache / mod_perl /XS internals right from the start, but you
get a good insight how everything works.
To start,
- check out modperl from the CVS
- install mod_perl on your system
- download the sources of xsbuilder and mpbuilder from
ftp://ftp.dev.ecos.de/pub/perl/xsbuilder/.
- Install XSBuilder as usualy (perl Makefile.PL && make install)
- Unpack mpbuilder
- Make a symlink named xs in the mpbuilder directory to the xs directory in
the modperl cvs
- adjust the lib paths in the xsbuilder/*.pl files to point to the
mpbuilder/lib and your modperl CVS directory
- run xsbuilder/source_scan.pl
- run xsbuilder/xs_generate.pl
- Now you have a WrapXS subdirectory which contains the generated XS files
- This directory also contains a pdd file for every module, which holds all
information avaiable for that module and it's method, this is the source for
generating the docs
Gerald
P.S. Some of the discussion of the autodoc generatation has only taken place
on the docs-dev list, so you may join this as well
-------------------------------------------------------------
Gerald Richter ecos electronic communication services gmbh
Internetconnect * Webserver/-design/-datenbanken * Consulting
Post: Tulpenstrasse 5 D-55276 Dienheim b. Mainz
E-Mail: richter@ecos.de Voice: +49 6133 925131
WWW: http://www.ecos.de Fax: +49 6133 925152
-------------------------------------------------------------
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@perl.apache.org
For additional commands, e-mail: dev-help@perl.apache.org
Re: Autogenerating XS code and Docs
Posted by Lyle Brooks <br...@deseret.com>.
I've been looking for a way to help out in the modperl-2.x development
effort. This sounds interesting.
Let me know where and how I can contribute my modest skills.
Quoting Stas Bekman (stas@stason.org):
> Gerald Richter wrote:
>
> > Since the whole Apache API is well documented in this way, it should be
> > possible to autogenerate most of the mod_perl API documentation from this
> > informations. It would be necessary that somebody writes a tool that takes
> > this informations, brings it together with some manualy maintained pod and
> > generates the pods out of it. This shouldn't be to hard to do.
>
> Can you please elaborate on this "merging manually maintained pod with
> autogenerated pod" part? I don't see how this can be done easily.
>
> e.g. for this doc that I've added recently:
> http://perl.apache.org/release/docs/2.0/api/mod_perl-2.0/Apache/Log.html
> there is very little to be re-used from the apache docs, may be 5%.
>
> I guess what we need is sort of a template for the API documentation,
> which will be automatically filled with autogenerated docs. When such a
> doc is created for the first time, it's copied away to the place where
> the final pod should be and filled in with manual craft. This
> autogenerated file should be stored somewhere, so the next time the doc
> is autogenerated again (if the Apache API changes) we will be able to
> create a diff against docs that were autogenerated before (e.g. on every
> release) and merge manually the changes (notice that the diff is done
> against the doc autogenerated in the previous time, not the final pod).
> That's how I see it working. So we keep in cvs:
>
> 1) WrapXS/Apache/RequestRec/RequestRec.pod.last
> 2) WrapXS/Apache/RequestRec/RequestRec.pod
> 3) docs/api/mod_perl-2.0/Apache/RequestRec.pod
>
> 1) autogenerated last time and already merged into 3)
> 2) generated now, so we can diff 2) against 1) and merge into 3)
> 3) the real pod, manualy edited.
>
> > For the XS genaration stuff there some issue with pTHX_ parameters left,
> > which I hope to resolve soon. Also the whole stuff for generating constants
> > is missing yet.
>
> Devel::PPPort?
>
> Another question I have:
> In order to use ExtUtils::XSBuilder we need to have it in mod_perl. So
> does that mean that we cannot use it before mod_perl replaces its
> proprietary WrapXS with ExtUtils::XSBuilder?
>
> And of course we need to discuss the template, but this can be done
> later when and if we start deploying ExtUtils::XSBuilder.
>
> __________________________________________________________________
> Stas Bekman JAm_pH ------> Just Another mod_perl Hacker
> http://stason.org/ mod_perl Guide ---> http://perl.apache.org
> mailto:stas@stason.org http://use.perl.org http://apacheweek.com
> http://modperlbook.org http://apache.org http://ticketmaster.com
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@perl.apache.org
> For additional commands, e-mail: dev-help@perl.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@perl.apache.org
For additional commands, e-mail: dev-help@perl.apache.org
Re: Autogenerating XS code and Docs
Posted by Stas Bekman <st...@stason.org>.
Gerald Richter wrote:
> Since the whole Apache API is well documented in this way, it should be
> possible to autogenerate most of the mod_perl API documentation from this
> informations. It would be necessary that somebody writes a tool that takes
> this informations, brings it together with some manualy maintained pod and
> generates the pods out of it. This shouldn't be to hard to do.
Can you please elaborate on this "merging manually maintained pod with
autogenerated pod" part? I don't see how this can be done easily.
e.g. for this doc that I've added recently:
http://perl.apache.org/release/docs/2.0/api/mod_perl-2.0/Apache/Log.html
there is very little to be re-used from the apache docs, may be 5%.
I guess what we need is sort of a template for the API documentation,
which will be automatically filled with autogenerated docs. When such a
doc is created for the first time, it's copied away to the place where
the final pod should be and filled in with manual craft. This
autogenerated file should be stored somewhere, so the next time the doc
is autogenerated again (if the Apache API changes) we will be able to
create a diff against docs that were autogenerated before (e.g. on every
release) and merge manually the changes (notice that the diff is done
against the doc autogenerated in the previous time, not the final pod).
That's how I see it working. So we keep in cvs:
1) WrapXS/Apache/RequestRec/RequestRec.pod.last
2) WrapXS/Apache/RequestRec/RequestRec.pod
3) docs/api/mod_perl-2.0/Apache/RequestRec.pod
1) autogenerated last time and already merged into 3)
2) generated now, so we can diff 2) against 1) and merge into 3)
3) the real pod, manualy edited.
> For the XS genaration stuff there some issue with pTHX_ parameters left,
> which I hope to resolve soon. Also the whole stuff for generating constants
> is missing yet.
Devel::PPPort?
Another question I have:
In order to use ExtUtils::XSBuilder we need to have it in mod_perl. So
does that mean that we cannot use it before mod_perl replaces its
proprietary WrapXS with ExtUtils::XSBuilder?
And of course we need to discuss the template, but this can be done
later when and if we start deploying ExtUtils::XSBuilder.
__________________________________________________________________
Stas Bekman JAm_pH ------> Just Another mod_perl Hacker
http://stason.org/ mod_perl Guide ---> http://perl.apache.org
mailto:stas@stason.org http://use.perl.org http://apacheweek.com
http://modperlbook.org http://apache.org http://ticketmaster.com
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@perl.apache.org
For additional commands, e-mail: dev-help@perl.apache.org
Re: Autogenerating XS code and Docs
Posted by Per Einar Ellefsen <pe...@skynet.be>.
At 09:35 12.06.2002, Gerald Richter wrote:
>Hi,
>
>as some of you may know, last fall I have started a project that splits out
>the XS autogenerating stuff from mod_perl 2.0 and generalize it to make it
>useable also outside of mod_perl. I have converted the C parser from C::Scan
>to a more flexible approach with Parse::RecDescent (which needs no C
>Compiler anymore), abtracted the Apache/mod_perl specific stuff into it's
>own subclass and added some other features. The result runs as
>ExtUtils::XSBuilder. I use this currently to build the Perl <-> C interface
>of Embperl 2.0 and for generating a mod_dav 1.0 interfaces (which I hope to
>release soon). Then, of course, I have tried to use it for mod_perl itself,
>but due to my limited time the process of makeing it run with mod_perl has
>been stalled since some time. I had a mail exchange with Stas some time ago
>and we though it will be the best to make the effort public, so maybe
>somebody can join in. Also I have some time now available, so I want to
>continue to work on it. There are two parts:
>
>1.) generating code
>2.) generating docs
This is great Gerald! Let's hope we can make something out of it here for
the docs.
--
Per Einar Ellefsen
per.einar@skynet.be
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org