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 2003/07/07 07:44:54 UTC
Re: Autogeneration of docs
Hi,
>
> Okay. I'm there.
That's a good first step!
>What do I do with them? That is, I've got all this
> great autogenerated stuff sitting in a directory, how do I make changes
> to the autogenerated stuff?
>
The point was to change the formatting in a way that you don't have to edit
them by hand. You can do this by modifying the methods in
ModPerl::PODTemplate (inside of mpbuilder). Take a look at the last mail
Stas send to the docs-dev mailing list, for what he thinks should be
changed. When the formatting is ok, then we should check that the docs are
complete, i.e. xsbuilder builder isn't missing any important piece of code
or doing the wrong thing at some point.
When these steps are complete we have a first set of documentation for the
whole mod_perl 2 stuff. This is a good starting point for doing hand editing
of the docs e.g. adding perl specific stuff, removing stuff that is only of
interenst for C programmeres etc.
When you feel there is any thing that should be done by xsbuilder (e.g.
something that is always wrong) let me know and I try to change xsbuilder in
that way.
Gerald
P.S. I moving the discussion back to the docs-dev mailing list so other can
participate
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org
Re: Autogeneration of docs
Posted by Stas Bekman <st...@stason.org>.
Gerald Richter wrote:
>>I have a suggestion/question for xsbuilder/ModPerl::PODTemplate. The
>>system is quite clever and useful, and it works, apparently. My
>>suggestion is to make the system use a templating module. I'm familiar
>>with TemplateToolkit and HTML::Template, but those are probably
>>overkill. Text::Template might do it. Of course, this adds a
>>dependency that you might not want to deal with. I offer it as a
>>suggestion/question only.
>>
>
>
> I had thought about using a Template module, but I think it's overkill. The
> POD ins't so complicated, that it would be necessary to add the dependency
> of a Template module (which will have more dependencies). Also it would be
> hard to choose one. When I choose one I would use Embperl, because I am the
> author of Embperl and xsbuilder is used to generate glue code for Embperl,
> but then the mod_perl poeple that like to work on the docs need to install
> Embperl. The other way around it would be necessary for the Embperl people
> to install anotherTemplate module.
>
> I think we should keep it simple and avoid such dependencies.
+1
not so much for dependecies, but for KISS.
__________________________________________________________________
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: Autogeneration of docs
Posted by Gerald Richter <ri...@ecos.de>.
> I have a suggestion/question for xsbuilder/ModPerl::PODTemplate. The
> system is quite clever and useful, and it works, apparently. My
> suggestion is to make the system use a templating module. I'm familiar
> with TemplateToolkit and HTML::Template, but those are probably
> overkill. Text::Template might do it. Of course, this adds a
> dependency that you might not want to deal with. I offer it as a
> suggestion/question only.
>
I had thought about using a Template module, but I think it's overkill. The
POD ins't so complicated, that it would be necessary to add the dependency
of a Template module (which will have more dependencies). Also it would be
hard to choose one. When I choose one I would use Embperl, because I am the
author of Embperl and xsbuilder is used to generate glue code for Embperl,
but then the mod_perl poeple that like to work on the docs need to install
Embperl. The other way around it would be necessary for the Embperl people
to install anotherTemplate module.
I think we should keep it simple and avoid such dependencies.
Gerald
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org
Re: Autogeneration of docs
Posted by Jack Nerad <jn...@bellsouth.net>.
Gerald Richter wrote:
>The point was to change the formatting in a way that you don't have to edit
>them by hand. You can do this by modifying the methods in
>ModPerl::PODTemplate (inside of mpbuilder). Take a look at the last mail
>Stas send to the docs-dev mailing list, for what he thinks should be
>changed. When the formatting is ok, then we should check that the docs are
>complete, i.e. xsbuilder builder isn't missing any important piece of code
>or doing the wrong thing at some point.
>
I have a suggestion/question for xsbuilder/ModPerl::PODTemplate. The
system is quite clever and useful, and it works, apparently. My
suggestion is to make the system use a templating module. I'm familiar
with TemplateToolkit and HTML::Template, but those are probably
overkill. Text::Template might do it. Of course, this adds a
dependency that you might not want to deal with. I offer it as a
suggestion/question only.
--
Jack
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org
Re: Autogeneration of docs
Posted by Gerald Richter <ri...@ecos.de>.
Stas,
>
> Gerald, can you please post the latest instructions on how to use
xsbuilder
> with mp2, so Jack can try first to use it as is, before changing anything.
I
> know you have posted it before, but please do so again (or point to that
> post). Thanks a lot.
>
I have already send it to him (I just don't wanted to send the attachments
to all the people on the mailing list) and if I didn't misunderstood his
email, he has already sucessfully set it up and got it running.
Gerald
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org
Re: Autogeneration of docs
Posted by Stas Bekman <st...@stason.org>.
Gerald Richter wrote:
> Hi,
>
>
>>Okay. I'm there.
>
>
> That's a good first step!
>
>
>>What do I do with them? That is, I've got all this
>>great autogenerated stuff sitting in a directory, how do I make changes
>>to the autogenerated stuff?
>>
>
>
> The point was to change the formatting in a way that you don't have to edit
> them by hand. You can do this by modifying the methods in
> ModPerl::PODTemplate (inside of mpbuilder). Take a look at the last mail
> Stas send to the docs-dev mailing list, for what he thinks should be
> changed. When the formatting is ok, then we should check that the docs are
> complete, i.e. xsbuilder builder isn't missing any important piece of code
> or doing the wrong thing at some point.
>
> When these steps are complete we have a first set of documentation for the
> whole mod_perl 2 stuff. This is a good starting point for doing hand editing
> of the docs e.g. adding perl specific stuff, removing stuff that is only of
> interenst for C programmeres etc.
>
> When you feel there is any thing that should be done by xsbuilder (e.g.
> something that is always wrong) let me know and I try to change xsbuilder in
> that way.
>
> Gerald
>
> P.S. I moving the discussion back to the docs-dev mailing list so other can
> participate
Gerald, can you please post the latest instructions on how to use xsbuilder
with mp2, so Jack can try first to use it as is, before changing anything. I
know you have posted it before, but please do so again (or point to that
post). Thanks a lot.
__________________________________________________________________
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