Re: GSoC Status Update
On 08/23/2011 11:03 PM, Marc Green wrote: Hello everyone, This is my last status update, as GSoC ended today (Monday, at the time of writing). [I am not able to send this out now because I do not have access to my email (well, to the Internet). I am going to send it out tomorrow or the day after.] I believe my project has been successful, and I am positive my mentors would agree. That being said, I am *still* not done with neither Pod::Html nor Pod::Checker. Well, I am done with all the coding -- they're both in their final stages in that regard, but they are yet to be merged into core and tested (and complained about). I plan to see them through though, and I plan on being the maintainer for both of them if possible. I was able to wrap up everything with Pod::Checker this week, so all I need to do is to clean up its commit history (which will get done within the next few days). Actually, that is a lie, I was not able to get everything wrapped up. There is one thing in particular that I did not get done: splitting Pod::Checker into Pod::Checker and Pod::Checker::Internals, the latter being-a Pod::Simple and the former having-a Pod::Checker::Internals. This split was conjured up in order to remove Pod::Simple from Pod::Checker's interface. However, as I just said, I was not able to do this. Instead, I added a warning in Pod::Checker's documentation explaining that no user should EVER use any aspect of Pod::Checker's interface that has to do with Pod::Simple unless it is documented. Perhaps this is a task that can be tackled by me or someone else in the future. Oh, actually, my lie in the previous paragraph was a lie for another reason too. My mentor, rjbs, offered to do some grunt work on Pod::Checker for me so I could focus on the bigger stuff. These tasks include removing the 5.14isms I used throughout and making Pod::Checker its own dist (apart from Pod::Parser). These are not done yet, but him and I are going to remain in contact so that the new Pod::Checker can see the light of day. Pod::Html shall also see the light of day. My second mentor, theory, released a new version of Pod::Simple which contains some new code I added to allow me to finish Pod::Html a while back. [At the time of writing this it might not be released, but he assured me it would be in the next few days, so I will take his word.] Now that it is released, I can rebase its commit history to remove some hacks that let me use the aforementioned new code. Pod::Html will then be merged into core and hopefully be a success. I feel this has been a wonderful experience for me; my foot is in the Perl community door now, and I have gotten a taste of what it is like to contribute to an open source project. It has also been a great experience for the Perl community (I can imagine), as who doesn't like seemingly free, beneficial code. (Seemingly beneficial, perhaps.) Thank you everyone who helped me this summer, in particular rjbs, theory, and rafl. I appreciate it! Marc Marc++
Re: GSoC Status Update
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
Re: GSoC Status Update
On 07/27/2011 07:58 AM, Marc Green wrote: 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 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.
Re: GSoC Status Update
Good job (anyway) keep the reports coming too, it is good to see that things go forward. Nadim. +++ Marc Green [Fri, May 27, 2011 at 05:52:15PM -0400]: Hello all, I am sending my status report early because I will not be able to send it at the beginning of next week. Although one could not tell from the most recent commitshttps://github.com/marcgreenI have pushed this past week, I have gotten a lot done. This is because I have found out what I have been doing is a colossal waste of time. More specifically, at the beginning of this week I was in the mindset that I needed to subclass Pod::Simple::Xhtml to modify it in order to resolve L directives to local links (as opposed to online links, as it does by default). So I went on my merry way, creating the module, tossing ideas back and forth about how to best achieve the desired result, until about 2 hours ago. I realized that it will be a pain pursuing my original plan (which was to use Pod::Simple::Search within my subclass of ::Xhtml in order to resolve the links). Consequently, I realized I need not subclass Xhtml to resolve links locally, the module itself provides methods to alter the URL of all links. It's embarrassing that I never thought to use said methods before, but oh well, the damage is done. Not only that, but I took on way too much when I was subclassing ::Xhtml. For some reason I thought it would be a great idea to scrap everything in Pod::Html and rewrite it using my subclass. I came to my senses today and realized I only need to have a drop in replacement for Pod::Html's pod parser and xhtml formatter. What a relief! But this week wasn't really a waste of time. Besides the obvious reason of finding a good way not to resolve links locally, I learned about the internals of Pod::Html much more (though not enough, yet). I cleaned out all of Pod::Html's old code, and started setting up to use ::Xhtml and ::Search. I also removed the --header feature of Pod::Html that was needlessly distracting me. I plan on adding it, in addition to other features I have removed, back, once I get the bare bones of the conversion to ::Xhtml done. I won't have a lot of time next week to work on this, (vacation :D), but when I get back I plan on, in no particular order: - using Pod::Simple::Search to resolve L directives - investigating how Pod::Html resolves other links (RFC links, perl.* links in verbatim text, etc) - write several test cases for Pod::Html, both to understand how it works and to have for when I convert it Thank you, Marc
