GSoC Status Update

[Marc Green]

Howdy,

The only thing left to do with regards to Pod::Html is to have it reviewed (available at https://github.com/marcgreen/perl/blob/gsoc-pod/ext/Pod-Html/lib/Pod/Html.pm if any of you would like to). Once that is done, that is, once all comments, suggestions, and warnings are considered and possibly acted upon, it will be ready to be merged into the core.

I am happy to announce that I have made much progress on porting Pod::Checker this week. I have made a list of all the errors that Pod::Simple already checks for, and by comparing that to what Pod::Checker additionally checks for, I can efficiently implement the rest. So that is what I have been doing. There is a minor snag in one of the error checks, the one that warns if there is any text after a =pod directive, because Pod::Simple does not offer any way to access said text. To overcome this I am adding such a feature to Pod::Simple::Blackbox, so I should resume porting the error checks shortly.

Also, there is going to be a modification of my proposed timeline. I am working on the third of five modules to port; the first of which is completely done (Module::Build::PodParser), the second is essentially done (Pod::Html), and the current one is progressing nicely (Pod::Checker). With only three weeks until the suggested pencils down date (August 22), however, I do not believe there is enough time to finish all five. I am going to work with my mentors to create a realistic schedule that focuses on getting what I have done merged without leaving unfinished code.

Thank you,
Marc

[Marc Green]

> I am happy to announce that I have made much progress on porting
> Pod::Checker this week. I have made a list of all the errors that
> Pod::Simple already checks for, and by comparing that to what Pod::Checker
> additionally checks for, I can efficiently implement the rest. So that is
> what I have been doing. There is a minor snag in one of the error checks,
> the one that warns if there is any text after a =pod directive, because
> Pod::Simple does not offer any way to access said text. To overcome this I
> am adding such a feature to Pod::Simple::Blackbox, so I should resume
> porting the error checks shortly.

When I looked at this before I found there tended to be significant
disagreement over whether the Pod::Checker checks were actually good
checks that ought to be included in Pod::Simple.

I know this is opening a huge can of worms but I'd be interested if you
could post the list of checks you're adding to Pod::Simple.

Michael

I am not adding checks to Pod::Simple, I was advised that would be a bad idea (and harder to do). Rather, I am rewriting Pod::Checker to have Pod::Simple as a superclass instead of Pod::Parser, and in doing so I need to rewrite the checks *within Pod::Checker* using Pod::Simple.

Rereading my email I realize my ambiguity, but I hope I have now cleared up any confusion. If not, let me know.

Also, if you still want to see what error checks I am rewriting, they are available at https://github.com/marcgreen/perl-pod-checker/tree/edit-bb/cpan/Pod-Parser. There are three files: ps-errors, pc-errors, and pc-errors-todo. The first is a list of what Pod::Simple checks for, the second is what Pod::Checker checks for, and the third is a list of the checks I have left to rewrite.

Thanks for your concern,
Marc

[Marc Green]

Here are a couple of pod checker errors that are in error, AFAICT

One is that it warns on any E<> above 255 as being out of range.  I think this is plain wrong, as people do this and it works.  Perhaps there are some circumstances when it is wrong, I don't know.

The other is that it warns that use of a link to a man page with a section number is deprecated.  We have discussed that on this list before, and as I remember it, the consensus was it should not be deprecated.

If no one objects to those being non errors, I will not implement them in the rewrite of Pod::Checker.

Thank you for letting me know Karl, I appreciate it.

Marc

[Marc Green]

Hey everyone,

This is my weekly status update.

I have nothing new to report on Pod::Html except that I plan on doing some commit squashing so the history is not so ugly.

On Pod::Checker, however, there is much to report. First off, to solve the issue of it being a subclass of Pod::Parser, my mentors, rafl, and I decided to make it its own dist. Also, rjbs advised to make Pod::Checker have-a Pod::Simple, instead of being-a Pod::Simple, so future changes won't have to worry about breaking the Pod::Simple interface. I will take his advice on this.

I have implemented a boat load of error/warning checks this week, starting at 36 combined, now down to 7ish. There is a small quirk where some error checks fail to check when below an unclosed =begin directive. It is a sensible quirk, but I need to work it out in order to get the 7ish down to 7. Three of said error/warnings are proving to be difficult as they require me to edit Pod::Simple::Blackbox, a file I would not mind ever opening, but I may have to stick an ugly TODO comment on them, depending on how much time I have.

I have added the pod_handler() feature to Pod::Simple that I briefly mentioned in last week's status update, too.

I am currently working on error checks for L<> formatting codes, and if you are curious you can read this week's meeting at https://github.com/rjbs/TPF-GSoC-Pod/tree/master/irclogs which describes my troubles in more detail.

For the upcoming week, I have quite a bit on my plate:
- implement different warning levels in Pod::Checker
- fix the unclosed =begin disable POD checks
- test the interface of Pod::Checker (e.g., $checker->idx(), $checker->hyperlinks(), $checker->nodes(), etc)
- implement the rest of the error checks

I suppose it does not look like a lot, but it is.

Thanks,
Marc

[Karl Williamson]

Here are a couple of pod checker errors that are in error, AFAICT