I have started to work on XSBuilder again. The first thing I have done is to create a module called ModPerl::PODTemplate, which contains a set of methods which allows to easily change the format of the generated POD. I attach you the new version, along with two files I have generated. I didn't have made any changes in the format so far. I would like to get your feedback, on how the output should look like, them I can implement it imediately (or of course you can change mpbuilder/lib/ModPerl/PODTemple.pm on your own and play with it)
But I have already provided the feedback, when you first posted it long time ago. http://mathforum.org/epigone/modperl-docs-dev/fyhahmen
Here are some more comments:
The examples look OK I suppose, I think we have already agreed to have $t->foo and not $t -> foo.
From the recent work on the docs, I think I prefer to have all the functions in =head2 to be enclosed in C<> so they look good in the TOC. Granted it makes it more cumbersome to write L<> links manually, but the end user gets better docs.
same for all variables, they should be C<>, to save us a lot of manual work.
Should description of the method come before its arguments?
things like <PRE> are HTML, not pod. see Table.pod that you have attached.
Things like PV/IV make little sense to users. Perhaps replace them with SCALAR? So we may have SCALAR, ARRAY, VOID
@since: 1.99 : should probably be more specific, i.e. 1.99_09
Finally, are you sure that we want to maintain this intermediary format. It's going to be a big pain. I suggest to drop the idea and go with the plain pod. We have very little human resources to work on docs, so the less we have to maintain the better.
The next thing I will do is looking after the constant issue.
Cool. Great to hear that you are back to work on it.
P.S. In case you want to try it out and didn't remeber mpbuilder/README contains a short setup description
__________________________________________________________________ Stas Bekman JAm_pH ------> Just Another mod_perl Hacker http://stason.org/ mod_perl Guide ---> http://perl.apache.org mailto:[EMAIL PROTECTED] http://use.perl.org http://apacheweek.com http://modperlbook.org http://apache.org http://ticketmaster.com
mpbuilder-0.03.tar.gz
Description: application/gzip
Description: application/gzip=head1 NAME Apache::RequestRec =head1 FUNCTIONS =head2 @func: proxyreq() $ret = $r -> proxyreq($val) =over 4 =item @param: Apache::RequestRec $r =item @param: SV $val =item @ret: IV =item @since: 1.99 =back =head2 @func: pool() $val = $obj -> pool($newval) =over 4 =item @param: Apache::RequestRec $obj =item @param: APR::Pool $newval =item @since: 1.99 =back The pool associated with the request =head2 @func: connection() $val = $obj -> connection($newval) =over 4 =item @param: Apache::RequestRec $obj =item @param: Apache::Connection $newval =item @since: 1.99 =back The connection to the client =head2 @func: server() $val = $obj -> server($newval) =over 4 =item @param: Apache::RequestRec $obj =item @param: Apache::Server $newval =item @since: 1.99 =back The virtual host for this request =head2 @func: next() $val = $obj -> next($newval) =over 4 =item @param: Apache::RequestRec $obj =item @param: Apache::RequestRec $newval =item @since: 1.99 =back Pointer to the redirected request if this is an external redirect =head2 @func: prev() $val = $obj -> prev($newval) =over 4 =item @param: Apache::RequestRec $obj =item @param: Apache::RequestRec $newval =item @since: 1.99 =back Pointer to the previous request if this is an internal redirect =head2 @func: main() $val = $obj -> main($newval) =over 4 =item @param: Apache::RequestRec $obj =item @param: Apache::RequestRec $newval =item @since: 1.99 =back Pointer to the main request if this is a sub-request (see request.h) =head2 @func: the_request() $val = $obj -> the_request($newval) =over 4 =item @param: Apache::RequestRec $obj =item @param: PV $newval =item @since: 1.99 =back protocol.c should ever touch... * First line of request =head2 @func: assbackwards() $val = $obj -> assbackwards($newval) =over 4 =item @param: Apache::RequestRec $obj =item @param: IV $newval =item @since: 1.99 =back HTTP/0.9, "simple" request (e.g. GET /foo\n w/no headers) =head2 @func: header_only() $val = $obj -> header_only($newval) =over 4 =item @param: Apache::RequestRec $obj =item @param: IV $newval =item @since: 1.99 =back HEAD request, as opposed to GET =head2 @func: protocol() $val = $obj -> protocol($newval) =over 4 =item @param: Apache::RequestRec $obj =item @param: PV $newval =item @since: 1.99 =back Protocol string, as given to us, or HTTP/0.9 =head2 @func: proto_num() $val = $obj -> proto_num($newval) =over 4 =item @param: Apache::RequestRec $obj =item @param: IV $newval =item @since: 1.99 =back Protocol version number of protocol; 1.1 = 1001 =head2 @func: hostname() $val = $obj -> hostname($newval) =over 4 =item @param: Apache::RequestRec $obj =item @param: PV $newval =item @since: 1.99 =back Host, as set by full URI or Host: =head2 @func: request_time() $val = $obj -> request_time($newval) =over 4 =item @param: Apache::RequestRec $obj =item @param: NV $newval =item @since: 1.99 =back Time when the request started =head2 @func: status_line() $val = $obj -> status_line($newval) =over 4 =item @param: Apache::RequestRec $obj =item @param: PV $newval =item @since: 1.99 =back Status line, if set by script =head2 @func: status() $val = $obj -> status($newval) =over 4 =item @param: Apache::RequestRec $obj =item @param: IV $newval =item @since: 1.99 =back Status line =head2 @func: method() $val = $obj -> method($newval) =over 4 =item @param: Apache::RequestRec $obj =item @param: PV $newval =item @since: 1.99 =back look, but don't touch. * Request method (eg. GET, HEAD, POST, etc.) =head2 @func: method_number() $val = $obj -> method_number($newval) =over 4 =item @param: Apache::RequestRec $obj =item @param: IV $newval =item @since: 1.99 =back M_GET, M_POST, etc. =head2 @func: allowed() $val = $obj -> allowed($newval) =over 4 =item @param: Apache::RequestRec $obj =item @param: NV $newval =item @since: 1.99 =back 'allowed' is a bitvector of the allowed methods. A handler must ensure that the request method is one that it is capable of handling. Generally modules should DECLINE any request methods they do not handle. Prior to aborting the handler like this the handler should set r->allowed to the list of methods that it is willing to handle. This bitvector is used to construct the "Allow:" header required for OPTIONS requests, and HTTP_METHOD_NOT_ALLOWED and HTTP_NOT_IMPLEMENTED status codes. Since the default_handler deals with OPTIONS, all modules can usually decline to deal with OPTIONS. TRACE is always allowed, modules don't need to set it explicitly. Since the default_handler will always handle a GET, a module which does *not* implement GET should probably return HTTP_METHOD_NOT_ALLOWED. Unfortunately this means that a Script GET handler can't be installed by mod_actions. =head2 @func: allowed_xmethods() $val = $obj -> allowed_xmethods($newval) =over 4 =item @param: Apache::RequestRec $obj =item @param: APR::ArrayHeader $newval =item @since: 1.99 =back Array of extension methods =head2 @func: allowed_methods() $val = $obj -> allowed_methods($newval) =over 4 =item @param: Apache::RequestRec $obj =item @param: Apache::MethodList $newval =item @since: 1.99 =back List of allowed methods =head2 @func: bytes_sent() $val = $obj -> bytes_sent($newval) =over 4 =item @param: Apache::RequestRec $obj =item @param: IV $newval =item @since: 1.99 =back body byte count, for easy access =head2 @func: mtime() $val = $obj -> mtime($newval) =over 4 =item @param: Apache::RequestRec $obj =item @param: NV $newval =item @since: 1.99 =back Last modified time of the requested resource =head2 @func: remaining() $val = $obj -> remaining($newval) =over 4 =item @param: Apache::RequestRec $obj =item @param: IV $newval =item @since: 1.99 =back Remaining bytes left to read from the request body =head2 @func: headers_in() $val = $obj -> headers_in($newval) =over 4 =item @param: Apache::RequestRec $obj =item @param: APR::Table $newval =item @since: 1.99 =back environment variables to be passed to subprocesses, so people can write modules to add to that environment. The difference between headers_out and err_headers_out is that the latter are printed even on error, and persist across internal redirects (so the headers printed for ErrorDocument handlers will have them). The 'notes' apr_table_t is for notes from one module to another, with no other set purpose in mind... * MIME header environment from the request =head2 @func: headers_out() $val = $obj -> headers_out($newval) =over 4 =item @param: Apache::RequestRec $obj =item @param: APR::Table $newval =item @since: 1.99 =back MIME header environment for the response =head2 @func: err_headers_out() $val = $obj -> err_headers_out($newval) =over 4 =item @param: Apache::RequestRec $obj =item @param: APR::Table $newval =item @since: 1.99 =back MIME header environment for the response, printed even on errors and persist across internal redirects =head2 @func: notes() $val = $obj -> notes($newval) =over 4 =item @param: Apache::RequestRec $obj =item @param: APR::Table $newval =item @since: 1.99 =back Notes from one module to another =head2 @func: handler() $val = $obj -> handler($newval) =over 4 =item @param: Apache::RequestRec $obj =item @param: PV $newval =item @since: 1.99 =back =head2 @func: content_encoding() $val = $obj -> content_encoding($newval) =over 4 =item @param: Apache::RequestRec $obj =item @param: PV $newval =item @since: 1.99 =back =head2 @func: content_languages() $val = $obj -> content_languages($newval) =over 4 =item @param: Apache::RequestRec $obj =item @param: APR::ArrayHeader $newval =item @since: 1.99 =back Array of strings representing the content languages =head2 @func: user() $val = $obj -> user($newval) =over 4 =item @param: Apache::RequestRec $obj =item @param: PV $newval =item @since: 1.99 =back If an authentication check was made, this gets set to the user name. =head2 @func: no_local_copy() $val = $obj -> no_local_copy($newval) =over 4 =item @param: Apache::RequestRec $obj =item @param: IV $newval =item @since: 1.99 =back There is no local copy of this response =head2 @func: unparsed_uri() $val = $obj -> unparsed_uri($newval) =over 4 =item @param: Apache::RequestRec $obj =item @param: PV $newval =item @since: 1.99 =back or content-negotiation mapping). * The URI without any parsing performed =head2 @func: uri() $val = $obj -> uri($newval) =over 4 =item @param: Apache::RequestRec $obj =item @param: PV $newval =item @since: 1.99 =back The path portion of the URI =head2 @func: filename() $val = $obj -> filename($newval) =over 4 =item @param: Apache::RequestRec $obj =item @param: PV $newval =item @since: 1.99 =back The filename on disk corresponding to this response =head2 @func: canonical_filename() $val = $obj -> canonical_filename($newval) =over 4 =item @param: Apache::RequestRec $obj =item @param: PV $newval =item @since: 1.99 =back =head2 @func: path_info() $val = $obj -> path_info($newval) =over 4 =item @param: Apache::RequestRec $obj =item @param: PV $newval =item @since: 1.99 =back The PATH_INFO extracted from this request =head2 @func: args() $val = $obj -> args($newval) =over 4 =item @param: Apache::RequestRec $obj =item @param: PV $newval =item @since: 1.99 =back The QUERY_ARGS extracted from this request =head2 @func: used_path_info() $val = $obj -> used_path_info($newval) =over 4 =item @param: Apache::RequestRec $obj =item @param: IV $newval =item @since: 1.99 =back Flag for the handler to accept or reject path_info on the current request. All modules should respect the AP_REQ_ACCEPT_PATH_INFO and AP_REQ_REJECT_PATH_INFO values, while AP_REQ_DEFAULT_PATH_INFO indicates they may follow existing conventions. This is set to the user's preference upon HOOK_VERY_FIRST of the fixups. =head2 @func: per_dir_config() $val = $obj -> per_dir_config($newval) =over 4 =item @param: Apache::RequestRec $obj =item @param: Apache::ConfVector $newval =item @since: 1.99 =back These are config vectors, with one void* pointer for each module (the thing pointed to being the module's business). * Options set in config files, etc. =head2 @func: request_config() $val = $obj -> request_config($newval) =over 4 =item @param: Apache::RequestRec $obj =item @param: Apache::ConfVector $newval =item @since: 1.99 =back Notes on *this* request =head2 @func: output_filters() $val = $obj -> output_filters($newval) =over 4 =item @param: Apache::RequestRec $obj =item @param: Apache::Filter $newval =item @since: 1.99 =back A list of output filters to be used for this request =head2 @func: input_filters() $val = $obj -> input_filters($newval) =over 4 =item @param: Apache::RequestRec $obj =item @param: Apache::Filter $newval =item @since: 1.99 =back A list of input filters to be used for this request =head2 @func: proto_output_filters() $val = $obj -> proto_output_filters($newval) =over 4 =item @param: Apache::RequestRec $obj =item @param: Apache::Filter $newval =item @since: 1.99 =back A list of protocol level output filters to be used for this request =head2 @func: proto_input_filters() $val = $obj -> proto_input_filters($newval) =over 4 =item @param: Apache::RequestRec $obj =item @param: Apache::Filter $newval =item @since: 1.99 =back A list of protocol level input filters to be used for this request=head1 NAME APR::Table =head1 FUNCTIONS =head2 @func: add() $t -> add($key,$val) =over 4 =item @param: APR::Table $t The table to add to =item @param: PV $key The key to use =item @param: PV $val The value to add. =item @since: 1.99 =back Add data to a table, regardless of whether there is another element with the same key. When adding data, this function makes a copy of both the key and the value. =head2 @func: clear() $t -> clear() =over 4 =item @param: APR::Table $t The table to clear =item @since: 1.99 =back Delete all of the elements from a table =head2 @func: copy() $ret = $t -> copy($p) =over 4 =item @param: APR::Table $t The table to copy =item @param: APR::Pool $p The pool to allocate the new table out of =item @ret: APR::Table =item @since: 1.99 =back Create a new table and copy another table into it =head2 @func: make() $ret = $p -> make($nelts) =over 4 =item @param: APR::Pool $p The pool to allocate the pool out of =item @param: IV $nelts The number of elements in the initial table. =item @ret: APR::Table =item @since: 1.99 =back Make a new table =head2 @func: merge() $t -> merge($key,$val) =over 4 =item @param: APR::Table $t The table to search for the data =item @param: PV $key The key to merge data for =item @param: PV $val The data to add =item @since: 1.99 =back Add data to a table by merging the value with data that has already been stored If the key is not found, then this function acts like apr_table_add =head2 @func: overlap() $a -> overlap($b,$flags) =over 4 =item @param: APR::Table $a The table to add the data to. =item @param: APR::Table $b The table to iterate over, adding its data to table a =item @param: UV $flags How to add the table to table a. One of: APR_OVERLAP_TABLES_SET Use apr_table_setn APR_OVERLAP_TABLES_MERGE Use apr_table_mergen =item @since: 1.99 =back For each element in table b, either use setn or mergen to add the data to table a. Which method is used is determined by the flags passed in. This function is highly optimized, and uses less memory and CPU cycles than a function that just loops through table b calling other functions. * <PRE> Conceptually, apr_table_overlap does this: apr_array_header_t *barr = apr_table_elts(b); apr_table_entry_t *belt = (apr_table_entry_t *)barr->elts; int i; for (i = 0; i < barr->nelts; ++i) { if (flags & APR_OVERLAP_TABLES_MERGE) { apr_table_mergen(a, belt[i].key, belt[i].val); } else { apr_table_setn(a, belt[i].key, belt[i].val); } } Except that it is more efficient (less space and cpu-time) especially when b has many elements. Notice the assumptions on the keys and values in b -- they must be in an ancestor of a's pool. In practice b and a are usually from the same pool. </PRE> =head2 @func: overlay() $ret = $base -> overlay($overlay,$p) =over 4 =item @param: APR::Table $base The table to add at the end of the new table =item @param: APR::Table $overlay The first table to put in the new table =item @param: APR::Pool $p The pool to use for the new table =item @ret: APR::Table =item @since: 1.99 =back Merge two tables into one new table =head2 @func: set() $t -> set($key,$val) =over 4 =item @param: APR::Table $t The table to add the data to. =item @param: PV $key The key fo use =item @param: PV $val The value to add =item @since: 1.99 =back Add a key/value pair to a table, if another element already exists with the same key, this will over-write the old data. When adding data, this function makes a copy of both the key and the value. =head2 @func: unset() $t -> unset($key) =over 4 =item @param: APR::Table $t The table to remove data from =item @param: PV $key The key of the data being removed =item @since: 1.99 =back Remove data from the table =head2 @func: EXISTS() $ret = $t -> EXISTS($key) =over 4 =item @param: APR::Table $t =item @param: PV $key =item @ret: IV =item @since: 1.99 =back =head2 @func: CLEAR() $t -> CLEAR() =over 4 =item @param: APR::Table $t =item @since: 1.99 =back =head2 @func: STORE() $t -> STORE($key,$value) =over 4 =item @param: APR::Table $t =item @param: PV $key =item @param: PV $value =item @since: 1.99 =back =head2 @func: DELETE() $t -> DELETE($key) =over 4 =item @param: APR::Table $t =item @param: PV $key =item @since: 1.99 =back =head2 @func: FETCH() $ret = $t -> FETCH($key) =over 4 =item @param: APR::Table $t =item @param: PV $key =item @ret: PV =item @since: 1.99 =back--------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
