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 -- To UNSUBSCRIBE, email to debian-lint-maint-requ...@lists.debian.org with a subject of "unsubscribe". Trouble? Contact listmas...@lists.debian.org Archive: http://lists.debian.org/ccf09ad5-104a-47f5-892c-006222629...@jeremiahfoster.com