Re: Example of proposed pod usage (with patch)
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
Reply to: