Re: Example of proposed pod usage (with patch)

["Jeremiah C. Foster" <jeremiah@jeremiahfoster.com>]

On Aug 13, 2011, at 13:06, Niels Thykier wrote:
> On 2011-08-12 22:34, Jeremiah C. Foster wrote:
>> Here is an example of how I think pod might work;
> 
> Hey,
> 
> I appreciate the idea of improving the documentation and making
> (htmlified-version of) README.developers appear on lintian.d.o was a
> very nice idea. :)
> 
> I thinking we can (ab)use some headings in the README.developers.  My
> attachment is an example, I am not sure how well it works (I am mostly
> used to do pod as a part of perl scripts/modules).

I agree on both points; we shouldn't abuse pod and . . . 

>  BTW, I committed your original README.developers with a few
> changes[1], so your patch would probably not apply cleanly.

thanks for your changes, they clarify my draft text. I'll merge into my separate repo https://github.com/jeremiah/lintian-jeremiah-branch just so it is easier for me to follow. I'll still send patches to the list in the format suggested unless you'd rather pull?

> For the frontend/* files, what would we want in the pod?  Personally I
> am used to embed the "manpage"-pod in that file, but we have it (and
> partly need it to be) in a separate file (man/*).  So what are we
> looking for here?

I'm going to defer to you and Russ in this regard. I'd hesitate to change a well functioning workflow. I am happy to document stuff (mostly for my own sake so I can understand the code) when I see it not documented and I can adapt to whichever format.

>  Personally I would probably skip the "LEGAL" part; if anything I would
> include a 2-3 line "LICENSE" in the bottom[2].  Otherwise I think it
> would just be "in the way".

Yup. +1

Regards,

Jeremiah