On Tue, 26 Jun 2001, Doug MacEachern wrote:
> On Tue, 26 Jun 2001, Stas Bekman wrote:
>
> > let's try to go with the inlines first, if we see that it's not good. we
> > extract all the inlines into the separate .pod files. This is something
> > that we can do much easier than the reverse operation, assuming that we
> > want the snippets of pod to be scattered around the code.
> >
> > The good thing about inlines is that there is a better chance that the
> > inline docs will be updated on code updates.
> >
> > For distributions we can have all docs in .pod files. We'll make sure that
> > we have .pod, .html, .ps, .pdf, (.xml?) and other formats available on
> > demand.
>
> oh yeah, that's another reason i was thinking of having module docs be in
> their own .pod file, for the docs distribution. if the pod is inlined in
> the .pm, will you extract that into a Module.pod for the docs dist?
in theory we can preprocess and do the extraction. I don't have this
functionality now. It doesn't seem to be a hard task.
> and then, if you install a doc kit that's new than the code, does
> 'perldoc Module' pickup the new Module.pod or pod inside Module.pm?
>
> > > > Also Doug you were talking about self-documenting code, I don't remember I
> > > > saw any details about this thingy in the docs. Can you elaborate on this?
> > >
> > > by that i literally meant 'self-documenting code'. like you can
> > > get a good understanding of the modperl C code just by reading the code.
> > > granted docs for the C api would be nice, hopefully attempting to write
> > > 'self-documenting code' will make that easier.
> >
> > Oh, I see :) From your original conference paper doc I understood that you
> > plan to autogenerate docs from the API code. I thought that would be
> > cool, but now I know that it was an illusion :)
>
> that was not an illusion, i did say API docs can be generated, and they
> still can be. 'autogenerated docs' and 'self-documenting code' are two
> very different things. i mentioned 'self-documenting code' in a recent
> offlist message when you asked about documentation for understanding the
> core code.
As usual, I mess things up :( sorry about that. I meant 'autogenerated
docs'.
Currently we don't have autogenerated docs, right? I was just thinking how
'make docs' should invoke other utils to create these autogenerated docs,
before it can proceed to generate other formats.
_____________________________________________________________________
Stas Bekman JAm_pH -- Just Another mod_perl Hacker
http://stason.org/ mod_perl Guide http://perl.apache.org/guide
mailto:[EMAIL PROTECTED] http://apachetoday.com http://eXtropia.com/
http://singlesheaven.com http://perl.apache.org http://perlmonth.com/
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
