On 2011-08-13 13:21, Jeremiah C. Foster wrote: > 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 . . . >
I did not mean to say we are "abusing" (I just like the "(ab)use" word-play). I do not have strong feelings using pod in README.developers... I have strong feelings about adding more documentation in docbook (or other xml(-like) formats[1]). If pod gives us the flexibility (e.g. to transform it to html) we need, then it has my full support. My only "concern" is that I have never used pod for "non-script/module" documentation, so I could use a "Do/Don'ts" for this use of pod. [1] I find xml is a pain to read, a pain to write and a pain to parse. :P >> 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? > I setup my repository to track your github one, so I should be ready to pull from it. I am not used to do it, but I might as well learn it. :) Also, should we move the READMEs to the top level source dir? Your original patch had it in the top-level dir, but I moved it to docs/ for consistency. We have the README.in -> README transformation build to inject the command line options into the installed README, but I am honestly not sure it is worth it. I feel a simple "to see the command line options available, please run lintian --help" ought to work just as well. >> 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. > My "past experience" part is from "non-lintian" projects. So I am curious to know where a pod / separate doc for the front-ends will be useful compared to in-line comments. What would you find useful to see when you run "perldoc frontend/lintian"? Overall design/algorithm? >> 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 > ~Niels -- To UNSUBSCRIBE, email to [email protected] with a subject of "unsubscribe". Trouble? Contact [email protected] Archive: http://lists.debian.org/[email protected]
